Suggestion: out-of-tree 'browser-half bundle' template + guide for dsh-plugin authors

[andreagosto]

Summary

Providing an out-of-tree browser-half bundle is much harder than the authoring docs imply, and there is no template or guide to copy. docs/cookbook/adding-a-settings-card.md even states: "No published preset exposes this package, so a package outside this repository has to reproduce the same output format itself." The required format (window.__ModuleLoader__.load({ id, factory }) lazy-CJS factory that exports { name, inject, apply }, served via a ./client export + dsh.client manifest) is only discoverable from the internal tsdown.client.ts preset or by reading installed bundles.

Motivation

• Community plugins (topic dsh-plugin) commonly need a browser half; without the monorepo toolchain, authors must reverse-engineer the artifact format by hand.
• Git-installed TypeScript plugins cannot build (no prepare runs), so the community needs a path that ships committed artifacts and a tiny reproducible build step.

Suggested deliverables

A minimal, self-contained out-of-tree template plus a short guide (either in docs/user/develop/ or a new create-dsh-plugin / template repo):

1. package.json with dsh.bundle.patch (cordis.patch.yml), dsh.client.platform: "web", and a ./client export.
2. A scripts/build.mjs that wraps a CJS source fragment into the __ModuleLoader__.load closure factory (committed lib/client.js, so git installs work with no prepare).
3. The minimal Host half (index.js) needed to make the package a Loader entry.
4. Validation/tests (structure + a light smoke test with a fake ctx).

Reference implementation to model on: https://github.com/andreagosto/dsh-tab-watchdog.

[argszero]

@andreagosto

This gap is real and I hit the same wall when I published a browser-half plugin. I verified the actual mechanics against current master so we can turn the "only discoverable from tsdown.client.ts" complaint into a concrete template. Here's what the bundle must actually do:

1. Node half — nearly empty.

// src/index.ts
export function apply(): void {}

The node half just has to exist so the plugin shows up in the host cordis.yml/Loader. The browser half is discovered separately through the dsh.client declaration.

2. The dsh.client manifest (package.json).

{
  "name": "@scope/dsh-plugin-foo",
  "exports": { "./client": "./lib/client/index.js" },
  "dsh": {
    "client": {
      "inject": [
        "@deepseek-ai/dsh-client-locale",
        "@deepseek-ai/dsh-client-ui-conversation",
        "@deepseek-ai/dsh-client-ui-renderer",
        "@deepseek-ai/dsh-client-ui-session"
      ],
      "platform": "web"
    }
  }
}

The inject list is the set of Host client packages your bundle may import across the module-table boundary — this is what makes the "bundle-purity gate rejects value imports" line in adding-a-settings-card.md concrete. Anything beyond those (or any non-contract value import from @deepseek-ai/*) is rejected at build time.

3. The bundle entry — lazy-CJS factory via window.__ModuleLoader__.load.

// the emitted artifact calls this once; the factory is NOT executed at load time
window.__ModuleLoader__.load({
  id: '@scope/dsh-plugin-foo',
  factory(require) {
    // module body side effects (including CSS injection) run here, at materialization
    const { inject, apply } = require('./index.js')
    return { name: 'dsh-plugin-foo', inject, apply }
  },
})

The factory receives the injected require and resolves externals through the loader's module table (cordis DI entities — no globals, no import map). The ./client export is what tsdown.client.ts compiles into this closure-artifact format.

The real gap is that none of this is any single discoverable doc — the dsh.client schema, the closure-factory contract, and the inject allowlist are spread between packages/client/modules/src/client/manifest.ts, packages/client/tsdown.client.ts, and packages/api/remotes/README.md. Concretely, what would help most:

• A starter template (package.json + dsh.client + a minimal ./client bundle + a tsdown.client.ts-driven build config) that a plugin author can copy.
• A one-page guide pointing at the three source files above, so the author isn't reverse-engineering the closure-factory format.

I've had to assemble exactly this template to publish my own browser-half plugins. Happy to post the full copyable template here (package.json + dsh.client + minimal entry) if that would unblock you — I can drop it in this thread rather than waiting on the upstream docs since the content is stable and self-contained. Also worth noting: the emit vs waterfall trap you mentioned (#5897) is a separate but related gap; the API_REMOTE_FORWARDED_EVENTS allowlist in packages/api/remotes/README.md is indeed the only source of truth and it's not reachable from the authoring guides.