@avantf/dsh-plugin-base 0.5.3 → 0.6.1

package/README.md

@@ -1,8 +1,8 @@
 # @avantf/dsh-plugin-base
 
 DSH 插件共用的底座（共享库）。**插件在运行时按 file URL 动态加载它**——不静态 `import`、不打包进插件，
-拿不到就降级挂载——把三件容易各写一遍的事收在一起：**启动期资源预装**、**宿主兼容门禁**、**一组与 DSH
-无关的共享工具**。
+拿不到就降级挂载——把四件容易各写一遍的事收在一起：**启动期资源预装**、**共享运行期依赖**、
+**宿主兼容门禁**、**一组与 DSH 无关的共享工具**。
 
 - **运行期零依赖**：`dependencies` 为空，源码里连 `zod` 都不 import。
 - 唯一一条 peer 是 `zod`（`>=4.4.3 <5`），由宿主 / 上层提供，好让调用方、本包与宿主解析到**同一份**
@@ -25,11 +25,38 @@ DSH 插件共用的底座（共享库）。**插件在运行时按 file URL 动
   `warn`（写明 holder 的 pid、已持有时长、本次已等待时长）后继续按预算等待；等不到就报 `lock/timeout`，
   消息里带 holder 与 mtime 诊断；
 - 每一项给出 `present / installed / skipped / failed`，失败带稳定 `code`；
-- 三种内置资源种类：`npm-package`、`binary-archive`、`model-cache`。新的种类 = 一个新的 provider，
-  核心不动；
+- 四种内置资源种类：`npm-package`、`binary-archive`、`model-cache`、`runtime-deps`。新的种类 =
+  一个新的 provider，核心不动；
 - 策略可配：离线、镜像、每项的并发与超时、启动预算、下载总闸。
 
-### 2. 宿主兼容门禁
+### 2. 共享运行期依赖（runtime-deps）
+
+插件需要**自己 install 树里没有**的运行期 npm 包（例如某个带原生模块的推理库），但两个插件不该各装一份、
+更不该把宿主单例（`zod`、DSH 包）装成两份。base 提供一个**按 spec 寻址（spec-addressed）、装一次就不再
+改写、全局共享**的依赖根：
+
+```
+插件声明（packages / sources / attempts / verify / peers）
+  → key = sha256(packages + verify + lockfile + platform/arch/Node ABI + manager 版本
+                 + attempts 的 source/env/scripts + peer 名/区间 + 解析到的宿主副本)
+  → 在 <home>/deps/runtime/<key>/ 只装一次（per-key 锁 + staging + 原子 rename）
+  → 插件用 createRequire(<根>/package.json) 加载
+```
+
+- key 是**声明**的摘要，不是取回字节的摘要：不给 `lockfile` 时，同一个 key 在不同时间/机器上可以装出不同
+  版本；根保证的是“装一次，之后本地不再改写”。要字节级可复现就把 `lockfile` 传进来；
+- 同 key ⇒ 同一份物理安装，所有插件共用；改了包、verify、lockfile、平台、manager、env，或 peer 的区间/
+  解析到的副本 ⇒ 新 key、新根，**旧根永不被改写**；
+- `sources` + `attempts` 按顺序尝试（registry / cache / 离线 / 脚本策略）；每个 attempt 都记录，全部失败报
+  `runtime-deps/install-failed`，插件照常挂载（`failed` 只是一条报告）；
+- `verify` 的每一项在写 `.ready` 之前用 `createRequire(...).resolve()` 验过；失败换下一个 attempt；
+- `peers` **只链接不安装**：宿主单例写在 `peerDependencies`（optional），装完从插件自己的树链接进来；复用
+  时同时核对**链接目标**与链接到的版本，同版本的另一个目录不算本 key 的根（没有 symlink 时的复制回退是
+  版本级身份，记录在 `.runtime.json` 的 `copiedPeers`）；
+- **base 不认识任何包名**：装什么、从哪装、验什么，全部来自插件的 `RuntimeDepsSpec`；
+- GC **显式**（`./internal` 的 `gcRuntimeDeps`），按 `status.json` 里记录的 key 保留，绝不在启动时自动回收。
+
+### 3. 宿主兼容门禁
 
 在挂载之前判断"当前宿主能不能跑这段代码"，语义是**只有被证实的不兼容才拒绝**：
 
@@ -39,7 +66,7 @@ DSH 插件共用的底座（共享库）。**插件在运行时按 file URL 动
 - `registerMegaphone` 在拒绝加载的路径上留一条用户可见的命令（那时它是唯一的信息渠道）；
 - `verifyRegisteredFaces` 在挂载后复查"声明的每个 schema / 工具真的注册上了"（只告警）。
 
-### 3. 共享工具（kit）
+### 4. 共享工具（kit）
 
 与 DSH 无关的纯逻辑，调用方在运行时复用：
 
@@ -259,6 +286,87 @@ if (!verdict.load) {
 }
 ```
 
+### 取用共享运行期依赖（runtime-deps）
+
+```ts
+// 注册 provider（它和别的 provider 一样进 provisioner）
+provisioner.register(framework.runtimeDepsProvider())
+
+provisioner.declare({
+  plugin: 'my-plugin',
+  items: [{
+    id: 'my-plugin:transformers',
+    kind: framework.RUNTIME_DEPS_KIND,           // 'runtime-deps'
+    spec: {
+      packages: { '@huggingface/transformers': '^4.2.0' },
+      sources: [
+        { id: 'npmmirror', registry: 'https://registry.npmmirror.com' },
+        { id: 'npmjs', registry: 'https://registry.npmjs.org' },
+      ],
+      attempts: [
+        { source: 'npmmirror' },
+        { source: 'npmmirror', env: { ONNXRUNTIME_NODE_INSTALL: 'skip' } },
+        { source: 'npmjs', manager: 'npm' },
+      ],
+      verify: ['@huggingface/transformers'],
+      peers: { zod: '>=4.4.3 <5' },              // 宿主单例：只链接，不从 registry 装
+    },
+    target: { root: 'deps/runtime' },            // 规范位置；换 root 就是另一个共享根
+    onMissing: { atStartup: 'degrade', atUse: 'error' },
+    schemaVersion: 1,
+  }],
+})
+
+const report = await provisioner.ensure({ only: ['my-plugin:transformers'], deadlineMs: 120_000 })
+if (!report.ok) logger.warn('运行期依赖未就绪，用内置降级路径继续')
+
+const state = provisioner.resolve('my-plugin:transformers')
+if (state.state === 'ready') {
+  const dir = state.handle.dir                   // <home>/deps/runtime/<key>
+  const req = createRequire(join(dir, 'package.json'))
+  const transformers = await import(req.resolve('@huggingface/transformers'))
+  // 完整记录（key / attempts / integrity / installedAt）在 <dir>/.runtime.json
+}
+```
+
+### 用 helper 声明运行期依赖 + 会话提示（v6）
+
+上面那种接线（注册 provider、拼 item、`ensure`、`createRequire`）可以缩成一次调用。helper 只是糖，底层
+`runtimeDepsProvider()` + `createProvisioner()` 的行为一字未改：
+
+```ts
+import { createRuntimeDeps } from '@avantf/dsh-plugin-base'
+
+const runtime = createRuntimeDeps({
+  namespace: 'my-plugin',                       // item id 默认 my-plugin:runtime-deps
+  packages: { 'some-runtime-pkg': '^1.2.0' },
+  sources: [{ id: 'npmmirror', registry: 'https://registry.npmmirror.com' }],
+  attempts: [{ source: 'npmmirror' }],
+  verify: ['some-runtime-pkg'],
+  // 文案永远是插件的（base 里没有任何包名/命令/句子）；when 决定它对应哪种状态
+  notices: [{
+    id: 'my-plugin:runtime-pkg',
+    severity: 'degraded',
+    when: 'failed',
+    body: '[my-plugin] 可选能力未就绪，已降级为内置路径。',
+  }],
+})
+
+provisioner.declare({ plugin: 'my-plugin', items: [runtime.item] })
+const entry = await runtime.ensure(provisioner)          // 这个 item 的报告条目
+if (entry?.action === 'failed') logger.warn(entry.reason ?? '')
+
+// 自己的 pre-step 里（owner 会话）：
+const lines = runtime.notices.consume(sessionId, { ownerOnly: true })
+if (lines.length > 0) return [...lines, existingHint].join('\n')   // 与已有提示合并成 ONE 条
+
+// 就绪后从共享根加载：不复制包、不写 node_modules
+const mod = await runtime.load('some-runtime-pkg')
+```
+
+`notices` 的状态是**每次 consume 重新判断**的（依赖修好了就不再提），一个 id 对每个 session 最多出一次，
+多条同时成立时按 `degraded` > `warning` > `info` 排序合并；`consume` 永不抛。
+
 ### 取用共享工具
 
 ```ts
@@ -333,6 +441,13 @@ assertProviderConformance(report)
 
 ## 接口要点
 
+- **v6（0.7.0）新增**：会话提示 registry `createSessionNotices`（+ `SessionNoticeSpec` /
+  `SessionNoticeRegistry`）与 runtime-deps 的薄 helper `createRuntimeDeps`（+ `RuntimeDepsConfig` /
+  `RuntimeDepsHandle`）；v6 是 v5 的增量世代（`BaseRuntimeV6 extends BaseRuntimeV5`），没有拿走任何旧名字。
+- **v5（0.6.0）新增**：`RUNTIME_DEPS_KIND` / `runtimeDepsProvider` 与 `DependencySource` /
+  `InstallAttempt` / `RuntimeDepsSpec`；v5 是 v4 的增量世代（`BaseRuntimeV5 extends BaseRuntimeV4`）。
+  `BuiltinKind` 增加 `'runtime-deps'`、`ProvisionCode` 增加 `runtime-deps/install-failed`（都是并集加宽）。
+
 `.` 上的导出（值 + 类型）构成本包的**接口**，由世代号冻结；`./preset` / `./conformance` / `./bootstrap`
 三个子路径也在承诺内，`./internal` 从不承诺稳定。
 
@@ -353,8 +468,10 @@ assertProviderConformance(report)
 
 ## 边界（不做的事）
 
-- **不做包管理器**：不推导传递依赖、不生成 lockfile、不做版本求解；每个 item 自包含。
-- **不接管原生模块**：`binding.gyp` / `*.node` / 依赖 `postinstall` 的包会被识别并拒绝。
+- **不自己当包管理器**：不推导传递依赖、不做版本求解；`runtime-deps` 把安装交给调用方声明的 npm / pnpm，
+  依赖图与 lockfile 由 manager 负责，base 只做 spec 寻址、锁、校验与失败报告。
+- **`npm-package` provider 不接管原生模块**：`binding.gyp` / `*.node` / 依赖 `postinstall` 的包会被识别并
+  拒绝；需要原生模块时走 `runtime-deps`（由 manager 安装）或 `binary-archive`。
 - **不跳过校验**：npm 包核对 `dist.integrity`，归档核对 `sha256`。
 - **不做进程内预热**：让文件在盘上是框架的事，读进内存是调用方自己的事。
 
@@ -362,11 +479,13 @@ assertProviderConformance(report)
 
 - 接口面是 `.` 上的导出（值 + 类型）加上 `./preset` / `./conformance` / `./bootstrap` 三个子路径；`./internal`
   是内部件，从不承诺稳定。
-- **当前这一代（v4）沿用 v3 的名字面**：`.` 只列"插件真取用、或插件作者被期望调用"的成员，其余进
-  `./internal`。这是为了把"内部件的改动"与"接口"解耦，不是"这个集合永远不变"：新能力从明确标注为
-  不稳定的入口引入，既有成员按弃用周期退出。v4 一个名字都没动 —— 它加宽的是**既有成员接受的入参**：
-  `verifyRegisteredFaces({ …, scope? })` 多了个可选、不透明的 `scope`，原样透传给 `tools.get(name,
-  scope)`，好让按作用域注册的工具面能被复查到；不传时行为与 v3 逐字相同。
+- **当前这一代（v6）是 v5 的增量**：`.` 仍然只列"插件真取用、或插件作者被期望调用"的成员，其余进
+  `./internal`。v6 新增会话提示 registry 与 runtime-deps helper（2 个值名 + 4 个类型名），没有拿走 v5 的
+  任何名字；`BaseRuntimeV6 extends BaseRuntimeV5`，所以 v1–v5 构建遇到 v6 base 仍判 `ok` + `warning`。
+  v5 本身是 v4 的增量（共享运行期依赖 provider：2 个值名 + 3 个类型名，外加 `BuiltinKind` /
+  `ProvisionCode` 两个并集加宽）；v4 则是一个名字都没动的换代 —— 它加宽的是**既有成员接受的入参**：
+  `verifyRegisteredFaces({ …, scope? })` 多了个可选、不透明的 `scope`，原样透传给
+  `tools.get(name, scope)`，不传时行为与 v3 逐字相同。
 - **v3 是第一次破坏性换代**：v2 的成员如果有消费者，v3 一个不少；但 v3 不再对 v2 做结构超集。旧调用方
   遇到更新的 base 仍判 `ok` + `warning`，遇到更旧的 base 才降级。
 - **接口与包版本是两条轴**：接口换代只升 `INTERFACE_VERSION` 并新增快照；包版本是普通 semver，只表达

package/lib/bootstrap.d.ts

@@ -3,7 +3,7 @@
  * @module bootstrap
  */
 /** The bootstrap version; the resolved framework must satisfy {@link supportedRange}. */
-export declare const VERSION = "0.5.3";
+export declare const VERSION = "0.6.1";
 /**
  * The framework interval this bootstrap can launch.
  *

package/lib/bootstrap.js

@@ -6,7 +6,7 @@ import { existsSync, promises as fsp, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 /** The bootstrap version; the resolved framework must satisfy {@link supportedRange}. */
-export const VERSION = '0.5.3';
+export const VERSION = '0.6.1';
 /**
  * The framework interval this bootstrap can launch.
  *

package/lib/client/load_more.d.ts

@@ -0,0 +1,157 @@
+/**
+ * "Scroll to the end → load the next page", as one DOM controller.
+ *
+ * **INTERNAL — no stability promise** (内部控制件，不承诺稳定): this module is reachable only through
+ * the `./internal` subpath, which the interface generation never covers (`docs/INTERFACE.md` §2/§5).
+ * It is not on `.`, it is not frozen with a generation, and a rename or a changed option shape is a
+ * base release, not a generation. Consumers (mem's 记忆 tab, mission's paged lists) follow the base.
+ *
+ * Why a DOM controller and not a React hook: this base has NO `react` peer (`package.json`), and it
+ * must stay that way — a Node user of the base must not be pulled into React, and the base ships no
+ * browser artifact. So the listener, the rAF throttle and the scrollport lookup live here, and each
+ * plugin keeps a thin wrapper of its own (mem: `useLoadMoreOnScroll`). The DOM detail then exists
+ * once instead of once per panel.
+ *
+ * Why the DOM types below are STRUCTURAL instead of `lib.dom`: the base compiles with `lib: es2023`
+ * and `types: node`, and adding `DOM` there retypes globals for the whole package (it breaks `fetch`
+ * bodies across the existing suite, for one). This module instead names the exact slice it reads —
+ * element, document, view — so the base stays node-only, its unit test needs no DOM environment, and
+ * a real `HTMLElement` / `Window` satisfies the interfaces as-is.
+ *
+ * Why a scroll listener and not an `IntersectionObserver` (three reasons measured in mem's panel):
+ *
+ * 1. **`rootMargin` cannot prefetch here.** A plugin panel usually owns no scrollport — the host's
+ *    conversation scroll body does — and an ancestor's clip rect is NOT expanded by `rootMargin`
+ *    (only the intersection root's is), so the promised look-ahead never happens.
+ * 2. **An observer only reports threshold CHANGES.** One page that failed to load leaves the
+ *    sentinel visible, so no new callback arrives and auto-load stays dead until something else
+ *    moves it. A scroll listener is level-triggered: the next scroll event simply tries again.
+ * 3. **The scrollport is found, not assumed.** {@link scrollParentOf} walks up to whatever element
+ *    really scrolls, so this keeps working if a panel ever gets its own scroller.
+ *
+ * The gap the listener alone cannot close — and why {@link AutoLoadMore.recheck} exists: a page that
+ * does NOT fill the scrollport produces no scroll event, and neither does a virtualized list that
+ * reaches its last row (the virtualizer window moves, the scroll position does not). Callers
+ * therefore re-check after a render (`recheck`), and after the data version changes
+ * (`setVersion`, which re-checks only when the number really moved).
+ *
+ * **Where the controller stops (the host boundary).** {@link scrollParentOf} has exactly one
+ * criterion for a scrollport: the element's OWN computed `overflow-y` is `auto`/`scroll` AND its
+ * `scrollHeight > clientHeight`. Two things follow, and both are deliberate rather than bugs to
+ * paper over here:
+ *
+ * - **A host whose PAGE is the scroller silently does not auto-load.** With no element satisfying the
+ *   criterion, {@link createAutoLoadMore} still attaches the listener to `window` (so nothing throws,
+ *   and a scrollport that appears later is picked up), but `check()` refuses to fire while it has no
+ *   scroller: there is no position to read, so the `window` listener alone changes nothing. The
+ *   caller then owns the gap — call {@link AutoLoadMore.recheck} from its own render/commit path, or
+ *   pass a real scrollport as `target` (e.g. `document.scrollingElement`, or the element whose
+ *   `scrollHeight` the page grows).
+ * - **The scrollport is resolved once, at creation.** A panel that gains (or replaces) its own
+ *   scroller later must `dispose()` and recreate the controller; `check` re-probes only while it has
+ *   no scroller at all.
+ *
+ * @module client/load_more
+ */
+/** Distance from the scrollport's end, in px, at which the next page is requested. */
+export declare const AUTO_LOAD_MORE_MARGIN_PX = 300;
+/**
+ * The slice of an `Element` this kit reads.
+ *
+ * A real `HTMLElement` satisfies it as-is (`scrollTop` / `scrollHeight` / `clientHeight` /
+ * `parentElement` / `ownerDocument` / the listener pair), and a test double is just an object — which
+ * is why the controller can be unit-tested without a DOM implementation.
+ */
+export interface ScrollElement {
+    readonly scrollTop: number;
+    readonly scrollHeight: number;
+    readonly clientHeight: number;
+    readonly parentElement: ScrollElement | null;
+    readonly ownerDocument: ScrollDocument | null;
+    addEventListener(type: 'scroll', listener: () => void, options: {
+        readonly passive: boolean;
+    }): void;
+    removeEventListener(type: 'scroll', listener: () => void): void;
+}
+/** The slice of a `Document` the overflow lookup reads: its view, when it has one. */
+export interface ScrollDocument {
+    readonly defaultView: ScrollView | null;
+}
+/** The slice of a `Window` the overflow lookup reads. */
+export interface ScrollView {
+    getComputedStyle(element: ScrollElement): {
+        readonly overflowY: string;
+    };
+}
+/** The caller's half of the controller: what it reads, and what it does when the end is reached. */
+export interface AutoLoadMoreOptions {
+    /**
+     * Where to start looking for the scrollport: normally the panel root (the scrollport is an
+     * ancestor — the host's conversation scroll body), or the scrollport itself when the caller owns one
+     * (a virtualized list's `getScrollElement()`). The nearest scroller at or above this node is the one
+     * that gets the listener; see {@link scrollParentOf}. `null` (the ref was not filled yet) makes the
+     * controller inert until the caller recreates it, which is what an effect that ran before the ref
+     * was set needs.
+     */
+    readonly target: ScrollElement | null;
+    /**
+     * Read on EVERY check, never captured: a check can run long after the controller was created, and a
+     * captured `true` would keep loading pages after the caller disabled it (loading, no rows left).
+     */
+    readonly isEnabled: () => boolean;
+    /** Asked for the next page. The caller owns the re-entrancy guard (`loading`), as with a click. */
+    readonly onLoadMore: () => void;
+    /** Initial data version (a row count). See {@link AutoLoadMore.setVersion}. */
+    readonly version?: number;
+    /** Overrides {@link AUTO_LOAD_MORE_MARGIN_PX}; a bigger value prefetches a whole row earlier. */
+    readonly marginPx?: number;
+}
+/** The handle `createAutoLoadMore` returns. Every method is safe to call after `dispose`. */
+export interface AutoLoadMore {
+    /**
+     * Check the scroll position RIGHT NOW, synchronously — the explicit entry for the two cases no
+     * scroll event covers: a page that did not fill the scrollport, and a virtualized list whose range
+     * reached its last row without the scroll position moving. Call it after a render.
+     */
+    recheck(): void;
+    /**
+     * Report a new data version (a row count, a page id). Re-checks once when the value actually
+     * changed, so a wrapper can call it on every render: the page that just landed changed the version
+     * and the next one is requested even though nothing scrolled.
+     *
+     * @returns whether the value changed — and therefore whether a check just ran. A wrapper that also
+     * has other re-check reasons (a gate reopening) can use this to run exactly ONE check per commit
+     * instead of one per reason.
+     */
+    setVersion(version: number): boolean;
+    /** Remove the listener, cancel the queued frame, drop the callback. Idempotent. */
+    dispose(): void;
+}
+/**
+ * The nearest element that actually scrolls `node`, at or above it.
+ *
+ * The criterion is the computed `overflow-y` (`auto`/`scroll`) AND "it really overflows"
+ * (`scrollHeight > clientHeight`): a host's wrapper elements are `overflow-y:auto` long before their
+ * content is taller than they are, and binding to one of those would listen to an element that never
+ * emits a scroll. A `null` result is therefore honest — nothing here scrolls — and the listener falls
+ * back to `window` (see {@link createAutoLoadMore}).
+ *
+ * `node` ITSELF is considered first. A panel normally passes its root (the scrollport is an ancestor:
+ * the host's conversation scroll body), but a list that owns its scroller — a virtualized list whose
+ * `getScrollElement()` is its own container — passes that container, which is the very element
+ * scroll events fire on. Scroll events do not bubble between scrollers, so getting THIS element (not
+ * some ancestor) is what makes such a list work.
+ */
+export declare function scrollParentOf(node: ScrollElement | null): ScrollElement | null;
+/**
+ * Build the controller: listen for scroll (passive + one rAF per burst), check once immediately, and
+ * stay silent while `isEnabled()` is false.
+ *
+ * The immediate first check is not an optimisation: the first page of a short list does not fill the
+ * scrollport, so waiting for a scroll event means waiting forever.
+ *
+ * @param options - see {@link AutoLoadMoreOptions}. Read at creation: `scrollParentOf` runs once, so a
+ * panel that later gets its own scroller must dispose and recreate the controller.
+ */
+export declare function createAutoLoadMore(options: AutoLoadMoreOptions): AutoLoadMore;
+//# sourceMappingURL=load_more.d.ts.map

package/lib/client/load_more.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load_more.d.ts","sourceRoot":"","sources":["../../src/client/load_more.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,sFAAsF;AACtF,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAE3C;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,IAAI,CAAA;IAC5C,QAAQ,CAAC,aAAa,EAAE,cAAc,GAAG,IAAI,CAAA;IAC7C,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAA;IACpG,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;CAChE;AAED,sFAAsF;AACtF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,UAAU,GAAG,IAAI,CAAA;CACxC;AAED,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;CACzE;AAED,oGAAoG;AACpG,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAA;IACrC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAA;IACjC,mGAAmG;IACnG,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAA;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,iGAAiG;IACjG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,6FAA6F;AAC7F,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,OAAO,IAAI,IAAI,CAAA;IACf;;;;;;;;OAQG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;IACpC,mFAAmF;IACnF,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,GAAG,aAAa,GAAG,IAAI,CAU/E;AA0DD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAsG7E"}

package/lib/client/load_more.js

@@ -0,0 +1,252 @@
+/**
+ * "Scroll to the end → load the next page", as one DOM controller.
+ *
+ * **INTERNAL — no stability promise** (内部控制件，不承诺稳定): this module is reachable only through
+ * the `./internal` subpath, which the interface generation never covers (`docs/INTERFACE.md` §2/§5).
+ * It is not on `.`, it is not frozen with a generation, and a rename or a changed option shape is a
+ * base release, not a generation. Consumers (mem's 记忆 tab, mission's paged lists) follow the base.
+ *
+ * Why a DOM controller and not a React hook: this base has NO `react` peer (`package.json`), and it
+ * must stay that way — a Node user of the base must not be pulled into React, and the base ships no
+ * browser artifact. So the listener, the rAF throttle and the scrollport lookup live here, and each
+ * plugin keeps a thin wrapper of its own (mem: `useLoadMoreOnScroll`). The DOM detail then exists
+ * once instead of once per panel.
+ *
+ * Why the DOM types below are STRUCTURAL instead of `lib.dom`: the base compiles with `lib: es2023`
+ * and `types: node`, and adding `DOM` there retypes globals for the whole package (it breaks `fetch`
+ * bodies across the existing suite, for one). This module instead names the exact slice it reads —
+ * element, document, view — so the base stays node-only, its unit test needs no DOM environment, and
+ * a real `HTMLElement` / `Window` satisfies the interfaces as-is.
+ *
+ * Why a scroll listener and not an `IntersectionObserver` (three reasons measured in mem's panel):
+ *
+ * 1. **`rootMargin` cannot prefetch here.** A plugin panel usually owns no scrollport — the host's
+ *    conversation scroll body does — and an ancestor's clip rect is NOT expanded by `rootMargin`
+ *    (only the intersection root's is), so the promised look-ahead never happens.
+ * 2. **An observer only reports threshold CHANGES.** One page that failed to load leaves the
+ *    sentinel visible, so no new callback arrives and auto-load stays dead until something else
+ *    moves it. A scroll listener is level-triggered: the next scroll event simply tries again.
+ * 3. **The scrollport is found, not assumed.** {@link scrollParentOf} walks up to whatever element
+ *    really scrolls, so this keeps working if a panel ever gets its own scroller.
+ *
+ * The gap the listener alone cannot close — and why {@link AutoLoadMore.recheck} exists: a page that
+ * does NOT fill the scrollport produces no scroll event, and neither does a virtualized list that
+ * reaches its last row (the virtualizer window moves, the scroll position does not). Callers
+ * therefore re-check after a render (`recheck`), and after the data version changes
+ * (`setVersion`, which re-checks only when the number really moved).
+ *
+ * **Where the controller stops (the host boundary).** {@link scrollParentOf} has exactly one
+ * criterion for a scrollport: the element's OWN computed `overflow-y` is `auto`/`scroll` AND its
+ * `scrollHeight > clientHeight`. Two things follow, and both are deliberate rather than bugs to
+ * paper over here:
+ *
+ * - **A host whose PAGE is the scroller silently does not auto-load.** With no element satisfying the
+ *   criterion, {@link createAutoLoadMore} still attaches the listener to `window` (so nothing throws,
+ *   and a scrollport that appears later is picked up), but `check()` refuses to fire while it has no
+ *   scroller: there is no position to read, so the `window` listener alone changes nothing. The
+ *   caller then owns the gap — call {@link AutoLoadMore.recheck} from its own render/commit path, or
+ *   pass a real scrollport as `target` (e.g. `document.scrollingElement`, or the element whose
+ *   `scrollHeight` the page grows).
+ * - **The scrollport is resolved once, at creation.** A panel that gains (or replaces) its own
+ *   scroller later must `dispose()` and recreate the controller; `check` re-probes only while it has
+ *   no scroller at all.
+ *
+ * @module client/load_more
+ */
+/** Distance from the scrollport's end, in px, at which the next page is requested. */
+export const AUTO_LOAD_MORE_MARGIN_PX = 300;
+/**
+ * The nearest element that actually scrolls `node`, at or above it.
+ *
+ * The criterion is the computed `overflow-y` (`auto`/`scroll`) AND "it really overflows"
+ * (`scrollHeight > clientHeight`): a host's wrapper elements are `overflow-y:auto` long before their
+ * content is taller than they are, and binding to one of those would listen to an element that never
+ * emits a scroll. A `null` result is therefore honest — nothing here scrolls — and the listener falls
+ * back to `window` (see {@link createAutoLoadMore}).
+ *
+ * `node` ITSELF is considered first. A panel normally passes its root (the scrollport is an ancestor:
+ * the host's conversation scroll body), but a list that owns its scroller — a virtualized list whose
+ * `getScrollElement()` is its own container — passes that container, which is the very element
+ * scroll events fire on. Scroll events do not bubble between scrollers, so getting THIS element (not
+ * some ancestor) is what makes such a list work.
+ */
+export function scrollParentOf(node) {
+    let current = node;
+    while (current !== null) {
+        const overflowY = computedOverflowY(current);
+        if ((overflowY === 'auto' || overflowY === 'scroll') && current.scrollHeight > current.clientHeight) {
+            return current;
+        }
+        current = current.parentElement;
+    }
+    return null;
+}
+/**
+ * The computed `overflow-y` of `element`, read off ITS OWN document's view.
+ *
+ * Not the bare `getComputedStyle` global: this module also runs under a test double or inside a
+ * detached document, and both need the style to come from somewhere explicit. An element with no
+ * view (no document, or a document without a window) reports `''` — "not a scrollport", the safe
+ * answer.
+ */
+function computedOverflowY(element) {
+    const view = element.ownerDocument?.defaultView;
+    if (view === null || view === undefined)
+        return '';
+    return view.getComputedStyle(element).overflowY;
+}
+/**
+ * Where to listen: the scrollport when one was found, else `window`.
+ *
+ * The `window` fallback is the case the seat's own history taught: a panel can be mounted in a
+ * document whose scrollport is the page itself. Listening there costs nothing, but the POSITION check
+ * still needs a scrollport, so nothing fires until an ancestor with its own scrollbar appears (or the
+ * caller drives {@link AutoLoadMore.recheck}). `null` only in a host without a `window` at all.
+ */
+function scrollEventSource(scroller) {
+    if (scroller !== null)
+        return scroller;
+    const view = globalThis['window'];
+    if (view === null || view === undefined || typeof view !== 'object')
+        return null;
+    const candidate = view;
+    if (typeof candidate.addEventListener !== 'function')
+        return null;
+    if (typeof candidate.removeEventListener !== 'function')
+        return null;
+    return view;
+}
+/**
+ * The host's animation-frame pair, read off `globalThis` (`lib.dom` is not in this package's types, and
+ * a node host has neither function — the controller then checks synchronously, its pre-rAF behaviour).
+ */
+function animationFrames() {
+    const host = globalThis;
+    const candidate = host;
+    if (typeof candidate.requestAnimationFrame !== 'function')
+        return null;
+    if (typeof candidate.cancelAnimationFrame !== 'function')
+        return null;
+    return host;
+}
+/**
+ * Build the controller: listen for scroll (passive + one rAF per burst), check once immediately, and
+ * stay silent while `isEnabled()` is false.
+ *
+ * The immediate first check is not an optimisation: the first page of a short list does not fill the
+ * scrollport, so waiting for a scroll event means waiting forever.
+ *
+ * @param options - see {@link AutoLoadMoreOptions}. Read at creation: `scrollParentOf` runs once, so a
+ * panel that later gets its own scroller must dispose and recreate the controller.
+ */
+export function createAutoLoadMore(options) {
+    const marginPx = options.marginPx ?? AUTO_LOAD_MORE_MARGIN_PX;
+    // Lazy on purpose: `scrollParentOf` only calls an element a scrollport when it is ALREADY taller
+    // than its viewport, and a controller is created before the first page of results is rendered — an
+    // empty (or short) result list answers "no scrollport" and would otherwise stay unscrollable
+    // forever. `check` re-probes and binds the moment an ancestor grows a scrollbar.
+    let scroller = scrollParentOf(options.target);
+    let source = scrollEventSource(scroller);
+    const frames = animationFrames();
+    let onLoadMore = options.onLoadMore;
+    let version = options.version ?? 0;
+    let disposed = false;
+    let queued = false;
+    let frame = null;
+    /** Bumped whenever a queued frame is superseded, so a callback the host still runs is a no-op. */
+    let generation = 0;
+    /** Move the listener onto `next`: the window fallback may be holding it, and a stale element listener
+     *  would keep listening on a node that no longer scrolls. */
+    const bind = (next) => {
+        if (next === scroller)
+            return;
+        source?.removeEventListener('scroll', onScroll);
+        scroller = next;
+        source = scrollEventSource(next);
+        source?.addEventListener('scroll', onScroll, { passive: true });
+    };
+    const check = () => {
+        frame = null;
+        queued = false;
+        if (disposed || onLoadMore === null)
+            return;
+        if (scroller === null) {
+            const found = scrollParentOf(options.target);
+            if (found === null)
+                return;
+            bind(found);
+        }
+        if (scroller === null)
+            return;
+        if (!options.isEnabled())
+            return;
+        // Level-triggered: "the end is within reach" is a POSITION, not an edge, so a page that failed is
+        // retried by the next scroll event instead of waiting for a threshold crossing that never comes.
+        if (scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - marginPx)
+            onLoadMore();
+    };
+    /**
+     * Drop the queued frame, if there is one, and make any callback already handed to the host inert.
+     *
+     * Called before a SYNC check (`recheck`/`setVersion`): the frame a scroll just scheduled reads the
+     * same position, so leaving it scheduled asks for the same page twice — the second `onLoadMore`
+     * arrives after the caller's own guard may already have cleared. The generation bump is belt and
+     * braces: a host (or a test) that runs a cancelled callback anyway must not ask again.
+     */
+    const cancelQueued = () => {
+        if (frame !== null && frames !== null)
+            frames.cancelAnimationFrame(frame);
+        frame = null;
+        queued = false;
+        generation += 1;
+    };
+    const onScroll = () => {
+        if (disposed || queued)
+            return;
+        queued = true;
+        // One check per animation frame: a scroll burst is dozens of events, and each check may ask for a
+        // page — that must not happen dozens of times.
+        if (frames === null)
+            check();
+        else {
+            const scheduled = generation;
+            frame = frames.requestAnimationFrame(() => {
+                if (scheduled !== generation)
+                    return; // superseded by a recheck/setVersion
+                check();
+            });
+        }
+    };
+    source?.addEventListener('scroll', onScroll, { passive: true });
+    check(); // the first page may leave the scrollport unfilled
+    return {
+        recheck() {
+            if (disposed)
+                return;
+            // A frame is queued from a scroll that just happened: this synchronous check supersedes it.
+            cancelQueued();
+            check();
+        },
+        setVersion(next) {
+            if (disposed || next === version)
+                return false;
+            version = next;
+            // Same supersede rule as `recheck`: one commit, one check, one possible ask.
+            cancelQueued();
+            check();
+            return true;
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            onLoadMore = null;
+            source?.removeEventListener('scroll', onScroll);
+            if (frame !== null && frames !== null)
+                frames.cancelAnimationFrame(frame);
+            frame = null;
+            queued = false;
+        },
+    };
+}
+//# sourceMappingURL=load_more.js.map

package/lib/conformance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAIV,WAAW,EACX,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EAGf,QAAQ,EAKT,MAAM,YAAY,CAAA;AAEnB,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAA;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAC7C;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;IACxC,kFAAkF;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,wEAAwE;IACxE,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5C,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,CAAC,EAAE,WAAW,CAAA;IACzB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAA;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAA;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAA;IACjC,gFAAgF;IAChF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAA;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,cAAc,CAAA;CAC9B;AA+JD,2FAA2F;AAC3F,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA4mBpG;AAED,2EAA2E;AAC3E,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAMzE"}
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAIV,WAAW,EACX,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EAGf,QAAQ,EAKT,MAAM,YAAY,CAAA;AAEnB,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;AAE7D,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAA;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAC7C;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;IACxC,kFAAkF;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,wEAAwE;IACxE,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5C,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,CAAC,EAAE,WAAW,CAAA;IACzB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAA;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAA;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAA;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAA;IACjC,gFAAgF;IAChF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAA;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,cAAc,CAAA;CAC9B;AAoKD,2FAA2F;AAC3F,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA4mBpG;AAED,2EAA2E;AAC3E,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAMzE"}

package/lib/conformance.js

@@ -54,11 +54,16 @@ function recordingFs(inner) {
     const mutations = [];
     // Recording is on by default.
     let recording = true;
+    // Bound once: `realpath` is optional on the seam, and forwarding it only when the wrapped fs has it
+    // keeps the kit honest about the documented path-level fallback (a kit-invented realpath would hide
+    // the difference between "resolved" and "spelled"). Read-only, so nothing is recorded.
+    const realpath = inner.realpath?.bind(inner);
     const note = (op, path, to) => {
         if (recording)
             mutations.push(to === undefined ? { op, path } : { op, path, to });
     };
     const fs = {
+        ...(realpath === undefined ? {} : { realpath }),
         readFile: path => inner.readFile(path),
         readdir: path => inner.readdir(path),
         stat: path => inner.stat(path),