@dsh-plugin/dsh-loader 1.0.0

package/src/adapters/dsh-1-x.js

@@ -0,0 +1,236 @@
+// dsh 1.x host adapter (design.md §7.4 / §5.1 / §3.3.1).
+//
+// Absorbs the verified repairs from dsh-upstream-fixes:
+//   - httpServer -> webServer single-hop service alias (fix 2).
+//   - settings namespace whitelist bypass bridge, gated behind
+//     `exposeAllNamespaces` (fix 5). Two independent paths:
+//       * host side: ctx.dshLoader.settings.* (handled by services/settings.js
+//         + the bridge routes registered here for the browser fetch path).
+//       * client side: fetch interceptor in src/client.js.
+//   - package-name aliasing for host-side CJS require (createRequire /
+//     require()) — intercepts Module._resolveFilename so a renamed dsh
+//     package resolves to its new name without plugin rebuilds.
+//
+// All registrations go through ctx.reflect.provide / ctx.effect so cordis
+// auto-recycles them when the dshloader fiber unloads (design.md §4.4). No
+// custom dispose() is needed for v1's covered capabilities.
+import { LOG_PREFIX } from '../version.js';
+import { toNamespaceView, settingsErrorToResult } from '../services/settings.js';
+
+// Covers the real dsh release line (0.1.0-rc.x, verified against
+// dsh-upstream-fixes) and the anticipated 1.x line. The adapter name keeps
+// the design-doc label "dsh-1-x"; the behavior is identical across both
+// ranges since dsh-upstream-fixes confirms httpServer->webServer + settings
+// bridge work the same way on 0.1.0-rc.7.
+export const supports = '>=0.1.0-rc.1 <2.0.0';
+export const name = 'dsh-1-x';
+
+// Browser-facing bridge prefix; the client fetch interceptor (src/client.js)
+// must use the same prefix.
+export const BRIDGE_PREFIX = '/api/dshloader';
+
+// Host-side package-name aliases. Maps stable @dshloader/* names to the
+// real dsh package names for this version. Plugins should require() from
+// the stable names; the Module._resolveFilename hook maps them to the real
+// package. When dsh renames a host package, only this table changes.
+//
+// This intercepts CJS require() (including createRequire) via
+// Module._resolveFilename; ESM static imports are build-time resolved and
+// cannot be intercepted at runtime (use pnpm overrides / tsconfig paths
+// for those).
+export const hostPackageAliases = {
+  '@dsh-plugin/dsh-loader/tools': '@deepseek-ai/dsh-tools',
+  '@dsh-plugin/dsh-loader/llm': '@deepseek-ai/dsh-llm',
+  '@dsh-plugin/dsh-loader/agent': '@deepseek-ai/dsh-agent',
+  '@dsh-plugin/dsh-loader/settings': '@deepseek-ai/dsh-settings',
+};
+
+/**
+ * Install a Module._resolveFilename hook that maps old package names to
+ * new ones for CJS require() calls. Returns a dispose function that
+ * removes the hook.
+ */
+export async function installHostPackageAliases(aliases) {
+  const entries = Object.entries(aliases);
+  if (entries.length === 0) return () => {};
+  const aliasMap = new Map(entries);
+  // Lazy-import Module to avoid loading it in browser/test contexts.
+  let Module;
+  try {
+    const mod = await import('node:module');
+    Module = mod.default ?? mod.Module ?? mod;
+  } catch {
+    return () => {};
+  }
+  if (!Module || typeof Module._resolveFilename !== 'function') return () => {};
+  const original = Module._resolveFilename;
+  const hooked = function dshloaderResolve(request, parent, ...rest) {
+    const mapped = aliasMap.get(request);
+    if (mapped !== undefined) return original.call(this, mapped, parent, ...rest);
+    return original.call(this, request, parent, ...rest);
+  };
+  Module._resolveFilename = hooked;
+  return () => {
+    if (Module._resolveFilename === hooked) Module._resolveFilename = original;
+  };
+}
+
+/**
+ * @param {object} ctx cordis context
+ * @param {{ exposeAllNamespaces?: boolean, hostPackageAliases?: Record<string,string> }} [config]
+ */
+export function create(ctx, config = {}) {
+  const exposeAllNamespaces = Boolean(config.exposeAllNamespaces);
+  const packageAliases = { ...hostPackageAliases, ...(config.hostPackageAliases ?? {}) };
+
+  async function apply() {
+    // --- service alias: httpServer -> webServer (fix 2) ---
+    if (ctx.get('httpServer') === undefined) {
+      const webServer = ctx.get('webServer');
+      if (webServer !== undefined) {
+        ctx.reflect.provide('httpServer', webServer);
+        console.log(`${LOG_PREFIX} aliased httpServer -> webServer`);
+      }
+    } else {
+      console.log(`${LOG_PREFIX} httpServer already exists, skip alias`);
+    }
+
+    // --- host package-name aliases (CJS require interception) ---
+    if (Object.keys(packageAliases).length > 0) {
+      ctx.effect(
+        () => installHostPackageAliases(packageAliases),
+        'dshloader: host package-name aliases',
+      );
+      console.log(`${LOG_PREFIX} installed host package aliases: ${Object.keys(packageAliases).join(', ')}`);
+    }
+
+    // --- settings bridge routes for the browser fetch path (fix 5, path 2) ---
+    // Only registered when the profile explicitly opts in. The host-side
+    // stable API (ctx.dshLoader.settings.*) is unaffected by this gate and
+    // always available to host plugin code.
+    if (exposeAllNamespaces) {
+      ctx.effect(
+        () => registerSettingsBridgeRoutes(ctx),
+        'dshloader: settings namespace bridge routes',
+      );
+    }
+  }
+
+  function dispose() {
+    // No cordis-unaware resources held in v1; effect auto-recycle covers
+    // everything registered in apply(). Implemented as a no-op to satisfy
+    // the HostAdapter interface and future hot-swap scenarios.
+  }
+
+  return { supports, name, apply, dispose };
+}
+
+/**
+ * Register host bridge routes that the client fetch interceptor forwards
+ * non-whitelisted settings requests to. Mirrors dsh-upstream-fixes/lib/index.js
+ * `registerRoutes` (settings section).
+ */
+function registerSettingsBridgeRoutes(ctx) {
+  const webServer = ctx.get('webServer') ?? ctx.get('httpServer');
+  if (webServer === undefined || typeof webServer.register !== 'function') return () => {};
+  return webServer.register({
+    kind: 'prefix',
+    path: BRIDGE_PREFIX,
+    handler: (req, res) => {
+      const json = (status, body) => {
+        res.statusCode = status;
+        res.setHeader('content-type', 'application/json');
+        res.end(JSON.stringify(body));
+      };
+      const readBody = () =>
+        new Promise((done, fail) => {
+          let body = '';
+          req.on?.('data', (chunk) => {
+            body += chunk.toString('utf8');
+          });
+          req.on?.('end', () => done(body));
+          req.on?.('error', fail);
+        });
+      const url = req.url ?? '/';
+      const method = (req.method ?? 'GET').toUpperCase();
+      const path = url.split('?')[0] ?? '/';
+
+      void (async () => {
+        try {
+          // GET /api/dshloader/settings/describe — full redacted namespace list.
+          if (method === 'GET' && (path === `${BRIDGE_PREFIX}/settings/describe` || path === `${BRIDGE_PREFIX}/settings/describe/`)) {
+            const settings = ctx.get('settings');
+            if (settings === undefined) {
+              json(200, { ok: false, message: 'settings service unavailable' });
+              return;
+            }
+            json(200, {
+              ok: true,
+              namespaces: settings.describe({ redactSecrets: true }).map(toNamespaceView),
+            });
+            return;
+          }
+
+          // POST /api/dshloader/settings/{update,mutate,replace} — write seam.
+          const writeMatch = /^\/api\/dshloader\/settings\/(update|mutate|replace)$/.exec(path);
+          if (method === 'POST' && writeMatch !== null) {
+            const mode = writeMatch[1];
+            let parsed = {};
+            try {
+              parsed = JSON.parse(await readBody());
+            } catch {
+              /* keep {} */
+            }
+            const ns = typeof parsed.ns === 'string' ? parsed.ns : '';
+            if (ns.length === 0) {
+              json(200, {
+                ok: true,
+                result: {
+                  ok: false,
+                  code: 'settings-rejected',
+                  message: 'settings write needs a namespace',
+                  details: {},
+                },
+              });
+              return;
+            }
+            const settings = ctx.get('settings');
+            const result = await runSettingsWrite(
+              settings,
+              mode,
+              ns,
+              mode === 'mutate' ? parsed.ops : parsed.section,
+              parsed.expectedRevision,
+            );
+            json(200, { ok: true, result });
+            return;
+          }
+
+          json(404, { ok: false, message: 'not found' });
+        } catch (error) {
+          json(500, { ok: false, message: error instanceof Error ? error.message : String(error) });
+        }
+      })();
+    },
+  });
+}
+
+async function runSettingsWrite(settings, mode, ns, section, expectedRevision) {
+  if (settings === undefined) {
+    return { ok: false, code: 'internal', message: 'settings service unavailable', details: {} };
+  }
+  try {
+    if (mode === 'update') await settings.update(ns, section, expectedRevision);
+    else if (mode === 'replace') await settings.replace(ns, section, expectedRevision);
+    else await settings.mutate(ns, section, expectedRevision);
+  } catch (error) {
+    return settingsErrorToResult(error, ns, mode);
+  }
+  const descriptor = settings
+    .describe({ redactSecrets: true })
+    .find((d) => String(d.ns) === String(ns));
+  if (descriptor === undefined) {
+    return { ok: false, code: 'internal', message: 'settings namespace disposed after write', details: { ns } };
+  }
+  return { ok: true, value: toNamespaceView(descriptor) };
+}

package/src/adapters/index.js

@@ -0,0 +1,59 @@
+// Adapter registration (design.md §7.4). Imports every host adapter and
+// registers it on the provided AdapterRegistry. Kept as a function so tests
+// can build a fresh registry per case.
+import * as dsh1x from './dsh-1-x.js';
+
+/** All host adapter factories, in registration order. */
+export const hostAdapters = [
+  { supports: dsh1x.supports, name: dsh1x.name, create: dsh1x.create },
+];
+
+/** Register every built-in host adapter onto a registry. */
+export function registerHostAdapters(registry) {
+  for (const factory of hostAdapters) registry.register(factory);
+  return registry;
+}
+
+// Client adapter metadata for dsh 1.x (consumed by src/client.js).
+//
+// packageAliases serves TWO roles:
+//   1. **Stable name → real name** (primary): plugins import from stable
+//      names like '@dshloader/ui-primitives' and the adapter maps them to
+//      the real dsh package name for this version. When dsh renames a
+//      package, only the adapter changes — plugin source and bundle stay
+//      the same.
+//   2. **Old real name → new real name** (fallback): if a plugin bundle
+//      was built before adopting stable names and still has
+//      `require('@deepseek-ai/dsh-client-ui-primitives')` baked in, the
+//      adapter can map the old real name to the new real name as a
+//      transition measure.
+export const clientAdapters = [
+  {
+    supports: dsh1x.supports,
+    name: dsh1x.name,
+    moduleAliases: {
+      // deep source import that breaks when dsh ships no `src/` (fix 1).
+      '@deepseek-ai/dsh-client-runtime/src/client/sessions/context-provenance.ts':
+        '@deepseek-ai/dsh-client-runtime/client',
+      // stable module name (design.md §3.3.3).
+      'dsh/runtime/context-provenance': '@deepseek-ai/dsh-client-runtime/client',
+    },
+    // Stable package names → real dsh package names for dsh 1.x.
+    // Plugins import from @dsh-plugin/dsh-loader/* subpaths (e.g.
+    // '@dsh-plugin/dsh-loader/ui-primitives'); the __ModuleLoader__
+    // wrapper (installed by installClient) maps them to the real dsh
+    // package before hitting the module table. When dsh renames a
+    // package, only this table changes — plugin source and bundle stay
+    // the same.
+    packageAliases: {
+      // Client UI component libraries
+      '@dsh-plugin/dsh-loader/ui-primitives': '@deepseek-ai/dsh-client-ui-primitives',
+      '@dsh-plugin/dsh-loader/ui-slots': '@deepseek-ai/dsh-client-ui-slots',
+      '@dsh-plugin/dsh-loader/web-react': '@deepseek-ai/dsh-client-web-react',
+      '@dsh-plugin/dsh-loader/schema-form': '@deepseek-ai/dsh-client-schema-form',
+      '@dsh-plugin/dsh-loader/ui-settings': '@deepseek-ai/dsh-client-ui-settings/client',
+      // Client runtime
+      '@dsh-plugin/dsh-loader/runtime': '@deepseek-ai/dsh-client-runtime/client',
+    },
+  },
+];

package/src/api.js

@@ -0,0 +1,56 @@
+// DshLoaderHostAPI construction (design.md §4.1 / §4.4).
+//
+// `createHostAPI` builds the `ctx.dshLoader` object exposed to other plugins.
+// Each capability (settings / web / services) is constructed from the active
+// adapter's overrides when present, otherwise from the default stable impl in
+// src/services/*.js. The adapter's `apply()` is invoked separately by the
+// bundle entry (src/index.js) so service aliases / bridge routes register via
+// cordis effects and auto-recycle on fiber unload (design.md §4.4).
+import { LOADER_VERSION } from './version.js';
+import { createSettingsAPI } from './services/settings.js';
+import { createWebAPI } from './services/web.js';
+import { createServicesAPI } from './services/services.js';
+import { installHostPackageAliases } from './adapters/dsh-1-x.js';
+
+/**
+ * @param {{
+ *   ctx: object,
+ *   dshVersion: string,
+ *   factory: { supports: string, name: string, create: Function },
+ *   adapter?: object,
+ *   exposeAllNamespaces?: boolean,
+ *   whitelist?: Set<string>,
+ *   hostPackageAliases?: Record<string, string>,
+ * }} opts
+ */
+export function createHostAPI({ ctx, dshVersion, factory, adapter, exposeAllNamespaces = false, whitelist, hostPackageAliases = {} }) {
+  const base = {
+    version: LOADER_VERSION,
+    dshVersion,
+    adapterVersion: factory.supports,
+  };
+
+  // Adapters may override any capability (design.md §4.4 HostAdapter.{settings,
+  // web, services}); otherwise the default stable impl is used.
+  const settings = adapter?.settings ?? createSettingsAPI({ ctx, exposeAllNamespaces, whitelist });
+  const web = adapter?.web ?? createWebAPI({ ctx });
+  const services = adapter?.services ?? createServicesAPI({ ctx });
+
+  // Runtime host package-name alias registration. The adapter's apply()
+  // installs the static set at boot; this method lets plugins add more
+  // aliases at runtime (e.g. for packages the adapter didn't know about).
+  const runtimeHostAliases = new Map(Object.entries(hostPackageAliases));
+  const registerPackageAlias = (oldName, newName) => {
+    runtimeHostAliases.set(oldName, newName);
+    // Re-install the hook with the updated map.
+    installHostPackageAliases(Object.fromEntries(runtimeHostAliases));
+  };
+
+  return {
+    ...base,
+    settings,
+    web,
+    services,
+    registerPackageAlias,
+  };
+}

package/src/client.js

@@ -0,0 +1,330 @@
+// dshloader client bundle entry (design.md §3.5 / §4.3 / §7.3).
+//
+// Loaded in the `immediately` prefetch tier (package.json `dsh.client`).
+// Responsibilities:
+//   1. Mount `window.__dshLoader__` with `require` / `registerModuleAlias` /
+//      `rpc.settings.*`.
+//   2. Register module-alias factories via `window.__ModuleLoader__.load` so
+//      deep source imports (fix 1) and stable module names resolve to the
+//      public runtime client entry.
+//   3. When `exposeAllNamespaces` is on, install a fetch interceptor that
+//      merges non-whitelisted namespaces into `/api/settings.describe` and
+//      routes non-whitelisted writes through the host bridge, echoing the
+//      request `rpcId` in the `{ type: 'server-response', rpcId, result }`
+//      envelope (fix 5, path 2 — mirrors dsh-upstream-fixes/lib/client.js).
+//
+// The module exports an `installClient` function for testability and runs an
+// IIFE at the bottom for the real browser bundle.
+import { LOADER_VERSION, LOG_PREFIX } from './version.js';
+import { clientAdapters } from './adapters/index.js';
+import { BRIDGE_PREFIX } from './adapters/dsh-1-x.js';
+
+export class ModuleNotFoundError extends Error {
+  constructor(specifier) {
+    super(`${LOG_PREFIX} module not found: ${specifier}`);
+    this.name = 'ModuleNotFoundError';
+    this.specifier = specifier;
+  }
+}
+
+/**
+ * Pick the client adapter for the given dsh version. v1 ships a single
+ * client adapter (dsh 1.x); when more are added, swap this for a semver-based
+ * selection mirroring the host AdapterRegistry.
+ */
+function pickClientAdapter(dshVersion) {
+  return clientAdapters[0];
+}
+
+/**
+ * Build the `window.__dshLoader__` API object.
+ * @param {{
+ *   dshVersion?: string,
+ *   adapterVersion?: string,
+ *   moduleAliases?: Record<string,string>,
+ *   requireImpl?: (spec: string) => any,
+ *   fetchBridge?: { describe: () => Promise<any>, write: (mode:string, payload:object) => Promise<any> },
+ *   clientCtx?: object,  // cordis client context (for services.get)
+ * }} opts
+ */
+export function createClientAPI(opts = {}) {
+  const aliases = new Map(Object.entries(opts.moduleAliases ?? {}));
+  const requireImpl = opts.requireImpl ?? ((spec) => {
+    throw new ModuleNotFoundError(spec);
+  });
+  const clientCtx = opts.clientCtx;
+  // Reuse the Map from installClient when provided so registerPackageAlias
+  // mutations are visible to the __ModuleLoader__ wrapper. Otherwise create
+  // a fresh Map from a plain object.
+  const packageAliases = opts.packageAliases instanceof Map
+    ? opts.packageAliases
+    : new Map(Object.entries(opts.packageAliases ?? {}));
+
+  const api = {
+    version: LOADER_VERSION,
+    dshVersion: opts.dshVersion,
+    adapterVersion: opts.adapterVersion,
+
+    require(specifier) {
+      if (typeof specifier !== 'string') throw new ModuleNotFoundError(String(specifier));
+      const target = aliases.get(specifier);
+      if (target === undefined) {
+        throw new ModuleNotFoundError(specifier);
+      }
+      return requireImpl(target);
+    },
+
+    registerModuleAlias(alias, target) {
+      aliases.set(alias, target);
+    },
+
+    /**
+     * Register a package-name alias for the client module loader's
+     * require(). When a plugin's bundle calls require('@old/pkg-name'),
+     * the loader's wrapped require remaps it to '@new/pkg-name' before
+     * hitting the module table. This lets dsh rename client packages
+     * across versions without forcing plugin bundles to rebuild.
+     */
+    registerPackageAlias(oldName, newName) {
+      packageAliases.set(oldName, newName);
+    },
+
+    /**
+     * Read a client-side cordis service by name.
+     * Proxies to `clientCtx.get(name)` — the same ctx.get plugins use
+     * inside their client `apply(ctx)`, but exposed through the stable
+     * dshloader surface so plugins don't depend on the cordis context
+     * shape directly.
+     *
+     * Only available when dshloader's client apply() received a ctx
+     * (cordis client boot). Returns undefined when ctx is not wired.
+     */
+    services: {
+      get(name) {
+        if (clientCtx === undefined || typeof clientCtx.get !== 'function') return undefined;
+        return clientCtx.get(name);
+      },
+    },
+
+    rpc: opts.fetchBridge
+      ? {
+          settings: {
+            describe: () => opts.fetchBridge.describe(),
+            update: (ns, section) => opts.fetchBridge.write('update', { ns, section }),
+            replace: (ns, section) => opts.fetchBridge.write('replace', { ns, section }),
+            mutate: (ns, ops) => opts.fetchBridge.write('mutate', { ns, ops }),
+          },
+        }
+      : undefined,
+  };
+
+  return api;
+}
+
+/**
+ * Install dshloader into a browser-like environment.
+ * @param {{
+ *   window?: any,
+ *   dshVersion?: string,
+ *   exposeAllNamespaces?: boolean,
+ *   requireImpl?: (spec: string) => any,
+ *   hostBridgePrefix?: string,
+ *   clientCtx?: object,  // cordis client context (passed from apply(ctx))
+ * }} [opts]
+ */
+export function installClient(opts = {}) {
+  const win = opts.window ?? (typeof window !== 'undefined' ? window : undefined);
+  if (win === undefined) return undefined;
+
+  const dshVersion = opts.dshVersion ?? win.__DSHLOADER_VERSION__ ?? undefined;
+  const adapter = pickClientAdapter(dshVersion);
+  const moduleAliases = { ...(adapter.moduleAliases ?? {}) };
+  // Merge adapter-declared package aliases with any passed via opts (opts
+  // win on conflict, so tests / runtime can override adapter defaults).
+  const packageAliases = new Map(Object.entries(adapter.packageAliases ?? {}));
+  if (opts.packageAliases) {
+    for (const [k, v] of Object.entries(opts.packageAliases)) packageAliases.set(k, v);
+  }
+
+  // fetch bridge (only meaningful when exposeAllNamespaces is on).
+  const exposeAllNamespaces = Boolean(
+    opts.exposeAllNamespaces ?? win.__DSHLOADER_CONFIG__?.exposeAllNamespaces,
+  );
+  const bridgePrefix = opts.hostBridgePrefix ?? BRIDGE_PREFIX;
+
+  const fetchBridge = exposeAllNamespaces
+    ? {
+        describe: () => win.fetch(`${bridgePrefix}/settings/describe`, { headers: { accept: 'application/json' } }).then((r) => r.json()),
+        write: (mode, payload) =>
+          win.fetch(`${bridgePrefix}/settings/${mode}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(payload),
+          }).then((r) => r.json()),
+      }
+    : undefined;
+
+  const api = createClientAPI({
+    dshVersion,
+    adapterVersion: adapter.supports,
+    moduleAliases,
+    packageAliases,
+    requireImpl: opts.requireImpl ?? ((spec) => win.__dshNativeRequire__?.(spec)),
+    fetchBridge,
+    clientCtx: opts.clientCtx,
+  });
+  win.__dshLoader__ = api;
+
+  // Wrap __ModuleLoader__.load so every factory's require() function
+  // applies package-name aliases before hitting the module table. This
+  // must happen BEFORE registering module-alias factories below, because
+  // those factories also receive the wrapped require.
+  const loader = win.__ModuleLoader__;
+  if (loader && typeof loader.load === 'function') {
+    const originalLoad = loader.load.bind(loader);
+    loader.load = function dshloaderLoad(handoff) {
+      const wrappedFactory = (require) => {
+        const aliasedRequire = (spec) => {
+          const mapped = packageAliases.get(spec);
+          return require(mapped ?? spec);
+        };
+        return handoff.factory(aliasedRequire);
+      };
+      return originalLoad({ id: handoff.id, factory: wrappedFactory });
+    };
+  }
+
+  // Register module-alias factories with the client module loader (fix 1).
+  if (loader && typeof loader.load === 'function') {
+    for (const [aliasId, target] of Object.entries(moduleAliases)) {
+      loader.load({
+        id: aliasId,
+        factory: (require) => {
+          const mod = require(target);
+          // Preserve the deep import's expected named export shape.
+          if (aliasId.endsWith('context-provenance.ts') || aliasId.endsWith('context-provenance')) {
+            return { contextProvenance: mod.contextProvenance };
+          }
+          return mod;
+        },
+      });
+    }
+  }
+
+  if (exposeAllNamespaces) {
+    installSettingsFetchInterceptor(win, bridgePrefix);
+    console.warn(`${LOG_PREFIX} exposeAllNamespaces enabled: bypassing official settings whitelist`);
+  }
+
+  return api;
+}
+
+/**
+ * Fetch interceptor for settings namespace whitelist bypass (fix 5, path 2).
+ * Mirrors dsh-upstream-fixes/lib/client.js (127-223).
+ *
+ * - /api/settings.describe: merge non-whitelisted namespaces from the host
+ *   bridge into the official response (rpcId/official fields preserved).
+ * - /api/settings.{update,mutate,replace}: route writes for namespaces the
+ *   official proxy does NOT expose through the host bridge, and rebuild the
+ *   response envelope as `{ type: 'server-response', rpcId, result }` so the
+ *   official client can correlate the response with the request.
+ */
+export function installSettingsFetchInterceptor(win, bridgePrefix = BRIDGE_PREFIX) {
+  if (typeof win.fetch !== 'function') return () => {};
+  const originalFetch = win.fetch;
+  /** Namespaces the official proxy itself exposed (learned from describe). */
+  const officialExposed = new Set();
+
+  win.fetch = async function dshloaderFetch(input, init) {
+    let pathname = '';
+    try {
+      pathname = new URL(typeof input === 'string' ? input : input.url, win.location?.origin ?? 'http://localhost').pathname;
+    } catch {
+      pathname = String(input).split('?')[0];
+    }
+    const method = (init?.method ?? 'GET').toUpperCase();
+
+    // describe: merge bridge namespaces into the official response.
+    if (pathname === '/api/settings.describe') {
+      const response = await originalFetch(input, init);
+      try {
+        const body = await response.clone().json();
+        const namespaces = body?.result?.value?.namespaces;
+        if (!Array.isArray(namespaces)) return response;
+        for (const row of namespaces) {
+          if (typeof row?.ns === 'string') officialExposed.add(row.ns);
+        }
+        const extra = await originalFetch(`${bridgePrefix}/settings/describe`, {
+          headers: { accept: 'application/json' },
+        });
+        const extraBody = await extra.json();
+        if (extraBody?.ok !== true || !Array.isArray(extraBody.namespaces)) return response;
+        const seen = new Set(namespaces.map((row) => row.ns));
+        const merged = [...namespaces, ...extraBody.namespaces.filter((row) => !seen.has(row.ns))];
+        return new win.Response(
+          JSON.stringify({ ...body, result: { ...body.result, value: { ...body.result.value, namespaces: merged } } }),
+          { status: 200, headers: { 'content-type': 'application/json' } },
+        );
+      } catch {
+        return response;
+      }
+    }
+
+    // writes: route non-whitelisted namespaces through the bridge, echo rpcId.
+    if (
+      (pathname === '/api/settings.update' || pathname === '/api/settings.mutate' || pathname === '/api/settings.replace') &&
+      method === 'POST'
+    ) {
+      let rpcId = null;
+      let payload = null;
+      try {
+        const parsed = JSON.parse(String(init?.body ?? '{}'));
+        rpcId = parsed.rpcId;
+        payload = parsed.payload;
+      } catch {
+        /* fall through to the original endpoint */
+      }
+      const ns = typeof payload?.ns === 'string' ? payload.ns : '';
+      if (rpcId !== null && ns !== '' && officialExposed.size > 0 && !officialExposed.has(ns)) {
+        try {
+          const mode = pathname.slice('/api/settings.'.length);
+          const res = await originalFetch(`${bridgePrefix}/settings/${mode}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(payload),
+          });
+          const body = await res.json();
+          if (body?.result) {
+            return new win.Response(
+              JSON.stringify({ type: 'server-response', rpcId, result: body.result }),
+              { status: 200, headers: { 'content-type': 'application/json' } },
+            );
+          }
+        } catch {
+          /* fall back to the original endpoint */
+        }
+      }
+    }
+
+    return originalFetch(input, init);
+  };
+
+  return () => {
+    win.fetch = originalFetch;
+  };
+}
+
+// ── cordis client-plugin entry ─────────────────────────────────────────
+// dsh's client boot applies every registered bundle as a cordis plugin:
+// the module must expose `apply` (third-party plugins / dsh-client-runtime
+// all do `exports.apply = apply`). Without it the client boot fails with
+// "invalid plugin, expect function or object with an \"apply\" method".
+// `installClient` mounts window.__dshLoader__, registers module aliases,
+// wires the client cordis ctx for `services.get`, and (when opted in)
+// installs the settings fetch interceptor.
+export const name = '@dsh-plugin/dsh-loader'
+export const inject = []
+export function apply(ctx) {
+  if (typeof window !== 'undefined') installClient({ window, clientCtx: ctx });
+}