ChatGPTClaudeGrok / X / CursorGemini

DSH plugin client modules: boot graph, bundles, and maps

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessClient modulesWebBootGraphBundle
DSH plugin client modules: dsh.client scanning, WebBootGraph contracts, combo bundle routes and source maps, and pull-model graph notifications.

Client code that fails to load usually did not reach the entry graph — it rarely failed to build. DSH plugin's client module service turns scanning, composing the graph, serving scripts, and injecting index into four faces of one service. Miss any face and the page never receives your bundle.

One service, four faces

It scans, composes, serves scripts, and answers injection, all over one state.(source)

dsh-client-modules is the Node half of the client module system, exposed as ctx.clientModules. It does four things:

  1. scans host Loader entries for packages declaring dsh.client;
  2. composes the window.__DSH_BOOT__ entry graph;
  3. serves versioned single- and multi-resource combo scripts under /plugins;
  4. answers every index injection collection with boot protocol lines.

It is an optional capability of the web GUI stack, outside the agent loop trunk, and a consumer of dsh-host-webserver: the carrier provides the prefix route this service registers and the webserver/index-inject event it answers.

The browser half of the same package (ctx.modules, the lazy CJS table that fetches and materializes those bundles) is kernel machinery documented in the package README, not on this layer.

wire is the single source of truth

The graph's shape is the protocol; a page cannot boot without a valid manifest.(source)

The graph is the single source of truth for the protocol layer between Node and browser halves. The host composes WebBootEntry rows and WebBootBatch descriptors from scanned packages, then contributes four things to the structured index injection table before the Vite entry: a registration facade, application preload, a bootstrap script, and the graph global.

The global row renders as globalThis["__DSH_BOOT__"] with < escaped, so plugin-controlled strings cannot escape the script element.

A page without a valid manifest cannot boot: the browser parser rejects malformed rows or batches, unknown members, and any entry not belonging to exactly one initial combo descriptor.

WebBootEntry fields each do one job: id is the package name; url is a revisioned single-resource combo reference used by HMR and resolved relative to the document; rev is the opaque plugin artifact revision used for HMR cache busting; inject is a package-name dependency edge; immediately marks first-phase prefetching; external carries an exact non-inject module request.

WebBootBatch describes one initial combo script: phase is bootstrap or application and scheduling phases may span descriptors; url is a content-addressed combo reference; rev derives from the ordered entry revisions; entries is the order in which the script registers factories.

WebBootGraph aggregates rev, optional release, entries in module graph order, and batches. Every entry must belong to exactly one descriptor.

Scanning: dsh.client and incremental reconciliation

When different Loader sources resolve to the same package name, composition fails.(source)

A package joins the table by declaring dsh.client in its own package.json (platform: 'web', optional inject edges, optional immediately) and exporting the built bundle at exports["./client"].

Each live row resolves from its own Loader specifier and owning tree baseUrl, using the same implementation as Host face imports when loader.internal.resolveSync is available. The nearest owning package manifest supplies the browser module id, so relative source and built overlays keep package identity.

If different active Loader sources resolve to the same package name, composition fails. After one source unloads, a surviving source provides that row without restarting the fiber.

Reconciliation is incremental by Loader entry name: every Cordis internal/plugin event during fiber construction or disposal marks that fiber's entry names dirty; each non-empty flush enumerates all Loader entries once at the start and indexes them by name; pending names use every same-name source in the index, while missing names use an empty list to remove unloaded sources. Package resolution must not synchronously add or remove Loader entries during reconciliation.

Failure handling has two phases, easily misjudged: during activation, malformed declarations, missing bundles, and flush enumeration failures aggregate into one composition error, failing the fiber and being reported by the startup flow; in steady state, a package failure only logs a warning and does not stop other names from reconciling. An enumeration failure consumes the failed batch, logs one warning, keeps package state and the published graph unchanged, and each affected name retries only on another notification.

Bundle routes and source maps

A combo script is concatenated once; a map is generated on first request.(source)

GET and HEAD on /plugins/??<package-a>/client.js,<package-b>/client.js&rev=<rev> address one generated combo script; single-resource requests use the same form and are also the HMR path. /plugins/<package>/assets/<path> serves package-published images.

The script is concatenated once on first GET and ends with a sourceMappingURL carrying only the combo query string, resolved relative to the script's own directory rather than the document. Boot, index rendering, and script GET and HEAD read no map files; the first map GET reads and validates them, composes an Indexed Source Map v3, and caches that body.

Components with their own maps feed the corresponding section; those without get an identity section whose sourcesContent is the captured bundle and whose source name comes from the packed sourceURL or the plugin route.

Two hard constraints: each boot request URL stays within 3 KiB of UTF-8 bytes with splitting computed by the longer map form; and every application URL is preloaded, while every bootstrap URL executes before the graph global and the Vite entry.

Error paths are explicit: unknown or modified resource lists, missing revisions, and stale revisions all return 404 and never serve other bytes, so the SPA fallback cannot return HTML as JavaScript; other methods return 405.

Read and rebuild surfaces

The graph is a stable object and notifications use a pull model.(source)

ClientModuleRegistry exposes read and rebuild surfaces:

  • graph() returns the current composed graph, the same stable object between changes;
  • clientPath(id) returns the bundle's absolute path;
  • artifactBaseline(id) returns stat values captured before reading the current snapshot, with path, mtimeMs, ctimeMs, and size;
  • fetchBundle() returns the same response as the HTTP route, reading package assets per request;
  • rebuilt(id) publishes a bundle rebuild not accompanied by an entry restart: it derives a revision from filesystem metadata and re-reads bytes, recomposes the graph, and notifies only when the revision changed.

Two notification paths: onRebuilt fires per changed bundle with its new revision, and onGraphChanged fires after any flush that recomposes the graph using a pull model, with listeners re-reading graph() themselves. Both absorb listener exceptions, so a throwing subscriber neither skips later subscribers nor kills the flush that triggered it.

HMR and page-local state

The graph describes target state and never claims host cleanup finished.(source)

The shipped web composition delivers dynamic graph snapshots through dsh-client-hmr. The host forwards existing graph changes immediately, and reconnect sends the current complete graph. The graph describes the browser's target entries and does not declare host cleanup complete; artifact polling separately reports rebuild revisions.

A source-map-only change never triggers a reload; a new combo-map URL appears only after a bundle revision changes, and each map body is pinned by its first GET.

Client Modules validates snapshots and serializes reconciliation with rebuilds; it owns the entry map created at boot, handling single-resource arrival, async removal, cleanup of unused modules and styles, and page-local retry state. Static platform modules and bootstrap stay for the page lifetime; Electron installation is a separate flow.

Verification: a minimal client module

Cover declaration, graph, routes, and injection.(source)

  1. Create a package declaring dsh.client.platform = 'web' and exporting ./client, restart, and assert graph().entries contains that id.
  2. Request /plugins/<pkg>/client.js and assert 200 with a sourceMappingURL.
  3. Request the same URL with a stale rev and assert 404 rather than an HTML fallback.
  4. Request /plugins/<pkg>/client.js.map and assert the first GET generates and caches the combined map.
  5. Change a source line without restarting the fiber, call rebuilt(id), and assert onRebuilt fires with onGraphChanged following.
  6. Change only the source map and assert rebuilt returns the same rev and the page does not reload.

If step 1 lacks the id, first check that exports["./client"] and dsh.client both live in the same package's package.json rather than scattered into subdirectories.

For the full bundling and profile flow, see plugin bundle; for client resource lifetime boundaries, see client resource lifecycle.

One line to close: four faces share one graph, wire is the protocol, same-name source conflicts fail, combos concatenate once, maps appear on first GET, and notifications pull.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

How is a DSH plugin client module declared?

Through dsh.client and exports in package.json. DSH plugin requires dsh.client to declare platform web and exports["./client"] to export the built bundle.

Is there a length limit on DSH plugin boot script URLs?

Yes. DSH plugin requires each boot request URL to stay within 3 KiB of UTF-8 bytes. DSH plugin splits by the longer map form so map requests never exceed it.

Are DSH plugin source maps read at startup?

No. DSH plugin reads no maps during boot, index rendering, or script GET and HEAD. DSH plugin reads, validates, and caches the combined result only on the first map GET.

Is a DSH plugin graph change notification a pushed payload?

No. DSH plugin uses a pull model. DSH plugin's onGraphChanged carries no payload, so listeners re-read graph() after being notified.

Related Terms

WebBootEntry
WebBootEntry is one client entry row the host composes: id, url, rev, and optional inject, immediately, and external.— packages/client/modules/src/client/manifest.ts
WebBootBatch
WebBootBatch describes one initial combo script: scheduling phase, url, rev derived from row revisions, and entry execution order.— packages/client/modules/src/client/manifest.ts
WebBootGraph
WebBootGraph is the composed graph injected as window.__DSH_BOOT__, holding a consistency rev, optional release, entries, and batches.— packages/client/modules/src/client/manifest.ts
artifactBaseline
artifactBaseline is the filesystem baseline captured before reading the current bundle: path, mtime, ctime, and size.— packages/client/modules/src/index.ts

Sources