@avantf/dsh-plugin-base 0.6.0 → 0.6.1

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.6.0";
+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.6.0';
+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/internal.d.ts

@@ -43,6 +43,8 @@ export { NPM_PACKAGE_KIND, npmPackageProvider } from './providers/npm.js';
 export type { NpmPackageSpec } from './providers/npm.js';
 export { RUNTIME_DEPS_DIR, RUNTIME_DEPS_KIND, gcRuntimeDeps, runtimeDepsLockPath, runtimeDepsProvider, runtimeDepsStore, } from './providers/runtime_deps.js';
 export type { DependencySource, InstallAttempt, RuntimeDepsAttemptRecord, RuntimeDepsGcOptions, RuntimeDepsGcReport, RuntimeDepsProviderOptions, RuntimeDepsRecord, RuntimeDepsRunInput, RuntimeDepsRunResult, RuntimeDepsSpec, } from './providers/runtime_deps.js';
+export { AUTO_LOAD_MORE_MARGIN_PX, createAutoLoadMore, scrollParentOf } from './client/load_more.js';
+export type { AutoLoadMore, AutoLoadMoreOptions, ScrollDocument, ScrollElement, ScrollView } from './client/load_more.js';
 export { createPluginLogger } from './kit/logger.js';
 export type { PluginLogger, PluginLoggerHost, PluginLoggerOptions } from './kit/logger.js';
 export { endpointId, fieldSymbol, resultSymbol, strictCodec } from './kit/typert.js';

package/lib/internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACrC,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC9H,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,UAAU,EACV,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAC7D,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,SAAS,EACT,aAAa,EACb,YAAY,EACZ,UAAU,EACV,UAAU,EACV,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAChG,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,WAAW,EACX,eAAe,EACf,yBAAyB,EACzB,mCAAmC,EACnC,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,aAAa,GACd,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACxD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,iBAAiB,EAAE,SAAS,EAAE,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AACvM,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAC5D,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,sBAAsB,EACtB,WAAW,EACX,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,cAAc,EACd,UAAU,EACV,cAAc,EACd,UAAU,EACV,QAAQ,EACR,cAAc,GACf,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,iBAAiB,EACjB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAO5E,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,OAAO,EACP,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AACxF,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACzE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAGxD,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,6BAA6B,CAAA;AACpC,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,wBAAwB,EACxB,oBAAoB,EACpB,mBAAmB,EACnB,0BAA0B,EAC1B,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,GAChB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACpD,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAC1F,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AACpF,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"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"}

package/lib/internal.js

@@ -42,6 +42,25 @@ export { NPM_PACKAGE_KIND, npmPackageProvider } from './providers/npm.js';
 // The runtime-deps store's operator/maintenance half. The PROVIDER itself is on `.` (v5); GC, the
 // store paths and the runner seams are explicit operator/test surface and stay off the interface.
 export { RUNTIME_DEPS_DIR, RUNTIME_DEPS_KIND, gcRuntimeDeps, runtimeDepsLockPath, runtimeDepsProvider, runtimeDepsStore, } from './providers/runtime_deps.js';
+// ── the browser-side kit ────────────────────────────────────────────────────────────────────────
+// "Scroll to the end → load the next page", shared by the panels that page a list (mem's 记忆 tab,
+// mission's paged lists). It lives HERE for two reasons, and neither changes the generation:
+// `.` must not grow a browser-only member, and the base has no `react` peer, so the controller is
+// plain DOM and each plugin keeps its own thin React wrapper. A client bundle INLINES this module (a
+// browser cannot load the base at runtime), which is why it reads no node built-in and holds no
+// shared runtime identity. Internal means internal: no compatibility promise, no generation entry,
+// changeable in any base release.
+export { AUTO_LOAD_MORE_MARGIN_PX, createAutoLoadMore, scrollParentOf } from './client/load_more.js';
+// …and the shared CONTROL STYLES, on the same terms. Not a value export: a stylesheet is not a
+// module this package can re-export, so it is its own subpath — `./internal/controls.module.css`,
+// mapped to `src/client/controls.module.css` (source, shipped as-is; `controls_css.spec.ts` pins
+// that). A plugin's client build writes
+//
+//   import controls from '@avantf/dsh-plugin-base/internal/controls.module.css'
+//
+// and INLINES it: the CSS Modules pipeline hashes the classes from this file and injects one style
+// tag, so the base still needs no browser artifact and no plugin fetches anything at runtime. mem's
+// 记忆 tab is the first consumer; mission follows.
 export { createPluginLogger } from './kit/logger.js';
 export { endpointId, fieldSymbol, resultSymbol, strictCodec } from './kit/typert.js';
 //# sourceMappingURL=internal.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avantf/dsh-plugin-base",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "The @avantf family base for DSH plugins: startup environment initialisation (declare → probe → fetch → verify → report), the host compatibility gate (provision / verdictOf / probes / report / post-registration verification), and one content-addressed shared store for runtime npm dependencies (runtimeDepsProvider). One package, loaded by the plugins through the inlined bootstrap.",
   "keywords": [
     "dsh",
@@ -39,6 +39,7 @@
       "types": "./lib/internal.d.ts",
       "default": "./lib/internal.js"
     },
+    "./internal/controls.module.css": "./src/client/controls.module.css",
     "./compat": {
       "types": "./lib/compat.d.ts",
       "default": "./lib/compat.js"
@@ -48,27 +49,13 @@
   "files": [
     "lib",
     "!lib/*.js.map",
-    "!lib/**/*.js.map"
+    "!lib/**/*.js.map",
+    "src/client/*.module.css"
   ],
   "sideEffects": false,
   "peerDependencies": {
     "zod": ">=4.4.3 <5"
   },
-  "scripts": {
-    "setup": "pnpm install --frozen-lockfile --ignore-scripts --config.strictDepBuilds=false",
-    "compile": "pnpm build",
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "node scripts/link-dsh.mjs && tsc -p tsconfig.test.json",
-    "test": "node scripts/link-dsh.mjs && vitest run",
-    "check": "pnpm typecheck && pnpm test",
-    "pack": "node scripts/pack.mjs",
-    "release:check": "node scripts/release-check.mjs",
-    "version:check": "node scripts/version.mjs check",
-    "version:set": "node scripts/version.mjs set",
-    "version:prune": "node scripts/version.mjs prune",
-    "prepack": "pnpm build",
-    "prepublishOnly": "node scripts/prepublish-assert.mjs --package @avantf/dsh-plugin-base && pnpm release:check"
-  },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "^5.5.0",
@@ -84,5 +71,18 @@
     "type": "git",
     "url": "git@gitee.com:ffeng86/dsh-plugin-base.git"
   },
-  "author": "qunqi.ff"
-}
+  "author": "qunqi.ff",
+  "scripts": {
+    "setup": "pnpm install --frozen-lockfile --ignore-scripts --config.strictDepBuilds=false",
+    "compile": "pnpm build",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "node scripts/link-dsh.mjs && tsc -p tsconfig.test.json",
+    "test": "node scripts/link-dsh.mjs && vitest run",
+    "check": "pnpm typecheck && pnpm test",
+    "pack": "node scripts/pack.mjs",
+    "release:check": "node scripts/release-check.mjs",
+    "version:check": "node scripts/version.mjs check",
+    "version:set": "node scripts/version.mjs set",
+    "version:prune": "node scripts/version.mjs prune"
+  }
+}

package/src/client/controls.module.css

@@ -0,0 +1,294 @@
+/*
+ * Shared CONTROL styles for the avantf DSH plugin family — the one source.
+ *
+ * **INTERNAL — no stability promise** (内部控制件，不承诺稳定): reachable only through the
+ * `./internal/controls.module.css` 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 renamed
+ * class is a base release, not a generation.
+ *
+ * Why a stylesheet and not components: this base has NO `react` peer and ships no browser artifact
+ * (`package.json`), and it must stay that way. So the family shares the STYLE LAYER and each plugin
+ * keeps its own markup (mem renders with `h()`, mission with its own view modules). A plugin's
+ * CLIENT BUILD inlines this file — the DSH client preset's CSS Modules loader compiles
+ * `<plugin>/src/client/*.module.css` into a hashed class map plus an injected `<style>` tag — which
+ * is why the file is published as SOURCE (`src/client/`, listed in `files`) and why nothing here
+ * reads the filesystem, imports another file, or assumes a build step in the base.
+ *
+ * The visual baseline is DSH's own design platform, not any one plugin:
+ *
+ *  - every colour/radius is a `--dsw-*` token (`packages/client/ui-theme/src/styles/design-platform.css`
+ *    for `--dsw-alias-*`, `base.css` for `--dsw-radius-*`); there is not a single colour literal here,
+ *    which `test/controls_css.spec.ts` enforces;
+ *  - the button is `ui-primitives`' Button (same box, same `sm` / `md` sizes, same
+ *    primary / ghost / outline variants, same disabled opacity), with `active` taken from the
+ *    `--dsw-alias-button-ghost-active-*` family (what a selected toggle looks like in the shell);
+ *  - the field controls are the shell's input box (`ui-settings-models`' `.input`: 0.5px `border-l4`,
+ *    `radius-md`, `bg-layer-1`, 14/22 type, focus turns the border to `state-business-primary`);
+ *  - the card is the shell's settings material (`--dsw-alias-settings-card-fill/-stroke`, published
+ *    on `body` by `ui-theme/src/styles/base.css`), at `radius-md` because plugin panels list rows,
+ *    not settings sections.
+ *
+ * What is deliberately NOT here: page layout (columns, sticky bars, toolbars, dialogs) stays in each
+ * plugin, and so does anything that names a plugin's own semantics (status hues, warn/err boxes with
+ * a plugin-specific sentence). A plugin adds its own class for those; this file owns the shape.
+ *
+ * Consuming it (mem is the first consumer, mission follows):
+ *
+ *   import controls from '@avantf/dsh-plugin-base/internal/controls.module.css'
+ *   <button className={`${controls.button} ${controls.sm} ${controls.outline}`} />
+ *
+ * The class map is hashed per stylesheet by lightningcss (`[hash]_[local]`), so two plugins that
+ * inline this file never collide — and neither do two plugins' own stylesheets.
+ */
+
+/* ── Buttons ─────────────────────────────────────────────────────────────────────────────────────
+ * One geometry (`.button`) + one size (`sm` 28px / `md` 36px) + one variant (`primary` / `ghost` /
+ * `outline` / `danger`) + the selected state (`active`). Composed at the call site, exactly like the
+ * shell's `Button` composes its own classes.
+ */
+.button {
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 4px;
+  padding: 0 14px;
+  border: none;
+  border-radius: var(--dsw-radius-md);
+  background: transparent;
+  color: var(--dsw-alias-label-primary);
+  font: inherit;
+  font-size: 14px;
+  line-height: 22px;
+  cursor: pointer;
+}
+
+.button:disabled {
+  cursor: not-allowed;
+  opacity: 0.4;
+}
+
+.md {
+  height: 36px;
+}
+
+.sm {
+  height: 28px;
+  padding: 0 10px;
+  border-radius: var(--dsw-radius-sm);
+  font-size: 12px;
+  line-height: 18px;
+}
+
+.primary {
+  background: var(--dsw-alias-button-primary-fill);
+  color: var(--dsw-alias-label-primary-foreground);
+}
+
+/* The transparent border preserves the layout; the inset stroke stays complete at fractional widths. */
+.outline {
+  border: 0.5px solid transparent;
+  background: transparent;
+  box-shadow: inset 0 0 0 var(--dsh-hairline-width, 0.5px) var(--dsw-alias-border-l3);
+}
+
+/* The error colour is `state-error-primary`: it is the token `design-platform.css` DEFINES. (mem's
+   old rules read `--dsw-alias-label-error`, which that sheet does not define — the declaration was
+   invalid at computed-value time and the text simply inherited the row's colour.) */
+.danger {
+  color: var(--dsw-alias-state-error-primary);
+}
+
+/* A selected toggle: the shell's ghost-active material, so "this filter is on" reads the same here
+   as it does in the shell's own toolbars. */
+.active {
+  background: var(--dsw-alias-button-ghost-active-fill);
+  box-shadow: inset 0 0 0 var(--dsh-hairline-width, 0.5px) var(--dsw-alias-button-ghost-active-border);
+  color: var(--dsw-alias-label-primary);
+}
+
+@media (hover: hover) {
+  .primary:hover:not(:disabled) {
+    background: var(--dsw-alias-button-primary-hover);
+  }
+
+  .ghost:hover:not(:disabled) {
+    background: var(--dsw-alias-interactive-bg-hover);
+  }
+
+  .outline:hover:not(:disabled) {
+    background: var(--dsw-alias-interactive-bg-hover);
+  }
+
+  .danger:hover:not(:disabled) {
+    background: var(--dsw-alias-interactive-bg-hover-danger);
+  }
+
+  .active:hover:not(:disabled) {
+    background: var(--dsw-alias-button-ghost-active-hover);
+  }
+}
+
+.ghost:active:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-active);
+}
+
+/* ── Text roles ─────────────────────────────────────────────────────────────────────────────────── */
+
+/* A neutral chip. A status TINT is a plugin's own class (its hue is the plugin's vocabulary); this
+   is the shape every tinted chip starts from. */
+.badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 0 6px;
+  border-radius: var(--dsw-radius-xs);
+  background: var(--dsw-alias-interactive-bg-hover);
+  color: var(--dsw-alias-label-secondary);
+  font-size: 11px;
+  line-height: 18px;
+}
+
+.list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* The shell's settings-card material, one step tighter: plugin panels list rows, they are not
+   settings sections. */
+.item {
+  padding: 10px 12px;
+  border: 0.5px solid var(--dsw-alias-settings-card-stroke);
+  border-radius: var(--dsw-radius-md);
+  background: var(--dsw-alias-settings-card-fill);
+  color: var(--dsw-alias-label-primary);
+  font-size: 13px;
+  line-height: 20px;
+}
+
+/* Secondary line inside a row (an id, a count, a timestamp). `block` because it always follows the
+   row's primary line. */
+.meta {
+  display: block;
+  margin-top: 2px;
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+/* A whole-line status sentence: the same type as `.meta` without the block/margin behaviour. */
+.status {
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+/* A failure the reader must be able to copy out: pre-wrap so a multi-line host message keeps its
+   own line breaks. */
+.error {
+  font-size: 12px;
+  line-height: 18px;
+  color: var(--dsw-alias-state-error-primary);
+  white-space: pre-wrap;
+}
+
+/* ── Fields ───────────────────────────────────────────────────────────────────────────────────── */
+
+/*
+ * The shared box. Width is NOT set here: a control sizes itself, and its container decides how wide
+ * it is (a field column stretches it, a toolbar row leaves it intrinsic). Every variant below adds
+ * only what makes it different.
+ */
+.input,
+.textarea,
+.select,
+.dateInput {
+  box-sizing: border-box;
+  min-width: 0;
+  padding: 0 10px;
+  border: 0.5px solid var(--dsw-alias-border-l4);
+  border-radius: var(--dsw-radius-md);
+  background: var(--dsw-alias-bg-layer-1);
+  color: var(--dsw-alias-label-primary);
+  font: inherit;
+  font-size: 14px;
+  line-height: 22px;
+}
+
+/* Single-line controls share the shell's 32px control height. */
+.input,
+.select,
+.dateInput {
+  height: 32px;
+}
+
+/* The shell keeps the global `:focus-visible` ring and turns the border to the accent; it never
+   removes the ring, and neither does this. */
+.input:focus-visible,
+.textarea:focus-visible,
+.select:focus-visible,
+.dateInput:focus-visible {
+  border-color: var(--dsw-alias-state-business-primary);
+}
+
+.input::placeholder {
+  color: var(--dsw-alias-label-dimmed);
+}
+
+.input:disabled,
+.textarea:disabled,
+.select:disabled,
+.dateInput:disabled {
+  opacity: 0.6;
+  cursor: default;
+}
+
+/* Fills the field it is placed in; a textarea has no intrinsic width worth showing. */
+.textarea {
+  width: 100%;
+  padding: 6px 10px;
+  resize: vertical;
+}
+
+.select {
+  cursor: pointer;
+}
+
+/* A native date input: same box, digits lined up in the row (`2026-10-26` next to a `~` separator
+   must not jitter). */
+.dateInput {
+  padding: 0 8px;
+  font-variant-numeric: tabular-nums;
+}
+
+/*
+ * The "clear this field" × — the shape only. A plugin places it (mem hangs it inside its search
+ * field); the button itself must not assume a positioned ancestor.
+ */
+.clear {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  padding: 0;
+  border: none;
+  border-radius: 999px;
+  background: transparent;
+  color: var(--dsw-alias-label-tertiary);
+  font: inherit;
+  font-size: 14px;
+  line-height: 1;
+  cursor: pointer;
+}
+
+@media (hover: hover) {
+  .clear:hover {
+    background: var(--dsw-alias-interactive-bg-hover);
+    color: var(--dsw-alias-label-primary);
+  }
+}