@dsh-plugin/dsh-loader 1.1.0-dev.32287576957 → 1.2.0

package/lib/types/ui/menu.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The wrapped platform MENU (`DshMenu`).
+ *
+ * Consumers import this from `@dsh-plugin/dsh-loader/client` instead of
+ * importing `@deepseek-ai/dsh-client-ui-primitives` directly. The wrapper exists
+ * so that changes to the platform primitive — a renamed export, a moved package,
+ * an altered prop shape — are absorbed HERE, in one line's distance, instead of
+ * breaking every plugin that renders a dropdown.
+ *
+ * Two deliberate properties:
+ *
+ *  1. TYPES ARE HAND-WRITTEN, not re-exported. A shipped `.d.ts` that says
+ *     `export { Menu } from '@deepseek-ai/...'` resolves from dshloader's own
+ *     install — which consumers do not have (see docs/ui-kit.md, 铁律三) — so
+ *     re-exported types break consumer typecheck the moment dshloader is
+ *     published without devDependencies. These interfaces are written out and
+ *     must be kept in sync with upstream BY HAND when a prop the plugins use
+ *     changes; that maintenance cost is the price of consumer-side purity.
+ *  2. THE PLATFORM IMPORT IS STATIC AND SINGULAR. This file is the only place in
+ *     dshloader that names the primitives package for menus. If it disappears or
+ *     renames, the fix is contained here. The static import means dshloader's
+ *     client bundle hard-depends on the primitive seed module — the same failure
+ *     mode the direct imports had, so no regression — which is also why the
+ *     missing-module degradation path is NOT attempted: with ESM compiled into
+ *     the CJS closure factory there is no clean way to defer the require, and a
+ *     half-working menu would be worse than an honest load error.
+ *
+ * @module @dsh-plugin/dsh-loader/ui/menu
+ */
+import * as React from 'react';
+/** One selectable row (optionally with a nested submenu). */
+export interface MenuItem {
+    id: string;
+    label: React.ReactNode;
+    disabled?: boolean;
+    /** Leading icon. */
+    icon?: React.ReactNode;
+    /** Destructive row: error-coloured text/icon and danger hover fill. */
+    danger?: boolean;
+    /** Nested card opened to the right on hover/focus. */
+    submenu?: readonly MenuItem[];
+}
+/** Hairline between item groups (not selectable). */
+export interface MenuSeparator {
+    type: 'separator';
+    id: string;
+}
+/** Non-interactive heading row above a group of items. */
+export interface MenuLabel {
+    type: 'label';
+    id: string;
+    text: string;
+}
+/** One primary-menu entry: a row, a separator, or a heading label. */
+export type MenuEntry = MenuItem | MenuSeparator | MenuLabel;
+/** {@link DshMenu} props — structurally the platform Menu's contract. */
+export interface DshMenuProps {
+    /** Whether the list is showing (owner-controlled). */
+    open: boolean;
+    /** The trigger element (rendered in place). */
+    anchor: React.ReactNode;
+    /** Selectable rows and optional separators/labels. */
+    items: readonly MenuEntry[];
+    /** Rows pinned below the scrolling items area. */
+    footer?: readonly MenuEntry[];
+    /** Row shown as selected. */
+    selectedId?: string | undefined;
+    /** Rows shown as selected with independent option groups. */
+    selectedIds?: readonly string[] | undefined;
+    /** Row click callback (not called for disabled rows). */
+    onSelect: (id: string) => void;
+    /** Invoked on outside click or Escape. */
+    onClose: () => void;
+    /** List alignment against the anchor (default `'start'`). */
+    align?: 'start' | 'end';
+    /** Open below (`'bottom'`, default), above, or to the right of the anchor. */
+    side?: 'bottom' | 'top' | 'right';
+    /**
+     * Render the list into `document.body`, fixed-positioned from the anchor rect.
+     * Use when an ancestor's overflow clipping would crop the in-place list.
+     */
+    portal?: boolean;
+    /**
+     * Close once the pointer has left both trigger and list for the grace period
+     * (default `false` keeps it open until outside click/Escape/selection).
+     */
+    closeOnPointerLeave?: boolean;
+    /** Reduce vertical row spacing only. */
+    dense?: boolean;
+    /** Reduced typography and spacing overall. */
+    compact?: boolean;
+    /** Portal mode only: supply the anchor rect directly. */
+    getAnchorRect?: () => DOMRect | null;
+    /** Extra class on the anchor wrapper. */
+    className?: string;
+}
+/**
+ * The stable menu surface for dshloader consumers.
+ *
+ * Forwards every prop verbatim to the platform primitive — this wrapper's job
+ * is ISOLATION (one import site, hand-owned types), not behaviour change. When
+ * the platform evolves, adaptation code goes here and consumers stay put.
+ */
+export declare function DshMenu(props: DshMenuProps): React.ReactElement | null;

package/lib/types/ui/slots.d.ts

@@ -0,0 +1,152 @@
+/**
+ * The dshloader UI SLOT engine (`ctx.dshLoader.ui` / `__dshLoader__.ui`).
+ *
+ * dsh's Web shell offers official slots for a few places (`settings.section`,
+ * `conversation.chat.node`, …) but not for everything plugins need to decorate.
+ * Today four plugins in this family each hand-roll the same DOM-injection
+ * boilerplate against hardcoded shell selectors:
+ *
+ *   - dsh-thought-buddy   → `[data-conversation-scroll] [role="status"]`
+ *   - dsh-auxiliary       → the Models page's editable model rows
+ *   - dsh-code-review     → `[data-shell-overlay]`, `.dshDesktopDetailsSurface`
+ *   - dsh-better-sidebar  → `#root [data-slot="conversation"]`, theme root, …
+ *
+ * Every one of them re-implements: a MutationObserver, requestAnimationFrame
+ * coalescing, an idempotence guard, self-healing after a React re-render, and
+ * teardown. This module implements that ONCE and moves the shell selectors into
+ * a named ANCHOR TABLE the version adapter owns — so when dsh moves its DOM,
+ * one anchor entry changes instead of four plugins.
+ *
+ * What it cannot do: invent an anchor that no longer exists. A vanished anchor
+ * turns N silent breakages into ONE diagnosable one (`ui.diagnose()`), which is
+ * the honest goal — DOM injection is centralised here, not made robust. The
+ * durable fix stays "get the anchor promoted to an official slot".
+ *
+ * @module @dsh-plugin/dsh-loader/ui/slots
+ */
+import * as React from 'react';
+/** Where a mount node is placed relative to its host element. */
+export type InsertMode = 'prepend' | 'append' | 'before' | 'after';
+/** How the active adapter locates one shell anchor. */
+export interface AnchorSpec {
+    /** Human-readable description, used by {@link UiAPI.diagnose}. */
+    describe: string;
+    /** Primary locator. Return every element that should host a mount. */
+    find: () => Iterable<Element>;
+    /**
+     * Fallback locator, tried only when `find` yields nothing. Lets an anchor
+     * survive a narrow selector going stale (the pattern thought-buddy uses:
+     * scoped selector first, whole-document second).
+     */
+    fallback?: () => Iterable<Element>;
+    /** Extra predicate a candidate must satisfy (e.g. matching text content). */
+    accept?: (host: Element) => boolean;
+    /** Placement of the mount node. Defaults to `'append'`. */
+    insert?: InsertMode;
+    /** Tag name for the generated mount node. Defaults to `'span'`. */
+    tagName?: string;
+}
+/** One plugin-supplied mount against an anchor. */
+export interface MountSpec {
+    /**
+     * Unique mount id, `'<plugin>:<what>'`. Doubles as the `data-dshl-slot`
+     * attribute value that makes mounting idempotent.
+     */
+    id: string;
+    /**
+     * Populate the mount node. Called once per host; return a cleanup that
+     * releases whatever was created.
+     */
+    render: (mount: HTMLElement, host: Element) => (() => void) | void;
+    /** Skip this host when the predicate returns false. */
+    when?: (host: Element) => boolean;
+}
+/** A React flavour of {@link MountSpec}. */
+export interface ReactMountSpec {
+    /** Unique mount id, `'<plugin>:<what>'`. */
+    id: string;
+    /** Component rendered into the mount node; receives the host element. */
+    component: React.ComponentType<{
+        host: Element;
+    }>;
+    /** Skip this host when the predicate returns false. */
+    when?: (host: Element) => boolean;
+}
+/** Diagnostics for one registered anchor. */
+export interface AnchorDiagnostic {
+    anchor: string;
+    describe: string;
+    /** Hosts the primary locator currently finds. */
+    hosts: number;
+    /** Whether the fallback locator had to be used. */
+    usedFallback: boolean;
+    /** Mount ids currently registered against this anchor. */
+    mounts: string[];
+    /** Live mount instances across all hosts. */
+    live: number;
+}
+/** The `ui` facade. */
+export interface UiAPI {
+    /**
+     * Register (or replace) an anchor. The adapter seeds the built-ins at boot;
+     * a plugin may add its own for shell areas dshloader does not know yet.
+     * @returns a disposer removing the anchor and unmounting everything on it.
+     */
+    defineAnchor(name: string, spec: AnchorSpec): () => void;
+    /** Anchor names currently registered. */
+    anchors(): string[];
+    /**
+     * The elements an anchor currently resolves to. Use this for anchors that are
+     * READ rather than decorated — e.g. reading the layout frame's collapsed
+     * attribute or grid width instead of mounting into it.
+     */
+    hosts(anchor: string): Element[];
+    /**
+     * Subscribe to "the shell's DOM has settled": called once per coalesced
+     * mutation batch, on the same observer and the same rAF frame the mount sweep
+     * uses.
+     *
+     * This exists for injections whose HOST IDENTIFICATION is itself business
+     * logic and therefore does not fit the anchor model — dsh-auxiliary's model
+     * catalog is the motivating case: it cross-references `aria-label` inputs
+     * against a provider directory, re-reads settings on a debounce, and also
+     * listens for `input` events, so an `AnchorSpec.find()` could never express
+     * it. Such a caller keeps its own sweep but stops running a second
+     * MutationObserver over the whole document.
+     *
+     * The listener MUST be idempotent: it is invoked again after any batch,
+     * including batches its own writes caused.
+     *
+     * @returns an unsubscribe function.
+     */
+    onDomSettled(listener: () => void): () => void;
+    /**
+     * Mount imperative content on every element an anchor resolves to, now and
+     * whenever the shell re-renders. Idempotent per (host, mount id).
+     * @returns a disposer unmounting every instance of this mount.
+     */
+    mount(anchor: string, spec: MountSpec): () => void;
+    /**
+     * Mount a React component on every element an anchor resolves to. A React
+     * root is created per host and unmounted on teardown.
+     * @returns a disposer unmounting every instance of this mount.
+     */
+    mountReact(anchor: string, spec: ReactMountSpec): () => void;
+    /** Snapshot of anchor health — the single place to look when injection stops working. */
+    diagnose(): AnchorDiagnostic[];
+    /** Stop observing and unmount everything (called by the loader's own teardown). */
+    destroy(): void;
+}
+/** Options for {@link createUiAPI}. */
+export interface CreateUiOptions {
+    /** Root to observe. Defaults to `document.documentElement`. */
+    observeRoot?: Element;
+    /** Diagnostic sink; defaults to `console.warn`. */
+    warn?: (message: string) => void;
+}
+/**
+ * Build the `ui` facade with its own observer. One engine serves every anchor
+ * and every mount, so the shell is observed exactly once regardless of how many
+ * plugins inject.
+ */
+export declare function createUiAPI(options?: CreateUiOptions): UiAPI;

package/lib/types/ui/style.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Design tokens and the idempotent stylesheet injector shared by every
+ * dshloader UI component.
+ *
+ * Tokens are the DSH shell's own CSS custom properties, each paired with a
+ * fallback so a component still renders sanely when the shell changes or the
+ * plugin is previewed outside it. The names were harvested from the shell
+ * styling the plugins in this family already rely on; when dsh renames one,
+ * this file is the single place to fix.
+ *
+ * @module @dsh-plugin/dsh-loader/ui/style
+ */
+/** `var(--name, fallback)` — a token reference that degrades instead of breaking. */
+export declare function token(name: string, fallback: string): string;
+/** The DSH shell tokens dshloader components consume. */
+export declare const T: {
+    /** Primary body text. */
+    readonly labelPrimary: string;
+    /** Secondary / supporting text. */
+    readonly labelSecondary: string;
+    /** Tertiary text (hints, units). */
+    readonly labelTertiary: string;
+    /** Caption / disabled text. */
+    readonly labelCaption: string;
+    /** Page / card background. */
+    readonly bgBase: string;
+    /** Raised surface inside a page (shell layer 1). */
+    readonly bgLayer1: string;
+    /** Subtle raised surface. */
+    readonly bgSubtle: string;
+    /** Hover wash for interactive rows. */
+    readonly bgHover: string;
+    /** Default control border. */
+    readonly border: string;
+    /** Lighter divider. */
+    readonly borderSubtle: string;
+    /** Primary button fill — the shell's own button colour, NOT the brand accent. */
+    readonly buttonPrimaryFill: string;
+    /** Text placed on top of {@link buttonPrimaryFill}. */
+    readonly buttonPrimaryForeground: string;
+    /** Brand accent (checked states, focus rings). */
+    readonly accent: string;
+    /** Accent text placed on top of the accent fill. */
+    readonly accentOn: string;
+    /** Destructive accent. */
+    readonly danger: string;
+    /** Success state (saved confirmations). */
+    readonly success: string;
+    /** Monospace stack for code / paths. */
+    readonly fontCode: string;
+};
+/**
+ * Shared control geometry so every dshloader control lines up.
+ *
+ * The values mirror the shell's native settings-page metrics (as established by
+ * dsh-auxiliary's section): pill-shaped primary buttons at height 32, inputs at
+ * height 28 with radius 6, cards with radius 10 and padding 16.
+ */
+export declare const G: {
+    /** Control height for inputs / selects. */
+    readonly controlHeight: 28;
+    /** Compact control height. */
+    readonly controlHeightSm: 24;
+    /** Primary button height (the shell's buttons run taller than inputs). */
+    readonly buttonHeight: 32;
+    /** Standard corner radius (inputs). */
+    readonly radius: 6;
+    /** Card corner radius. */
+    readonly cardRadius: 10;
+    /** Pill radius (primary buttons, switches, chips). */
+    readonly radiusPill: 999;
+    /** Horizontal padding inside an input. */
+    readonly padX: 8;
+    /** Horizontal padding inside a primary button. */
+    readonly padXButton: 14;
+    /** Standard row gap. */
+    readonly gap: 8;
+    /** Base font size. */
+    readonly fontSize: 13;
+    /** Small font size (descriptions). */
+    readonly fontSizeSm: 12;
+};
+/**
+ * Inject a stylesheet once, tagged with the DSH client-module ownership
+ * attributes (`data-plugin` / `data-plugin-css`) so the HMR driver can reclaim
+ * it. Calling this repeatedly with the same `cssId` is a no-op.
+ *
+ * @param pluginId - owning plugin id (package name), for `data-plugin`.
+ * @param cssId - stylesheet id within the plugin, e.g. `'ui/components.css'`.
+ * @param css - the stylesheet text.
+ * @returns a disposer removing the tag, for callers that want one.
+ */
+export declare function injectStyle(pluginId: string, cssId: string, css: string): () => void;
+/** The class-name prefix every dshloader UI class carries. */
+export declare const CX = "dshl";
+/** Join truthy class names. */
+export declare function cx(...parts: Array<string | false | null | undefined>): string;

package/lib/types/version.d.ts

@@ -0,0 +1,2 @@
+export declare const LOADER_VERSION = "1.2.0";
+export declare const LOG_PREFIX = "[dshloader]";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plugin/dsh-loader",
-  "version": "1.1.0-dev.32287576957",
+  "version": "1.2.0",
   "description": "Runtime compatibility shim for dsh (DeepSeek Harness) cordis bundle plugins: decouples third-party plugins from real dsh internal service names, module paths, and RPC details via a version-aware adapter registry.",
   "type": "module",
   "repository": {
@@ -10,7 +10,10 @@
   "main": "dist/index.js",
   "exports": {
     ".": "./dist/index.js",
-    "./client": "./lib/client.js",
+    "./client": {
+      "types": "./lib/types/client-ui.d.ts",
+      "default": "./lib/client.js"
+    },
     "./registry": "./dist/registry.js",
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json",
@@ -23,7 +26,12 @@
     "./tools": "./src/stable/tools.js",
     "./llm": "./src/stable/llm.js",
     "./agent": "./src/stable/agent.js",
-    "./settings": "./src/stable/settings.js"
+    "./settings": "./src/stable/settings.js",
+    "./timeout": "./src/stable/timeout.js",
+    "./subagent": "./src/stable/subagent.js",
+    "./credentials": "./src/stable/credentials.js",
+    "./compaction-basic": "./src/stable/compaction-basic.js",
+    "./patch": "./dist/patch.js"
   },
   "bin": {
     "dshloader": "./bin/dshloader.mjs"
@@ -34,33 +42,55 @@
     "bin",
     "lib/client.js",
     "lib/client.js.map",
+    "lib/types",
     "cordis.patch.yml",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && tsdown --config tsdown.client.config.mjs",
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.client.types.json && tsdown --config tsdown.client.config.mjs",
     "build:host": "tsc -p tsconfig.build.json",
-    "build:client": "tsdown --config tsdown.client.config.mjs",
-    "typecheck": "tsc --noEmit",
+    "build:client": "tsc -p tsconfig.client.types.json && tsdown --config tsdown.client.config.mjs",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.client.json --noEmit",
     "pretest": "npm run build:host",
-    "test": "node --test \"tests/**/*.test.mjs\"",
+    "test": "node --test \"tests/**/*.test.mjs\" && vitest run",
     "test:l1": "node --test \"tests/*.test.mjs\"",
     "test:l2": "node --test \"tests/module/*.test.mjs\"",
     "test:l3": "node --test \"tests/integration/*.test.mjs\"",
+    "test:ui": "vitest run",
     "setup": "node bin/dshloader.mjs setup"
   },
   "engines": {
     "node": ">=18"
   },
   "dependencies": {
+    "@icon-park/react": "^1.4.2",
     "semver": "^7.8.5"
   },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
     "@types/node": "^26.2.0",
+    "@types/react": "^18.3.31",
+    "@types/react-dom": "^18.3.7",
     "@types/semver": "^7.8.0",
+    "jsdom": "^25.0.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "tsdown": "^0.22.2",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "vitest": "^2.1.0"
   },
   "dsh": {
     "bundle": {
@@ -68,7 +98,10 @@
     },
     "client": {
       "platform": "web",
-      "immediately": true
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-primitives"
+      ]
     }
   },
   "license": "LGPL-3.0-only"

package/src/stable/compaction-basic.d.ts

@@ -0,0 +1 @@
+export * from '@deepseek-ai/dsh-compaction-basic';

package/src/stable/compaction-basic.js

@@ -0,0 +1,5 @@
+// Stable re-export: @dsh-plugin/dsh-loader/compaction-basic
+//
+// The BasicCompactionEngine base class plugins subclass.
+// When dsh renames the package, only this file changes.
+export * from '@deepseek-ai/dsh-compaction-basic';

package/src/stable/credentials.d.ts

@@ -0,0 +1 @@
+export * from '@deepseek-ai/dsh-credentials';

package/src/stable/credentials.js

@@ -0,0 +1,5 @@
+// Stable re-export: @dsh-plugin/dsh-loader/credentials
+//
+// Credential references (credentialRef).
+// When dsh renames the package, only this file changes.
+export * from '@deepseek-ai/dsh-credentials';

package/src/stable/subagent.d.ts

@@ -0,0 +1 @@
+export * from '@deepseek-ai/dsh-subagent';

package/src/stable/subagent.js

@@ -0,0 +1,5 @@
+// Stable re-export: @dsh-plugin/dsh-loader/subagent
+//
+// Subagent helpers (delegationDepthOf).
+// When dsh renames the package, only this file changes.
+export * from '@deepseek-ai/dsh-subagent';

package/src/stable/timeout.d.ts

@@ -0,0 +1 @@
+export * from '@deepseek-ai/dsh-timeout';

package/src/stable/timeout.js

@@ -0,0 +1,5 @@
+// Stable re-export: @dsh-plugin/dsh-loader/timeout
+//
+// Timer / deadline helpers (MAX_TIMER_DELAY_MS, deadline).
+// When dsh renames the package, only this file changes.
+export * from '@deepseek-ai/dsh-timeout';