dsh-deferred-boot 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.3.0] - 2026-11-07
+
+### Added
+- Per-field hints in the configuration form (zh/en), explaining what each
+  value changes.
+- Plugin-market publishing: `scripts/gen-market-index.mjs` generates a
+  format-1 market index (`market/index.json`), and `docs/PUBLISHING.md`
+  documents the npm + index-source flow.
+- npm metadata: keywords, author, engines, files whitelist, and
+  `@deepseek-ai/schemastery` as a runtime dependency.
+
+### Changed
+- The form no longer depends on `props.ctx`; it reads the ctx captured in
+  `apply()`, matching the reference web-search card.
+- README rewritten for the plugin page and npm: badges, install steps,
+  configuration table, development layout.
+
+### Fixed
+- Configuration form showing "配置服务暂不可用" on newer DSH clients.
+
+## [0.2.0] - 2026-11-07
+
+### Added
+- Graphical configuration form on the plugin page (`plugins.bundle.config`),
+  backed by the `deferred-boot` settings namespace; values are saved to the
+  current profile's Cordis patch, so `cordis.patch.yml` no longer has to be
+  edited by hand.
+- `Config` schema with four volatile fields: `idleDelay`, `disposeTimeout`,
+  `readyFallbackMs`, `deferredPlugins`.
+- Locale dictionaries (zh/en) for the plugin page and the form.
+- Icon, LICENSE (MIT), CI workflow, and packaging scripts.
+
+### Fixed
+- `cannot set property "deferredBoot" without provide`: the service is now
+  exposed with `ctx.provide('deferredBoot', api)`, which the strict Cordis 4
+  context requires.
+
+## [0.1.0] - 2026-11-07
+
+### Added
+- Initial scheduler: mounts deferred plugins after the main UI is ready, one
+  target per idle slice.
+- Existence check before `loader.create`, per-target failure isolation,
+  `dispose` raced against `disposeTimeout`, three failed attempts freeze a
+  target as `failed`, and manual `ctx.deferredBoot.ensure(id)` mounting.
+- Strategies: `idle`, `manual`, `inline-lazy`, `disabled`.
+- Tests for the scheduler, config normalization, and the client module.
+
+[0.2.0]: https://github.com/your-name/dsh-deferred-boot/releases/tag/v0.2.0
+[0.1.0]: https://github.com/your-name/dsh-deferred-boot/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BuSheng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# dsh-deferred-boot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![platform](https://img.shields.io/badge/platform-DSH%20Web-4d6bfe.svg)](#)
+[![dsh](https://img.shields.io/badge/dsh-%3E%3D0.2.0--rc.1-blueviolet.svg)](#)
+
+把指定插件推迟到**主界面就绪之后**再挂载，一次空闲切片只挂一个，避免插件成批初始化拖住首屏。只搬运挂载时机，不修改目标插件。
+
+## 特性
+
+- 就绪后再调度：优先 `connection.hostDescription`，退化为 `connection.host`、`app.ready` 轮询与兜底超时
+- 分段空闲调度：`scheduler.postTask(background)` → `requestIdleCallback` → `setTimeout`，一次回调只挂一个目标
+- 安全挂载：`loader.create` 前检查同名/同 id 条目，已存在则跳过并标记 `mounted`
+- 故障隔离：每个目标独立 `try/catch`，连续 3 次失败冻结为 `failed`，不影响其余目标
+- 卸载不挂死：`dispose` 与 `disposeTimeout` 竞速，超时后移出活跃表，迟到的 rejection 挂空处理
+- 手动模式：`ctx.deferredBoot.ensure(id)` 随时补挂 `manual` 目标
+- 图形配置：插件详情页直接改参数，保存写入当前 profile 的 Cordis patch
+- 中英双语：插件页标题/描述与表单文案随界面语言切换
+
+## 安装
+
+**本地包**（自带 `node_modules`，离线可用）：
+
+1. 解压到任意目录
+2. 运行 `install.ps1`（自动定位 profile、建 `node_modules` 链接、写入 profile 的 `package.json`）
+3. 重启 DSH
+
+**npm**（发布后）：
+
+```bash
+dsh plugin add dsh-deferred-boot
+```
+
+发布到插件市场（npm + 索引源）见 [docs/PUBLISHING.md](docs/PUBLISHING.md)。
+
+## 配置
+
+侧栏「插件」→ **dsh-deferred-boot** 详情页 → 页面描述下方的配置表单，保存即生效，不用手改配置文件。表单里每个字段下方都有同样的用途说明。
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `idleDelay` | 1200 | 就绪后到首次调度的延迟（毫秒）。调大更晚开始、首屏更稳；调小更早挂载目标。 |
+| `disposeTimeout` | 10000 | 单个目标 dispose 的硬上界（毫秒）。超时视为已卸载并继续，防止热重载卡住调度。 |
+| `readyFallbackMs` | 5000 | 就绪信号兜底超时（毫秒）。没有就绪信号时，最多等这么久就按已就绪处理。 |
+| `deferredPlugins` | `[]` | JSON 数组，每项 `{ id, name, strategy, config }`。 |
+
+`strategy`：
+
+- `idle`：就绪后由分段空闲调度自动挂载
+- `manual`：不自动挂载，调用 `ctx.deferredBoot.ensure(id)` 才挂载
+- `inline-lazy`：不搬，只在日志里提示「目标应在自身 apply 内做 idle 初始化」
+- `disabled`：跳过
+
+保存后切换插件开关重载（或重启 DSH）使调度参数生效。等价 YAML：
+
+```yaml
+- id: deferred-boot
+  name: dsh-deferred-boot
+  config:
+    idleDelay: 1200
+    disposeTimeout: 10000
+    readyFallbackMs: 5000
+    deferredPlugins:
+      - id: heavy-plugin
+        name: heavy-plugin
+        strategy: idle
+```
+
+## 边界
+
+本插件只搬挂载时机。目标插件 `apply` **内部**无法拆分的同步 CPU 长任务不会被拆分——那需要目标插件自己改成 idle 初始化。
+
+## 开发
+
+```text
+├── src/             host 半侧：index.js（apply / Config）、scheduler.js（调度器）
+├── lib/client.js    浏览器半侧：插件详情页配置表单
+├── locale/          zh/en 插件页标题与描述
+├── test/            node:test 单元测试（调度器 / 配置 / 客户端模块）
+├── docs/design.md   实现取舍、存在性检查、dispose 竞速、验收自检
+├── cordis.patch.yml bundle 补丁
+├── install.ps1      本地安装
+├── pack.ps1         打包 zip
+└── icon.svg         插件图标
+```
+
+```bash
+node --test test/*.test.mjs   # 运行测试
+./pack.cmd                    # 重新打 zip 包
+```
+
+实现细节与已知限制见 [docs/design.md](docs/design.md)。
+
+## 许可证
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,22 @@
+# dsh-deferred-boot bundle patch.
+#
+# One insert layer over the profile root, following the bundle patch dialect:
+# a patch is a mapping with `insert: [rows]`. The row mounts the scheduler
+# itself; it is deliberately NOT marked `immediately: true`, so mounting this
+# plugin never pulls heavy work into the startup window.
+#
+# Target plugins are listed under `deferredPlugins` and are mounted by the
+# scheduler after the main UI is ready. Replace the empty list with real rows:
+#
+#   - id: stats-panel
+#     name: "@scope/plugin-stats"
+#     config: {}
+#     strategy: idle
+- insert:
+    - id: deferred-boot
+      name: dsh-deferred-boot
+      config:
+        idleDelay: 1200
+        disposeTimeout: 10000
+        readyFallbackMs: 5000
+        deferredPlugins: []

package/docs/PUBLISHING.md

@@ -0,0 +1,58 @@
+# 发布到插件市场
+
+DSH 的「插件 → 发现」不是中心化官方市场：每个用户自己添加**插件索引源**（一个 HTTPS URL），市场读取其中的 JSON（格式 1）并列表、安装其中的组合包。所以「发布出去让别人能下载」= **发布包** + **托管一份索引 JSON** + **把索引 URL 给用户**。
+
+目前没有官方插件索引；索引由发布者自己托管（GitHub Pages、gist raw、对象存储、任意 HTTPS 静态服务）。
+
+## 1. 发布到 npm
+
+包名 `dsh-deferred-boot` 已确认在 npm 上空闲。
+
+```bash
+npm login                     # 或配置 npm token / .npmrc
+npm publish --access public   # 首次发布
+```
+
+- `package.json` 已声明 `dependencies: { "@deepseek-ai/schemastery": "^3.18.5" }`，npm/pnpm 安装时会自动拉取；本地 `node_modules` 不进 npm 包（`files` 白名单里没有）。
+- 以后升级：`npm version patch`（或 minor/major）→ `npm publish` → 重新生成索引（见第 2 步）。
+- 若临时不发 npm，也可以把索引的 `source` 改成 `{ "type": "git", "url": "https://github.com/<you>/dsh-deferred-boot", "commit": "<40 位 sha>" }`，但 git 方式要求仓库里带 `node_modules`（否则 `@deepseek-ai/schemastery` 缺失），体积较大，不推荐。
+
+## 2. 生成市场索引
+
+```bash
+node scripts/gen-market-index.mjs
+# 可选：node scripts/gen-market-index.mjs --index-url https://<you>.github.io/dsh-deferred-boot/index.json
+```
+
+输出 `market/index.json`，格式 1，包含插件名、中英文标题/描述、内联图标（data: URL）、作者、关键词、版本列表（`source.type = "npm"`）与 `engines.dsh`。
+
+## 3. 托管索引
+
+任选一种：
+
+- **GitHub Pages**：新建仓库 → 把 `market/index.json` 放到根目录 → Settings → Pages → 选分支 → 得到 `https://<you>.github.io/<repo>/index.json`。
+- **Gist**：新建 gist 放入 `index.json` → 用 `https://gist.githubusercontent.com/.../raw/index.json`。
+- **任意静态托管**：对象存储 / nginx / Cloudflare Pages 等，要求 HTTPS、可被匿名 GET。
+
+## 4. 别人怎么安装
+
+1. DSH 侧栏 **插件** → **发现** 标签页；
+2. 点 **添加索引源**，粘贴第 3 步的索引 URL；
+3. 在列表里找到 **延迟启动 / Deferred Boot**，点 **安装**，确认后安装并重启 DSH。
+
+## 5. 版本更新
+
+1. 改版本号并 `npm publish`；
+2. `node scripts/gen-market-index.mjs`（会写入新的 `publishTimestamp` 与版本）；
+3. 推送新的 `market/index.json` 到托管位置；
+4. 用户刷新「发现」即可看到新版本，点「有新版本」升级。
+
+## 校验索引
+
+DSH 用 `@deepseek-ai/dsh-plugin-market-index` 的 `parseMarketIndex` 校验索引（格式 1）。发布前可用任意安装该包的 Node 环境自检：
+
+```js
+import { parseMarketIndex } from '@deepseek-ai/dsh-plugin-market-index'
+const index = parseMarketIndex(JSON.parse(await readFile('market/index.json', 'utf8')), 'https://example.com/index.json')
+console.log(index.plugins.map((p) => p.name))
+```

package/docs/design.md

@@ -0,0 +1,78 @@
+# dsh-deferred-boot 实现细节
+
+## 工程约束与实现取舍
+
+### 挂载前存在性检查
+
+`duplicate loader entry id` 在 DSH 中是硬错误：Loader 应用配置后一旦出现重复 id 会直接拒绝启动，没有可捕获的恢复路径。因此 `create()` 之前必须检查：
+
+1. `loader.store[target.id]`
+2. `loader.entries()` 中 `options.id === target.id` 或 `options.name === target.name`
+3. `loader.resolve(target.id)`（缺失会抛错，属预期）
+
+命中任一即标记 `mounted` 并跳过，绝不再挂第二份。
+
+### 每个 create 独立 try/catch
+
+单个目标失败只记录 `attempts`／`lastError` 并继续下一个；连续 3 次失败标记 `failed` 后停止重试，调度循环不中断、异常不冒泡到启动路径。
+
+### dispose 与超时竞速
+
+`fiber.dispose()` 会等到所有异步清理兑现才 resolve；目标卡在等一个永不返回的服务时，`dispose()` 会无限挂起。卡死的 dispose 持有 mutation lock 时，整个界面会「点了没反应」。
+
+本插件的做法：先把目标从活跃表移除（`target.handle = null`），再让 `dispose()` 与 `disposeTimeout` 竞速；超时只记日志并继续。原始 Promise 始终挂一个 `catch`，晚到的 rejection 不会变成 unhandled rejection。
+
+### 分段调度
+
+一次空闲回调**只处理一个目标**，剩余目标留给下一次调度。调度原语优先级：
+
+1. `scheduler.postTask({ priority: "background" })`
+2. `requestIdleCallback(fn, { timeout: 1000 })`
+3. `setTimeout(fn, 0)`（host 端 Node 没有前两者时使用）
+
+### 就绪等待的多重兜底
+
+1. `ctx.connection.hostDescription`（字符串或函数）
+2. `ctx.connection.host`（ready 握手发布的 `{ home }` 对象，流一断即清空）
+3. 任一暴露 `ready === true` 的服务（`app` / `webApp`）
+4. `readyFallbackMs` 计时兜底
+
+不硬编码任何宿主事件名。
+
+### HMR 重载后的状态重建
+
+插件重载后从当前 loader 的存在性检查重建状态（`status()` 内部调用 `rebuildFromLoader()`），不会把已挂载目标再挂一遍。
+
+### 目标依赖在延迟窗口内消失
+
+调度器不负责替目标等待依赖；目标自身必须正确声明 `inject`。延迟挂载会暴露「假设服务启动时一定在」的脆弱性，这是目标插件的问题。
+
+### 卸载清理
+
+通过 `ctx.effect(() => () => scheduler.stop())` 注册清理，插件卸载后无残留定时器/观察者。
+
+## 图形界面实现
+
+- Host 侧 `Config` 的四个字段声明为 `.volatile()`；`src/scheduler.js` 在 `normalizeConfig` 里解包 volatile 引用（`get()`）后再使用。
+- 客户端 `lib/client.js` 通过 `ctx.configForms.whileServed(['deferred-boot'], ...)` 等 settings 命名空间就绪，再向 `plugins.bundle.config` 槽位注册表单（key 为包名 `dsh-deferred-boot`）；保存走 `ctx.configForms.mutate`，一次提交四个字段。
+- `package.json` 的 `dsh.client.inject` 列出客户端依赖包，`exports["./client"]` 指向 `lib/client.js`。
+
+## 验收自检
+
+`test/scheduler.test.mjs` 覆盖：
+
+- [x] 本插件不设 `immediately: true`；`apply` 内无 I/O、计算、`await`，同步返回
+- [x] 目标已存在于 loader：跳过并标记 `mounted`，不产生重复 entry
+- [x] 单个目标 `loader.create` 抛错：其余目标正常挂载，该目标为 `failed`
+- [x] 目标 `dispose()` 永不结算：`disposeTimeout` 后调度器继续，晚到 reject 不变成 unhandled rejection
+- [x] 就绪信号缺失时，`readyFallbackMs` 后仍能继续调度
+- [x] `manual` 目标在 `ensure(id)` 前不挂载
+- [x] 调度器自身被重载后，不会把已挂载目标再挂一遍
+
+`test/config.test.mjs` 覆盖 Config 的 volatile 解析与调度器归一化；`test/client.test.mjs` 覆盖客户端模块加载、slot 注册与表单首次渲染。
+
+## 已知限制
+
+- `hostDescription` 在当前 checkout 的 connection 服务上未以该名字导出；实际可用信号是 `host`（ready 握手对象）。探测顺序已按仓库现状适配。
+- 调度器只负责挂载时机；目标插件在 `apply` 内的同步重活不会被本插件拆分。
+- 图形界面依赖 settings 服务；settings 不可用时表单显示「配置服务尚未就绪」，插件本身仍正常工作。

package/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" fill="none">
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="#4D6BFE"/>
+  <circle cx="32" cy="34" r="13" stroke="#FFFFFF" stroke-width="3.5"/>
+  <path d="M32 26.5V34L37 37" stroke="#FFFFFF" stroke-width="3.5" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M13 18H23M13 24H20" stroke="#FFFFFF" stroke-opacity="0.55" stroke-width="3" stroke-linecap="round"/>
+  <path d="M43 22L47 18M47 22L43 18" stroke="#FFFFFF" stroke-width="3" stroke-linecap="round"/>
+</svg>

package/lib/client.js

@@ -0,0 +1,228 @@
+// Client half of dsh-deferred-boot.
+//
+// It renders the plugin's form on the plugin page (the bundle-config slot of
+// dsh-client-ui-plugin-manager) and reads/writes the `deferred-boot` settings
+// namespace through ctx.configForms. The host half (src/index.js) declares the
+// four fields as volatile so this form is the only place they are edited.
+window.__ModuleLoader__.load({
+  id: 'dsh-deferred-boot',
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    const React = require('react')
+    const h = React.createElement
+
+    const styles = {
+      root: { display: 'flex', flexDirection: 'column', gap: '6px', fontSize: 13, lineHeight: 1.5 },
+      intro: { margin: '0 0 10px', color: 'var(--dsh-text-2, #c8c8c8)' },
+      row: { display: 'flex', flexDirection: 'column', gap: '3px', padding: '6px 0' },
+      rowMain: { display: 'flex', alignItems: 'center', gap: 12 },
+      label: { width: 156, flex: '0 0 156px', color: 'var(--dsh-text-2, #c8c8c8)' },
+      input: {
+        flex: '0 1 240px',
+        minWidth: 120,
+        padding: '4px 8px',
+        borderRadius: 6,
+        border: '1px solid var(--dsh-border, #3a3a3a)',
+        background: 'var(--dsh-surface, #1f1f1f)',
+        color: 'inherit',
+        font: 'inherit',
+      },
+      hint: { margin: '0 0 0 168px', fontSize: 12, lineHeight: 1.5, color: 'var(--dsh-text-3, #8b8b8b)' },
+      note: { margin: '0 0 0 168px', fontSize: 12, color: 'var(--dsh-text-3, #8b8b8b)' },
+      textarea: {
+        width: '100%',
+        minHeight: 96,
+        padding: '6px 8px',
+        borderRadius: 6,
+        border: '1px solid var(--dsh-border, #3a3a3a)',
+        background: 'var(--dsh-surface, #1f1f1f)',
+        color: 'inherit',
+        font: 'inherit',
+        resize: 'vertical',
+      },
+      actions: { display: 'flex', alignItems: 'center', gap: 10, marginTop: 8 },
+      button: {
+        padding: '4px 14px',
+        borderRadius: 6,
+        border: '1px solid var(--dsh-accent, #4d6bfe)',
+        background: 'var(--dsh-accent, #4d6bfe)',
+        color: '#fff',
+        cursor: 'pointer',
+        font: 'inherit',
+      },
+      status: { fontSize: 12, color: 'var(--dsh-text-3, #8b8b8b)' },
+    }
+
+    const ZH = {
+      intro: '把指定的插件推迟到主界面就绪之后再挂载，一次空闲切片只挂一个，避免插件成批初始化把首屏拖住。',
+      'field.idleDelay': '就绪后延迟 (ms)',
+      'field.disposeTimeout': 'dispose 超时 (ms)',
+      'field.readyFallbackMs': '就绪兜底超时 (ms)',
+      'field.deferredPlugins': '延迟挂载的插件',
+      'plugins.label': '延迟挂载的插件（JSON 数组，每项 { id, name, strategy, config }）',
+      'plugins.hint': 'strategy: idle（就绪后自动挂载）/ manual（调用 deferredBoot.ensure(id) 才挂载）/ inline-lazy / disabled。',
+      'hint.idleDelay': '主界面就绪后等待多久才开始第一次空闲调度（毫秒）。调大更晚开始、首屏更稳；调小更早挂载目标插件。',
+      'hint.disposeTimeout': '卸载或热重载目标插件时最多等待多久（毫秒）。超时视为已卸载并继续，防止卸载卡住调度。',
+      'hint.readyFallbackMs': '等不到“主界面已就绪”信号时的兜底超时（毫秒）。超时后按已就绪处理，继续延迟挂载。',
+      'hint.plugins': '每项一个目标插件：id 为 loader 条目 id，name 为模块名，strategy 决定挂载方式，config 传给目标插件。',
+      save: '保存',
+      saving: '保存中…',
+      saved: '已保存，下一次操作起生效。',
+      conflict: '配置已被其他窗口修改，已重新载入，请再保存一次。',
+      failed: '保存失败，请查看 Host 日志。',
+      badJson: '延迟插件不是合法 JSON，请修正后再保存。',
+      notArray: '延迟插件必须是 JSON 数组。',
+      unavailable: '配置服务暂不可用（需要新版 DSH 客户端）。',
+      note: '配置写入当前 profile 的 Cordis patch，无需手动编辑 cordis.patch.yml。',
+    }
+
+    const EN = {
+      intro: 'Mount the listed plugins after the main UI is ready, one idling slice at a time, so a batch of heavy plugins cannot hold up the first screen.',
+      'field.idleDelay': 'Delay after ready (ms)',
+      'field.disposeTimeout': 'Dispose timeout (ms)',
+      'field.readyFallbackMs': 'Ready fallback (ms)',
+      'field.deferredPlugins': 'Deferred plugins',
+      'plugins.label': 'Deferred plugins (JSON array, each { id, name, strategy, config })',
+      'plugins.hint': 'strategy: idle (mount after ready) / manual (wait for deferredBoot.ensure(id)) / inline-lazy / disabled.',
+      'hint.idleDelay': 'How long to wait after the main UI is ready before the first idle slice (ms). Larger waits longer for a steadier first paint; smaller mounts targets sooner.',
+      'hint.disposeTimeout': 'Maximum time to wait while unloading or hot-reloading a target (ms). On timeout the target is treated as unmounted and scheduling continues.',
+      'hint.readyFallbackMs': 'Fallback timeout for “main UI ready” (ms). When no ready signal arrives, mounting starts after this delay.',
+      'hint.plugins': 'One entry per deferred plugin: id is the loader entry id, name is the module name, strategy controls how it mounts, config is passed to the target.',
+      save: 'Save',
+      saving: 'Saving…',
+      saved: 'Saved; takes effect from the next operation.',
+      conflict: 'The settings changed in another window. Reloaded — please save again.',
+      failed: 'Save failed; check the host log.',
+      badJson: 'Deferred plugins is not valid JSON.',
+      notArray: 'Deferred plugins must be a JSON array.',
+      unavailable: 'The config form service is unavailable (a newer DSH client is required).',
+      note: 'The change is written to the current profile Cordis patch; cordis.patch.yml stays untouched.',
+    }
+
+    function Row(props) {
+      return h(
+        'div',
+        { style: styles.row },
+        h('div', { style: styles.rowMain }, h('span', { style: styles.label }, props.label), props.children),
+        props.hint ? h('p', { style: styles.hint }, props.hint) : null,
+      )
+    }
+
+    function useSnapshot(form) {
+      const [snapshot, setSnapshot] = React.useState(() => form.getSnapshot())
+      React.useEffect(() => {
+        setSnapshot(form.getSnapshot())
+        return form.subscribe(setSnapshot)
+      }, [form])
+      return snapshot
+    }
+
+    function toDraft(snapshot) {
+      const value = (snapshot && snapshot.value) || {}
+      const plugins = Array.isArray(value.deferredPlugins) ? value.deferredPlugins : []
+      return {
+        idleDelay: String(value.idleDelay ?? 1200),
+        disposeTimeout: String(value.disposeTimeout ?? 10000),
+        readyFallbackMs: String(value.readyFallbackMs ?? 5000),
+        plugins: JSON.stringify(plugins, null, 2),
+      }
+    }
+
+    // The slot system does not guarantee that a form component receives the
+    // plugin ctx, so keep the injected instance reachable from apply().
+    let pluginCtx = null
+
+    function DeferredBootForm(props) {
+      const t = typeof props?.t === 'function' ? props.t : (key) => key
+      const forms = (props && props.ctx && props.ctx.configForms) || (pluginCtx && pluginCtx.configForms)
+      if (!forms || typeof forms.get !== 'function') return h('p', { style: styles.intro }, t('unavailable'))
+      const form = forms.get('deferred-boot')
+      const snapshot = useSnapshot(form)
+      const [draft, setDraft] = React.useState(() => toDraft(snapshot))
+      const [status, setStatus] = React.useState('')
+
+      React.useEffect(() => {
+        setDraft(toDraft(snapshot))
+      }, [snapshot])
+
+      const set = (key) => (event) => setDraft((prev) => ({ ...prev, [key]: event.target.value }))
+
+      const save = async () => {
+        let plugins
+        try {
+          plugins = JSON.parse(draft.plugins)
+        } catch {
+          setStatus(t('badJson'))
+          return
+        }
+        if (!Array.isArray(plugins)) {
+          setStatus(t('notArray'))
+          return
+        }
+        setStatus(t('saving'))
+        try {
+          const base = snapshot && snapshot.revision
+          const result = await form.mutate(
+            [
+              { op: 'set', path: ['idleDelay'], value: Number(draft.idleDelay) || 0 },
+              { op: 'set', path: ['disposeTimeout'], value: Number(draft.disposeTimeout) || 0 },
+              { op: 'set', path: ['readyFallbackMs'], value: Number(draft.readyFallbackMs) || 0 },
+              { op: 'set', path: ['deferredPlugins'], value: plugins },
+            ],
+            base,
+          )
+          if (result === false) setStatus(t('conflict'))
+          else setStatus(t('saved'))
+        } catch {
+          setStatus(t('failed'))
+        }
+      }
+
+      return h(
+        'div',
+        { style: styles.root },
+        h('p', { style: styles.intro }, t('intro')),
+        h('div', { style: styles.row, padding: 0 }, h('span', { style: styles.label }, t('plugins.label'))),
+        h(Row, {
+          label: t('field.idleDelay'),
+          hint: t('hint.idleDelay'),
+        }, h('input', { style: styles.input, type: 'number', value: draft.idleDelay, onChange: set('idleDelay') })),
+        h(Row, {
+          label: t('field.disposeTimeout'),
+          hint: t('hint.disposeTimeout'),
+        }, h('input', { style: styles.input, type: 'number', value: draft.disposeTimeout, onChange: set('disposeTimeout') })),
+        h(Row, {
+          label: t('field.readyFallbackMs'),
+          hint: t('hint.readyFallbackMs'),
+        }, h('input', { style: styles.input, type: 'number', value: draft.readyFallbackMs, onChange: set('readyFallbackMs') })),
+        h('p', { style: { margin: '10px 0 0', color: 'var(--dsh-text-2, #c8c8c8)' } }, t('plugins.label')),
+        h('p', { style: styles.note, margin: '2px 0 6px' }, t('plugins.hint')),
+        h('textarea', { style: styles.textarea, value: draft.plugins, onChange: set('plugins') }),
+        h('p', { style: styles.hint, margin: '2px 0 0' }, t('hint.plugins')),
+        h('div', { style: styles.actions }, h('button', { style: styles.button, type: 'button', onClick: save }, t('save')), h('span', { style: styles.status }, status || t('note'))),
+      )
+    }
+
+    function apply(ctx) {
+      pluginCtx = ctx
+      if (ctx.locale && typeof ctx.locale.register === 'function') {
+        ctx.effect(() => ctx.locale.register('deferredBoot', 'zh', ZH), 'dsh-deferred-boot: zh dictionary')
+        ctx.effect(() => ctx.locale.register('deferredBoot', 'en', EN), 'dsh-deferred-boot: en dictionary')
+      }
+      ctx.effect(
+        () =>
+          ctx.configForms.whileServed(['deferred-boot'], () =>
+            ctx.slots.inject('plugins.bundle.config', () =>
+              ctx.slots.register({ name: 'plugins.bundle.config', key: 'dsh-deferred-boot', locale: 'deferredBoot' }, DeferredBootForm),
+            ),
+          ),
+        'dsh-deferred-boot: bundle config form',
+      )
+    }
+
+    exports.apply = apply
+    exports.inject = ['slots', 'configForms', 'remote', 'locale']
+    return module.exports
+  },
+})

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Deferred Boot",
+    "description": "Mount selected plugins after the main UI is ready, one idle slice at a time, so a batch of plugin initializations does not hold the first screen."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "延迟启动",
+    "description": "主界面就绪之后再挂载指定插件，一次空闲切片只挂一个，避免插件成批初始化把首屏拖住。"
+  }
+}

package/market/index.json

@@ -0,0 +1,50 @@
+{
+  "format": 1,
+  "title": {
+    "en": "Deferred Boot",
+    "zh": "延迟启动"
+  },
+  "description": {
+    "en": "Plugins that defer heavy plugins until the main UI is ready",
+    "zh": "把指定插件推迟到主界面就绪之后再挂载的启动调度插件"
+  },
+  "plugins": [
+    {
+      "name": "dsh-deferred-boot",
+      "title": {
+        "en": "Deferred Boot",
+        "zh": "延迟启动"
+      },
+      "description": {
+        "en": "Mount selected plugins after the main UI is ready, one idle slice at a time, so a batch of plugin initializations does not hold the first screen.",
+        "zh": "主界面就绪之后再挂载指定插件，一次空闲切片只挂一个，避免插件成批初始化把首屏拖住。"
+      },
+      "icon": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2NCIgaGVpZ2h0PSI2NCIgdmlld0JveD0iMCAwIDY0IDY0IiBmaWxsPSJub25lIj4KICA8cmVjdCB4PSIyIiB5PSIyIiB3aWR0aD0iNjAiIGhlaWdodD0iNjAiIHJ4PSIxNCIgZmlsbD0iIzRENkJGRSIvPgogIDxjaXJjbGUgY3g9IjMyIiBjeT0iMzQiIHI9IjEzIiBzdHJva2U9IiNGRkZGRkYiIHN0cm9rZS13aWR0aD0iMy41Ii8+CiAgPHBhdGggZD0iTTMyIDI2LjVWMzRMMzcgMzciIHN0cm9rZT0iI0ZGRkZGRiIgc3Ryb2tlLXdpZHRoPSIzLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCIvPgogIDxwYXRoIGQ9Ik0xMyAxOEgyM00xMyAyNEgyMCIgc3Ryb2tlPSIjRkZGRkZGIiBzdHJva2Utb3BhY2l0eT0iMC41NSIgc3Ryb2tlLXdpZHRoPSIzIiBzdHJva2UtbGluZWNhcD0icm91bmQiLz4KICA8cGF0aCBkPSJNNDMgMjJMNDcgMThNNDcgMjJMNDMgMTgiIHN0cm9rZT0iI0ZGRkZGRiIgc3Ryb2tlLXdpZHRoPSIzIiBzdHJva2UtbGluZWNhcD0icm91bmQiLz4KPC9zdmc+Cg==",
+      "author": "BuSheng",
+      "metadata": {
+        "keywords": [
+          "dsh",
+          "dsh-plugin",
+          "deepseek-harness",
+          "cordis",
+          "startup",
+          "lazy-loading",
+          "deferred",
+          "plugin-manager"
+        ]
+      },
+      "versions": [
+        {
+          "version": "0.3.0",
+          "publishTimestamp": 1794044331,
+          "source": {
+            "type": "npm"
+          },
+          "engines": {
+            "dsh": ">=0.2.0-rc.1"
+          }
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "dsh-deferred-boot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Mount deferred plugins after the main UI is ready, one idle slice at a time",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./scheduler": "./src/scheduler.js",
+    "./client": "./lib/client.js",
+    "./icon": "./icon.svg",
+    "./locale/*.json": "./locale/*.json",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "icon": "./icon.svg",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-plugin-manager",
+        "@deepseek-ai/dsh-api-remotes"
+      ],
+      "platform": "web"
+    }
+  },
+  "files": [
+    "src",
+    "lib",
+    "locale",
+    "docs",
+    "market",
+    "scripts",
+    "cordis.patch.yml",
+    "icon.svg",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "cordis",
+    "startup",
+    "lazy-loading",
+    "deferred",
+    "plugin-manager"
+  ],
+  "author": "BuSheng",
+  "engines": {
+    "dsh": ">=0.2.0-rc.1",
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.1.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.5"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "pack": "powershell -NoProfile -ExecutionPolicy Bypass -File pack.ps1",
+    "index": "node scripts/gen-market-index.mjs"
+  },
+  "license": "MIT"
+}

package/scripts/gen-market-index.mjs

@@ -0,0 +1,55 @@
+// Generate the plugin market index (format 1) for this plugin.
+//
+//   node scripts/gen-market-index.mjs [--index-url https://example.com/market/index.json]
+//
+// The output is `market/index.json`. Host it anywhere that serves HTTPS; users
+// add that URL as an index source in 插件 → 发现 → 添加索引源.
+// The icon is inlined as a data: URL so the JSON is self-contained.
+import { readFile, mkdir, writeFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const read = async (rel) => readFile(join(root, rel), 'utf8')
+
+const pkg = JSON.parse(await read('package.json'))
+const zh = JSON.parse(await read('locale/zh.json'))
+const en = JSON.parse(await read('locale/en.json'))
+const icon = await read('icon.svg')
+
+const iconDataUrl = `data:image/svg+xml;base64,${Buffer.from(icon, 'utf8').toString('base64')}`
+const args = process.argv.slice(2)
+const indexUrlFlag = args.indexOf('--index-url')
+const indexUrl = indexUrlFlag >= 0 ? args[indexUrlFlag + 1] : 'https://example.com/dsh-deferred-boot/index.json'
+
+const title = { en: en.meta?.title ?? 'Deferred Boot', zh: zh.meta?.title ?? '延迟启动' }
+const description = { en: en.meta?.description ?? '', zh: zh.meta?.description ?? '' }
+
+const index = {
+  format: 1,
+  title,
+  description: { en: 'Plugins that defer heavy plugins until the main UI is ready', zh: '把指定插件推迟到主界面就绪之后再挂载的启动调度插件' },
+  plugins: [
+    {
+      name: pkg.name,
+      title,
+      description,
+      icon: iconDataUrl,
+      author: pkg.author,
+      metadata: { keywords: pkg.keywords ?? [] },
+      versions: [
+        {
+          version: pkg.version,
+          publishTimestamp: Math.floor(Date.now() / 1000),
+          source: { type: 'npm' },
+          engines: { dsh: pkg.engines?.dsh ?? '>=0.2.0-rc.1' },
+        },
+      ],
+    },
+  ],
+}
+
+await mkdir(join(root, 'market'), { recursive: true })
+await writeFile(join(root, 'market', 'index.json'), `${JSON.stringify(index, null, 2)}\n`)
+console.log(`wrote market/index.json for ${pkg.name}@${pkg.version}`)
+console.log(`host it as a static file, then use its URL as an index source: ${indexUrl}`)

package/src/index.js

@@ -0,0 +1,60 @@
+// dsh-deferred-boot — host-side entry.
+//
+// apply() must stay synchronous and cheap: register the scheduler, hand it to
+// the context, and return. No I/O, no imports of target plugins, no awaits.
+//
+// The Config fields are declared `.volatile()` so the settings service exposes
+// an editable form for them. The profile's plugin page renders that form under
+// `plugins.bundle.config` (see lib/client.js), and saving writes the values into
+// the profile patch — the user never edits cordis.patch.yml by hand.
+import Schema from '@deepseek-ai/schemastery'
+import { createDeferredBoot } from './scheduler.js'
+
+export const name = 'dsh-deferred-boot'
+
+export const Config = Schema.object({
+  idleDelay: Schema.number().default(1200).volatile(),
+  disposeTimeout: Schema.number().default(10000).volatile(),
+  readyFallbackMs: Schema.number().default(5000).volatile(),
+  deferredPlugins: Schema.array(Schema.object({
+    id: Schema.string().required(),
+    name: Schema.string().required(),
+    strategy: Schema.string().default('manual'),
+    config: Schema.any().default({}),
+  })).default([]).volatile(),
+})
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {{ idleDelay?: number, disposeTimeout?: number, readyFallbackMs?: number, deferredPlugins?: unknown[] }} [config]
+ */
+export function apply(ctx, config = {}) {
+  const scheduler = createDeferredBoot(ctx, config, { log: ctx.logger })
+  const api = {
+    /** Mount a `manual` target on demand. Resolves when the attempt settled. */
+    ensure: (id) => scheduler.ensure(id),
+    /** Snapshot of every target: { id, strategy, state, attempts, lastError }. */
+    status: () => scheduler.status(),
+    /** Dispose one mounted target with the configured timeout. */
+    unmount: (id) => scheduler.unmount(id),
+  }
+  // Cordis 4 contexts are strict proxies: assigning an unknown property throws
+  // `cannot set property "..." without provide`. Register the service through
+  // ctx.provide() so the fiber owns it and disposes it on unload; older Cordis
+  // builds without provide() accept the plain assignment.
+  if (typeof ctx.provide === 'function') {
+    ctx.provide('deferredBoot', api)
+  } else {
+    ctx.deferredBoot = api
+  }
+
+  if (typeof ctx.effect === 'function') {
+    ctx.effect(() => () => scheduler.stop())
+  } else if (typeof ctx.on === 'function') {
+    ctx.on('dispose', () => scheduler.stop())
+  }
+
+  // start() only schedules a microtask; apply() itself stays synchronous.
+  scheduler.start()
+  return api
+}

package/src/scheduler.js

@@ -0,0 +1,419 @@
+// dsh-deferred-boot scheduler core.
+//
+// Responsibilities:
+//   - wait for a "main UI ready" signal with layered fallbacks
+//   - mount deferred targets one at a time, on idle slices (never a whole batch
+//     inside one idle callback)
+//   - check loader existence before every create() (duplicate ids are fatal)
+//   - isolate per-target failures; freeze after repeated failures
+//   - race dispose() against a hard timeout, never leave an unhandled rejection
+//
+// The module is runtime-neutral: it never imports Node or browser globals at
+// load time, only probes them when a schedule is requested.
+
+export const DEFAULT_CONFIG = {
+  idleDelay: 1200,
+  disposeTimeout: 10000,
+  readyFallbackMs: 5000,
+  deferredPlugins: [],
+}
+
+const STRATEGIES = new Set(['idle', 'manual', 'inline-lazy', 'disabled'])
+const MAX_ATTEMPTS = 3
+const READY_POLL_MS = 150
+
+/**
+ * Schemastery's `.volatile()` fields arrive as references with get()/set()
+ * instead of plain values. Unwrap them so the scheduler always sees data.
+ */
+function unwrap(value) {
+  if (value && typeof value === 'object' && typeof value.get === 'function') {
+    try {
+      return value.get()
+    } catch {
+      return value
+    }
+  }
+  return value
+}
+
+function numberOr(value, fallback) {
+  const number = Number(unwrap(value))
+  return Number.isFinite(number) && number >= 0 ? number : fallback
+}
+
+/**
+ * Normalize the user config. Unknown strategies fall back to `manual` so a typo
+ * can never make a heavy plugin mount automatically.
+ */
+export function normalizeConfig(raw) {
+  const source = raw ?? {}
+  const plugins = unwrap(source.deferredPlugins)
+  const config = {
+    idleDelay: numberOr(source.idleDelay, DEFAULT_CONFIG.idleDelay),
+    disposeTimeout: numberOr(source.disposeTimeout, DEFAULT_CONFIG.disposeTimeout),
+    readyFallbackMs: numberOr(source.readyFallbackMs, DEFAULT_CONFIG.readyFallbackMs),
+    deferredPlugins: Array.isArray(plugins) ? plugins : DEFAULT_CONFIG.deferredPlugins,
+  }
+  config.deferredPlugins = config.deferredPlugins.map((item, index) => {
+    const strategy = STRATEGIES.has(item.strategy) ? item.strategy : 'manual'
+    const id = String(item.id ?? item.name ?? `deferred-${index}`)
+    return {
+      id,
+      name: String(item.name ?? id),
+      config: item.config ?? {},
+      strategy,
+      attempts: 0,
+      state: 'pending',
+      lastError: null,
+      handle: null,
+    }
+  })
+  return config
+}
+
+/** Turn one idle task trigger into a callback. Never runs a batch. */
+export function scheduleSlice(run) {
+  const g = globalThis
+  if (g.scheduler && typeof g.scheduler.postTask === 'function') {
+    // background priority: the browser may run it after user-visible work.
+    g.scheduler.postTask(() => run(), { priority: 'background' }).catch(() => {})
+    return
+  }
+  if (typeof g.requestIdleCallback === 'function') {
+    g.requestIdleCallback(() => run(), { timeout: 1000 })
+    return
+  }
+  // Node (host runtime) has neither API. A zero-delay timer keeps the slice
+  // asynchronous and lets the event loop breathe between targets.
+  setTimeout(() => run(), 0)
+}
+
+/**
+ * Wait for the main UI to be ready.
+ *
+ * Probe order:
+ *   1. ctx.connection.hostDescription (string or function)
+ *   2. ctx.connection.host (object with home/name), i.e. the ready handshake
+ *   3. any service exposing a boolean `ready`
+ *   4. readyFallbackMs timer, so a missing signal can never stall the queue
+ *
+ * Never hard-codes a host event name.
+ */
+export function waitForReady(ctx, fallbackMs, { pollMs = READY_POLL_MS } = {}) {
+  return new Promise((resolve) => {
+    let settled = false
+    let timer = null
+    let poll = null
+    const finish = (source) => {
+      if (settled) return
+      settled = true
+      if (timer) clearTimeout(timer)
+      if (poll) clearInterval(poll)
+      resolve(source)
+    }
+
+    const probe = () => {
+      const connection = readService(ctx, 'connection')
+      if (connection) {
+        const description = connection.hostDescription
+        const value = typeof description === 'function' ? description() : description
+        if (typeof value === 'string' && value.length > 0) {
+          finish('connection.hostDescription')
+          return true
+        }
+        const host = connection.host
+        if (host && (host.home || host.name || host.id)) {
+          finish('connection.host')
+          return true
+        }
+      }
+      const app = readService(ctx, 'app') ?? readService(ctx, 'webApp')
+      if (app && app.ready === true) {
+        finish('app.ready')
+        return true
+      }
+      return false
+    }
+
+    if (probe()) return
+
+    timer = setTimeout(() => finish('fallback-timeout'), fallbackMs)
+    poll = setInterval(() => {
+      if (probe()) {
+        // finish() clears the interval itself
+      }
+    }, pollMs)
+  })
+}
+
+function readService(ctx, name) {
+  try {
+    if (typeof ctx.get === 'function') {
+      const service = ctx.get(name)
+      if (service) return service
+    }
+  } catch {
+    // service missing: fall through
+  }
+  try {
+    return ctx[name] ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Look for an entry that already represents `target` in the current loader.
+ * `loader.create` with an existing id replaces/hot-updates rather than adding a
+ * duplicate row, but DSH treats a duplicate entry id in the tree as a hard
+ * startup error, so the check must happen before create().
+ */
+export function findExistingEntry(loader, target) {
+  try {
+    const direct = loader.store?.[target.id]
+    if (direct) return direct
+  } catch {
+    // store is not enumerable in some hosts
+  }
+  try {
+    if (typeof loader.entries === 'function') {
+      for (const entry of loader.entries()) {
+        if (entry?.options?.id === target.id) return entry
+        if (entry?.options?.name === target.name) return entry
+      }
+    }
+  } catch {
+    // entries() may throw while the tree is mutating; treat as absent
+  }
+  try {
+    if (typeof loader.resolve === 'function') {
+      return loader.resolve(target.id)
+    }
+  } catch {
+    // resolve() throws for missing ids: expected
+  }
+  return null
+}
+
+function readFiber(entry) {
+  if (!entry) return null
+  if (entry.fiber && typeof entry.fiber.dispose === 'function') return entry.fiber
+  if (entry.ctx?.fiber && typeof entry.ctx.fiber.dispose === 'function') return entry.ctx.fiber
+  return null
+}
+
+/**
+ * Dispose one mounted target with a hard upper bound.
+ *
+ * Cordis fiber.dispose() resolves only after every async cleanup settles; a
+ * target waiting on a service that never comes back can hang it forever. A
+ * hung dispose holding the mutation lock is what freezes the whole UI, so the
+ * target is removed from the active table *before* the race and a late
+ * rejection gets a sink.
+ */
+export async function disposeWithTimeout(target, loader, timeoutMs, log) {
+  const entry = target.handle ?? findExistingEntry(loader, target)
+  target.handle = null // remove from the active table before awaiting anything
+  const fiber = readFiber(entry)
+  if (!fiber) {
+    try {
+      loader.remove?.(target.id)
+    } catch (error) {
+      log?.warn?.(`dsh-deferred-boot: remove(${target.id}) failed: ${describe(error)}`)
+    }
+    return 'no-fiber'
+  }
+
+  let disposed = false
+  const settle = () => {
+    disposed = true
+  }
+  const disposal = Promise.resolve()
+    .then(() => fiber.dispose())
+    .then(settle, (error) => {
+      settle()
+      log?.warn?.(`dsh-deferred-boot: dispose(${target.id}) rejected: ${describe(error)}`)
+    })
+  // keep a sink on the original promise so a late rejection is never unhandled
+  disposal.catch(() => {})
+
+  const timeout = new Promise((resolve) => setTimeout(resolve, Math.max(1, timeoutMs)))
+  const winner = await Promise.race([
+    disposal.then(() => 'disposed'),
+    timeout.then(() => 'timeout'),
+  ])
+  if (winner === 'timeout' && !disposed) {
+    log?.warn?.(
+      `dsh-deferred-boot: dispose(${target.id}) exceeded ${timeoutMs}ms; continuing without waiting`,
+    )
+  }
+  return winner
+}
+
+export function describe(error) {
+  if (error instanceof Error) return error.message || error.name
+  if (typeof error === 'string') return error
+  try {
+    return JSON.stringify(error)
+  } catch {
+    return String(error)
+  }
+}
+
+/**
+ * Build the scheduler. `apply()` calls this and returns immediately: no I/O,
+ * no awaits, no target imports here.
+ */
+export function createDeferredBoot(ctx, rawConfig, { log } = {}) {
+  const config = normalizeConfig(rawConfig)
+  // Resolve through the service accessor first: a direct ctx.loader read throws
+  // on a context whose inject declaration does not cover the loader service.
+  const loader = readService(ctx, 'loader')
+  const logger = log ?? ctx?.logger
+  const active = new Map()
+  let started = false
+  let readySource = null
+  let stopped = false
+
+  const queue = config.deferredPlugins.filter((t) => t.strategy === 'idle')
+  const manual = new Map(
+    config.deferredPlugins.filter((t) => t.strategy === 'manual').map((t) => [t.id, t]),
+  )
+
+  for (const target of config.deferredPlugins) {
+    if (target.strategy === 'inline-lazy') {
+      logger?.info?.(
+        `dsh-deferred-boot: ${target.id} is inline-lazy; move its heavy work into an idle init inside its own apply() instead of deferring the mount`,
+      )
+    }
+    if (target.strategy === 'disabled') target.state = 'disabled'
+  }
+
+  function status() {
+    if (rebuildFromLoader()) {
+      // state was rebuilt from the live loader after an HMR reload
+    }
+    return config.deferredPlugins.map((t) => ({
+      id: t.id,
+      strategy: t.strategy,
+      state: t.state,
+      attempts: t.attempts,
+      lastError: t.lastError,
+    }))
+  }
+
+  /**
+   * Rebuild mount state from the loader itself, so a scheduler HMR reload does
+   * not mount an already-mounted target twice. Returns true when it changed
+   * anything (used only to keep the call explicit in status()).
+   */
+  function rebuildFromLoader() {
+    if (!loader) return false
+    let changed = false
+    for (const target of config.deferredPlugins) {
+      if (target.state === 'mounted' || target.state === 'disabled') continue
+      const entry = findExistingEntry(loader, target)
+      if (entry) {
+        target.handle = entry
+        target.state = 'mounted'
+        changed = true
+      }
+    }
+    return changed
+  }
+
+  async function mountOne(target, reason) {
+    if (stopped) return
+    if (target.state === 'mounted' || target.state === 'disabled' || target.state === 'failed') return
+    if (target.strategy === 'manual' && reason !== 'ensure') return
+    if (!loader) {
+      target.lastError = 'loader service is unavailable'
+      target.state = 'failed'
+      return
+    }
+    const existing = findExistingEntry(loader, target)
+    if (existing) {
+      target.handle = existing
+      target.state = 'mounted'
+      logger?.info?.(`dsh-deferred-boot: ${target.id} already present; skipped`)
+      return
+    }
+    try {
+      const id = await loader.create({ id: target.id, name: target.name, config: target.config })
+      target.handle = loader.store?.[id] ?? findExistingEntry(loader, target)
+      target.state = 'mounted'
+      logger?.info?.(`dsh-deferred-boot: mounted ${target.id} (${reason})`)
+    } catch (error) {
+      target.attempts += 1
+      target.lastError = describe(error)
+      const fatal = target.attempts >= MAX_ATTEMPTS
+      target.state = fatal ? 'failed' : 'pending'
+      logger?.warn?.(
+        `dsh-deferred-boot: mount(${target.id}) failed (attempt ${target.attempts}${fatal ? ', frozen' : ', will retry'}): ${target.lastError}`,
+      )
+    }
+  }
+
+  function start() {
+    if (started) return
+    started = true
+    if (!queue.length && !manual.size) return
+    // Defer the first probe so apply() stays synchronous and cheap.
+    queueMicrotask(async () => {
+      readySource = await waitForReady(ctx, config.readyFallbackMs)
+      logger?.info?.(`dsh-deferred-boot: ready via ${readySource}`)
+      scheduleSlice(drain)
+    })
+  }
+
+  function drain() {
+    if (stopped) return
+    if (!queue.length) return
+    const target = queue[0]
+    const pending = target.state === 'pending'
+    if (pending && target.attempts < MAX_ATTEMPTS) {
+      mountOne(target, 'idle')
+        .catch((error) => {
+          logger?.warn?.(`dsh-deferred-boot: unexpected mount error: ${describe(error)}`)
+        })
+        .finally(() => {
+          // retry pending target after a failure, but only after idleDelay slices
+          if (target.state === 'pending') {
+            scheduleSlice(drain)
+          } else {
+            queue.shift()
+            scheduleSlice(drain)
+          }
+        })
+      return
+    }
+    // terminal or non-idle: drop and continue the queue
+    queue.shift()
+    scheduleSlice(drain)
+  }
+
+  async function ensure(id) {
+    if (stopped) return
+    const target = manual.get(id) ?? config.deferredPlugins.find((t) => t.id === id)
+    if (!target) {
+      logger?.warn?.(`dsh-deferred-boot: ensure(${id}) unknown target`)
+      return
+    }
+    if (target.state === 'mounted') return
+    await mountOne(target, 'ensure')
+  }
+
+  async function unmount(id) {
+    const target = config.deferredPlugins.find((t) => t.id === id)
+    if (!target || !target.handle) return
+    await disposeWithTimeout(target, loader, config.disposeTimeout, logger)
+    target.state = 'pending'
+  }
+
+  function stop() {
+    stopped = true
+  }
+
+  return { start, status, ensure, unmount, stop, rebuildFromLoader, get config() { return config } }
+}