From bab659f8bd2851ac675fb4c9906d848a933bc1fc Mon Sep 17 00:00:00 2001
From: Menghuan1918 <menghuan2003@outlook.com>
Date: Wed, 12 Aug 2026 18:19:44 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E5=AE=A2=E6=88=B7=E7=AB=AF=E6=87=92?=
 =?UTF-8?q?=E5=8A=A0=E8=BD=BD=E5=88=86=E5=9D=97=20=E2=80=94=20=E9=87=8D?=
 =?UTF-8?q?=E4=BE=9D=E8=B5=96=EF=BC=88Univer/xterm/CodeMirror/Office?=
 =?UTF-8?q?=EF=BC=89=E6=8B=86=E7=8B=AC=E7=AB=8B=20bundle=20=E6=8C=89?=
 =?UTF-8?q?=E9=9C=80=E4=B8=8B=E5=8F=91=EF=BC=88/sidebar/bundle=20=E8=B7=AF?=
 =?UTF-8?q?=E7=94=B1=20+=20=5F=5FdshChunks=5F=5F=20=E6=B3=A8=E5=86=8C?=
 =?UTF-8?q?=E8=A1=A8=EF=BC=89=EF=BC=8C=E6=A0=B8=E5=BF=83=E5=90=AF=E5=8A=A8?=
 =?UTF-8?q?=E4=BB=85=20~325KB?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md                                   |   1 +
 README.md                                   |   1 +
 docs/plans/2026-08-12-lazy-chunks-design.md |  88 +++++++
 package.json                                |   6 +
 scripts/package-registry.mjs                |  12 +
 src/bundle-route.ts                         | 130 ++++++++++
 src/client/builtins/tabs.tsx                |  33 ++-
 src/client/builtins/viewers.tsx             |  44 ++--
 src/client/chunk-loader.ts                  | 196 +++++++++++++++
 src/client/chunks/docx.tsx                  |   8 +
 src/client/chunks/editor.tsx                |   9 +
 src/client/chunks/pptx.tsx                  |   8 +
 src/client/chunks/terminal.tsx              |   9 +
 src/client/chunks/xlsx.tsx                  |   9 +
 src/client/docx-view.tsx                    | 113 +++++++++
 src/client/index.tsx                        |   5 +
 src/client/lazy-chunk.tsx                   |  89 +++++++
 src/client/office-shared.tsx                |  40 +++
 src/client/office-view.tsx                  | 257 +-------------------
 src/client/xlsx-view.tsx                    | 116 +++++++++
 src/index.ts                                |  20 +-
 tests/browser-globals.ts                    |   7 +-
 tests/bundle-route.spec.ts                  | 148 +++++++++++
 tests/chunk-artifact.spec.ts                |  43 ++++
 tests/chunk-loader.spec.ts                  | 210 ++++++++++++++++
 tests/lazy-chunk.spec.tsx                   | 194 +++++++++++++++
 tests/manifest-consistency.spec.ts          |  22 +-
 tests/smoke.spec.ts                         |   2 +-
 tsdown.config.ts                            | 216 ++++++++++------
 29 files changed, 1691 insertions(+), 345 deletions(-)
 create mode 100644 docs/plans/2026-08-12-lazy-chunks-design.md
 create mode 100644 src/bundle-route.ts
 create mode 100644 src/client/chunk-loader.ts
 create mode 100644 src/client/chunks/docx.tsx
 create mode 100644 src/client/chunks/editor.tsx
 create mode 100644 src/client/chunks/pptx.tsx
 create mode 100644 src/client/chunks/terminal.tsx
 create mode 100644 src/client/chunks/xlsx.tsx
 create mode 100644 src/client/docx-view.tsx
 create mode 100644 src/client/lazy-chunk.tsx
 create mode 100644 src/client/office-shared.tsx
 create mode 100644 src/client/xlsx-view.tsx
 create mode 100644 tests/bundle-route.spec.ts
 create mode 100644 tests/chunk-artifact.spec.ts
 create mode 100644 tests/chunk-loader.spec.ts
 create mode 100644 tests/lazy-chunk.spec.tsx

diff --git a/AGENTS.md b/AGENTS.md
index b909a41..dc6fd75 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -396,6 +396,7 @@ interface BetterSidebarService {
 | **host 半无此服务** | `ctx.betterSidebar` 只在 client 侧存在；host 半需要 better-sidebar 数据走 `/sidebar/api/*` HTTP 路由 |
 | **portal 限制** | 整面板 slot 由 ui-layout 独占，外部 tab 只能进入 better-sidebar 的 portal 内部，无法全屏替换 |
 | **id 冲突** | `registerTab` / `registerFileViewer` 对重复 id 抛错；建议用包前缀（`my-plugin:xxx`） |
+| **懒加载 chunk** | 内置重依赖（Univer/xterm/CodeMirror/pptx/docx）在独立 bundle（`lib/client-<name>.js`）中，经 `/sidebar/bundle` 路由按需下发；每个脚本把 factory 赋到插件自有全局注册表 `globalThis.__dshChunks__[<name>]`，由 `src/client/chunk-loader.ts` 用自定义 require（externals 经 `__DSH_MODULES__` seed 分支解析）物化——**不经过** `__ModuleLoader__` 注册；**核心 bundle 禁止静态 import `src/client/chunks/*`**（会把库拖回启动路径）；对消费插件透明——懒加载只作用于内置 descriptor，`component` 契约（`(props) => ReactNode` 纯渲染函数）不变 |
 
 ---
 
diff --git a/README.md b/README.md
index db1e883..6a6a8c4 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,7 @@
 
 - **🗂️ 资源管理器**：懒加载目录树（根 = 会话 cwd）、点击在侧边栏打开、行尾 `@文件` 引用到输入框、右键复制路径
 - **📝 编辑与预览**：CodeMirror 6 多语言高亮 + Ctrl/Cmd+S 原子保存；图片 / Markdown（预览/编辑切换）/ HTML（沙箱 iframe 预览，相对资源可加载）/ PDF / Word / Excel / PPT 内联预览，切换 Tab 不丢草稿
+- **⚡ 客户端懒加载**：Office / 终端 / 代码编辑器等重依赖按需分块加载——启动只拉 ~325KB 核心，打开 .xlsx 才拉 Univer（~20MB）、打开 .docx 只拉 docx 预览器、打开终端才拉 xterm；首次打开短暂 loading 后即用（详见 `docs/plans/2026-08-12-lazy-chunks-design.md`）
 - **🌐 浏览器**：内嵌网页浏览 tab（多开），后退/前进/刷新 +「在浏览器中打开」；页面在**沙箱 iframe** 中运行（不透明源：无法访问界面数据与本地文件，拒绝 localhost 等本机地址），界面实时显示沙箱状态、可临时解锁（关闭时红色警示）；被站点拒绝嵌入（X-Frame-Options）时显示原因面板；聊天/界面里的 http(s) 外链默认在侧边栏打开
 - **💻 终端**：xterm.js + node-pty 真实 shell（每会话 3 个 UI 上限）、Tab 保活重连回放；可选为模型注入 8 个 `terminal_*` 工具
 - **🌿 Git 面板**：真 diff + VSCode 式 diff tab、懒加载历史、右键暂存/放弃/提交/还原/捡取
diff --git a/docs/plans/2026-08-12-lazy-chunks-design.md b/docs/plans/2026-08-12-lazy-chunks-design.md
new file mode 100644
index 0000000..0a81d9d
--- /dev/null
+++ b/docs/plans/2026-08-12-lazy-chunks-design.md
@@ -0,0 +1,88 @@
+# 客户端懒加载分块（lazy chunks）设计
+
+> 日期:2026-08-12
+> 状态:已实现
+> 范围:`dsh-better-sidebar` 插件,客户端 bundle 拆分
+
+## 1. 背景与问题
+
+改造前客户端是单文件 bundle(`lib/client.js`,约 24.6MB),页面启动时全部**下载 + 解析 + 执行**。实测构成(按 sourcemap 源字节):
+
+| 依赖 | 体积 | 用途 |
+|---|---|---|
+| `@univerjs/*` 全家桶 + echarts/zrender 等 | ~18MB | .xlsx 预览 |
+| `@codemirror/*` + `@lezer/*` | ~1.9MB | 文本编辑器高亮 |
+| `xlsx`(SheetJS) | ~0.6MB | .xlsx 解析 |
+| `@aiden0z/pptx-renderer` | ~0.5MB | .pptx 预览 |
+| `xterm` | ~0.3MB | 终端 |
+| `docx-preview` + `jszip` | ~0.2MB | .docx 预览 |
+| 插件自身代码 | ~0.35MB | — |
+
+虽然 `office-view.tsx` 用了动态 `import()`,但 `codeSplitting: false` 只保证**延迟执行**(`Promise.resolve().then(() => (init_docx_preview(), ...))`),下载与解析成本仍在启动时;且 `xlsx-to-univer.ts` 对 `@univerjs/presets` 的静态 value-import 让 Univer 核心实际在启动时执行。
+
+**目标**:重依赖拆成独立脚本,首次打开对应功能才下载/解析/执行;启动只拉核心(~325KB)。
+
+## 2. 机制
+
+chunk 脚本**不经过** `window.__ModuleLoader__` / `ClientModuleSystem.import()` 的物化路径——模块系统的 import() 只解析 seed word / shell-own 模块 / 已注册 factory / boot graph row,chunk id 四者皆非,解析行为依赖 DSH 版本(实测某些版本在 factory 已注册时仍抛 "cannot resolve")。因此改为插件自有的全局 factory 注册表:
+
+1. **构建期**:每个 chunk 是独立 tsdown 浏览器 bundle(`lib/client-<name>.js`),脚本首行为:
+   ```js
+   globalThis.__dshChunks__ = globalThis.__dshChunks__ || {};
+   globalThis.__dshChunks__["terminal"] = (require) => { /* CJS 闭包体 */ };
+   ```
+   与主 bundle 相同的 externals(react 等走 module table)、纯度门、CSS 内联管线;`codeSplitting: false` 保持单文件。
+2. **运行期** `loadChunk(name)`:
+   - 注入 `<script src="/sidebar/bundle/<name>.js">`(经典同源脚本;官方 `/plugins/<id>/client.js` 路由的路径白名单无法服务任意文件名,故走插件自有路由);
+   - 从 `globalThis.__dshChunks__[name]` 读取 factory(脚本执行即赋值,幂等——重复执行覆盖槽位,无 "duplicate factory registration" 错误类);
+   - 用**自定义 require** 物化:externals(CLIENT_EXTERNALS 清单)经 `__DSH_MODULES__.import(spec)` 的 **seed 分支**逐一解析(页面级记忆化;解析失败的 spec 标记未解析,仅当 chunk 实际 require 时才报错)——seed 分支是模块系统最稳定、跨版本一致的部分。
+
+## 3. 分块清单
+
+| chunk 名 | 入口 | 内容 | 构建产物 | 触发 |
+|---|---|---|---|---|
+| `xlsx` | `src/client/chunks/xlsx.tsx` | `XlsxView` + Univer 全家桶 + xlsx + Univer CSS | lib/client-xlsx.js(~20MB) | 打开 .xlsx |
+| `docx` | `src/client/chunks/docx.tsx` | `DocxView` + docx-preview + jszip | lib/client-docx.js(~330KB) | 打开 .docx |
+| `pptx` | `src/client/chunks/pptx.tsx` | `PptxView` + pptx-renderer | lib/client-pptx.js(~2.4MB) | 打开 .pptx |
+| `terminal` | `src/client/chunks/terminal.tsx` | `TerminalView` + xterm + addon-fit + xterm.css | lib/client-terminal.js(~450KB) | 打开终端 tab |
+| `editor` | `src/client/chunks/editor.tsx` | `TextEditor` + @codemirror/* + lang.ts + cm-themes | lib/client-editor.js(~1.6MB) | 打开 code/md/html 文件 |
+| 核心 | `src/client/index.tsx` | 其余全部 | lib/client.js(~325KB) | 启动 |
+
+关键拆分:**`office-view.tsx` 拆为 `docx-view.tsx` + `xlsx-view.tsx` + `office-shared.tsx`**(共享 `LoadState`/`BinaryFallback`)。若不拆,docx chunk 会经共享文件静态拖入 `xlsx-to-univer` → Univer 14.5MB。原路径 `office-view.tsx` 保留为 re-export 垫片,兼容 `./src/*` 深导入。
+
+## 4. 缓存契约(三层,各带失败路径)
+
+| 层 | 机制 | 失败路径 |
+|---|---|---|
+| 内存 | `loadChunk` 每 chunk 一个 in-flight promise,并发去重,常驻到 `resetChunks` | 失败删除缓存项 → 下次调用重试 |
+| 执行 | 脚本执行即覆盖全局注册表槽位(赋值幂等) | 物化失败清缓存 → 重试重新注入 + 重新执行脚本 |
+| HTTP | `/sidebar/bundle` 路由 `cache-control: no-cache` + ETag(内容哈希,按 mtime/size 记忆化),`If-None-Match` 命中返回 304 | 页面刷新/HMR 重激活时 304 免重下载 17MB;文件变化 ETag 轮转返回 200 |
+
+**HMR**:`apply()` 每次激活调用 `resetChunks()`(清内存缓存 + externals 记忆),热更新后重新拉取新代码。chunk 源码单独改动需手动刷新页面(HMR 轮询只盯 client.js)。
+
+## 5. 对外 API 兼容性(硬约束)
+
+- `ctx.betterSidebar` 服务方法签名与行为零变化;懒加载只作用于**内置** descriptor,外部插件注册的原样存储/渲染。
+- `component` 契约 `(props) => ReactNode` 保持:懒包装是**纯渲染函数**(函数体无 hooks,hooks 在内部 `LazyChunkView`),兼容 Sidebar 的函数式调用与 EditorHost 的 `createElement` 渲染两种风格。
+- 内置 viewer/tab 的 id、exts、priority、detect、icon、title、settings 全部不变 → `matchFileViewer` 语义、外部插件同扩展名高优先级覆盖、设置页清单不变。
+- 公开类型面(`./client/service`、`./client/api`)不变;无新增 peerDeps。
+- 契约测试:`tests/lazy-chunk.spec.tsx` 钉住"component 可直接函数调用不抛错"。
+
+## 6. 边界与失败模式
+
+- chunk 加载/执行/物化失败 → 视图级错误 + 重试 UI(`css.editorError` + `css.terminalRetry`),面板其余部分不受影响;
+- host 旧版本无 `/sidebar/bundle` 路由(404) → 同样的错误 + 重试,升级 host 后重试即可;
+- `window.__DSH_MODULES__` 缺失(异常环境) → 明确报错,不触网;
+- chunk 注册 id 恒定 `dsh-better-sidebar/<name>`,两渠道共用(每页只活一个渠道——双渠道并存本就双挂载,属既有破损组合);
+- 跨 chunk 复用:`t()`/`api.ts`/`SandboxStatusBar`/`clsx`/`sidebar.module.css` 等无状态小模块允许在各 chunk 内联(几十 KB 级重复),避免 chunk→主 bundle require 的脆弱耦合;
+- CSS:`sidebar.module.css` 的 tagId 与官方渠道核心一致 → 幂等跳过注入;registry 渠道会多注入一份同内容样式(数据标签差异,无功能影响);xterm.css/Univer.css 随各自 chunk 注入。
+
+## 7. 实施偏差记录
+
+- 原设想 React.lazy + Suspense 被否决:错误处理需 error boundary,重试语义差;改用有状态包装组件(loading/error/retry 三态),与本库"每个视图自带 loading/error/retry"风格一致。
+- 原设想 chunk 注册 id 按渠道区分(`__DSH_PLUGIN_ID__` define)被否决:chunk 文件两渠道共用,恒定槽位即可;避免重复构建 6 份产物。
+- `resetChunks` 同时清空测试注册表(测试隔离需要)。
+- `lazy-chunk.tsx` 内部渲染用 `ComponentType<any>` 状态成员规避 React 18 createElement 泛型重载限制(仅内部一处显式 any)。
+- **v2(运行时修复)**:最初实现经 `window.__ModuleLoader__.load({id})` 注册 chunk factory、再 `__DSH_MODULES__.import(id)` 物化——真实环境报 `client-modules: cannot resolve "dsh-better-sidebar/terminal"`(某 DSH 版本的 import() 不解析已注册的非 boot 图 id)。改为全局 factory 注册表(`globalThis.__dshChunks__`) + 自定义 externals require(seed 分支),彻底不依赖模块系统的 factory 解析行为;`resetChunks` 不再需要 invalidate。
+- **v3(运行时修复)**:terminal 懒包装把整个 `TabComponentProps` 原样透传,但 `TerminalView` 的 props 是 `{ scope, tabId, store }` 而 `TabComponentProps` 只有 `tab` 对象、没有 `tabId` → `tabId` 为 undefined → `isAgentTabId` 里 `undefined.startsWith` 崩溃(`dsh-better-sidebar: Cannot read properties of undefined (reading 'startsWith')`)。修复:descriptor 显式映射 `tabId={tab.id}`,懒包装的 props 泛型 = TerminalView 真实签名(`{ scope, tabId, store }`);回归测试钉住映射(lazy-chunk.spec.tsx)。**教训:懒包装的 props 泛型必须等于目标组件真实 props,而非描述符 props 全集**。
+- **v2 附加**:bundled 产物经真实 `ClientModuleSystem`(带真实 react seed)端到端验证——5 个 chunk 均能物化出真实 React 组件;产物契约由 `tests/chunk-artifact.spec.ts` 长期钉住(脚本执行赋值槽位 + factory 可被 externals require 物化)。
diff --git a/package.json b/package.json
index 502b684..743425f 100644
--- a/package.json
+++ b/package.json
@@ -47,6 +47,12 @@
     "lib/index.js",
     "lib/invariant.js",
     "lib/client.js",
+    "lib/client-registry.js",
+    "lib/client-docx.js",
+    "lib/client-xlsx.js",
+    "lib/client-pptx.js",
+    "lib/client-terminal.js",
+    "lib/client-editor.js",
     "lib/types/**/*.d.ts",
     "src"
   ],
diff --git a/scripts/package-registry.mjs b/scripts/package-registry.mjs
index b13bade..18f5862 100644
--- a/scripts/package-registry.mjs
+++ b/scripts/package-registry.mjs
@@ -29,6 +29,18 @@ const files = [
   'lib/invariant.js',
   'lib/client-registry.js',
   'lib/client-registry.js.map',
+  // Lazy chunks: the client fetches these from the host's /sidebar/bundle
+  // route on first use (see src/client/chunk-loader.ts / src/bundle-route.ts).
+  'lib/client-docx.js',
+  'lib/client-docx.js.map',
+  'lib/client-xlsx.js',
+  'lib/client-xlsx.js.map',
+  'lib/client-pptx.js',
+  'lib/client-pptx.js.map',
+  'lib/client-terminal.js',
+  'lib/client-terminal.js.map',
+  'lib/client-editor.js',
+  'lib/client-editor.js.map',
   'README.md',
   'LICENSE',
 ]
diff --git a/src/bundle-route.ts b/src/bundle-route.ts
new file mode 100644
index 0000000..16aab38
--- /dev/null
+++ b/src/bundle-route.ts
@@ -0,0 +1,130 @@
+/**
+ * Lazy chunk route: serves the client bundle's chunk scripts
+ * (/sidebar/bundle/<name>.js). The official /plugins/<id>/client.js route
+ * cannot serve arbitrary file names, so the plugin serves its own split
+ * bundles (lib/client-<name>.js) here; the client injects the script on
+ * first use of the feature that needs it (see src/client/chunk-loader.ts).
+ *
+ * Caching contract: every response carries `cache-control: no-cache` plus an
+ * ETag (content hash, memoized per file by mtime/size) and honors
+ * If-None-Match — the browser revalidates each fetch, but a 304 avoids
+ * re-downloading multi-MB chunks that did not change (page refresh, HMR
+ * re-activation). Same browser-trust fence as every other /sidebar route;
+ * only allowlisted chunk names are servable (no path traversal).
+ */
+import { createHash } from 'node:crypto'
+import { stat, readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { Context } from './context-types.ts'
+
+/** The chunk names the client may request (mirror of src/client/chunk-loader.ts). */
+export const CHUNK_NAMES = ['docx', 'xlsx', 'pptx', 'terminal', 'editor'] as const
+export type ChunkName = (typeof CHUNK_NAMES)[number]
+
+/** Directory of this host-half module (lib/ — the chunk scripts live next to it). */
+const LIB_DIR = dirname(fileURLToPath(import.meta.url))
+
+/** sha1 content hash shortened to 12 hex chars (same shape as the client-modules rev). */
+function shortHash(input: string | Buffer): string {
+  return createHash('sha1').update(input).digest('hex').slice(0, 12)
+}
+
+interface ChunkEtag {
+  mtimeMs: number
+  size: number
+  etag: string
+}
+
+/** ETag memo: recompute the content hash only when the file's stat changed. */
+const etags = new Map<string, ChunkEtag>()
+
+/**
+ * The chunk file's ETag (quoted hash), or undefined when the file is
+ * missing. Hash is recomputed only when mtime/size changed (hashing a
+ * multi-MB chunk per request is wasteful).
+ */
+async function etagOf(name: ChunkName, chunkDir: string): Promise<string | undefined> {
+  const path = join(chunkDir, `client-${name}.js`)
+  const key = `${chunkDir}:${name}`
+  try {
+    const info = await stat(path)
+    const memo = etags.get(key)
+    if (memo !== undefined && memo.mtimeMs === info.mtimeMs && memo.size === info.size) {
+      return memo.etag
+    }
+    const etag = `"${shortHash(await readFile(path))}"`
+    etags.set(key, { mtimeMs: info.mtimeMs, size: info.size, etag })
+    return etag
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Build the /sidebar/bundle route handler. `fence` is the shared browser-
+ * trust check every /sidebar route applies; `chunkDir` is the directory the
+ * chunk scripts live in (overridable for tests).
+ */
+export function createBundleRouteHandler(
+  fence: (req: IncomingMessage) => boolean,
+  chunkDir: string = LIB_DIR,
+): (req: IncomingMessage, res: ServerResponse) => Promise<void> {
+  return async (req, res): Promise<void> => {
+    if (!fence(req)) {
+      res.writeHead(403)
+      res.end('forbidden')
+      return
+    }
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+      res.writeHead(405)
+      res.end()
+      return
+    }
+    const pathname = new URL(req.url ?? '/', 'http://dsh.internal').pathname
+    const match = /^\/sidebar\/bundle\/([a-z0-9-]+)\.js$/.exec(pathname)
+    const name = match?.[1] as ChunkName | undefined
+    if (name === undefined || !(CHUNK_NAMES as readonly string[]).includes(name)) {
+      res.writeHead(404)
+      res.end('not found')
+      return
+    }
+    const etag = await etagOf(name, chunkDir)
+    if (etag === undefined) {
+      // Registered name but unreadable (bundle not built yet): loud 404.
+      res.writeHead(404)
+      res.end('not found')
+      return
+    }
+    if (req.headers['if-none-match'] === etag) {
+      // Revalidation hit: unchanged chunk, no body — avoids re-downloading
+      // multi-MB scripts on page refresh / HMR re-activation.
+      res.writeHead(304, { 'cache-control': 'no-cache', etag })
+      res.end()
+      return
+    }
+    try {
+      const body = await readFile(join(chunkDir, `client-${name}.js`))
+      res.writeHead(200, {
+        'content-type': 'text/javascript; charset=utf-8',
+        'cache-control': 'no-cache',
+        etag,
+      })
+      res.end(body)
+    } catch {
+      // Read raced a delete/rebuild between the stat and the read.
+      res.writeHead(404)
+      res.end('not found')
+    }
+  }
+}
+
+/** Register the /sidebar/bundle route (disposed with the fiber). */
+export function registerBundleRoute(ctx: Context, fence: (req: IncomingMessage) => boolean): () => void {
+  return ctx.httpServer.register({
+    kind: 'prefix',
+    path: '/sidebar/bundle',
+    handler: createBundleRouteHandler(fence),
+  })
+}
diff --git a/src/client/builtins/tabs.tsx b/src/client/builtins/tabs.tsx
index 36538fe..e778edb 100644
--- a/src/client/builtins/tabs.tsx
+++ b/src/client/builtins/tabs.tsx
@@ -13,14 +13,41 @@ import { t } from '../locales.ts'
 import { openSidebarFile } from '../intercept.tsx'
 import { ExplorerView } from '../ExplorerView.tsx'
 import { EditorHost } from '../EditorHost.tsx'
-import { TerminalView } from '../TerminalView.tsx'
+import { lazyChunkComponent } from '../lazy-chunk.tsx'
 import { GitView } from '../GitView.tsx'
 import { DiffTab } from '../DiffTab.tsx'
 import { SubagentView } from '../SubagentView.tsx'
 import { BrowserView } from '../BrowserView.tsx'
 import { IconTerminalOutline16, IconDiffOutline16, IconGlobeOutline16 } from '../icons.tsx'
+import type { ComponentType } from 'react'
+import type { SessionScope } from '../api.ts'
+import type { SidebarStore } from '../state.ts'
 import type { TabDescriptor } from '../service.ts'
 
+/**
+ * Lazy wrapper over the terminal view: xterm (and its stylesheet) is fetched
+ * only when a terminal tab is first opened (see chunk-loader.ts). The
+ * wrapper keeps the descriptor contract `(props) => ReactNode` — Sidebar
+ * calls it as a plain function.
+ *
+ * TerminalView's props are { scope, tabId, store } — `tabId` is NOT part of
+ * TabComponentProps (it carries `tab: SidebarTab` instead), so the
+ * descriptor maps it explicitly; a bare pass-through would leave tabId
+ * undefined and TerminalView's isAgentTabId(tabId) would crash on
+ * `undefined.startsWith` (regression-pinned in tests/lazy-chunk.spec.tsx).
+ */
+const LazyTerminal = lazyChunkComponent<TerminalViewProps>(
+  'terminal',
+  (mod) => mod.TerminalView as ComponentType<TerminalViewProps> | undefined,
+)
+
+/** The terminal view's props (mirror of TerminalView's own signature). */
+interface TerminalViewProps {
+  scope: SessionScope
+  tabId: string
+  store: SidebarStore
+}
+
 /** How many UI-owned terminals may be open at once (agent-owned ones are uncapped). */
 export const TERMINAL_LIMIT = 3
 
@@ -133,9 +160,7 @@ export function builtinTabs(ctx: Context): readonly TabDescriptor[] {
           patch: { nextTerminal: state.nextTerminal + 1 },
         }
       },
-      component: ({ scope, tab, store }) => (
-        <TerminalView scope={scope} tabId={tab.id} store={store} />
-      ),
+      component: ({ tab, scope, store }) => <LazyTerminal scope={scope} store={store} tabId={tab.id} />,
     },
     {
       id: 'browser',
diff --git a/src/client/builtins/viewers.tsx b/src/client/builtins/viewers.tsx
index 832b553..3ffd734 100644
--- a/src/client/builtins/viewers.tsx
+++ b/src/client/builtins/viewers.tsx
@@ -6,15 +6,21 @@
  * binaries and serves doc/xls/ppt by extension; `code` is the catch-all
  * (`exts: []`, lowest priority) that claims any file no other viewer did.
  *
+ * The heavy viewers (docx/xlsx/pptx and the CodeMirror-backed
+ * markdown/html/code) render through {@link lazyChunkComponent} wrappers —
+ * their libraries are fetched only when such a file is first opened (see
+ * chunk-loader.ts). The descriptor metadata (id/exts/priority/detect) is
+ * identical either way, so matching semantics and external-plugin
+ * overrides are unaffected; the `component` wrapper keeps the descriptor
+ * contract `(props) => ReactNode`.
+ *
  * Every viewer carries the declarative settings-surface fields — `title`
  * and `icon` — so the Side card settings page can render the enable/disable
  * inventory without hardcoding (eating our own dogfood).
  */
 import { IconCodeOutline16, IconDownloadOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
-import { DocxView, XlsxView } from '../office-view.tsx'
+import { lazyChunkComponent } from '../lazy-chunk.tsx'
 import { PdfView } from '../PdfView.tsx'
-import { PptxView } from '../PptxView.tsx'
-import { TextEditor } from '../TextEditor.tsx'
 import { BinaryDownload } from '../binary-download.tsx'
 import {
   IconImageOutline16,
@@ -25,10 +31,22 @@ import {
   IconPptxOutline16,
   IconHtmlOutline16,
 } from '../icons.tsx'
-import type { FileViewerDescriptor } from '../service.ts'
+import type { ComponentType } from 'react'
+import type { FileViewerDescriptor, FileViewerProps } from '../service.ts'
 import { t } from '../locales.ts'
 import css from '../sidebar.module.css'
 
+/**
+ * Lazy wrappers over the chunk-resident viewer components. The `pick`
+ * functions are module-level (stable identity — the wrapper effect depends
+ * on them); the cast bridges the chunk exports record to the descriptor
+ * prop shape (the views read only their own subset of FileViewerProps).
+ */
+const LazyDocx = lazyChunkComponent<FileViewerProps>('docx', (mod) => mod.DocxView as ComponentType<FileViewerProps> | undefined)
+const LazyXlsx = lazyChunkComponent<FileViewerProps>('xlsx', (mod) => mod.XlsxView as ComponentType<FileViewerProps> | undefined)
+const LazyPptx = lazyChunkComponent<FileViewerProps>('pptx', (mod) => mod.PptxView as ComponentType<FileViewerProps> | undefined)
+const LazyTextEditor = lazyChunkComponent<FileViewerProps>('editor', (mod) => mod.TextEditor as ComponentType<FileViewerProps> | undefined)
+
 /** The 9 built-in file viewer descriptors. */
 export function builtinViewers(): readonly FileViewerDescriptor[] {
   return [
@@ -60,9 +78,7 @@ export function builtinViewers(): readonly FileViewerDescriptor[] {
       icon: (size: number) => <IconDocxOutline16 size={size} />,
       exts: ['docx'],
       fetchStrategy: 'mediaUrl',
-      component: ({ scope, path, title }) => (
-        <DocxView scope={scope} path={path} title={title} />
-      ),
+      component: (props) => <LazyDocx {...props} />,
     },
     {
       id: 'xlsx',
@@ -70,9 +86,7 @@ export function builtinViewers(): readonly FileViewerDescriptor[] {
       icon: (size: number) => <IconXlsxOutline16 size={size} />,
       exts: ['xlsx'],
       fetchStrategy: 'mediaUrl',
-      component: ({ scope, path, title }) => (
-        <XlsxView scope={scope} path={path} title={title} />
-      ),
+      component: (props) => <LazyXlsx {...props} />,
     },
     {
       id: 'pptx',
@@ -80,9 +94,7 @@ export function builtinViewers(): readonly FileViewerDescriptor[] {
       icon: (size: number) => <IconPptxOutline16 size={size} />,
       exts: ['pptx'],
       fetchStrategy: 'mediaUrl',
-      component: ({ scope, path, title }) => (
-        <PptxView scope={scope} path={path} title={title} />
-      ),
+      component: (props) => <LazyPptx {...props} />,
     },
     {
       id: 'markdown',
@@ -90,7 +102,7 @@ export function builtinViewers(): readonly FileViewerDescriptor[] {
       icon: (size: number) => <IconMarkdownOutline16 size={size} />,
       exts: ['md', 'markdown'],
       fetchStrategy: 'fsRead',
-      component: (props) => <TextEditor {...props} />,
+      component: (props) => <LazyTextEditor {...props} />,
     },
     {
       id: 'html',
@@ -112,7 +124,7 @@ export function builtinViewers(): readonly FileViewerDescriptor[] {
           desc: () => t('settingsHtmlDefaultUnsafeDesc'),
         }],
       },
-      component: (props) => <TextEditor {...props} />,
+      component: (props) => <LazyTextEditor {...props} />,
     },
     {
       id: 'code',
@@ -121,7 +133,7 @@ export function builtinViewers(): readonly FileViewerDescriptor[] {
       exts: [],
       priority: -100,
       fetchStrategy: 'fsRead',
-      component: (props) => <TextEditor {...props} />,
+      component: (props) => <LazyTextEditor {...props} />,
     },
     {
       id: 'binary-download',
diff --git a/src/client/chunk-loader.ts b/src/client/chunk-loader.ts
new file mode 100644
index 0000000..30d974c
--- /dev/null
+++ b/src/client/chunk-loader.ts
@@ -0,0 +1,196 @@
+/**
+ * Lazy chunk loader for the client bundle. The heavy preview/terminal
+ * libraries (Univer, docx-preview, pptx-renderer, CodeMirror, xterm — the
+ * office/terminal/editor stacks, tens of MB) live in separate build-time
+ * bundles (`lib/client-<name>.js`) fetched only on first use of the feature
+ * that needs them, so startup downloads/parses only the ~1MB core bundle.
+ *
+ * How a chunk script works (see tsdown.config.ts chunkBundle):
+ *
+ *   globalThis.__dshChunks__ = globalThis.__dshChunks__ || {};
+ *   globalThis.__dshChunks__["terminal"] = (require) => { ...exports };
+ *
+ * The script registers its factory on a plugin-owned global registry (NOT
+ * through window.__ModuleLoader__.load — the module loader's import() only
+ * resolves seed words, shell-own modules, registered factories, and boot
+ * graph rows; a chunk id is none of those, so resolution would be version-
+ * dependent). Materialization is plugin-owned:
+ *
+ * 1. inject <script src="/sidebar/bundle/<name>.js"> (classic same-origin
+ *    script; the official /plugins/<id>/client.js route cannot serve
+ *    arbitrary file names, so the plugin's own host route serves the chunks),
+ * 2. read the factory from the global registry,
+ * 3. call it with a require that resolves the platform externals through
+ *    `__DSH_MODULES__.import(spec)` — the seed-word branch, the one part of
+ *    the module system that is stable across versions.
+ *
+ * Caching contract (three layers, each with a failure path):
+ * - In-memory: one in-flight promise per chunk, memoized until
+ *   {@link resetChunks}; a failed load removes its entry so the next call
+ *   retries from scratch.
+ * - Script execution: each re-execution overwrites the global registry slot
+ *   (assignment, never registration) — no "duplicate factory registration"
+ *   class of errors; a failed materialization clears the cache so the retry
+ *   re-injects and re-executes.
+ * - HTTP: the bundle route revalidates every request (`cache-control:
+ *   no-cache` + ETag, 304 when unchanged), so page refreshes and HMR
+ *   re-activations never re-download a multi-MB chunk that did not change.
+ *
+ * HMR: each plugin activation calls {@link resetChunks}, which drops the
+ * in-memory cache (and any test registry), so a hot-reloaded core bundle
+ * re-fetches and re-executes the current chunk scripts on the next lazy
+ * open. Chunk-only source edits still need a manual page refresh (the HMR
+ * poll watches only client.js).
+ */
+export type ChunkName = 'docx' | 'xlsx' | 'pptx' | 'terminal' | 'editor'
+
+/** The module exports a chunk factory provides (namespace-ish record). */
+export type ChunkExports = Record<string, unknown>
+
+/** A chunk factory: (require) => exports (the chunk's CJS closure shape). */
+type ChunkFactory = (require: (spec: string) => unknown) => ChunkExports
+
+/**
+ * The platform externals a chunk bundle may require (mirror of
+ * CLIENT_EXTERNALS in tsdown.config.ts — the chunk builds keep these
+ * external and the loader resolves them here). A superset is safe: the
+ * require only answers what the chunk actually asks for.
+ */
+export const CHUNK_EXTERNALS: readonly string[] = [
+  'react',
+  'react/jsx-runtime',
+  'react-dom',
+  'react-dom/client',
+  'cordis',
+  '@deepseek-ai/dsh-client-ui-slots',
+  '@deepseek-ai/dsh-client-web-react',
+  '@deepseek-ai/dsh-client-ui-primitives',
+  '@deepseek-ai/dsh-client-schema-form',
+  '@deepseek-ai/dsh-client-runtime/client',
+]
+
+/** Chunk script endpoint served by the plugin host half (src/bundle-route.ts). */
+const CHUNK_URL = (name: ChunkName): string => `/sidebar/bundle/${name}.js`
+
+/** The client module system surface this loader needs (window.__DSH_MODULES__). */
+interface ChunkModuleSystem {
+  import(specifier: string): Promise<unknown>
+}
+
+/** Resolve the shell-installed module system (set before any plugin activates). */
+function moduleSystem(): ChunkModuleSystem | undefined {
+  return (globalThis as { __DSH_MODULES__?: ChunkModuleSystem }).__DSH_MODULES__
+}
+
+/** The plugin-owned chunk factory registry the chunk scripts populate. */
+interface ChunkRegistry {
+  [name: string]: ChunkFactory | undefined
+}
+
+function chunkRegistry(): ChunkRegistry {
+  const g = globalThis as { __dshChunks__?: ChunkRegistry }
+  return g.__dshChunks__ ??= {}
+}
+
+/** Script-load hook; tests replace it with a stub (the default needs a real DOM + network). */
+export type ChunkScriptLoader = (src: string) => Promise<void>
+
+const defaultScriptLoader: ChunkScriptLoader = (src) => new Promise((resolve, reject) => {
+  const el = document.createElement('script')
+  el.async = true
+  el.src = src
+  el.addEventListener('load', () => {
+    el.remove()
+    resolve()
+  }, { once: true })
+  el.addEventListener('error', () => {
+    el.remove()
+    reject(new Error(`[dsh-better-sidebar] chunk script ${src} failed to load`))
+  }, { once: true })
+  document.head.append(el)
+})
+
+let scriptLoader: ChunkScriptLoader = defaultScriptLoader
+
+/** Test hook: replace the chunk-script loader (pass null to restore the default). */
+export function setChunkScriptLoaderForTests(loader: ChunkScriptLoader | null): void {
+  scriptLoader = loader ?? defaultScriptLoader
+}
+
+/** Test/dev hook: resolve a chunk without fetching a script (e.g. vitest). */
+const testLoaders = new Map<ChunkName, () => Promise<ChunkExports>>()
+export function registerChunkForTests(name: ChunkName, loader: () => Promise<ChunkExports>): void {
+  testLoaders.set(name, loader)
+}
+
+/** Memoized externals require, resolved once per page from the seed table. */
+let externalsRequire: ((spec: string) => unknown) | undefined
+
+async function buildExternalsRequire(modules: ChunkModuleSystem): Promise<(spec: string) => unknown> {
+  if (externalsRequire !== undefined) return externalsRequire
+  // Per-spec tolerance: a spec the running DSH version cannot resolve (e.g.
+  // the runtime/client exemption row) stays unresolved until a chunk
+  // actually requires it — only then it is a loud error.
+  const entries = await Promise.all(CHUNK_EXTERNALS.map(async (spec) => {
+    try {
+      return [spec, await modules.import(spec)] as const
+    } catch {
+      return [spec, undefined] as const
+    }
+  }))
+  const table = new Map<string, unknown>(entries)
+  externalsRequire = (spec: string): unknown => {
+    if (!table.has(spec)) {
+      // Single quotes: the bundle-consistency scan regexes for require("...")
+      // lexical calls — a double-quoted literal here would trip it.
+      throw new Error(`[dsh-better-sidebar] chunk require('${spec}') missed the module table`)
+    }
+    return table.get(spec)
+  }
+  return externalsRequire
+}
+
+/** In-flight/memoized chunk loads; a failure removes its entry so a retry re-fetches. */
+const cache = new Map<ChunkName, Promise<ChunkExports>>()
+
+/**
+ * Load (once) and materialize a lazy chunk, returning its module exports.
+ * Concurrent callers share one in-flight load; a failure clears the cache
+ * entry so the next call retries (the script re-executes and overwrites its
+ * global registry slot — assignments are idempotent).
+ * @param name - the chunk to load.
+ */
+export function loadChunk(name: ChunkName): Promise<ChunkExports> {
+  const cached = cache.get(name)
+  if (cached !== undefined) return cached
+  const task = (async (): Promise<ChunkExports> => {
+    const test = testLoaders.get(name)
+    if (test !== undefined) return test()
+    const modules = moduleSystem()
+    if (modules === undefined) {
+      throw new Error(`[dsh-better-sidebar] chunk "${name}": client module system unavailable`)
+    }
+    await scriptLoader(CHUNK_URL(name))
+    const factory = chunkRegistry()[name]
+    if (typeof factory !== 'function') {
+      throw new Error(`[dsh-better-sidebar] chunk "${name}" script did not register its factory`)
+    }
+    const require = await buildExternalsRequire(modules)
+    return factory(require)
+  })()
+  cache.set(name, task)
+  void task.catch(() => { cache.delete(name) })
+  return task
+}
+
+/**
+ * Drop all chunk state for a fresh plugin activation (HMR-safe): clear the
+ * in-memory cache and any test-registry entries, so the next lazy open
+ * re-fetches and re-executes the current chunk scripts (the registry slots
+ * are overwritten by the re-execution — no cleanup needed).
+ */
+export function resetChunks(): void {
+  cache.clear()
+  testLoaders.clear()
+  externalsRequire = undefined
+}
diff --git a/src/client/chunks/docx.tsx b/src/client/chunks/docx.tsx
new file mode 100644
index 0000000..9ccd57a
--- /dev/null
+++ b/src/client/chunks/docx.tsx
@@ -0,0 +1,8 @@
+/**
+ * Lazy chunk entry: the .docx preview (docx-preview + jszip). Built as
+ * `lib/client-docx.js` and registered under `dsh-better-sidebar/docx` —
+ * fetched only when a .docx is first opened (see chunk-loader.ts and
+ * docs/plans/2026-08-12-lazy-chunks-design.md). Never import this module
+ * from the core bundle: it pulls the office library into the startup path.
+ */
+export { DocxView } from '../docx-view.tsx'
diff --git a/src/client/chunks/editor.tsx b/src/client/chunks/editor.tsx
new file mode 100644
index 0000000..6c4324f
--- /dev/null
+++ b/src/client/chunks/editor.tsx
@@ -0,0 +1,9 @@
+/**
+ * Lazy chunk entry: the code/markdown/html text editor (CodeMirror 6 + the
+ * language packages). Built as `lib/client-editor.js` and registered under
+ * `dsh-better-sidebar/editor` — fetched only when a text file is first
+ * opened (see chunk-loader.ts and docs/plans/2026-08-12-lazy-chunks-design.md).
+ * Never import this module from the core bundle: it pulls CodeMirror into
+ * the startup path.
+ */
+export { TextEditor } from '../TextEditor.tsx'
diff --git a/src/client/chunks/pptx.tsx b/src/client/chunks/pptx.tsx
new file mode 100644
index 0000000..c908e1d
--- /dev/null
+++ b/src/client/chunks/pptx.tsx
@@ -0,0 +1,8 @@
+/**
+ * Lazy chunk entry: the .pptx preview (pptx-renderer). Built as
+ * `lib/client-pptx.js` and registered under `dsh-better-sidebar/pptx` —
+ * fetched only when a .pptx is first opened (see chunk-loader.ts and
+ * docs/plans/2026-08-12-lazy-chunks-design.md). Never import this module
+ * from the core bundle: it pulls the renderer into the startup path.
+ */
+export { PptxView } from '../PptxView.tsx'
diff --git a/src/client/chunks/terminal.tsx b/src/client/chunks/terminal.tsx
new file mode 100644
index 0000000..9e8f002
--- /dev/null
+++ b/src/client/chunks/terminal.tsx
@@ -0,0 +1,9 @@
+/**
+ * Lazy chunk entry: the interactive terminal (xterm + fit addon). Built as
+ * `lib/client-terminal.js` and registered under
+ * `dsh-better-sidebar/terminal` — fetched only when a terminal tab is first
+ * opened (see chunk-loader.ts and docs/plans/2026-08-12-lazy-chunks-design.md).
+ * Never import this module from the core bundle: it pulls xterm (and its
+ * stylesheet) into the startup path.
+ */
+export { TerminalView } from '../TerminalView.tsx'
diff --git a/src/client/chunks/xlsx.tsx b/src/client/chunks/xlsx.tsx
new file mode 100644
index 0000000..c990ad6
--- /dev/null
+++ b/src/client/chunks/xlsx.tsx
@@ -0,0 +1,9 @@
+/**
+ * Lazy chunk entry: the .xlsx preview (Univer family + SheetJS, several MB).
+ * Built as `lib/client-xlsx.js` and registered under
+ * `dsh-better-sidebar/xlsx` — fetched only when a .xlsx is first opened
+ * (see chunk-loader.ts and docs/plans/2026-08-12-lazy-chunks-design.md).
+ * Never import this module from the core bundle: it pulls Univer into the
+ * startup path.
+ */
+export { XlsxView } from '../xlsx-view.tsx'
diff --git a/src/client/docx-view.tsx b/src/client/docx-view.tsx
new file mode 100644
index 0000000..b9314e0
--- /dev/null
+++ b/src/client/docx-view.tsx
@@ -0,0 +1,113 @@
+/**
+ * The .docx preview component: renders via docx-preview (preserved
+ * styles/images/tables). Lives in its own module (split out of the former
+ * office-view.tsx) so it builds as a standalone lazy chunk
+ * (`lib/client-docx.js`) — the library is loaded only when a .docx is first
+ * opened, and never pulls in the Univer/xlsx stack.
+ *
+ * Errors degrade to the shared download-button affordance, so a corrupted /
+ * encrypted / oversized file always leaves the user with a way to get it.
+ */
+import { useEffect, useRef, useState } from 'react'
+import { mediaUrl } from './api.ts'
+import { t } from './locales.ts'
+import { BinaryFallback, type LoadState, type OfficeViewProps } from './office-shared.tsx'
+import css from './sidebar.module.css'
+
+/**
+ * Render a .docx file via docx-preview. The library renders into a container
+ * div (no canvas); images and styles are inlined. Unmounting clears the
+ * container's innerHTML — docx-preview has no dispose API, but tearing down
+ * the DOM is enough.
+ */
+export function DocxView(props: OfficeViewProps): JSX.Element {
+  const { scope, path, title } = props
+  const viewportRef = useRef<HTMLDivElement>(null)
+  const wrapRef = useRef<HTMLDivElement>(null)
+  const [load, setLoad] = useState<LoadState>({ status: 'loading' })
+  const [zoom, setZoom] = useState(100)
+
+  useEffect(() => {
+    let cancelled = false
+    const container = viewportRef.current
+    const wrap = wrapRef.current
+    if (container === null || wrap === null) return
+    setZoom(100)
+    void (async () => {
+      try {
+        const response = await fetch(mediaUrl(scope, path))
+        if (cancelled) return
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}`)
+        }
+        const buf = await response.arrayBuffer()
+        if (cancelled) return
+        // docx-preview ships its own CSS through the className option; the
+        // wrapper div scopes its render output.
+        const { renderAsync } = await import('docx-preview')
+        await renderAsync(buf, wrap, undefined, {
+          className: 'docx',
+          inWrapper: true,
+          ignoreWidth: false,
+          ignoreHeight: false,
+          breakPages: true,
+          experimental: false,
+        })
+        if (!cancelled) setLoad({ status: 'ready' })
+      } catch (error) {
+        if (!cancelled) {
+          setLoad({ status: 'error', message: error instanceof Error ? error.message : String(error) })
+        }
+      }
+    })()
+    return () => {
+      cancelled = true
+      // Tear down the rendered DOM so a reopen starts clean.
+      if (wrap !== null) wrap.innerHTML = ''
+    }
+  }, [scope.sessionId, scope.cwd, path])
+
+  useEffect(() => {
+    const viewport = viewportRef.current
+    if (viewport === null) return
+    const onWheel = (event: WheelEvent): void => {
+      if (!event.altKey) return
+      event.preventDefault()
+      const delta = event.deltaY < 0 ? 10 : -10
+      setZoom(current => Math.max(50, Math.min(200, current + delta)))
+    }
+    viewport.addEventListener('wheel', onWheel, { passive: false })
+    return () => { viewport.removeEventListener('wheel', onWheel) }
+  }, [])
+
+  return (
+    <div className={css.editorDocx}>
+      <div className={css.editorDocxViewport} ref={viewportRef}>
+        {load.status === 'loading' && <div className={css.editorPlaceholder}>{t('loading')}</div>}
+        {load.status === 'error' && <BinaryFallback scope={scope} path={path} message={load.message} />}
+        {load.status !== 'error' && (
+          <div
+            className={css.editorDocxWrap}
+            ref={wrapRef}
+            aria-label={title}
+            style={{ zoom: zoom / 100 }}
+          />
+        )}
+      </div>
+      <div className={css.editorDocxZoom}>
+        <span className={css.editorDocxZoomHint}>{t('zoomHint')}</span>
+        <input
+          className={css.editorDocxZoomRange}
+          type="range"
+          min={50}
+          max={200}
+          step={10}
+          value={zoom}
+          aria-label={t('zoom')}
+          onChange={(event) => { setZoom(Number(event.currentTarget.value)) }}
+        />
+        <span className={css.editorDocxZoomValue}>{zoom}%</span>
+      </div>
+    </div>
+  )
+}
diff --git a/src/client/index.tsx b/src/client/index.tsx
index 240d537..6d673be 100644
--- a/src/client/index.tsx
+++ b/src/client/index.tsx
@@ -13,6 +13,7 @@ import { createRoot, type Root } from 'react-dom/client'
 import type { Context } from '../context-types.ts'
 import { createSidebarStore } from './state.ts'
 import { createBetterSidebarService } from './service.ts'
+import { resetChunks } from './chunk-loader.ts'
 import { registerBuiltins } from './builtins/index.ts'
 import { Sidebar } from './Sidebar.tsx'
 import { registerOpenPathInterception, registerTurnTailInterception } from './intercept.tsx'
@@ -103,6 +104,10 @@ export function apply(ctx: Context): void {
     }
   }
   try {
+    // Fresh chunk state for this activation: invalidate any chunk factories
+    // registered by a previous fiber (HMR) and drop the in-memory load cache
+    // so the next lazy open re-fetches the current chunk scripts.
+    resetChunks()
     ctx.effect(() => {
       let disposed = false
       let root: Root | undefined
diff --git a/src/client/lazy-chunk.tsx b/src/client/lazy-chunk.tsx
new file mode 100644
index 0000000..b8ce62a
--- /dev/null
+++ b/src/client/lazy-chunk.tsx
@@ -0,0 +1,89 @@
+/**
+ * Lazy chunk view wrapper: mounts a component that lives in a lazy chunk,
+ * showing a loading placeholder while the chunk script loads and an error +
+ * retry affordance on failure. Used by the built-in tab/viewer descriptors.
+ *
+ * Contract note: {@link lazyChunkComponent} returns a plain render-prop
+ * function — the descriptor contract is `component: (props) => ReactNode`,
+ * and the repo renders descriptors BOTH ways: Sidebar calls
+ * `descriptor.component(props)` directly, EditorHost renders it via
+ * `createElement`. The wrapper function body therefore contains no hooks;
+ * all state lives in the inner {@link LazyChunkView} component.
+ */
+import { createElement, useEffect, useState, type ComponentType, type ReactNode } from 'react'
+import { loadChunk, type ChunkExports, type ChunkName } from './chunk-loader.ts'
+import { t } from './locales.ts'
+import css from './sidebar.module.css'
+
+interface LazyChunkViewProps<P> {
+  chunk: ChunkName
+  /** Module-level-stable selector (an inline lambda would re-trigger the effect). */
+  pick: (mod: ChunkExports) => ComponentType<P> | undefined
+  props: P
+}
+
+function LazyChunkView<P>({ chunk, pick, props }: LazyChunkViewProps<P>): ReactNode {
+  const [attempt, setAttempt] = useState(0)
+  const [state, setState] = useState<
+    | { status: 'loading' }
+    | { status: 'error'; message: string }
+    | { status: 'ready'; Comp: ComponentType<any> }
+  >({ status: 'loading' })
+
+  useEffect(() => {
+    let cancelled = false
+    setState({ status: 'loading' })
+    loadChunk(chunk).then((mod) => {
+      if (cancelled) return
+      const Comp = pick(mod)
+      if (Comp === undefined) {
+        setState({ status: 'error', message: `[dsh-better-sidebar] chunk "${chunk}" is missing its component` })
+        return
+      }
+      setState({ status: 'ready', Comp })
+    }).catch((error: unknown) => {
+      if (cancelled) return
+      setState({ status: 'error', message: error instanceof Error ? error.message : String(error) })
+    })
+    return () => { cancelled = true }
+  }, [chunk, pick, attempt])
+
+  if (state.status === 'loading') {
+    return <div className={css.editorPlaceholder}>{t('loading')}</div>
+  }
+  if (state.status === 'error') {
+    return (
+      <div className={css.editorError}>
+        <span>{state.message}</span>
+        <button
+          type="button"
+          className={css.terminalRetry}
+          onClick={() => { setAttempt(current => current + 1) }}
+        >
+          {t('terminalRetry')}
+        </button>
+      </div>
+    )
+  }
+  return createElement(state.Comp, props)
+}
+
+/**
+ * Build a descriptor-compatible lazy wrapper for a chunk-resident component.
+ * The returned function is the descriptor `component` itself: it returns an
+ * element and never calls hooks, so both invocation styles (plain function
+ * call and createElement/JSX render) work. `pick` must be a module-level
+ * function (stable identity) — an inline lambda would re-trigger the load
+ * effect on every render.
+ * @param chunk - the chunk name (see chunk-loader.ts).
+ * @param pick - select the component from the chunk's exports.
+ */
+export function lazyChunkComponent<P extends object>(
+  chunk: ChunkName,
+  pick: (mod: ChunkExports) => ComponentType<P> | undefined,
+): (props: P) => ReactNode {
+  return (props: P) => createElement(
+    LazyChunkView as ComponentType<LazyChunkViewProps<P>>,
+    { chunk, pick, props },
+  )
+}
diff --git a/src/client/office-shared.tsx b/src/client/office-shared.tsx
new file mode 100644
index 0000000..3cd0e43
--- /dev/null
+++ b/src/client/office-shared.tsx
@@ -0,0 +1,40 @@
+/**
+ * Shared pieces of the Office preview views (docx / xlsx): the load-state
+ * union, the shared props, and the download fallback. The two views live in
+ * their own modules (docx-view.tsx / xlsx-view.tsx) so the bundler can emit
+ * them as separate lazy chunks — docx-preview and the Univer family (several
+ * MB) must never share a script (see docs/plans/2026-08-12-lazy-chunks-design.md).
+ */
+import { downloadUrl, type SessionScope } from './api.ts'
+import { t } from './locales.ts'
+import css from './sidebar.module.css'
+
+/** Loading / ready / error state shared by both views. */
+export type LoadState =
+  | { status: 'loading' }
+  | { status: 'ready' }
+  | { status: 'error'; message: string }
+
+/** Shared props. */
+export interface OfficeViewProps {
+  scope: SessionScope
+  path: string
+  title: string
+}
+
+/**
+ * The shared error / fallback affordance: the failure reason plus a download
+ * link, so the user always has a path to the file. Used by both DocxView and
+ * XlsxView, and matches the binary placeholder download link.
+ */
+export function BinaryFallback(props: { scope: SessionScope; path: string; message: string }): JSX.Element {
+  const { scope, path, message } = props
+  return (
+    <div className={css.editorBinary}>
+      <span className={css.editorBinaryNotice}>{message}</span>
+      <a className={css.editorDownloadLink} href={downloadUrl(scope, path)} download>
+        {t('downloadToView')}
+      </a>
+    </div>
+  )
+}
diff --git a/src/client/office-view.tsx b/src/client/office-view.tsx
index 3766aa0..559d042 100644
--- a/src/client/office-view.tsx
+++ b/src/client/office-view.tsx
@@ -1,249 +1,12 @@
 /**
- * Office preview components: {@link DocxView} renders .docx via docx-preview
- * (preserved styles/images/tables), {@link XlsxView} renders .xlsx via the
- * Univer sheets preset (data + formulas + formatting). Both load the file
- * bytes through the existing /sidebar/file media route and own their library
- * lifecycle (dispose on unmount so canvases/workers don't leak — mirrors the
- * TerminalView dispose discipline).
- *
- * Errors degrade to the same download-button affordance the binary
- * placeholder uses, so a corrupted / encrypted / oversized file always
- * leaves the user with a way to get the file.
- *
- * Both libraries pull in several MB; tsdown's `codeSplitting: false` inlines
- * them into the single client bundle (the CJS __ModuleLoader__ wrapper's
- * `require` cannot load relative chunk URLs in the browser, so dynamic
- * import() collapses to a synchronous inline — see tsdown.config.ts).
+ * Compat re-export shim for the historical `src/client/office-view.tsx`
+ * path. The office preview views were split into docx-view.tsx /
+ * xlsx-view.tsx (+ office-shared.tsx) so the bundler can emit each library
+ * as its own lazy chunk (see docs/plans/2026-08-12-lazy-chunks-design.md).
+ * This module keeps deep imports of this path resolvable through the
+ * `./src/*` exports subpath — it deliberately re-exports BOTH views, so it
+ * must never be imported from the core bundle or a chunk entry (it would
+ * drag both libraries into that bundle).
  */
-import { useEffect, useRef, useState } from 'react'
-import { downloadUrl, mediaUrl, type SessionScope } from './api.ts'
-import { t } from './locales.ts'
-import { xlsxWorkbookToUniver } from './xlsx-to-univer.ts'
-import css from './sidebar.module.css'
-// Univer's stylesheets ride the same dsh-css-inline pipeline as xterm's CSS
-// (one <style data-plugin-css> tag, idempotent). Static import so the styles
-// are present before the first .xlsx opens.
-import '@univerjs/preset-sheets-core/lib/index.css'
-
-/** Loading / ready / error state shared by both views. */
-type LoadState =
-  | { status: 'loading' }
-  | { status: 'ready' }
-  | { status: 'error'; message: string }
-
-/** Shared props. */
-interface OfficeViewProps {
-  scope: SessionScope
-  path: string
-  title: string
-}
-
-/**
- * Render a .docx file via docx-preview. The library renders into a container
- * div (no canvas); images and styles are inlined. Unmounting clears the
- * container's innerHTML — docx-preview has no dispose API, but tearing down
- * the DOM is enough.
- */
-export function DocxView(props: OfficeViewProps): JSX.Element {
-  const { scope, path, title } = props
-  const viewportRef = useRef<HTMLDivElement>(null)
-  const wrapRef = useRef<HTMLDivElement>(null)
-  const [load, setLoad] = useState<LoadState>({ status: 'loading' })
-  const [zoom, setZoom] = useState(100)
-
-  useEffect(() => {
-    let cancelled = false
-    const container = viewportRef.current
-    const wrap = wrapRef.current
-    if (container === null || wrap === null) return
-    setZoom(100)
-    void (async () => {
-      try {
-        const response = await fetch(mediaUrl(scope, path))
-        if (cancelled) return
-        if (!response.ok) {
-          throw new Error(`HTTP ${response.status}`)
-        }
-        const buf = await response.arrayBuffer()
-        if (cancelled) return
-        // docx-preview ships its own CSS through the className option; the
-        // wrapper div scopes its render output.
-        const { renderAsync } = await import('docx-preview')
-        await renderAsync(buf, wrap, undefined, {
-          className: 'docx',
-          inWrapper: true,
-          ignoreWidth: false,
-          ignoreHeight: false,
-          breakPages: true,
-          experimental: false,
-        })
-        if (!cancelled) setLoad({ status: 'ready' })
-      } catch (error) {
-        if (!cancelled) {
-          setLoad({ status: 'error', message: error instanceof Error ? error.message : String(error) })
-        }
-      }
-    })()
-    return () => {
-      cancelled = true
-      // Tear down the rendered DOM so a reopen starts clean.
-      if (wrap !== null) wrap.innerHTML = ''
-    }
-  }, [scope.sessionId, scope.cwd, path])
-
-  useEffect(() => {
-    const viewport = viewportRef.current
-    if (viewport === null) return
-    const onWheel = (event: WheelEvent): void => {
-      if (!event.altKey) return
-      event.preventDefault()
-      const delta = event.deltaY < 0 ? 10 : -10
-      setZoom(current => Math.max(50, Math.min(200, current + delta)))
-    }
-    viewport.addEventListener('wheel', onWheel, { passive: false })
-    return () => { viewport.removeEventListener('wheel', onWheel) }
-  }, [])
-
-  return (
-    <div className={css.editorDocx}>
-      <div className={css.editorDocxViewport} ref={viewportRef}>
-        {load.status === 'loading' && <div className={css.editorPlaceholder}>{t('loading')}</div>}
-        {load.status === 'error' && <BinaryFallback scope={scope} path={path} message={load.message} />}
-        {load.status !== 'error' && (
-          <div
-            className={css.editorDocxWrap}
-            ref={wrapRef}
-            aria-label={title}
-            style={{ zoom: zoom / 100 }}
-          />
-        )}
-      </div>
-      <div className={css.editorDocxZoom}>
-        <span className={css.editorDocxZoomHint}>{t('zoomHint')}</span>
-        <input
-          className={css.editorDocxZoomRange}
-          type="range"
-          min={50}
-          max={200}
-          step={10}
-          value={zoom}
-          aria-label={t('zoom')}
-          onChange={(event) => { setZoom(Number(event.currentTarget.value)) }}
-        />
-        <span className={css.editorDocxZoomValue}>{zoom}%</span>
-      </div>
-    </div>
-  )
-}
-
-/**
- * Render a .xlsx file via Univer. The sheets preset creates a canvas-based
- * spreadsheet (formula bar, sheet tabs, formula engine) sized to its
- * container, so the host fills the pane. Unmounting calls `univer.dispose()`
- * — without it the canvas, workers, and DOM listeners leak (mirrors the
- * xterm dispose discipline in TerminalView).
- */
-export function XlsxView(props: OfficeViewProps): JSX.Element {
-  const { scope, path, title } = props
-  const hostRef = useRef<HTMLDivElement>(null)
-  const univerRef = useRef<{ dispose: () => void } | null>(null)
-  const [load, setLoad] = useState<LoadState>({ status: 'loading' })
-
-  useEffect(() => {
-    let cancelled = false
-    const host = hostRef.current
-    if (host === null) return
-    void (async () => {
-      try {
-        const response = await fetch(mediaUrl(scope, path))
-        if (cancelled) return
-        if (!response.ok) {
-          throw new Error(`HTTP ${response.status}`)
-        }
-        const buf = await response.arrayBuffer()
-        if (cancelled) return
-
-        // Dynamic imports — collapsed into the bundle by codeSplitting:false.
-        // The dynamic form keeps the source readable: each lib is only pulled
-        // in when an .xlsx is actually opened (semantically; the bundle still
-        // contains all of them).
-        const XLSX = await import('xlsx')
-        const { createUniver, LocaleType, mergeLocales } = await import('@univerjs/presets')
-        const { UniverSheetsCorePreset } = await import('@univerjs/preset-sheets-core')
-        // Locales pick the browser language; falls back to en-US.
-        const isZh = typeof navigator !== 'undefined' && navigator.language.toLowerCase().startsWith('zh')
-        const localePack = await (isZh
-          ? import('@univerjs/preset-sheets-core/locales/zh-CN').then(m => m.default).catch(() => null)
-          : import('@univerjs/preset-sheets-core/locales/en-US').then(m => m.default).catch(() => null))
-
-        const wb = XLSX.read(buf, { type: 'array' })
-        const locale = isZh ? LocaleType.ZH_CN : LocaleType.EN_US
-        const workbookData = xlsxWorkbookToUniver(wb, '0.25.1', locale)
-
-        if (cancelled) return
-        const { univer, univerAPI } = createUniver({
-          locale,
-          locales: localePack !== null ? { [locale]: mergeLocales(localePack) } : {},
-          presets: [UniverSheetsCorePreset({ container: host })],
-        })
-        univerRef.current = univer
-        univerAPI.createWorkbook(workbookData)
-        if (!cancelled) setLoad({ status: 'ready' })
-      } catch (error) {
-        if (!cancelled) {
-          try {
-            univerRef.current?.dispose()
-          } catch {
-            // Partially initialized instance — ignore disposal errors.
-          }
-          univerRef.current = null
-          host.innerHTML = ''
-          setLoad({ status: 'error', message: error instanceof Error ? error.message : String(error) })
-        }
-      }
-    })()
-    return () => {
-      cancelled = true
-      // Critical: dispose the Univer instance (canvas + workers + listeners).
-      try {
-        univerRef.current?.dispose()
-      } catch {
-        // Already torn down — ignore.
-      }
-      univerRef.current = null
-      // Clear the host in case dispose left DOM behind.
-      if (host !== null) host.innerHTML = ''
-    }
-  }, [scope.sessionId, scope.cwd, path])
-
-  return (
-    <div className={css.editorXlsx} aria-label={title}>
-      {/* Univer exclusively owns this element's descendants. React only owns
-          the sibling overlay, so Univer cannot remove a React child. */}
-      <div className={css.editorUniverHost} ref={hostRef} />
-      {load.status !== 'ready' && (
-        <div className={css.editorOfficeOverlay}>
-          {load.status === 'loading' && <div className={css.editorPlaceholder}>{t('loading')}</div>}
-          {load.status === 'error' && <BinaryFallback scope={scope} path={path} message={load.message} />}
-        </div>
-      )}
-    </div>
-  )
-}
-
-/**
- * The shared error / fallback affordance: the failure reason plus a download
- * link, so the user always has a path to the file. Used by both DocxView and
- * XlsxView, and matches the binary placeholder download link.
- */
-function BinaryFallback(props: { scope: SessionScope; path: string; message: string }): JSX.Element {
-  const { scope, path, message } = props
-  return (
-    <div className={css.editorBinary}>
-      <span className={css.editorBinaryNotice}>{message}</span>
-      <a className={css.editorDownloadLink} href={downloadUrl(scope, path)} download>
-        {t('downloadToView')}
-      </a>
-    </div>
-  )
-}
+export { DocxView } from './docx-view.tsx'
+export { XlsxView } from './xlsx-view.tsx'
diff --git a/src/client/xlsx-view.tsx b/src/client/xlsx-view.tsx
new file mode 100644
index 0000000..7977f2d
--- /dev/null
+++ b/src/client/xlsx-view.tsx
@@ -0,0 +1,116 @@
+/**
+ * The .xlsx preview component: renders via the Univer sheets preset (data +
+ * formulas + formatting). Lives in its own module (split out of the former
+ * office-view.tsx) so it builds as a standalone lazy chunk
+ * (`lib/client-xlsx.js`) — the Univer family and SheetJS pull in several MB
+ * but are loaded only when a .xlsx is first opened. The docx stack never
+ * shares this script.
+ *
+ * Errors degrade to the shared download-button affordance, so a corrupted /
+ * encrypted / oversized file always leaves the user with a way to get it.
+ */
+import { useEffect, useRef, useState } from 'react'
+import { mediaUrl } from './api.ts'
+import { t } from './locales.ts'
+import { BinaryFallback, type LoadState, type OfficeViewProps } from './office-shared.tsx'
+import { xlsxWorkbookToUniver } from './xlsx-to-univer.ts'
+import css from './sidebar.module.css'
+// Univer's stylesheets ride the same dsh-css-inline pipeline as xterm's CSS
+// (one <style data-plugin-css> tag, idempotent). Static import so the styles
+// are present before the first .xlsx opens.
+import '@univerjs/preset-sheets-core/lib/index.css'
+
+/**
+ * Render a .xlsx file via Univer. The sheets preset creates a canvas-based
+ * spreadsheet (formula bar, sheet tabs, formula engine) sized to its
+ * container, so the host fills the pane. Unmounting calls `univer.dispose()`
+ * — without it the canvas, workers, and DOM listeners leak (mirrors the
+ * xterm dispose discipline in TerminalView).
+ */
+export function XlsxView(props: OfficeViewProps): JSX.Element {
+  const { scope, path, title } = props
+  const hostRef = useRef<HTMLDivElement>(null)
+  const univerRef = useRef<{ dispose: () => void } | null>(null)
+  const [load, setLoad] = useState<LoadState>({ status: 'loading' })
+
+  useEffect(() => {
+    let cancelled = false
+    const host = hostRef.current
+    if (host === null) return
+    void (async () => {
+      try {
+        const response = await fetch(mediaUrl(scope, path))
+        if (cancelled) return
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}`)
+        }
+        const buf = await response.arrayBuffer()
+        if (cancelled) return
+
+        // Dynamic imports — collapsed into the chunk by codeSplitting:false.
+        // The dynamic form keeps the source readable: each lib is only pulled
+        // in when an .xlsx is actually opened (semantically; the chunk still
+        // contains all of them — the chunk itself only loads on first .xlsx).
+        const XLSX = await import('xlsx')
+        const { createUniver, LocaleType, mergeLocales } = await import('@univerjs/presets')
+        const { UniverSheetsCorePreset } = await import('@univerjs/preset-sheets-core')
+        // Locales pick the browser language; falls back to en-US.
+        const isZh = typeof navigator !== 'undefined' && navigator.language.toLowerCase().startsWith('zh')
+        const localePack = await (isZh
+          ? import('@univerjs/preset-sheets-core/locales/zh-CN').then(m => m.default).catch(() => null)
+          : import('@univerjs/preset-sheets-core/locales/en-US').then(m => m.default).catch(() => null))
+
+        const wb = XLSX.read(buf, { type: 'array' })
+        const locale = isZh ? LocaleType.ZH_CN : LocaleType.EN_US
+        const workbookData = xlsxWorkbookToUniver(wb, '0.25.1', locale)
+
+        if (cancelled) return
+        const { univer, univerAPI } = createUniver({
+          locale,
+          locales: localePack !== null ? { [locale]: mergeLocales(localePack) } : {},
+          presets: [UniverSheetsCorePreset({ container: host })],
+        })
+        univerRef.current = univer
+        univerAPI.createWorkbook(workbookData)
+        if (!cancelled) setLoad({ status: 'ready' })
+      } catch (error) {
+        if (!cancelled) {
+          try {
+            univerRef.current?.dispose()
+          } catch {
+            // Partially initialized instance — ignore disposal errors.
+          }
+          univerRef.current = null
+          host.innerHTML = ''
+          setLoad({ status: 'error', message: error instanceof Error ? error.message : String(error) })
+        }
+      }
+    })()
+    return () => {
+      cancelled = true
+      // Critical: dispose the Univer instance (canvas + workers + listeners).
+      try {
+        univerRef.current?.dispose()
+      } catch {
+        // Already torn down — ignore.
+      }
+      univerRef.current = null
+      // Clear the host in case dispose left DOM behind.
+      if (host !== null) host.innerHTML = ''
+    }
+  }, [scope.sessionId, scope.cwd, path])
+
+  return (
+    <div className={css.editorXlsx} aria-label={title}>
+      {/* Univer exclusively owns this element's descendants. React only owns
+          the sibling overlay, so Univer cannot remove a React child. */}
+      <div className={css.editorUniverHost} ref={hostRef} />
+      {load.status !== 'ready' && (
+        <div className={css.editorOfficeOverlay}>
+          {load.status === 'loading' && <div className={css.editorPlaceholder}>{t('loading')}</div>}
+          {load.status === 'error' && <BinaryFallback scope={scope} path={path} message={load.message} />}
+        </div>
+      )}
+    </div>
+  )
+}
diff --git a/src/index.ts b/src/index.ts
index f3b318a..4b919dd 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,11 +1,12 @@
 /**
  * dsh-better-sidebar host half: the /sidebar JSON API (explorer listing, file
- * read/write, git), the /sidebar/file media route (images), and the terminal
- * WebSocket upgrade. Every route passes the same browser-trust fence as the
- * /api gateway — Host-header loopback or the connection row's `trustedHosts`
- * (the `dsh web` launcher derives LAN IP literals per boot) — with the
- * trustedHosts read live from the connection loader row so the fence never
- * drifts from the deployment's.
+ * read/write, git), the /sidebar/file media route (images), the /sidebar/html
+ * preview route, the /sidebar/bundle lazy-chunk route (client code splits),
+ * and the terminal WebSocket upgrade. Every route passes the same
+ * browser-trust fence as the /api gateway — Host-header loopback or the
+ * connection row's `trustedHosts` (the `dsh web` launcher derives LAN IP
+ * literals per boot) — with the trustedHosts read live from the connection
+ * loader row so the fence never drifts from the deployment's.
  *
  * All operations are conversation-scoped: requests carry a sessionId, the
  * session's authoritative cwd comes from the session store, and terminal
@@ -29,6 +30,7 @@ import { isWithin, parentOf, requireAbsolute, listDirectory, rootLabel } from '.
 import { decodeHtmlUrl } from './html-route.ts'
 import { extractFrameAncestors } from './browser-probe.ts'
 import { isTrustedApiRequest, isLoopbackHostname } from './trust-fence.ts'
+import { registerBundleRoute } from './bundle-route.ts'
 import * as git from './git.ts'
 import { SettingsConflictError, settingsNamespace, type SettingsNamespace } from '@deepseek-ai/dsh-settings'
 import { defaultShell, ensureSpawnHelper, PtyManager } from './pty-manager.ts'
@@ -517,6 +519,12 @@ export function apply(ctx: Context, config?: SidebarConfig): void {
     },
   }), 'dsh-better-sidebar: /sidebar/api routes')
 
+  // ── Lazy chunk route (client bundle splits) ─────────────────────────────
+  // Serves the client half's split bundles (lib/client-<name>.js) so the
+  // heavy preview/terminal libraries load on first use, not at page start
+  // (see bundle-route.ts / src/client/chunk-loader.ts).
+  ctx.effect(() => registerBundleRoute(ctx, fence), 'dsh-better-sidebar: /sidebar/bundle chunk route')
+
   // ── Media route (images for the editor) ─────────────────────────────────
   ctx.effect(() => ctx.httpServer.register({
     kind: 'prefix',
diff --git a/tests/browser-globals.ts b/tests/browser-globals.ts
index 3380ce8..a7aae4a 100644
--- a/tests/browser-globals.ts
+++ b/tests/browser-globals.ts
@@ -12,6 +12,8 @@ if (g.self === undefined) g.self = globalThis
 
 const elementStub = (): Record<string, unknown> => ({
   style: {},
+  dataset: {},
+  textContent: '',
   classList: { add: () => {}, remove: () => {}, contains: () => false },
   setAttribute: () => {},
   getAttribute: () => null,
@@ -32,9 +34,12 @@ if (g.document === undefined) {
     removeEventListener: () => {},
     defaultView: globalThis,
     body: elementStub(),
-    // CodeMirror's view module probes the UA and injects styles at load.
+    // CodeMirror's view module probes the UA and injects styles at load;
+    // the plugin's css-inline prologue probes for existing style tags.
     documentElement: elementStub(),
     head: elementStub(),
+    querySelector: () => null,
+    querySelectorAll: () => [],
     styleSheets: [],
   }
 }
diff --git a/tests/bundle-route.spec.ts b/tests/bundle-route.spec.ts
new file mode 100644
index 0000000..5bf0322
--- /dev/null
+++ b/tests/bundle-route.spec.ts
@@ -0,0 +1,148 @@
+/**
+ * Lazy chunk route tests (src/bundle-route.ts): the /sidebar/bundle handler
+ * that serves the client's split bundles. Pins the trust fence, the name
+ * allowlist (no traversal), method gating, and the caching contract — ETag
+ * + If-None-Match 304 so multi-MB chunks revalidate cheaply instead of
+ * re-downloading.
+ */
+import { describe, expect, it } from 'vitest'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { CHUNK_NAMES, createBundleRouteHandler } from '../src/bundle-route.ts'
+
+interface FakeRes {
+  status: number
+  headers: Record<string, string>
+  body: string
+  writeHead(status: number, headers?: Record<string, string>): void
+  end(body?: string | Buffer): void
+}
+
+function fakeRes(): FakeRes {
+  return {
+    status: 0,
+    headers: {},
+    body: '',
+    writeHead(status, headers = {}) {
+      this.status = status
+      this.headers = headers
+    },
+    end(body) {
+      if (body !== undefined) this.body = body.toString()
+    },
+  } as FakeRes
+}
+
+function req(method: string, url: string, headers: Record<string, string> = {}): IncomingMessage {
+  return { method, url, headers } as unknown as IncomingMessage
+}
+
+/** One handler instance over a scratch dir with a fake chunk file. */
+function setup(): { handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>; dir: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), 'bundle-route-'))
+  writeFileSync(join(dir, 'client-xlsx.js'), 'window.__ModuleLoader__ && 0;')
+  const handler = createBundleRouteHandler(() => true, dir)
+  return { handler, dir, cleanup: () => { rmSync(dir, { recursive: true, force: true }) } }
+}
+
+describe('/sidebar/bundle route', () => {
+  it('serves an allowlisted chunk with the JS content type and an ETag', async () => {
+    const { handler, cleanup } = setup()
+    try {
+      const res = fakeRes()
+      await handler(req('GET', '/sidebar/bundle/xlsx.js'), res as unknown as ServerResponse)
+      expect(res.status).toBe(200)
+      expect(res.headers['content-type']).toBe('text/javascript; charset=utf-8')
+      expect(res.headers['cache-control']).toBe('no-cache')
+      expect(res.headers.etag).toMatch(/^"[0-9a-f]{12}"$/)
+      expect(res.body).toContain('window.__ModuleLoader__')
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('revalidates with a 304 when If-None-Match matches (no re-download)', async () => {
+    const { handler, cleanup } = setup()
+    try {
+      const first = fakeRes()
+      await handler(req('GET', '/sidebar/bundle/xlsx.js'), first as unknown as ServerResponse)
+      const etag = first.headers.etag!
+      const second = fakeRes()
+      await handler(req('GET', '/sidebar/bundle/xlsx.js', { 'if-none-match': etag }), second as unknown as ServerResponse)
+      expect(second.status).toBe(304)
+      expect(second.body).toBe('')
+      expect(second.headers.etag).toBe(etag)
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('serves the new body after the file changed (ETag rotates)', async () => {
+    const { handler, dir, cleanup } = setup()
+    try {
+      const first = fakeRes()
+      await handler(req('GET', '/sidebar/bundle/xlsx.js'), first as unknown as ServerResponse)
+      writeFileSync(join(dir, 'client-xlsx.js'), 'window.__ModuleLoader__ && 1;')
+      const second = fakeRes()
+      await handler(req('GET', '/sidebar/bundle/xlsx.js', { 'if-none-match': first.headers.etag! }), second as unknown as ServerResponse)
+      expect(second.status).toBe(200)
+      expect(second.headers.etag).not.toBe(first.headers.etag)
+      expect(second.body).toContain('&& 1')
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('rejects unknown chunk names (including traversal attempts) with 404', async () => {
+    const { handler, cleanup } = setup()
+    try {
+      for (const url of ['/sidebar/bundle/evil.js', '/sidebar/bundle/xlsx', '/sidebar/bundle/../secret.js', '/sidebar/bundle/xlsx.js/extra']) {
+        const res = fakeRes()
+        await handler(req('GET', url), res as unknown as ServerResponse)
+        expect(res.status, url).toBe(404)
+      }
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('404s an allowlisted name whose built file is missing', async () => {
+    const { handler, cleanup } = setup()
+    try {
+      const res = fakeRes()
+      await handler(req('GET', '/sidebar/bundle/editor.js'), res as unknown as ServerResponse)
+      expect(res.status).toBe(404)
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('gates non-GET/HEAD methods with 405', async () => {
+    const { handler, cleanup } = setup()
+    try {
+      const res = fakeRes()
+      await handler(req('POST', '/sidebar/bundle/xlsx.js'), res as unknown as ServerResponse)
+      expect(res.status).toBe(405)
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('enforces the browser-trust fence with 403 before any lookup', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'bundle-route-fence-'))
+    try {
+      const handler = createBundleRouteHandler(() => false, dir)
+      const res = fakeRes()
+      await handler(req('GET', '/sidebar/bundle/xlsx.js'), res as unknown as ServerResponse)
+      expect(res.status).toBe(403)
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('exports the chunk allowlist (mirror of src/client/chunk-loader.ts)', () => {
+    expect([...CHUNK_NAMES]).toEqual(['docx', 'xlsx', 'pptx', 'terminal', 'editor'])
+  })
+})
diff --git a/tests/chunk-artifact.spec.ts b/tests/chunk-artifact.spec.ts
new file mode 100644
index 0000000..8ebdf26
--- /dev/null
+++ b/tests/chunk-artifact.spec.ts
@@ -0,0 +1,43 @@
+/**
+ * Built chunk artifact contract: each lib/client-<name>.js must, when
+ * executed as a classic script, assign its factory to the plugin-owned
+ * global registry (globalThis.__dshChunks__[<name>]), and the factory must
+ * be callable with a require that resolves the platform externals — the
+ * exact shape the loader (src/client/chunk-loader.ts) depends on. Reads the
+ * built lib/ output, so run `pnpm build` first (like manifest-consistency).
+ */
+import { readFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+// Browser globals first: chunk bodies probe `self`/`document` at evaluation
+// (xterm's UMD wrapper, CodeMirror's UA probe).
+import './browser-globals.ts'
+import { CHUNK_EXTERNALS } from '../src/client/chunk-loader.ts'
+
+const g = globalThis as Record<string, unknown>
+
+const CHUNKS = ['docx', 'xlsx', 'pptx', 'terminal', 'editor']
+
+describe('built chunk artifacts', () => {
+  it('each chunk assigns its global registry slot when executed as a script', () => {
+    g.window = g // classic-script globals
+    for (const name of CHUNKS) {
+      const code = readFileSync(`lib/client-${name}.js`, 'utf8')
+      // eslint-disable-next-line no-new-func
+      expect(() => new Function(code)(), name).not.toThrow()
+      const registry = g.__dshChunks__ as Record<string, unknown>
+      expect(typeof registry[name], name).toBe('function')
+    }
+  })
+
+  it('each chunk factory materializes through a require over the platform externals', () => {
+    const registry = g.__dshChunks__ as Record<string, unknown>
+    const table = new Map<string, unknown>(CHUNK_EXTERNALS.map(spec => [spec, { spec }]))
+    for (const name of CHUNKS) {
+      const factory = registry[name] as (require: (spec: string) => unknown) => Record<string, unknown>
+      expect(() => factory((spec) => {
+        if (!table.has(spec)) throw new Error(`require("${spec}") missed the module table`)
+        return table.get(spec)
+      }), name).not.toThrow()
+    }
+  })
+})
diff --git a/tests/chunk-loader.spec.ts b/tests/chunk-loader.spec.ts
new file mode 100644
index 0000000..e1c416b
--- /dev/null
+++ b/tests/chunk-loader.spec.ts
@@ -0,0 +1,210 @@
+/**
+ * Chunk loader tests: the lazy chunk machinery (src/client/chunk-loader.ts).
+ * Pins the caching contract that makes the lazy mechanism correct:
+ * - one in-flight promise per chunk (concurrent opens share it),
+ * - a failed load clears the cache so the next call retries (the script
+ *   re-executes and overwrites its global registry slot — assignments are
+ *   idempotent, no duplicate-registration class of errors),
+ * - externals resolve through the module system's seed branch (the stable,
+ *   version-independent part), once per page,
+ * - resetChunks drops the cache and the externals memo (HMR).
+ * The production path runs against a fake `window.__DSH_MODULES__` and a
+ * stub script loader that simulates the executed chunk script by assigning
+ * the plugin-owned global factory registry.
+ */
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import './browser-globals.ts'
+import {
+  CHUNK_EXTERNALS,
+  loadChunk,
+  registerChunkForTests,
+  resetChunks,
+  setChunkScriptLoaderForTests,
+} from '../src/client/chunk-loader.ts'
+import type { ChunkExports } from '../src/client/chunk-loader.ts'
+
+interface FakeModuleSystem {
+  import: ReturnType<typeof vi.fn>
+}
+
+function installModuleSystem(): FakeModuleSystem {
+  const fake: FakeModuleSystem = {
+    import: vi.fn(async (specifier: string) => ({ seed: specifier })),
+  }
+  ;(globalThis as Record<string, unknown>).__DSH_MODULES__ = fake
+  return fake
+}
+
+function removeModuleSystem(): void {
+  delete (globalThis as Record<string, unknown>).__DSH_MODULES__
+}
+
+/** The global registry the chunk scripts populate (mirror of chunk-loader). */
+function registry(): Record<string, unknown> {
+  return (globalThis as { __dshChunks__?: Record<string, unknown> }).__dshChunks__ ?? {}
+}
+
+/** Simulate a chunk script executing: it assigns its factory to the registry. */
+function simulateScript(name: string, factory: (require: (spec: string) => unknown) => ChunkExports): void {
+  const g = globalThis as { __dshChunks__?: Record<string, unknown> }
+  g.__dshChunks__ = g.__dshChunks__ ?? {}
+  g.__dshChunks__[name] = factory
+}
+
+beforeEach(() => {
+  removeModuleSystem()
+  delete (globalThis as Record<string, unknown>).__dshChunks__
+  resetChunks()
+  setChunkScriptLoaderForTests(null)
+})
+
+describe('test-registry path (vitest / jsdom-less environments)', () => {
+  it('returns the registered chunk exports, loading once even for concurrent callers', async () => {
+    let calls = 0
+    registerChunkForTests('docx', async () => {
+      calls += 1
+      return { DocxView: 'docx-view' }
+    })
+    const [a, b, c] = await Promise.all([loadChunk('docx'), loadChunk('docx'), loadChunk('docx')])
+    expect(a).toEqual({ DocxView: 'docx-view' })
+    expect(b).toBe(a)
+    expect(c).toBe(a)
+    expect(calls).toBe(1)
+    // Memoized after resolution too.
+    expect(await loadChunk('docx')).toBe(a)
+    expect(calls).toBe(1)
+  })
+
+  it('a failed load clears the cache so the next call retries', async () => {
+    let calls = 0
+    registerChunkForTests('pptx', async () => {
+      calls += 1
+      if (calls === 1) throw new Error('boom')
+      return { PptxView: 'pptx-view' }
+    })
+    await expect(loadChunk('pptx')).rejects.toThrow('boom')
+    await expect(loadChunk('pptx')).resolves.toEqual({ PptxView: 'pptx-view' })
+    expect(calls).toBe(2)
+  })
+})
+
+describe('production path (script injection + global registry + externals require)', () => {
+  it('injects the chunk script, then materializes the factory with externals from the module table', async () => {
+    const modules = installModuleSystem()
+    const loaded: string[] = []
+    setChunkScriptLoaderForTests(async (src) => {
+      loaded.push(src)
+      simulateScript('xlsx', (require) => ({ XlsxView: `view:${String(require('react'))}` }))
+    })
+    const exports = await loadChunk('xlsx')
+    expect(loaded).toEqual(['/sidebar/bundle/xlsx.js'])
+    expect(exports).toEqual({ XlsxView: 'view:[object Object]' })
+    // Externals resolved through the module system's seed branch, once.
+    expect(modules.import).toHaveBeenCalledTimes(CHUNK_EXTERNALS.length)
+    // Memoized: no second script injection, no second externals resolution.
+    await loadChunk('xlsx')
+    expect(loaded).toHaveLength(1)
+    expect(modules.import).toHaveBeenCalledTimes(CHUNK_EXTERNALS.length)
+  })
+
+  it('resolves the externals table once across chunks', async () => {
+    const modules = installModuleSystem()
+    const seen: string[] = []
+    setChunkScriptLoaderForTests(async (src) => {
+      seen.push(src)
+      simulateScript(src.endsWith('editor.js') ? 'editor' : 'terminal', () => ({}))
+    })
+    await loadChunk('terminal')
+    await loadChunk('editor')
+    expect(seen).toEqual(['/sidebar/bundle/terminal.js', '/sidebar/bundle/editor.js'])
+    expect(modules.import).toHaveBeenCalledTimes(CHUNK_EXTERNALS.length)
+  })
+
+  it('a chunk requiring an unresolvable externals spec fails loudly', async () => {
+    installModuleSystem()
+    setChunkScriptLoaderForTests(async () => {
+      simulateScript('docx', (require) => { require('not-in-the-table'); return {} })
+    })
+    await expect(loadChunk('docx')).rejects.toThrow('missed the module table')
+  })
+
+  it('a script load failure rejects without materializing', async () => {
+    const modules = installModuleSystem()
+    setChunkScriptLoaderForTests(async () => { throw new Error('script 404') })
+    await expect(loadChunk('terminal')).rejects.toThrow('script 404')
+    expect(modules.import).not.toHaveBeenCalled()
+    // Cache cleared: the retry re-attempts the script load.
+    setChunkScriptLoaderForTests(async () => { simulateScript('terminal', () => ({ TerminalView: 'ok' })) })
+    await expect(loadChunk('terminal')).resolves.toEqual({ TerminalView: 'ok' })
+  })
+
+  it('a script that ran but registered no factory fails with a clear error', async () => {
+    installModuleSystem()
+    setChunkScriptLoaderForTests(async () => { /* executes but assigns nothing */ })
+    await expect(loadChunk('editor')).rejects.toThrow('did not register its factory')
+  })
+
+  it('a materialization failure clears the cache; the retry re-executes cleanly (idempotent slot assignment)', async () => {
+    const modules = installModuleSystem()
+    let calls = 0
+    setChunkScriptLoaderForTests(async () => {
+      calls += 1
+      simulateScript('pptx', () => {
+        if (calls === 1) throw new Error('materialize boom')
+        return { PptxView: 'pptx-view' }
+      })
+    })
+    await expect(loadChunk('pptx')).rejects.toThrow('materialize boom')
+    // Retry: script re-injected, slot overwritten, materialization succeeds.
+    await expect(loadChunk('pptx')).resolves.toEqual({ PptxView: 'pptx-view' })
+    expect(calls).toBe(2)
+    expect(modules.import).toHaveBeenCalled()
+  })
+
+  it('fails loudly when no module system is installed (before touching the network)', async () => {
+    const loaded: string[] = []
+    setChunkScriptLoaderForTests(async (src) => { loaded.push(src) })
+    await expect(loadChunk('docx')).rejects.toThrow('client module system unavailable')
+    expect(loaded).toEqual([])
+  })
+
+  it('resetChunks drops the cache and the externals memo (HMR re-activation)', async () => {
+    const modules = installModuleSystem()
+    let calls = 0
+    setChunkScriptLoaderForTests(async () => {
+      calls += 1
+      simulateScript('editor', () => ({ TextEditor: 'editor-view' }))
+    })
+    await loadChunk('editor')
+    expect(calls).toBe(1)
+    expect(modules.import).toHaveBeenCalledTimes(CHUNK_EXTERNALS.length)
+    resetChunks()
+    // Cache dropped: the next open re-fetches and re-executes; the externals
+    // memo is rebuilt (fresh module-table resolution).
+    await loadChunk('editor')
+    expect(calls).toBe(2)
+    expect(modules.import).toHaveBeenCalledTimes(CHUNK_EXTERNALS.length * 2)
+  })
+
+  it('resetChunks is a safe no-op without a module system', () => {
+    resetChunks()
+    expect(() => resetChunks()).not.toThrow()
+  })
+})
+
+describe('externals contract', () => {
+  it('the loader resolves exactly the platform externals the chunk builds keep external', () => {
+    expect(CHUNK_EXTERNALS).toEqual([
+      'react',
+      'react/jsx-runtime',
+      'react-dom',
+      'react-dom/client',
+      'cordis',
+      '@deepseek-ai/dsh-client-ui-slots',
+      '@deepseek-ai/dsh-client-web-react',
+      '@deepseek-ai/dsh-client-ui-primitives',
+      '@deepseek-ai/dsh-client-schema-form',
+      '@deepseek-ai/dsh-client-runtime/client',
+    ])
+  })
+})
diff --git a/tests/lazy-chunk.spec.tsx b/tests/lazy-chunk.spec.tsx
new file mode 100644
index 0000000..bc631fb
--- /dev/null
+++ b/tests/lazy-chunk.spec.tsx
@@ -0,0 +1,194 @@
+/**
+ * Lazy wrapper tests (src/client/lazy-chunk.tsx): the wrapper that mounts
+ * chunk-resident components from the built-in descriptors. Pins the two
+ * contracts that matter for the descriptor API:
+ * - the wrapper is a plain render-prop function — `component(props)` can be
+ *   called directly (Sidebar's style) without a chunk registered and
+ *   without throwing; hooks live in the inner component only,
+ * - loading → placeholder, failure → error + retry that recovers, success →
+ *   the chunk component rendered.
+ */
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { createElement, type ComponentType, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { act } from 'react-dom/test-utils'
+import { builtinTabs } from '../src/client/builtins/tabs.tsx'
+import { builtinViewers } from '../src/client/builtins/viewers.tsx'
+import { registerChunkForTests, resetChunks } from '../src/client/chunk-loader.ts'
+import { lazyChunkComponent } from '../src/client/lazy-chunk.tsx'
+import type { Context } from '../src/context-types.ts'
+import type { FileViewerProps, TabComponentProps } from '../src/client/service.ts'
+import css from '../src/client/sidebar.module.css'
+
+/** Render `node` into a detached body container under React's act(). */
+function mount(node: ReactNode): { container: HTMLDivElement; unmount: () => void } {
+  const container = document.createElement('div')
+  document.body.append(container)
+  const root: Root = createRoot(container)
+  // act() flushes the (concurrent) initial commit — the placeholder must be
+  // in the DOM before the async load flushes below.
+  act(() => { root.render(node) })
+  const unmount = (): void => {
+    act(() => { root.unmount() })
+    container.remove()
+  }
+  return { container, unmount }
+}
+
+const Marker = (): ReactNode => createElement('div', { 'data-testid': 'chunk-rendered' }, 'loaded')
+
+beforeEach(() => {
+  resetChunks()
+})
+
+afterEach(() => {
+  // Defensive: drop any containers left by failed assertions.
+  for (const el of document.querySelectorAll('body > div')) el.remove()
+})
+
+describe('lazyChunkComponent', () => {
+  it('renders the loading placeholder first, then the chunk component', async () => {
+    let calls = 0
+    registerChunkForTests('editor', async () => {
+      calls += 1
+      return { TextEditor: Marker }
+    })
+    const Wrapper = lazyChunkComponent<{ label: string }>('editor', (mod) => mod.TextEditor as ComponentType<{ label: string }> | undefined)
+    const { container, unmount } = mount(createElement(Wrapper, { label: 'x' }))
+    // Initial paint: the loading placeholder (no chunk loaded yet).
+    expect(container.querySelector(`.${css.editorPlaceholder}`)).not.toBeNull()
+    await act(async () => {})
+    expect(container.querySelector('[data-testid="chunk-rendered"]')).not.toBeNull()
+    expect(container.textContent).toContain('loaded')
+    expect(calls).toBe(1)
+    unmount()
+  })
+
+  it('shows the failure reason with a retry that recovers', async () => {
+    let fail = true
+    registerChunkForTests('docx', async () => {
+      if (fail) throw new Error('boom')
+      return { DocxView: Marker }
+    })
+    const Wrapper = lazyChunkComponent<Record<string, never>>('docx', (mod) => mod.DocxView as ComponentType<Record<string, never>> | undefined)
+    const { container, unmount } = mount(createElement(Wrapper, {}))
+    await act(async () => {})
+    expect(container.textContent).toContain('boom')
+    // The failed load cleared the loader cache; retry now succeeds.
+    fail = false
+    const button = container.querySelector('button')
+    expect(button).not.toBeNull()
+    await act(async () => { button!.click() })
+    await act(async () => {})
+    expect(container.querySelector('[data-testid="chunk-rendered"]')).not.toBeNull()
+    unmount()
+  })
+
+  it('props flow through to the chunk component', async () => {
+    const Recorder = (props: { label: string }): ReactNode => createElement('div', { 'data-testid': 'rec', 'data-label': props.label })
+    registerChunkForTests('pptx', async () => ({ PptxView: Recorder }))
+    const Wrapper = lazyChunkComponent<{ label: string }>('pptx', (mod) => mod.PptxView as ComponentType<{ label: string }> | undefined)
+    const { container, unmount } = mount(createElement(Wrapper, { label: 'hello' }))
+    await act(async () => {})
+    expect(container.querySelector('[data-testid="rec"]')?.getAttribute('data-label')).toBe('hello')
+    unmount()
+  })
+})
+
+describe('built-in descriptor contract (render-prop functions)', () => {
+  it('every heavy built-in viewer component is callable as a plain function without a chunk (returns an element)', () => {
+    const viewers = builtinViewers()
+    for (const id of ['docx', 'xlsx', 'pptx', 'markdown', 'html', 'code']) {
+      const descriptor = viewers.find(viewer => viewer.id === id)
+      expect(descriptor, id).toBeDefined()
+      // No chunk registered: calling must not throw — it returns the lazy
+      // element (the loading placeholder renders once mounted).
+      expect(() => descriptor!.component({} as FileViewerProps), id).not.toThrow()
+    }
+  })
+
+  it('the terminal tab component keeps the same contract', () => {
+    const tabs = builtinTabs({} as Context)
+    const terminal = tabs.find(tab => tab.id === 'terminal')
+    expect(terminal).toBeDefined()
+    // The descriptor reads tab.id (the tabId mapping); a real tab is part of
+    // the contract — Sidebar always provides one.
+    const props = { tab: { id: 'terminal:1', type: 'terminal', title: '终端 1' } } as unknown as TabComponentProps
+    expect(() => terminal!.component(props)).not.toThrow()
+  })
+
+  it('a built-in viewer mounted without a chunk available degrades to the error + retry affordance (no crash)', async () => {
+    // No test chunk registered and jsdom has no client module system: the
+    // load fails and the wrapper must degrade gracefully, never throw.
+    const viewers = builtinViewers()
+    const code = viewers.find(viewer => viewer.id === 'code')!
+    const { container, unmount } = mount(createElement(code.component, {} as FileViewerProps))
+    await act(async () => {})
+    expect(container.querySelector(`.${css.editorError}`)).not.toBeNull()
+    expect(container.querySelector('button')).not.toBeNull()
+    unmount()
+  })
+
+  it('a registered chunk makes the built-in viewer render through the real descriptor path', async () => {
+    registerChunkForTests('editor', async () => ({ TextEditor: Marker }))
+    const viewers = builtinViewers()
+    const markdown = viewers.find(viewer => viewer.id === 'markdown')!
+    // EditorHost renders viewer components via createElement(component, props).
+    const { container, unmount } = mount(createElement(markdown.component, {
+      ctx: {},
+      store: undefined,
+      scope: { sessionId: 's1', cwd: '/p' },
+      path: '/p/a.md',
+      title: 'a.md',
+      viewerId: 'markdown',
+    } as unknown as FileViewerProps))
+    await act(async () => {})
+    expect(container.querySelector('[data-testid="chunk-rendered"]')).not.toBeNull()
+    unmount()
+  })
+
+  it('the terminal descriptor maps tab.id → tabId (TerminalView props are not TabComponentProps)', async () => {
+    let received: unknown
+    registerChunkForTests('terminal', async () => ({
+      TerminalView: ((props: { tabId: string }) => {
+        received = props.tabId
+        return createElement('div', { 'data-testid': 'terminal-tabid' }, props.tabId)
+      }) as unknown as ComponentType<Record<string, never>>,
+    }))
+    const tabs = builtinTabs({} as Context)
+    const terminal = tabs.find(tab => tab.id === 'terminal')!
+    const props = {
+      ctx: {},
+      store: undefined,
+      scope: { sessionId: 's1', cwd: '/p' },
+      tab: { id: 'terminal:2', type: 'terminal', title: '终端 2' },
+      visible: true,
+    } as unknown as TabComponentProps
+    const { container, unmount } = mount(createElement(terminal.component, props))
+    await act(async () => {})
+    expect(container.querySelector('[data-testid="terminal-tabid"]')?.textContent).toBe('terminal:2')
+    expect(received).toBe('terminal:2')
+    unmount()
+  })
+
+  it('the loader cache survives across descriptor mounts (chunk fetched once)', async () => {
+    let calls = 0
+    registerChunkForTests('terminal', async () => {
+      calls += 1
+      return { TerminalView: Marker }
+    })
+    const tabs = builtinTabs({} as Context)
+    const terminal = tabs.find(tab => tab.id === 'terminal')!
+    const props = { tab: { id: 'terminal:1', type: 'terminal', title: '终端 1' } } as unknown as TabComponentProps
+    const { container: first, unmount: unmountFirst } = mount(createElement(terminal.component, props))
+    await act(async () => {})
+    expect(first.querySelector('[data-testid="chunk-rendered"]')).not.toBeNull()
+    unmountFirst()
+    const { container: second, unmount: unmountSecond } = mount(createElement(terminal.component, props))
+    await act(async () => {})
+    expect(second.querySelector('[data-testid="chunk-rendered"]')).not.toBeNull()
+    unmountSecond()
+    expect(calls).toBe(1)
+  })
+})
diff --git a/tests/manifest-consistency.spec.ts b/tests/manifest-consistency.spec.ts
index da33771..bf101c1 100644
--- a/tests/manifest-consistency.spec.ts
+++ b/tests/manifest-consistency.spec.ts
@@ -64,6 +64,17 @@ function bundleId(file: string): string {
   return match[1]!
 }
 
+/** The lazy chunk bundle names (mirror of src/bundle-route.ts CHUNK_NAMES). */
+const CHUNK_FILES = ['docx', 'xlsx', 'pptx', 'terminal', 'editor'].map(name => `lib/client-${name}.js`)
+
+/** The global registry slot a built chunk script assigns (its factory key). */
+function chunkSlot(file: string): string {
+  const source = readFileSync(resolve(ROOT, file), 'utf8')
+  const match = /globalThis\.__dshChunks__\["([a-z0-9-]+)"\]/.exec(source)
+  if (match === null) throw new Error(`${file} assigns no globalThis.__dshChunks__ slot — run \`pnpm build\` first`)
+  return match[1]!
+}
+
 describe('registry manifest consistency (dsh.plugin.json)', () => {
   it('id is a valid two-segment registry id (native form)', () => {
     expect(manifest.id).toMatch(ID_PATTERN)
@@ -86,13 +97,20 @@ describe('registry manifest consistency (dsh.plugin.json)', () => {
     expect(registryId).not.toBe(pkg.name)
   })
 
+  it('the lazy chunk bundles exist and assign their global registry slots (served by /sidebar/bundle)', () => {
+    for (const file of CHUNK_FILES) {
+      expect(existsSync(resolve(ROOT, file)), file).toBe(true)
+      expect(chunkSlot(file), file).toBe(file.slice('lib/client-'.length, -'.js'.length))
+    }
+  })
+
   it('client bundles require only frozen module-table entries', () => {
-    for (const file of ['lib/client.js', manifest.client!.main!]) {
+    for (const file of ['lib/client.js', manifest.client!.main!, ...CHUNK_FILES]) {
       const source = readFileSync(resolve(ROOT, file), 'utf8')
       // Exclude method calls such as `freeModule.require("util")`; only the
       // loader factory's lexical require() is constrained by the module table.
       const required = [...source.matchAll(/(^|[^.$\w])require\("([^"]+)"\)/gm)].map(match => match[2]!)
-      expect([...new Set(required)].filter(id => !CLIENT_REQUIRE_ALLOWED.has(id))).toEqual([])
+      expect([...new Set(required)].filter(id => !CLIENT_REQUIRE_ALLOWED.has(id)), file).toEqual([])
     }
   })
 
diff --git a/tests/smoke.spec.ts b/tests/smoke.spec.ts
index 4480df7..2b8ed93 100644
--- a/tests/smoke.spec.ts
+++ b/tests/smoke.spec.ts
@@ -58,7 +58,7 @@ describe('host plugin smoke', () => {
       inject: () => () => {},
     }
     apply(ctx as never)
-    expect(routes.map(route => route.path)).toEqual(['/sidebar/api', '/sidebar/file', '/sidebar/html'])
+    expect(routes.map(route => route.path)).toEqual(['/sidebar/api', '/sidebar/bundle', '/sidebar/file', '/sidebar/html'])
     expect(upgrades.map(route => route.path)).toEqual(['/sidebar/ws/terminal', '/sidebar/ws/agent-terminals'])
     // Teardown runs without throwing (pty manager has nothing open).
     for (const cleanup of effects) cleanup()
diff --git a/tsdown.config.ts b/tsdown.config.ts
index 40798e2..95a65df 100644
--- a/tsdown.config.ts
+++ b/tsdown.config.ts
@@ -27,6 +27,17 @@
  * - each artifact registers itself via window.__ModuleLoader__.load({id,
  *   factory}) with the (require) => exports CJS closure shape.
  *
+ * Lazy chunks (lib/client-<name>.js): the heavy preview/terminal libraries
+ * (Univer, docx-preview, pptx-renderer, CodeMirror, xterm — tens of MB)
+ * build as five standalone chunk bundles (src/client/chunks/<name>.tsx),
+ * shared by both channels. Each script assigns its factory to the
+ * plugin-owned global registry (globalThis.__dshChunks__) and is fetched by
+ * the client on first use from the plugin's own /sidebar/bundle route —
+ * chunks deliberately do NOT go through the module loader (see
+ * src/client/chunk-loader.ts). `codeSplitting: false` keeps every chunk a
+ * single script; the core client.js must never statically import a chunks/
+ * entry.
+ *
  * Types ship from lib/types (tsc -p tsconfig.build.json), not from tsdown.
  */
 import { readFile } from 'node:fs/promises'
@@ -155,71 +166,7 @@ function clientBundle(pluginId: string, entryFile: string): UserConfig {
     },
     // External wins for module-table entries; every other dependency inlines.
     noExternal: (id: string) => (CLIENT_EXTERNALS.includes(id) ? undefined : true),
-    plugins: [{
-      // Bundle purity gate (mirror of the official preset): platform seed
-      // entries stay external, inline-safe wire layers inline, and every
-      // other @deepseek-ai value import is a build error — a cross-plugin
-      // value import either inlines a duplicate runtime instance or requires
-      // a specifier the frozen module table cannot answer. Cross-plugin
-      // collaboration goes through cordis services instead. Type-only
-      // imports are erased and never reach this gate.
-      name: 'dsh-client-bundle-purity',
-      resolveId(source: string) {
-        if (NODE_BUILTINS.has(source)) {
-          throw new Error(
-            `client bundle purity: Node builtin "${source}" cannot run in the browser module table — `
-            + 'select the dependency browser export or add an explicit browser implementation',
-          )
-        }
-        if (!source.startsWith('@deepseek-ai/')) return null
-        if (CLIENT_EXTERNALS.includes(source)) return null // platform module: external wins
-        if (INLINE_SAFE.test(source)) return null // wire/type layer: inline is the point
-        throw new Error(
-          `client bundle purity: "${source}" is not a platform module (CLIENT_EXTERNALS) and not an inline-safe wire layer — `
-          + 'cross-plugin value imports are forbidden; collaborate through cordis services (type-only imports are erased and never reach this gate)',
-        )
-      },
-    }, {
-      name: 'dsh-css-inline',
-      resolveId(source: string, importer: string | undefined) {
-        if (!source.endsWith('.css')) return null
-        // Relative/absolute paths resolve against the importer; bare
-        // specifiers (e.g. 'xterm/css/xterm.css') resolve from the package.
-        let abs: string
-        if (source.startsWith('.') || source.startsWith('/') || /^[A-Za-z]:[\\/]/.test(source)) {
-          abs = importer === undefined ? source : resolvePath(dirname(importer), source)
-        } else {
-          abs = require.resolve(source)
-        }
-        return CSS_VIRTUAL_PREFIX + abs + CSS_VIRTUAL_SUFFIX
-      },
-      async load(virtualId: string) {
-        if (!virtualId.startsWith(CSS_VIRTUAL_PREFIX)) return null
-        const fileId = virtualId.slice(CSS_VIRTUAL_PREFIX.length, -CSS_VIRTUAL_SUFFIX.length)
-        this.addWatchFile(fileId)
-        const source = await readFile(fileId)
-        // CSS Modules (x.module.css) become hashed class maps; plain css
-        // (xterm's stylesheet) is inlined verbatim.
-        if (fileId.endsWith('.module.css')) {
-          const { code, exports: cssExports } = transform({
-            filename: fileId,
-            code: source,
-            cssModules: { pattern: `[hash]_[local]` },
-            minify: true,
-          })
-          const classMap: Record<string, string> = {}
-          for (const [local, exp] of Object.entries(cssExports ?? {})) classMap[local] = exp.name
-          return [
-            injectTag(pluginId, fileId, code.toString()),
-            `export default ${JSON.stringify(classMap)};`,
-          ].join('\n')
-        }
-        return [
-          injectTag(pluginId, fileId, source.toString('utf8')),
-          'export default "";',
-        ].join('\n')
-      },
-    }],
+    plugins: [purityGatePlugin(), makeCssPlugin(pluginId)],
     outputOptions: {
       entryFileNames: entryFile,
       sourcemapPathTransform: browserSourcePath,
@@ -228,14 +175,144 @@ function clientBundle(pluginId: string, entryFile: string): UserConfig {
       intro: 'var module = { exports: {} }; var exports = module.exports;',
       // The CJS wrapper factory's `require` only resolves module-table entries
       // (react, cordis, ...); it cannot load relative chunk URLs in the browser.
-      // Disable code splitting so dynamic import() inlines into the single
-      // factory chunk (Office preview libs — docx-preview, Univer — pull in
-      // several MB but only when first opened, the trade-off for wrapper safety).
+      // Disable code splitting so every artifact is one script (the lazy chunk
+      // files themselves are separate bundles — see chunkBundle below).
       codeSplitting: false,
     },
   }
 }
 
+/**
+ * One lazy chunk bundle: a heavy feature slice of the client built as a
+ * standalone single script (lib/client-<name>.js), fetched by the client on
+ * first use through the plugin's /sidebar/bundle route. The core bundle must
+ * never statically import the chunk entry.
+ *
+ * Chunks do NOT register with window.__ModuleLoader__: the module loader's
+ * import() resolves seed words / shell-own modules / registered factories /
+ * boot graph rows, and a chunk id is none of those — resolution would be
+ * version-dependent. Instead each script assigns its CJS factory to the
+ * plugin-owned global registry `globalThis.__dshChunks__[<name>]`, and the
+ * loader (src/client/chunk-loader.ts) materializes it with a require built
+ * from the module table's seed words.
+ *
+ * Chunk css tags use the constant plugin id `dsh-better-sidebar` (matching
+ * the official channel; the registry channel re-injects an identical copy
+ * of the shared module css — same content, no functional impact).
+ * @param name - chunk name; entry src/client/chunks/<name>.tsx, output
+ *   lib/client-<name>.js. Keep in sync with CHUNK_NAMES in src/bundle-route.ts.
+ */
+function chunkBundle(name: string): UserConfig {
+  return {
+    entry: { [name]: `src/client/chunks/${name}.tsx` },
+    outDir: 'lib',
+    format: 'cjs',
+    platform: 'browser',
+    dts: false,
+    sourcemap: true,
+    clean: false,
+    external: [...CLIENT_EXTERNALS],
+    define: {
+      'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV ?? 'production'),
+      'import.meta.env.MODE': JSON.stringify(process.env.NODE_ENV ?? 'production'),
+      'import.meta.env': JSON.stringify({ MODE: process.env.NODE_ENV ?? 'production' }),
+      'import.meta.resolve': 'undefined',
+    },
+    alias: {
+      jszip: JSZIP_BROWSER_ENTRY,
+      xlsx: XLSX_BROWSER_ENTRY,
+    },
+    inputOptions: {
+      resolve: {
+        conditionNames: ['browser', 'import', 'require', 'default'],
+      },
+    },
+    noExternal: (id: string) => (CLIENT_EXTERNALS.includes(id) ? undefined : true),
+    plugins: [purityGatePlugin(), makeCssPlugin('dsh-better-sidebar')],
+    outputOptions: {
+      entryFileNames: `client-${name}.js`,
+      sourcemapPathTransform: browserSourcePath,
+      banner: `globalThis.__dshChunks__ = globalThis.__dshChunks__ || {}; globalThis.__dshChunks__[${JSON.stringify(name)}] = (require) => {`,
+      footer: 'return module.exports; };',
+      intro: 'var module = { exports: {} }; var exports = module.exports;',
+      codeSplitting: false,
+    },
+  }
+}
+
+/** A rolldown plugin as tsdown's config accepts it (contextual `this` for load/resolveId). */
+type BuildPlugin = NonNullable<UserConfig['plugins']>
+
+/** The shared client-bundle purity gate (see the clientBundle doc). */
+function purityGatePlugin(): BuildPlugin {
+  return {
+    name: 'dsh-client-bundle-purity',
+    resolveId(source: string) {
+      if (NODE_BUILTINS.has(source)) {
+        throw new Error(
+          `client bundle purity: Node builtin "${source}" cannot run in the browser module table — `
+          + 'select the dependency browser export or add an explicit browser implementation',
+        )
+      }
+      if (!source.startsWith('@deepseek-ai/')) return null
+      if (CLIENT_EXTERNALS.includes(source)) return null // platform module: external wins
+      if (INLINE_SAFE.test(source)) return null // wire/type layer: inline is the point
+      throw new Error(
+        `client bundle purity: "${source}" is not a platform module (CLIENT_EXTERNALS) and not an inline-safe wire layer — `
+        + 'cross-plugin value imports are forbidden; collaborate through cordis services (type-only imports are erased and never reach this gate)',
+      )
+    },
+  }
+}
+
+/** The shared CSS-inline virtual-module plugin (one <style data-plugin> per file). */
+function makeCssPlugin(pluginId: string): BuildPlugin {
+  return {
+    name: 'dsh-css-inline',
+    resolveId(source: string, importer: string | undefined) {
+      if (!source.endsWith('.css')) return null
+      // Relative/absolute paths resolve against the importer; bare
+      // specifiers (e.g. 'xterm/css/xterm.css') resolve from the package.
+      let abs: string
+      if (source.startsWith('.') || source.startsWith('/') || /^[A-Za-z]:[\\/]/.test(source)) {
+        abs = importer === undefined ? source : resolvePath(dirname(importer), source)
+      } else {
+        abs = require.resolve(source)
+      }
+      return CSS_VIRTUAL_PREFIX + abs + CSS_VIRTUAL_SUFFIX
+    },
+    async load(virtualId: string) {
+      if (!virtualId.startsWith(CSS_VIRTUAL_PREFIX)) return null
+      const fileId = virtualId.slice(CSS_VIRTUAL_PREFIX.length, -CSS_VIRTUAL_SUFFIX.length)
+      this.addWatchFile(fileId)
+      const source = await readFile(fileId)
+      // CSS Modules (x.module.css) become hashed class maps; plain css
+      // (xterm's stylesheet) is inlined verbatim.
+      if (fileId.endsWith('.module.css')) {
+        const { code, exports: cssExports } = transform({
+          filename: fileId,
+          code: source,
+          cssModules: { pattern: `[hash]_[local]` },
+          minify: true,
+        })
+        const classMap: Record<string, string> = {}
+        for (const [local, exp] of Object.entries(cssExports ?? {})) classMap[local] = exp.name
+        return [
+          injectTag(pluginId, fileId, code.toString()),
+          `export default ${JSON.stringify(classMap)};`,
+        ].join('\n')
+      }
+      return [
+        injectTag(pluginId, fileId, source.toString('utf8')),
+        'export default "";',
+      ].join('\n')
+    },
+  }
+}
+
+/** The lazy chunk names (keep in sync with src/bundle-route.ts CHUNK_NAMES). */
+const CHUNKS = ['docx', 'xlsx', 'pptx', 'terminal', 'editor']
+
 export default [
   {
     entry: { index: 'src/index.ts', invariant: 'src/invariant.ts' },
@@ -254,4 +331,7 @@ export default [
   clientBundle('dsh-better-sidebar', 'client.js'),
   // Plugin-registry channel: bundle id = manifest id (dsh.plugin.json `id`).
   clientBundle('dsh-external/dsh-better-sidebar', 'client-registry.js'),
+  // Lazy chunks: shared by both channels, fetched on first use through the
+  // plugin's /sidebar/bundle route (see src/client/chunk-loader.ts).
+  ...CHUNKS.map(chunkBundle),
 ] satisfies UserConfig[]