From 9cc74b6ae873abfd1089648704c37fb771907701 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Tue, 18 Aug 2026 03:31:33 +0000
Subject: [PATCH 1/3] feat(hub): resolve bare-specifier client scripts through
 the host runtime
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A dock client script's importFrom can now name an npm module (e.g.
'vite-plugin-vue-tracer/client/vite-devtools') instead of a served URL.
Bare specifiers are a host-runtime capability: the host advertises a URL
template as ConnectionMeta.configs.dock.clientModuleResolution (declared
via initHub({ clientModuleResolution })), and every client-script loader
applies it before the native import — createDevframeClientHost (which
also gains a resolveClientModule override), hub-ui's setup-script
loader, and the generated __client-imports.js module.

@devframes/vite/hub declares '/@id/{specifier}' by default, so the
import routes through Vite's own resolution and import-analysis: the
script's transitive bare imports work too and share the app's module
graph — the fix for vue-tracer's dock breaking once v0.9's middleware
began serving hub assets verbatim, outside Vite's transform pipeline.

Hosts without such a runtime (Next.js) keep the URL contract; a new
DF8111 diagnostic warns at dock registration when a bare specifier is
doomed there, and both browser loaders name the capability gap in their
error. The reference hubs stay at parity through one shared demo
package (examples/demo-dock-client): hub-vite consumes it by bare
specifier, hub-next as a statically-mounted self-contained bundle, and
its globalThis-anchored store documents the state pattern the docs'
new protocol guarantee prescribes.
---
 docs/errors/DF8111.md                         |  43 ++++++++
 docs/guide/client-context.md                  |  36 ++++++-
 examples/demo-dock-client/README.md           |  16 +++
 examples/demo-dock-client/package.json        |  25 +++++
 examples/demo-dock-client/src/index.ts        |  50 +++++++++
 examples/demo-dock-client/src/node.ts         |  10 ++
 examples/demo-dock-client/tsconfig.json       |  10 ++
 examples/demo-dock-client/tsdown.config.ts    |  41 +++++++
 examples/hub-next/README.md                   |   2 +
 examples/hub-next/package.json                |   1 +
 examples/hub-next/src/client/app/page.tsx     |  26 ++++-
 .../src/client/devframe/next-devframe-hub.ts  |  58 ++++++++++
 examples/hub-vite/README.md                   |   2 +
 examples/hub-vite/package.json                |   1 +
 examples/hub-vite/src/client/main.ts          |  24 ++++-
 examples/hub-vite/vite.config.ts              |  16 +++
 knip.jsonc                                    |  14 +++
 .../hub-ui/src/client/state/setup-script.ts   |  23 +++-
 packages/hub/src/client-modules.test.ts       | 102 ++++++++++++++++++
 packages/hub/src/client-modules.ts            |  93 ++++++++++++++++
 packages/hub/src/client/host.ts               |  39 ++++++-
 packages/hub/src/client/index.ts              |   1 +
 .../hub/src/node/__tests__/host-docks.test.ts |  60 +++++++++++
 .../hub/src/node/__tests__/initiate.test.ts   |  49 +++++++++
 packages/hub/src/node/diagnostics.ts          |   4 +
 packages/hub/src/node/host-docks.ts           |  22 ++++
 packages/hub/src/node/initiate.ts             |  38 ++++++-
 packages/hub/src/types/docks.ts               |  39 ++++++-
 packages/vite/src/hub.ts                      |  30 ++++++
 pnpm-lock.yaml                                |  63 +++++++----
 pnpm-workspace.yaml                           |   1 +
 .../@devframes/hub/client.snapshot.d.ts       |  10 ++
 .../tsnapi/@devframes/hub/client.snapshot.js  |   4 +
 .../tsnapi/@devframes/hub/index.snapshot.d.ts |   3 +
 .../@devframes/hub/initiate.snapshot.d.ts     |   1 +
 .../tsnapi/@devframes/hub/node.snapshot.d.ts  |   1 +
 .../tsnapi/@devframes/hub/types.snapshot.d.ts |   1 +
 .../tsnapi/@devframes/vite/hub.snapshot.d.ts  |   5 +
 .../tsnapi/@devframes/vite/hub.snapshot.js    |   4 +
 39 files changed, 933 insertions(+), 35 deletions(-)
 create mode 100644 docs/errors/DF8111.md
 create mode 100644 examples/demo-dock-client/README.md
 create mode 100644 examples/demo-dock-client/package.json
 create mode 100644 examples/demo-dock-client/src/index.ts
 create mode 100644 examples/demo-dock-client/src/node.ts
 create mode 100644 examples/demo-dock-client/tsconfig.json
 create mode 100644 examples/demo-dock-client/tsdown.config.ts
 create mode 100644 packages/hub/src/client-modules.test.ts
 create mode 100644 packages/hub/src/client-modules.ts

diff --git a/docs/errors/DF8111.md b/docs/errors/DF8111.md
new file mode 100644
index 00000000..a209cb57
--- /dev/null
+++ b/docs/errors/DF8111.md
@@ -0,0 +1,43 @@
+---
+outline: deep
+---
+
+# DF8111: Bare-Specifier Client Script Without Host Resolution
+
+## Message
+
+> Dock "`{id}`" declares the bare-specifier client script "`{specifier}`", but this host advertises no client-module resolution — the browser cannot resolve a bare npm specifier natively, so the script will fail to load.
+
+## Cause
+
+A dock entry's client script (`clientScript` on iframe docks, `action`, `renderer`) names an npm module (`'vite-plugin-vue-tracer/client/vite-devtools'`) as its `importFrom`. Client scripts load with a native browser `import()`, and a browser only resolves URL specifiers — bare specifiers work when the **host runtime** resolves them, advertised as `ConnectionMeta.configs.dock.clientModuleResolution` (a URL template whose `{specifier}` token is replaced with the specifier). This host declared none, so every client-script loader will throw `TypeError: Failed to resolve module specifier` for this entry.
+
+## Example
+
+```ts
+initHub({
+  base: '/__devframes/',
+  configure(ctx) {
+    ctx.docks.register({
+      type: 'action',
+      id: 'vue-tracer',
+      title: 'Vue Tracer',
+      icon: 'ph:crosshair-simple-duotone',
+      // ✗ Bare specifier on a host with no `clientModuleResolution`
+      action: { importFrom: 'vite-plugin-vue-tracer/client/vite-devtools' },
+    })
+  },
+})
+```
+
+## Fix
+
+Pick whichever side you control:
+
+- **Run under a host that resolves bare specifiers.** A Vite host serves any npm module through its own module graph — declare `initHub({ clientModuleResolution: '/@id/{specifier}' })`. `@devframes/vite/hub` declares this by default, so the example above is fine there; the script's transitive bare imports work too and share the app's module graph.
+- **Ship the script as a self-contained bundle** and pass a URL the host serves as `importFrom` (the a11y inspector pattern): `{ importFrom: '/__devframes/my-agent/inject.js' }` after mounting the bundle's directory with `ctx.host.mountStatic(...)`.
+- **Resolve it in the viewer.** A custom viewer may pass `createDevframeClientHost({ resolveClientModule })` (or ship a page import map); the warning is then safe to disregard — it fires because the *server* can't know a viewer will cover the gap.
+
+## Source
+
+- [`packages/hub/src/node/host-docks.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/host-docks.ts) — `DevframeDocksHost.register()` warns when a bare-specifier client script registers on a host whose `staticConfig.dock` declares no `clientModuleResolution`.
diff --git a/docs/guide/client-context.md b/docs/guide/client-context.md
index 902acece..2d323f6d 100644
--- a/docs/guide/client-context.md
+++ b/docs/guide/client-context.md
@@ -136,7 +136,12 @@ A script that fails to import is logged and retried on the next dock update.
 
 ### Shipping a client script
 
-Build the script as a single self-contained ES module — it loads outside any chunk graph or import map. Attach it when mounting the devframe:
+`importFrom` accepts two shapes:
+
+- **A URL the host serves** — a single self-contained ES module, loading outside any chunk graph. Works on every host.
+- **A bare npm specifier** (`'vite-plugin-vue-tracer/client/vite-devtools'`) — resolved through the host runtime, where supported.
+
+For the URL shape, attach the built bundle when mounting the devframe:
 
 ```ts
 await ctx.install(myDevframe, {
@@ -146,6 +151,35 @@ await ctx.install(myDevframe, {
 
 Under Vite, `/@fs/<absolute path>` serves the built bundle directly; other hosts mount the bundle's directory statically and pass that URL instead.
 
+### Bare npm specifiers
+
+Bare specifiers are a **host-runtime capability**. A host that can serve npm modules to the browser advertises a resolution template as `ConnectionMeta.configs.dock.clientModuleResolution` — the `{specifier}` token is replaced with the specifier, and every client-script loader (the client host, the hub-ui viewers, `__client-imports.js`) applies it before importing:
+
+```ts
+// A Vite host resolves bare specifiers through its own module graph.
+// `@devframes/vite/hub` declares this by default.
+initHub({ clientModuleResolution: '/@id/{specifier}' })
+```
+
+On a Vite host, `/@id/<specifier>` routes the import through Vite's own resolution and import-analysis, so the script's transitive bare imports work too and resolve in the same module graph as the inspected app — a plugin whose injected app-side code and dock client script import the same modules shares their instances. A plugin can then declare its dock with just the specifier:
+
+```ts
+ctx.docks.register({
+  type: 'action',
+  id: 'vue-tracer',
+  title: 'Vue Tracer',
+  icon: 'ph:crosshair-simple-duotone',
+  action: { importFrom: 'vite-plugin-vue-tracer/client/vite-devtools' },
+})
+```
+
+A host that declares no template (Next.js today) supports the URL shape only — registering a bare specifier there warns [`DF8111`](/errors/DF8111). A viewer can also resolve bare specifiers itself with `createDevframeClientHost({ resolveClientModule })`, which wins over the host template.
+
+Two guarantees to design against:
+
+- **Client scripts always execute in the inspected page's realm** — the same `window` as the app being inspected.
+- **Module identity is best-effort, realm identity is the contract.** On Vite hosts a bare specifier shares the app's module graph; elsewhere a script ships as its own bundle. A plugin keeping shared state between its injected app code and its dock script should anchor that state on `globalThis` (vue-tracer's `__vue_tracer__` store is the reference pattern) rather than rely on both sides importing one module instance.
+
 ### Dual boots
 
 The [a11y inspector](/plugins/a11y)'s in-page agent is the canonical client script, and it boots both ways from one bundle: the default export accepts the client-script context (mirroring each scan into the hub's messages feed), while a deferred, globally-guarded self-boot lets a plain `<script type="module">` start the same agent outside a hub. The context-ful call wins because the hub invokes the default export before the deferred self-boot runs.
diff --git a/examples/demo-dock-client/README.md b/examples/demo-dock-client/README.md
new file mode 100644
index 00000000..8f41e5b8
--- /dev/null
+++ b/examples/demo-dock-client/README.md
@@ -0,0 +1,16 @@
+# Demo Dock Client
+
+The shared dock client script the two reference hubs consume in their two supported shapes — one package, both `importFrom` forms:
+
+- **`hub-vite`** registers it by **bare specifier** (`action: { importFrom: 'demo-dock-client' }`). The Vite host advertises `clientModuleResolution: '/@id/{specifier}'` (the `@devframes/vite/hub` default), so the client host imports `dist/index.mjs` through Vite's own module graph — its bare `nanoevents` import resolves there too.
+- **`hub-next`** mounts the prebuilt **self-contained bundle** (`dist/bundle.mjs`, nanoevents inlined) statically and passes the served URL. Next declares no `clientModuleResolution`, so the URL shape is the supported one there.
+
+The script itself demonstrates the state pattern bare-specifier plugins should follow: shared state anchored on `globalThis` (`__devframes_demo_dock_client__`), the same design as `vite-plugin-vue-tracer`'s `__vue_tracer__` store — realm identity is the contract, module identity is best-effort. On each dock activation it bumps the shared counter and reports into the hub's messages feed, naming the URL it was loaded from.
+
+## Entries
+
+| Entry | Built as | Role |
+|---|---|---|
+| `demo-dock-client` | `dist/index.mjs` (deps external) | Bare-specifier consumption through a host's module graph |
+| — | `dist/bundle.mjs` (self-contained) | URL consumption on hosts without bare-specifier resolution |
+| `demo-dock-client/node` | `dist/node.mjs` | Node helper exporting `demoDockClientBundlePath` for static mounting |
diff --git a/examples/demo-dock-client/package.json b/examples/demo-dock-client/package.json
new file mode 100644
index 00000000..0953066b
--- /dev/null
+++ b/examples/demo-dock-client/package.json
@@ -0,0 +1,25 @@
+{
+  "name": "demo-dock-client",
+  "type": "module",
+  "version": "0.9.0",
+  "private": true,
+  "description": "Reference dock client script for the hub examples: bare npm imports and globalThis-anchored shared state.",
+  "homepage": "https://github.com/devframes/devframe/tree/main/examples/demo-dock-client",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./node": "./dist/node.mjs",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "nanoevents": "catalog:frontend"
+  },
+  "devDependencies": {
+    "@devframes/hub": "workspace:*",
+    "@types/node": "catalog:types",
+    "tsdown": "catalog:build"
+  }
+}
diff --git a/examples/demo-dock-client/src/index.ts b/examples/demo-dock-client/src/index.ts
new file mode 100644
index 00000000..b071302f
--- /dev/null
+++ b/examples/demo-dock-client/src/index.ts
@@ -0,0 +1,50 @@
+import type { DockClientScriptContext } from '@devframes/hub/client'
+import type { Emitter } from 'nanoevents'
+import { createNanoEvents } from 'nanoevents'
+
+interface DemoEvents {
+  activated: (count: number) => void
+}
+
+interface DemoStore {
+  /** How many times the demo dock has been activated on this page. */
+  activations: number
+  /** Shared emitter — every module instance converges on this one. */
+  events: Emitter<DemoEvents>
+}
+
+const KEY_GLOBAL = '__devframes_demo_dock_client__'
+
+/**
+ * Shared state anchored on `globalThis`, the pattern
+ * `vite-plugin-vue-tracer`'s `__vue_tracer__` store establishes: the same
+ * script may load as a Vite-graph module on one host and as a self-contained
+ * bundle on another, so two module instances must converge on one store
+ * rather than rely on module identity. Realm identity (the inspected page's
+ * `window`) is the contract; module identity is best-effort.
+ */
+function getStore(): DemoStore {
+  const holder = globalThis as Record<string, unknown> & { [KEY_GLOBAL]?: DemoStore }
+  if (!holder[KEY_GLOBAL]) {
+    const store: DemoStore = { activations: 0, events: createNanoEvents<DemoEvents>() }
+    Object.defineProperty(holder, KEY_GLOBAL, { value: store, configurable: true, enumerable: false })
+  }
+  return holder[KEY_GLOBAL]!
+}
+
+/**
+ * The dock `action` client script: counts activations in the shared store and
+ * mirrors each one into the hub's messages feed, so both consumption modes
+ * (bare specifier through the host's module graph, self-contained bundle by
+ * URL) demonstrably run the same code against the same state.
+ */
+export default function setup(ctx: DockClientScriptContext): void {
+  const store = getStore()
+  ctx.current.events.on('entry:activated', () => {
+    store.activations += 1
+    store.events.emit('activated', store.activations)
+    void ctx.messages.info(`Demo client script activated (#${store.activations} this page)`, {
+      description: `Loaded from ${new URL(import.meta.url).pathname}`,
+    })
+  })
+}
diff --git a/examples/demo-dock-client/src/node.ts b/examples/demo-dock-client/src/node.ts
new file mode 100644
index 00000000..4065a1c5
--- /dev/null
+++ b/examples/demo-dock-client/src/node.ts
@@ -0,0 +1,10 @@
+import { fileURLToPath } from 'node:url'
+
+/**
+ * Absolute path of the prebuilt, self-contained client script
+ * (`dist/bundle.mjs`, nanoevents inlined). A host without bare-specifier
+ * resolution mounts this file's directory statically and passes the served
+ * URL as the dock's `importFrom` — the same pattern as
+ * `@devframes/plugin-a11y`'s `a11yAgentBundlePath`.
+ */
+export const demoDockClientBundlePath: string = fileURLToPath(new URL('./bundle.mjs', import.meta.url))
diff --git a/examples/demo-dock-client/tsconfig.json b/examples/demo-dock-client/tsconfig.json
new file mode 100644
index 00000000..85d98824
--- /dev/null
+++ b/examples/demo-dock-client/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["esnext", "dom"],
+    "types": ["node"],
+    "noEmit": true
+  },
+  "include": ["src", "tsdown.config.ts"],
+  "exclude": ["dist", "node_modules"]
+}
diff --git a/examples/demo-dock-client/tsdown.config.ts b/examples/demo-dock-client/tsdown.config.ts
new file mode 100644
index 00000000..e2d82604
--- /dev/null
+++ b/examples/demo-dock-client/tsdown.config.ts
@@ -0,0 +1,41 @@
+import { defineConfig } from 'tsdown'
+
+const tsconfig = '../../tsconfig.base.json'
+
+// Two builds of the same client script, one per consumption mode the hub
+// examples demonstrate:
+//   1. `dist/index.mjs` — dependencies stay external (`import 'nanoevents'`
+//      survives as a bare import), for hosts that resolve bare specifiers
+//      through their own module graph (hub-vite imports
+//      `'demo-dock-client'` via the Vite `/@id/{specifier}` template);
+//   2. `dist/bundle.mjs` — self-contained (nanoevents inlined), for hosts
+//      without bare-specifier resolution (hub-next mounts it statically and
+//      passes the served URL as `importFrom`).
+// Plus the node-side path helper the Next host uses to locate the bundle.
+export default defineConfig([
+  {
+    clean: true,
+    platform: 'browser',
+    tsconfig,
+    dts: false,
+    outExtensions: () => ({ js: '.mjs' }),
+    entry: { index: 'src/index.ts' },
+  },
+  {
+    clean: false,
+    platform: 'browser',
+    tsconfig,
+    dts: false,
+    outExtensions: () => ({ js: '.mjs' }),
+    entry: { bundle: 'src/index.ts' },
+    deps: { alwaysBundle: ['nanoevents'] },
+  },
+  {
+    clean: false,
+    platform: 'node',
+    tsconfig,
+    dts: false,
+    outExtensions: () => ({ js: '.mjs' }),
+    entry: { node: 'src/node.ts' },
+  },
+])
diff --git a/examples/hub-next/README.md b/examples/hub-next/README.md
index ab98534b..941338d6 100644
--- a/examples/hub-next/README.md
+++ b/examples/hub-next/README.md
@@ -47,6 +47,7 @@ The instance is memoized on `globalThis`, so Next's dev-time module re-evaluatio
 - `createDevframeClientHost()` boots the hub's framework-level client runtime in the host page: it publishes the shared client context and imports each dock's `clientScript` (here, the a11y agent) so plugins run code in the page being inspected
 - The **JSON Render** dock renders through a **local React renderer** (`src/client/json-render/react-renderer.tsx` - a compact React port of the base catalog) registered at `createDevframeClientHost({ renderers })`. The hub *also* publishes the reference Vue frontend through its renderer manifest (`renderers: [jsonRenderUiRenderer()]` on `initHub`), but local registration takes precedence - witnessing that any frontend implementing the `JsonRenderDockRenderer` contract can replace the reference one. Delete the local `renderers` option and the same dock renders via the manifest-served module instead. (The sibling `hub-vite` witness ships no local renderer and consumes the manifest directly - the other side of the swap seam.)
 - The **No Renderer** dock witnesses the missing-renderer path: its type is covered by nothing, so `renderers.mount()` resolves `{ status: 'missing-renderer' }` and the shell shows *No renderer for "demo-unrendered" in the current environment* instead of a dead panel
+- The **Client Script Demo** dock witnesses the **URL shape of client scripts**: this host declares no `clientModuleResolution` (Next's bundler exposes no browser-reachable on-demand module URL, so bare-specifier client scripts are unsupported here), so it mounts `demo-dock-client`'s prebuilt self-contained bundle statically and passes the served URL as `action.importFrom`. The sibling `hub-vite` host consumes the **same package** as a bare npm specifier through its `/@id/{specifier}` template - the two shapes of `importFrom` side by side
 
 ## Hosting built-in plugins in a bundler
 
@@ -58,6 +59,7 @@ The plugins run node-side (child processes, the native `zigpty` PTY backend) and
 |---|---|
 | `src/client/devframe/next-devframe-hub.ts` | The Next host - one `initHub()` call: devframes (incl. the a11y agent's dock `clientScript`), hub RPCs, commands, the json-render dock + renderer manifest, instance-registry registration |
 | `src/client/devframe/unrendered-dock.ts` | A dock type registered with no renderer on purpose - the missing-renderer fallback witness |
+| `../demo-dock-client/` | The shared demo client script, consumed here as a statically-mounted self-contained bundle |
 | `src/client/app/%5F_devframes/[[...path]]/route.ts` | The one catch-all - delegates every `/__devframes/*` request to the instance's `handler` |
 | `src/client/app/page.tsx` | The browser UI that consumes the hub protocol, including the interactive-OTP authorization view |
 | `src/client/app/icons.ts` | Offline Phosphor icons for the dock |
diff --git a/examples/hub-next/package.json b/examples/hub-next/package.json
index 4c31de82..f4611d29 100644
--- a/examples/hub-next/package.json
+++ b/examples/hub-next/package.json
@@ -27,6 +27,7 @@
     "@devframes/plugin-terminals": "workspace:*",
     "@json-render/react": "catalog:frontend",
     "colorjs.io": "catalog:frontend",
+    "demo-dock-client": "workspace:*",
     "devframe": "workspace:*",
     "dompurify": "catalog:frontend",
     "json-render": "workspace:*",
diff --git a/examples/hub-next/src/client/app/page.tsx b/examples/hub-next/src/client/app/page.tsx
index df9ded24..4f6c2b26 100644
--- a/examples/hub-next/src/client/app/page.tsx
+++ b/examples/hub-next/src/client/app/page.tsx
@@ -65,6 +65,13 @@ function isRenderableDock(d: DevframeDockEntry): boolean {
   return isIframeDock(d) || !NATIVE_TYPES.has(d.type)
 }
 
+// `action` docks carry no panel: they render in the rail as momentary buttons
+// whose click fires `entry:activated` for the dock's client script (loaded by
+// the client host at boot), leaving the panel selection untouched.
+function isActionDock(d: DevframeDockEntry): boolean {
+  return d.type === 'action'
+}
+
 // One iframe is kept alive per `frameId` (shared-frame docks) or per dock id
 // (plain iframe docks), so shared-frame member docks reuse the same element and
 // soft-navigate rather than reload.
@@ -498,6 +505,8 @@ export default function Page() {
   }, [])
 
   const renderableDocks = useMemo(() => docks.filter(isRenderableDock), [docks])
+  // The rail also lists momentary `action` docks alongside the selectable ones.
+  const railDocks = useMemo(() => docks.filter(d => isRenderableDock(d) || isActionDock(d)), [docks])
 
   // Wire each dock's state once so a selection change - from a click, or from
   // the frame-nav adapter reacting to in-frame navigation - updates the UI.
@@ -645,13 +654,24 @@ export default function Page() {
         <aside className="flex flex-col gap-0.5 of-auto border-r border-base bg-secondary p2">
           <h2 className="px2 py1 text-[0.68rem] uppercase tracking-wider color-muted">Docks</h2>
           <ul className="m0 flex flex-col list-none gap-0.5 p0">
-            {renderableDocks.length === 0
+            {railDocks.length === 0
               ? <li className="op-mute px2 text-sm">No docks</li>
-              : renderableDocks.map(dock => (
+              : railDocks.map(dock => (
                   <li key={dock.id}>
                     <button
                       type="button"
-                      onClick={() => void hostRef.current?.context.docks.switchEntry(dock.id)}
+                      onClick={() => {
+                        const ctx = hostRef.current?.context
+                        if (!ctx)
+                          return
+                        // Momentary action dock: fire its client script, keep
+                        // the panel selection as-is.
+                        if (isActionDock(dock)) {
+                          ctx.docks.getStateById(dock.id)?.events.emit('entry:activated')
+                          return
+                        }
+                        void ctx.docks.switchEntry(dock.id)
+                      }}
                       className={`relative inline-flex items-center gap-1.5 max-w-52 px-2 py-1 rounded-md border border-transparent text-sm op-fade select-none cursor-pointer transition hover:op100 hover:bg-active w-full! max-w-none! gap-2.5!${dock.id === selectedDockId ? ' op100! bg-active border-base! color-base' : ''}`}
                       title={dock.title}
                     >
diff --git a/examples/hub-next/src/client/devframe/next-devframe-hub.ts b/examples/hub-next/src/client/devframe/next-devframe-hub.ts
index 7c5c7939..93754fd3 100644
--- a/examples/hub-next/src/client/devframe/next-devframe-hub.ts
+++ b/examples/hub-next/src/client/devframe/next-devframe-hub.ts
@@ -126,6 +126,44 @@ async function loadA11yAgentMount(): Promise<A11yAgentMount | null> {
   }
 }
 
+/**
+ * URL base the demo dock-client bundle is served under - inside the hub
+ * namespace, so the one catch-all route reaches it.
+ */
+const DEMO_CLIENT_MOUNT_BASE = `${DEVFRAMES_HUB_BASE}demo-dock-client/`
+
+interface DemoDockClientMount {
+  /** On-disk directory holding the built self-contained bundle. */
+  dir: string
+  /** Same-origin URL of the bundle, importable by the hub client runtime. */
+  importFrom: string
+}
+
+/**
+ * Locate the shared demo dock-client script (examples/demo-dock-client) as a
+ * prebuilt **self-contained bundle** - this host declares no
+ * `clientModuleResolution` (Next's bundler exposes no browser-reachable
+ * on-demand module URL), so bare-specifier client scripts are unsupported
+ * here and the script ships by URL instead. The Vite reference host consumes
+ * the same package as a bare specifier through its `/@id/{specifier}`
+ * template - the capability difference between the two hosts. Loaded through
+ * the same bundler-ignored dynamic `import()` as the plugins (the package
+ * resolves its bundle via `import.meta.url`). Returns `null` if unbuilt.
+ */
+async function loadDemoDockClientMount(): Promise<DemoDockClientMount | null> {
+  try {
+    const mod = await import(/* webpackIgnore: true */ /* turbopackIgnore: true */ 'demo-dock-client/node')
+    const bundle = mod.demoDockClientBundlePath as string
+    return {
+      dir: dirname(bundle),
+      importFrom: `${DEMO_CLIENT_MOUNT_BASE}bundle.mjs`,
+    }
+  }
+  catch {
+    return null
+  }
+}
+
 export interface NextDevframeHubOptions {
   /** Pin the side-car RPC/WS port. Default: `initHub` walks a free port near 9777. */
   port?: number
@@ -186,6 +224,11 @@ export async function nextDevframeHub(
   // the origin, so their BroadcastChannel connects.
   const a11yAgent = await loadA11yAgentMount()
 
+  // The shared demo dock-client script, served as a prebuilt self-contained
+  // bundle (see loadDemoDockClientMount above for why this host uses the
+  // URL shape rather than a bare specifier).
+  const demoDockClient = await loadDemoDockClientMount()
+
   // The reference json-render renderer module, loaded the same bundler-ignored
   // way so its `import.meta.url` bundle path resolves to the published `dist`.
   const jsonRenderRenderer = await loadJsonRenderUiRenderer()
@@ -289,6 +332,21 @@ export async function nextDevframeHub(
       if (a11yAgent)
         await ctx.host.mountStatic(A11Y_AGENT_MOUNT_BASE, a11yAgent.dir)
 
+      // The demo dock-client script - the same package the Vite reference
+      // host loads via a bare specifier - mounted statically and attached as
+      // a momentary `action` dock by its served URL.
+      if (demoDockClient) {
+        await ctx.host.mountStatic(DEMO_CLIENT_MOUNT_BASE, demoDockClient.dir)
+        ctx.docks.register({
+          type: 'action',
+          id: 'example:demo-client-script',
+          title: 'Client Script Demo',
+          icon: 'ph:plugs-connected-duotone',
+          category: 'app',
+          action: { importFrom: demoDockClient.importFrom },
+        })
+      }
+
       // Dogfood the opt-in JSON-render hub integration: author a view on the
       // hub context and project it onto a `json-render` dock. The client
       // (app/page.tsx) renders it with a mini React registry.
diff --git a/examples/hub-vite/README.md b/examples/hub-vite/README.md
index b93eeb00..608a2759 100644
--- a/examples/hub-vite/README.md
+++ b/examples/hub-vite/README.md
@@ -34,6 +34,7 @@ The **RPC & State Inspector** carries an **Instances** tab that lists every devf
 - `createDevframeClientHost()` boots the hub's framework-level client runtime in the host page: it publishes the shared client context and imports each dock's `clientScript` (here, the a11y agent) so plugins run code in the page being inspected
 - The **JSON Render** dock is rendered by a prebuilt module this page never compiles in: the host passes `renderers: [jsonRenderUiRenderer()]` to `initHub()`, the hub serves the module at `/__devframes/__renderers/json-render.mjs` and publishes it in the renderer manifest, and the client's renderer registry imports it lazily on first mount. (The sibling `hub-next` witness registers a local React renderer for the same type instead, which takes precedence over the manifest - the other side of the swap seam.)
 - The **No Renderer** dock witnesses the missing-renderer path: its type is covered by nothing, so `renderers.mount()` resolves `{ status: 'missing-renderer' }` and the shell shows *No renderer for "demo-unrendered" in the current environment* instead of a dead panel
+- The **Client Script Demo** dock witnesses **bare-specifier client scripts**: its `action.importFrom` is the npm package name `demo-dock-client`, resolved through the Vite host's advertised `clientModuleResolution` template (`'/@id/{specifier}'`, the `@devframes/vite/hub` default) - the script and its own bare `nanoevents` import load through Vite's module graph, shared with this very page. The sibling `hub-next` host has no such runtime capability, so it consumes the **same package** as a prebuilt self-contained bundle served by URL - the two shapes of `importFrom` side by side
 
 ## Build your own
 
@@ -46,6 +47,7 @@ The dock UI is plain DOM in `src/client/`. To skin your own viewer, read the sam
 | `src/vite-devframe-hub.ts` | The Vite host - one `initHub()` call mounted as connect middleware, plus instance-registry registration |
 | `vite.config.ts` | Passes the built-in plugins and demo devframes to the host's `devframes` option; attaches the a11y agent as its dock's `clientScript`; composes the json-render frontend via `renderers` |
 | `src/unrendered-dock.ts` | A dock type registered with no renderer on purpose - the missing-renderer fallback witness |
+| `../demo-dock-client/` | The shared demo client script, consumed here via bare specifier (`action: { importFrom: 'demo-dock-client' }`) |
 | `src/client/main.ts` | The browser UI that consumes the hub protocol, including the interactive-OTP authorization view |
 | `src/client/icons.ts` | Offline Phosphor icons for the dock |
 | `index.html` | The UI shell |
diff --git a/examples/hub-vite/package.json b/examples/hub-vite/package.json
index 8a8afe4b..7b134055 100644
--- a/examples/hub-vite/package.json
+++ b/examples/hub-vite/package.json
@@ -26,6 +26,7 @@
     "@devframes/plugin-terminals": "workspace:*",
     "@devframes/vite": "workspace:*",
     "colorjs.io": "catalog:frontend",
+    "demo-dock-client": "workspace:*",
     "devframe": "workspace:*",
     "dompurify": "catalog:frontend",
     "json-render": "workspace:*"
diff --git a/examples/hub-vite/src/client/main.ts b/examples/hub-vite/src/client/main.ts
index 636fdb39..4fc57279 100644
--- a/examples/hub-vite/src/client/main.ts
+++ b/examples/hub-vite/src/client/main.ts
@@ -130,6 +130,13 @@ function isRenderableDock(d: DevframeDockEntry): boolean {
   return isIframeDock(d) || !NATIVE_TYPES.has(d.type)
 }
 
+// `action` docks carry no panel: they render in the rail as momentary buttons
+// whose click fires `entry:activated` for the dock's client script (loaded by
+// the client host at boot), leaving the panel selection untouched.
+function isActionDock(d: DevframeDockEntry): boolean {
+  return d.type === 'action'
+}
+
 // ── client-only dock content (synthesized in the browser) ───────────────────
 
 // A self-contained document for the client-only "Client Notes" dock, from a
@@ -459,9 +466,10 @@ function wireDockRail(host: Awaited<ReturnType<typeof createDevframeClientHost>>
   // (a click, or the frame-nav adapter reacting to in-frame navigation).
   const wired = new Set<string>()
   function render(): void {
-    const list = docksCtx.entries.filter(isRenderableDock)
-    if (!docksCtx.selectedId && list.length > 0)
-      void docksCtx.switchEntry(list[0].id)
+    const list = docksCtx.entries.filter(d => isRenderableDock(d) || isActionDock(d))
+    const selectable = list.filter(isRenderableDock)
+    if (!docksCtx.selectedId && selectable.length > 0)
+      void docksCtx.switchEntry(selectable[0].id)
 
     for (const entry of list) {
       if (wired.has(entry.id))
@@ -478,7 +486,15 @@ function wireDockRail(host: Awaited<ReturnType<typeof createDevframeClientHost>>
   el.docks.addEventListener('click', (event) => {
     const button = (event.target as HTMLElement).closest<HTMLButtonElement>('button[data-dock-id]')
     const id = button?.dataset.dockId
-    if (id && id !== docksCtx.selectedId)
+    if (!id)
+      return
+    // Momentary action dock: fire its client script, keep the panel as-is.
+    const state = docksCtx.getStateById(id)
+    if (state && isActionDock(state.entryMeta)) {
+      state.events.emit('entry:activated')
+      return
+    }
+    if (id !== docksCtx.selectedId)
       void docksCtx.switchEntry(id)
   })
 
diff --git a/examples/hub-vite/vite.config.ts b/examples/hub-vite/vite.config.ts
index faabdb20..4fd577ec 100644
--- a/examples/hub-vite/vite.config.ts
+++ b/examples/hub-vite/vite.config.ts
@@ -176,6 +176,22 @@ export default defineConfig({
           icon: 'ph:layout-duotone',
           category: 'app',
         }))
+        // Bare-specifier client script demo: `importFrom` names the npm
+        // package itself. The Vite host advertises its default
+        // `clientModuleResolution` (`'/@id/{specifier}'`), so the client host
+        // imports the script through Vite's own module graph — its bare
+        // `nanoevents` import resolves there too. The Next reference host
+        // consumes the same package as a prebuilt self-contained bundle
+        // instead (see examples/demo-dock-client).
+        context.docks.register({
+          type: 'action',
+          id: 'example:demo-client-script',
+          title: 'Client Script Demo',
+          icon: 'ph:plugs-connected-duotone',
+          category: 'app',
+          action: { importFrom: 'demo-dock-client' },
+        })
+
         // Witness the missing-renderer path: a dock type nothing covers —
         // the client shows its fallback view instead of a dead panel.
         context.docks.register(unrenderedDockEntry)
diff --git a/knip.jsonc b/knip.jsonc
index 11898832..ecfa6feb 100644
--- a/knip.jsonc
+++ b/knip.jsonc
@@ -82,6 +82,20 @@
         "@devframes/plugin-terminals"
       ]
     },
+    "examples/hub-vite": {
+      // `demo-dock-client` is consumed only as a runtime string — the demo
+      // dock's `action.importFrom` bare specifier, resolved by Vite through
+      // the hub's `clientModuleResolution` template (`/@id/{specifier}`) —
+      // never a static import knip's graph can see.
+      "ignoreDependencies": ["demo-dock-client"]
+    },
+    // Multi-entry example package (see `packages/devframe` above for why
+    // exports-mapped entries are listed explicitly): `src/index.ts` is the
+    // dock client script the hub examples import at runtime by URL/specifier,
+    // `src/node.ts` the bundle-path helper the Next host loads dynamically.
+    "examples/demo-dock-client": {
+      "entry": ["src/{index,node}.ts"]
+    },
     "examples/next-runtime-snapshot": {
       // Same nested Next.js client root as `hub-next` above.
       "postcss": {
diff --git a/packages/hub-ui/src/client/state/setup-script.ts b/packages/hub-ui/src/client/state/setup-script.ts
index 19337c5b..f94b173f 100644
--- a/packages/hub-ui/src/client/state/setup-script.ts
+++ b/packages/hub-ui/src/client/state/setup-script.ts
@@ -1,5 +1,6 @@
 import type { ClientScriptEntry, DevframeDockUserEntry } from '@devframes/hub'
 import type { DockClientScriptContext } from '@devframes/hub/client'
+import { isBareModuleSpecifier, resolveClientModuleSpecifier } from '@devframes/hub/client'
 
 /**
  * Resolve the {@link ClientScriptEntry} a dock entry carries — an `action`'s
@@ -25,20 +26,36 @@ async function _executeSetupScript(
   const script = clientScriptOf(entry)
   if (!script?.importFrom)
     throw new Error(`[@devframes/hub-ui] Dock entry "${entry.id}" carries no client script to run`)
+  // A bare specifier resolves through the host-advertised template
+  // (`configs.dock.clientModuleResolution`); URL specifiers pass through
+  // untouched. Mirrors `@devframes/hub`'s `createDevframeClientHost`.
+  const specifier = resolveClientModuleSpecifier(script.importFrom, {
+    connectionMeta: context.rpc.connectionMeta,
+    // Optional-chained: a partial rpc stub (stories, bespoke viewers) may
+    // carry no connection record — the template then resolves page-relative.
+    metaBaseUrl: context.rpc.connection?.metaBaseUrl,
+  })
   try {
     // Keep this a *native* dynamic import in every bundler — the specifier is
     // a runtime URL served by the hub, not a build-time module. Mirrors the
     // client-script loading of `@devframes/hub`'s `createDevframeClientHost`.
-    const mod = await import(/* @vite-ignore */ /* webpackIgnore: true */ script.importFrom)
+    const mod = await import(/* @vite-ignore */ /* webpackIgnore: true */ specifier)
     const fn = mod[script.importName ?? 'default']
     if (typeof fn !== 'function')
-      throw new Error(`[@devframes/hub-ui] "${script.importFrom}" exports no callable "${script.importName ?? 'default'}"`)
+      throw new Error(`[@devframes/hub-ui] "${specifier}" exports no callable "${script.importName ?? 'default'}"`)
     await fn(context)
   }
   catch (error) {
     // TODO: maybe popup a error toast here?
     // TODO: A unified logger API
-    console.error('[@devframes/hub-ui] Error executing client script', error)
+    // An unresolved bare specifier is a host-capability gap, not a plugin
+    // bug — say so instead of surfacing the browser's opaque TypeError.
+    const hint = specifier === script.importFrom && isBareModuleSpecifier(script.importFrom)
+      ? ` — "${specifier}" is a bare npm specifier and this host advertises no client-module resolution `
+      + '(`ConnectionMeta.configs.dock.clientModuleResolution`). Serve the script as a self-contained '
+      + 'bundle by URL, or run under a host that resolves bare specifiers (e.g. Vite: `/@id/{specifier}`).'
+      : ''
+    console.error(`[@devframes/hub-ui] Error executing client script${hint}`, error)
     throw error
   }
 }
diff --git a/packages/hub/src/client-modules.test.ts b/packages/hub/src/client-modules.test.ts
new file mode 100644
index 00000000..4b191b14
--- /dev/null
+++ b/packages/hub/src/client-modules.test.ts
@@ -0,0 +1,102 @@
+import type { ConnectionMeta } from 'devframe/types'
+import { describe, expect, it } from 'vitest'
+import {
+  applyClientModuleResolutionTemplate,
+  isBareModuleSpecifier,
+  resolveClientModuleSpecifier,
+} from './client-modules'
+
+function metaWith(clientModuleResolution?: string): ConnectionMeta {
+  return {
+    backend: 'websocket',
+    ...(clientModuleResolution
+      ? { configs: { dock: { clientModuleResolution } } }
+      : {}),
+  }
+}
+
+describe('isBareModuleSpecifier', () => {
+  it('recognizes npm-style names, scoped packages, and subpaths', () => {
+    expect(isBareModuleSpecifier('nanoevents')).toBe(true)
+    expect(isBareModuleSpecifier('@scope/pkg')).toBe(true)
+    expect(isBareModuleSpecifier('vite-plugin-vue-tracer/client/vite-devtools')).toBe(true)
+  })
+
+  it('rejects everything the browser resolves natively', () => {
+    expect(isBareModuleSpecifier('/@fs/abs/path.js')).toBe(false)
+    expect(isBareModuleSpecifier('/@id/pkg')).toBe(false)
+    expect(isBareModuleSpecifier('./relative.js')).toBe(false)
+    expect(isBareModuleSpecifier('../up.js')).toBe(false)
+    expect(isBareModuleSpecifier('//cdn.example.com/mod.js')).toBe(false)
+    expect(isBareModuleSpecifier('https://example.com/mod.js')).toBe(false)
+    expect(isBareModuleSpecifier('data:text/javascript,export default 1')).toBe(false)
+    expect(isBareModuleSpecifier('blob:http://localhost/x')).toBe(false)
+    expect(isBareModuleSpecifier('')).toBe(false)
+    expect(isBareModuleSpecifier('   ')).toBe(false)
+  })
+})
+
+describe('applyClientModuleResolutionTemplate', () => {
+  it('replaces the {specifier} token', () => {
+    expect(applyClientModuleResolutionTemplate('/@id/{specifier}', 'foo/bar')).toBe('/@id/foo/bar')
+  })
+
+  it('uses a token-less template as a prefix', () => {
+    expect(applyClientModuleResolutionTemplate('/modules/', 'foo')).toBe('/modules/foo')
+  })
+})
+
+describe('resolveClientModuleSpecifier', () => {
+  it('passes URL specifiers through untouched, template or not', () => {
+    expect(resolveClientModuleSpecifier('/@fs/abs/inject.js', {
+      connectionMeta: metaWith('/@id/{specifier}'),
+      metaBaseUrl: 'http://localhost:5173/__devframes/__connection.json',
+    })).toBe('/@fs/abs/inject.js')
+    expect(resolveClientModuleSpecifier('./mod.js', {})).toBe('./mod.js')
+  })
+
+  it('leaves a bare specifier unchanged when nothing resolves it', () => {
+    expect(resolveClientModuleSpecifier('foo/bar', { connectionMeta: metaWith() })).toBe('foo/bar')
+    expect(resolveClientModuleSpecifier('foo/bar', {})).toBe('foo/bar')
+  })
+
+  it('applies the host-advertised template, resolved against metaBaseUrl', () => {
+    expect(resolveClientModuleSpecifier('vite-plugin-vue-tracer/client/vite-devtools', {
+      connectionMeta: metaWith('/@id/{specifier}'),
+      metaBaseUrl: 'http://localhost:5173/__devframes/__connection.json',
+    })).toBe('http://localhost:5173/@id/vite-plugin-vue-tracer/client/vite-devtools')
+  })
+
+  it('returns the applied template as-is without a usable base', () => {
+    expect(resolveClientModuleSpecifier('foo', {
+      connectionMeta: metaWith('/@id/{specifier}'),
+    })).toBe('/@id/foo')
+  })
+
+  it('prefers the explicit resolveClientModule option over the template', () => {
+    expect(resolveClientModuleSpecifier('foo', {
+      resolveClientModule: s => `/custom/${s}`,
+      connectionMeta: metaWith('/@id/{specifier}'),
+      metaBaseUrl: 'http://localhost:5173/__devframes/__connection.json',
+    })).toBe('/custom/foo')
+  })
+
+  it('falls through to the template when the option returns undefined', () => {
+    expect(resolveClientModuleSpecifier('foo', {
+      resolveClientModule: () => undefined,
+      connectionMeta: metaWith('/@id/{specifier}'),
+      metaBaseUrl: 'http://localhost:5173/__devframes/__connection.json',
+    })).toBe('http://localhost:5173/@id/foo')
+  })
+
+  it('never calls the option for URL specifiers', () => {
+    let called = false
+    expect(resolveClientModuleSpecifier('/already/a/url.js', {
+      resolveClientModule: (s) => {
+        called = true
+        return `/custom/${s}`
+      },
+    })).toBe('/already/a/url.js')
+    expect(called).toBe(false)
+  })
+})
diff --git a/packages/hub/src/client-modules.ts b/packages/hub/src/client-modules.ts
new file mode 100644
index 00000000..eb37bdc5
--- /dev/null
+++ b/packages/hub/src/client-modules.ts
@@ -0,0 +1,93 @@
+import type { ConnectionMeta } from 'devframe/types'
+
+/** Token a {@link DockConnectionConfig.clientModuleResolution} template replaces with the bare specifier. */
+export const CLIENT_MODULE_SPECIFIER_TOKEN = '{specifier}'
+
+const URL_SCHEME_RE = /^[a-z][a-z\d+.-]*:/i
+
+/**
+ * Whether a client-script `importFrom` is a **bare module specifier** — an
+ * npm-style name (`vite-plugin-vue-tracer/client/vite-devtools`) rather than a
+ * URL the browser can resolve natively (root-relative, dot-relative,
+ * protocol-relative, or carrying a URL scheme).
+ */
+export function isBareModuleSpecifier(specifier: string): boolean {
+  const value = specifier.trim()
+  if (!value)
+    return false
+  return !value.startsWith('/')
+    && !value.startsWith('./')
+    && !value.startsWith('../')
+    && !URL_SCHEME_RE.test(value)
+}
+
+export interface ResolveClientModuleSpecifierOptions {
+  /**
+   * Explicit resolver — wins over the host-advertised template. Return a URL
+   * to import instead, or `undefined` to fall through to the template.
+   */
+  resolveClientModule?: (specifier: string) => string | undefined
+  /**
+   * The connection meta carrying the host-declared
+   * `configs.dock.clientModuleResolution` template.
+   */
+  connectionMeta?: ConnectionMeta
+  /**
+   * Absolute URL of the `__connection.json` that produced `connectionMeta`.
+   * A relative template result resolves against it, so an external viewer on
+   * another origin still imports from the host that declared the template.
+   */
+  metaBaseUrl?: string
+}
+
+/**
+ * Apply a host's client-module resolution template to a bare specifier:
+ * replace the `{specifier}` token (or suffix the specifier onto a token-less
+ * template). The result is a URL path on the host — e.g. Vite's
+ * `'/@id/{specifier}'` template maps `foo/bar` to `/@id/foo/bar`, which routes
+ * through Vite's own module graph.
+ */
+export function applyClientModuleResolutionTemplate(template: string, specifier: string): string {
+  return template.includes(CLIENT_MODULE_SPECIFIER_TOKEN)
+    ? template.replaceAll(CLIENT_MODULE_SPECIFIER_TOKEN, specifier)
+    : template + specifier
+}
+
+/**
+ * Resolve a dock client script's `importFrom` to the URL the client host
+ * should import. URL specifiers pass through untouched; a **bare** specifier
+ * resolves through, in order:
+ *
+ * 1. the explicit {@link ResolveClientModuleSpecifierOptions.resolveClientModule}
+ *    option (a viewer's own policy),
+ * 2. the host-advertised template
+ *    (`ConnectionMeta.configs.dock.clientModuleResolution`), resolved against
+ *    `metaBaseUrl` so it targets the host's origin from any viewer,
+ * 3. unchanged — the native import may still succeed if the page carries an
+ *    import map for it.
+ */
+export function resolveClientModuleSpecifier(
+  specifier: string,
+  options: ResolveClientModuleSpecifierOptions = {},
+): string {
+  if (!isBareModuleSpecifier(specifier))
+    return specifier
+
+  const custom = options.resolveClientModule?.(specifier)
+  if (custom)
+    return custom
+
+  const template = options.connectionMeta?.configs?.dock?.clientModuleResolution
+  if (!template)
+    return specifier
+
+  const applied = applyClientModuleResolutionTemplate(template, specifier)
+  try {
+    return new URL(applied, options.metaBaseUrl).href
+  }
+  catch {
+    // No usable base (same-origin host page) — let the browser resolve the
+    // root-relative result against the page origin.
+    return applied
+  }
+}
diff --git a/packages/hub/src/client/host.ts b/packages/hub/src/client/host.ts
index c16d3884..d91b22b9 100644
--- a/packages/hub/src/client/host.ts
+++ b/packages/hub/src/client/host.ts
@@ -26,6 +26,7 @@ import type {
 import type { DockRenderer, DockRendererManifest, DockRenderersContext } from './renderers'
 import { connectDevframe } from 'devframe/client'
 import { createEventEmitter } from 'devframe/utils/events'
+import { isBareModuleSpecifier, resolveClientModuleSpecifier } from '../client-modules'
 import { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS, DOCK_RENDERERS_STATE_KEY } from '../constants'
 import { getDevframeClientContext, setDevframeClientContext } from './context'
 import { attachFrameNavClient } from './frame-nav'
@@ -57,6 +58,22 @@ export interface DevframeClientHostOptions {
    * `custom-render`, and iframe `clientScript`). Default `true`.
    */
   loadClientScripts?: boolean
+  /**
+   * Resolve a **bare-specifier** client script (`importFrom` naming an npm
+   * module, e.g. `'vite-plugin-vue-tracer/client/vite-devtools'`) to a URL
+   * this page can import — a viewer's own policy, winning over the
+   * host-advertised `ConnectionMeta.configs.dock.clientModuleResolution`
+   * template. Return `undefined` to fall through to that template. URL
+   * specifiers never reach this hook.
+   *
+   * A viewer running inside a Vite-served page can route bare specifiers
+   * through the app's own module graph:
+   *
+   * ```ts
+   * createDevframeClientHost({ resolveClientModule: s => `/@id/${s}` })
+   * ```
+   */
+  resolveClientModule?: (specifier: string) => string | undefined
   /**
    * Dock renderers to register at boot, keyed by dock `type`. The host
    * application injects the ones it wants (e.g.
@@ -501,10 +518,20 @@ export async function createDevframeClientHost(
   }
 
   async function runClientScript(entryId: string, script: ClientScriptEntry): Promise<void> {
+    // A bare specifier resolves through the explicit option, then the
+    // host-advertised template (`configs.dock.clientModuleResolution`); URL
+    // specifiers pass through untouched.
+    const specifier = resolveClientModuleSpecifier(script.importFrom, {
+      ...(options.resolveClientModule ? { resolveClientModule: options.resolveClientModule } : {}),
+      connectionMeta: rpc.connectionMeta,
+      // Optional-chained: a partial rpc stub (tests, bespoke viewers) may
+      // carry no connection record — the template then resolves page-relative.
+      metaBaseUrl: rpc.connection?.metaBaseUrl,
+    })
     try {
       // Keep this a *native* dynamic import in every bundler — the specifier
       // is a runtime URL served by the host, not a build-time module.
-      const mod = await import(/* @vite-ignore */ /* webpackIgnore: true */ /* turbopackIgnore: true */ script.importFrom)
+      const mod = await import(/* @vite-ignore */ /* webpackIgnore: true */ /* turbopackIgnore: true */ specifier)
       const fn = mod[script.importName ?? 'default']
       if (typeof fn !== 'function')
         return
@@ -519,7 +546,15 @@ export async function createDevframeClientHost(
     }
     catch (error) {
       loadedScripts.delete(entryId)
-      console.error(`[@devframes/hub] failed to load client script for "${entryId}" from ${script.importFrom}`, error)
+      // An unresolved bare specifier is a host-capability gap, not a plugin
+      // bug — say so instead of surfacing the browser's opaque TypeError.
+      const hint = specifier === script.importFrom && isBareModuleSpecifier(script.importFrom)
+        ? ' — the specifier is a bare npm specifier and this host advertises no client-module resolution '
+        + '(`ConnectionMeta.configs.dock.clientModuleResolution`). Serve the script as a self-contained '
+        + 'bundle by URL, pass `resolveClientModule` to this client host, or run under a host that '
+        + 'resolves bare specifiers (e.g. Vite: `/@id/{specifier}`).'
+        : ''
+      console.error(`[@devframes/hub] failed to load client script for "${entryId}" from ${specifier}${hint}`, error)
     }
   }
 }
diff --git a/packages/hub/src/client/index.ts b/packages/hub/src/client/index.ts
index 97bdfebd..a2257eb8 100644
--- a/packages/hub/src/client/index.ts
+++ b/packages/hub/src/client/index.ts
@@ -1,3 +1,4 @@
+export * from '../client-modules'
 export * from './client-script'
 export * from './context'
 export * from './dock-resources'
diff --git a/packages/hub/src/node/__tests__/host-docks.test.ts b/packages/hub/src/node/__tests__/host-docks.test.ts
index 392b6b6b..1139b354 100644
--- a/packages/hub/src/node/__tests__/host-docks.test.ts
+++ b/packages/hub/src/node/__tests__/host-docks.test.ts
@@ -333,3 +333,63 @@ describe('devframeDockHost ~builtin category', () => {
     expect(launcher?.digest).toBe('compiling…')
   })
 })
+
+describe('devframeDockHost bare-specifier client scripts', () => {
+  function withWarnSpy(run: (warn: ReturnType<typeof vi.spyOn>) => void): void {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      run(warn)
+    }
+    finally {
+      warn.mockRestore()
+    }
+  }
+
+  it('warns (DF8111) for a bare-specifier client script on a host without clientModuleResolution', () => {
+    withWarnSpy((warn) => {
+      const host = new DevframeDocksHost(createContext())
+      host.register({
+        type: 'action',
+        id: 'vue-tracer',
+        title: 'Vue Tracer',
+        icon: 'ph:crosshair-simple-duotone',
+        action: { importFrom: 'vite-plugin-vue-tracer/client/vite-devtools' },
+      })
+      expect(warn).toHaveBeenCalledOnce()
+      expect(warn.mock.calls[0]!.join(' ')).toMatch(/DF8111/)
+      expect(warn.mock.calls[0]!.join(' ')).toContain('vite-plugin-vue-tracer/client/vite-devtools')
+    })
+  })
+
+  it('stays silent when the host advertises clientModuleResolution', () => {
+    withWarnSpy((warn) => {
+      const context = createContext()
+      ;(context as { staticConfig: Record<string, unknown> }).staticConfig
+        = { dock: { clientModuleResolution: '/@id/{specifier}' } }
+      const host = new DevframeDocksHost(context)
+      host.register({
+        type: 'action',
+        id: 'vue-tracer',
+        title: 'Vue Tracer',
+        icon: 'ph:crosshair-simple-duotone',
+        action: { importFrom: 'vite-plugin-vue-tracer/client/vite-devtools' },
+      })
+      expect(warn).not.toHaveBeenCalled()
+    })
+  })
+
+  it('stays silent for URL client scripts on any host', () => {
+    withWarnSpy((warn) => {
+      const host = new DevframeDocksHost(createContext())
+      host.register({
+        type: 'iframe',
+        id: 'a11y',
+        title: 'A11y',
+        icon: 'ph:person-arms-spread-duotone',
+        url: '/__devframes/a11y/',
+        clientScript: { importFrom: '/@fs/abs/inject.js' },
+      })
+      expect(warn).not.toHaveBeenCalled()
+    })
+  })
+})
diff --git a/packages/hub/src/node/__tests__/initiate.test.ts b/packages/hub/src/node/__tests__/initiate.test.ts
index 51c666a6..12185055 100644
--- a/packages/hub/src/node/__tests__/initiate.test.ts
+++ b/packages/hub/src/node/__tests__/initiate.test.ts
@@ -222,6 +222,55 @@ describe('initHub', () => {
     }
   })
 
+  it('clientModuleResolution: advertised in ConnectionMeta.configs.dock and applied in __client-imports.js', async () => {
+    const wsPort = await getPort({ port: 18227, host: '127.0.0.1' })
+    const hub = initHub({
+      base: DEVFRAMES_HUB_BASE,
+      auth: false,
+      host: '127.0.0.1',
+      ws: { port: wsPort },
+      clientModuleResolution: '/@id/{specifier}',
+      devframes: [makeFrame('alpha')],
+      configure(ctx) {
+        // A bare-specifier client script (the vite-plugin-vue-tracer shape) —
+        // registered on a host that declared the resolution, so no DF8111.
+        ctx.docks.register({
+          type: 'action',
+          id: 'vue-tracer',
+          title: 'Vue Tracer',
+          icon: 'ph:crosshair-simple-duotone',
+          action: { importFrom: 'vite-plugin-vue-tracer/client/vite-devtools' },
+        })
+        // A URL client script stays verbatim in the imports module.
+        ctx.docks.register({
+          type: 'action',
+          id: 'bundled',
+          title: 'Bundled',
+          icon: 'ph:package-duotone',
+          action: { importFrom: '/__devframes/agent/inject.js' },
+        })
+      },
+    })
+
+    try {
+      await hub.ready
+      const origin = 'http://localhost:5173'
+
+      // Advertised to every client through the connection handshake.
+      const meta = await (await hub.handler(new Request(`${origin}/__devframes/__connection.json`))).json()
+      expect(meta.configs.dock).toEqual({ clientModuleResolution: '/@id/{specifier}' })
+
+      // Applied server-side in the generated dock-imports module, so external
+      // viewers importing it get resolvable URLs too.
+      const imports = await (await hub.handler(new Request(`${origin}/__devframes/__client-imports.js`))).text()
+      expect(imports).toContain('import("/@id/vite-plugin-vue-tracer/client/vite-devtools")')
+      expect(imports).toContain('import("/__devframes/agent/inject.js")')
+    }
+    finally {
+      await hub.close()
+    }
+  })
+
   it('aggregate MCP: one endpoint lists tools from every mounted frame', async () => {
     const wsPort = await getPort({ port: 18230, host: '127.0.0.1' })
     const hub = initHub({ base: DEVFRAMES_HUB_BASE, auth: false, host: '127.0.0.1', ws: { port: wsPort }, mcp: true, devframes: [makeFrame('alpha'), makeFrame('beta')] })
diff --git a/packages/hub/src/node/diagnostics.ts b/packages/hub/src/node/diagnostics.ts
index f682b364..02164523 100644
--- a/packages/hub/src/node/diagnostics.ts
+++ b/packages/hub/src/node/diagnostics.ts
@@ -72,6 +72,10 @@ export const diagnostics = defineDiagnostics({
       why: (p: { type: string }) => `Dock type "${p.type}" is not a servable renderer-module name — the hub serves each module at \`<base>__renderers/<type>.mjs\``,
       fix: 'Renderer types become URL segments, so they may only contain letters, digits, `_`, `-`, and `.`. Use a route-safe dock type (e.g. `json-render`).',
     },
+    DF8111: {
+      why: (p: { id: string, specifier: string }) => `Dock "${p.id}" declares the bare-specifier client script "${p.specifier}", but this host advertises no client-module resolution — the browser cannot resolve a bare npm specifier natively, so the script will fail to load.`,
+      fix: 'Bare specifiers are a host-runtime capability, advertised as `ConnectionMeta.configs.dock.clientModuleResolution`. Run under a host that declares it (a Vite host resolves them through its own module graph via `initHub({ clientModuleResolution: \'/@id/{specifier}\' })` — `@devframes/vite/hub` does this by default), or ship the script as a self-contained bundle and pass a URL the host serves as `importFrom` instead. A viewer may also resolve them itself via `createDevframeClientHost({ resolveClientModule })`, in which case this warning is safe to disregard.',
+    },
     DF8200: {
       why: (p: { id: string }) => `Terminal session with id "${p.id}" already registered`,
     },
diff --git a/packages/hub/src/node/host-docks.ts b/packages/hub/src/node/host-docks.ts
index 4f1769a6..e70439e9 100644
--- a/packages/hub/src/node/host-docks.ts
+++ b/packages/hub/src/node/host-docks.ts
@@ -1,6 +1,7 @@
 import type { DevframeNodeContext } from 'devframe/types'
 import type { SharedState } from 'devframe/utils/shared-state'
 import type {
+  ClientScriptEntry,
   DevframeDockEntry,
   DevframeDocksHost as DevframeDocksHostType,
   DevframeDockUserEntry,
@@ -14,6 +15,7 @@ import { createStorage } from 'devframe/node'
 import { getInternalContext } from 'devframe/node/hub-internals'
 import { createEventEmitter } from 'devframe/utils/events'
 import { join } from 'pathe'
+import { isBareModuleSpecifier } from '../client-modules'
 import { DEFAULT_STATE_USER_SETTINGS } from '../constants'
 import { buildRemoteConnectionUrl } from '../remote-url'
 import { diagnostics } from './diagnostics'
@@ -89,6 +91,7 @@ export class DevframeDocksHost implements DevframeDocksHostType {
       throw diagnostics.DF8100({ id: view.id })
     }
     this.validateGroupMembership(view)
+    this.warnUnresolvableClientScript(view)
     this.prepareRemoteRegistration(view)
     this.views.set(view.id, view)
     this.events.emit('dock:entry:updated', view)
@@ -128,6 +131,25 @@ export class DevframeDocksHost implements DevframeDocksHostType {
     this.events.emit('dock:activate', { dockId, params })
   }
 
+  /**
+   * Warn (don't throw — a viewer-side `resolveClientModule` may still cover
+   * it) when a dock declares a **bare-specifier** client script on a host
+   * that advertises no client-module resolution: the browser cannot resolve
+   * a bare npm specifier natively, so the script is doomed to fail there.
+   * On a host that declares `staticConfig.dock.clientModuleResolution`
+   * (e.g. Vite's `'/@id/{specifier}'`), bare specifiers are first-class and
+   * this stays silent.
+   */
+  private warnUnresolvableClientScript(view: DevframeDockUserEntry): void {
+    if (this.context.staticConfig?.dock?.clientModuleResolution)
+      return
+    const script = (view as { clientScript?: ClientScriptEntry }).clientScript
+      ?? (view as { action?: ClientScriptEntry }).action
+      ?? (view as { renderer?: ClientScriptEntry }).renderer
+    if (script?.importFrom && isBareModuleSpecifier(script.importFrom))
+      diagnostics.DF8111({ id: view.id, specifier: script.importFrom })
+  }
+
   private validateGroupMembership(view: DevframeDockUserEntry): void {
     if (view.groupId === undefined)
       return
diff --git a/packages/hub/src/node/initiate.ts b/packages/hub/src/node/initiate.ts
index 9c175d43..c5de574a 100644
--- a/packages/hub/src/node/initiate.ts
+++ b/packages/hub/src/node/initiate.ts
@@ -17,6 +17,7 @@ import { mountStaticHandler } from 'devframe/utils/serve-static'
 import { H3 } from 'h3'
 import { resolve } from 'pathe'
 import { joinURL, withoutLeadingSlash, withTrailingSlash } from 'ufo'
+import { applyClientModuleResolutionTemplate, isBareModuleSpecifier } from '../client-modules'
 import { DEVFRAMES_HUB_BASE, DOCK_RENDERERS_STATE_KEY, normalizeHubBase } from '../constants'
 import { createHubContext } from './context'
 import { diagnostics } from './diagnostics'
@@ -263,6 +264,22 @@ export interface InitHubOptions {
    * (`id`, `name`, `basePath`, …).
    */
   register?: boolean | Partial<DevframeInstanceRecord>
+  /**
+   * Advertise that this host runtime resolves **bare-specifier** client
+   * scripts (`ClientScriptEntry.importFrom` naming an npm module) — a URL
+   * template whose `{specifier}` token is replaced with the specifier,
+   * published as `ConnectionMeta.configs.dock.clientModuleResolution` and
+   * applied by every client-script loader (`createDevframeClientHost`, the
+   * hub-ui viewers, `__client-imports.js`).
+   *
+   * Declare it only when the host can actually serve npm modules to the
+   * browser — a Vite host passes `'/@id/{specifier}'` (requests route through
+   * Vite's own resolution and import-analysis, sharing the app's module
+   * graph; `@devframes/vite/hub` declares this by default). Left undeclared,
+   * bare specifiers are unsupported on this host and registering one warns
+   * `DF8111` — ship a self-contained bundle and pass its URL instead.
+   */
+  clientModuleResolution?: string
   /** Working directory for the hub context. Default: `process.cwd()`. */
   cwd?: string
   /** Override where persisted devframe state lives. */
@@ -360,9 +377,15 @@ function resolveRendererRegistrations(
  * import thunk per dock that carries a client script (`clientScript` on
  * iframe docks, `action`, `renderer`). External viewers import this module
  * from `<base>__client-imports.js` to load per-dock client code into the
- * host page; `importFrom` values must be URL paths the host serves.
+ * host page; `importFrom` values are URL paths the host serves, or bare npm
+ * specifiers resolved through the host's `clientModuleResolution` template.
  */
 function renderClientImportsModule(ctx: DevframeHubContext): string {
+  const template = ctx.staticConfig.dock?.clientModuleResolution
+  const specifierOf = (script: ClientScriptEntry): string =>
+    template && isBareModuleSpecifier(script.importFrom)
+      ? applyClientModuleResolutionTemplate(template, script.importFrom)
+      : script.importFrom
   const entries: string[] = []
   for (const [id, view] of ctx.docks.views) {
     const scripts: ClientScriptEntry[] = []
@@ -375,7 +398,7 @@ function renderClientImportsModule(ctx: DevframeHubContext): string {
       scripts.push(anyView.renderer)
     if (scripts.length === 0)
       continue
-    const thunks = scripts.map(script => `() => import(${JSON.stringify(script.importFrom)})`)
+    const thunks = scripts.map(script => `() => import(${JSON.stringify(specifierOf(script))})`)
     entries.push(`  ${JSON.stringify(id)}: [${thunks.join(', ')}],`)
   }
   return `// Generated by @devframes/hub — dock client-script import map.\nexport const clientImports = {\n${entries.join('\n')}\n}\nexport default clientImports\n`
@@ -470,6 +493,17 @@ export function initHub(options: InitHubOptions): HubInstance {
         })
       }
 
+      // Publish the host's bare-specifier resolution template before anything
+      // registers a dock, so the docks host's bare-specifier capability check
+      // (`DF8111`) already sees it — the shell serializes `ctx.staticConfig`
+      // into `ConnectionMeta.configs` after this `init` returns.
+      if (options.clientModuleResolution) {
+        ctx.staticConfig.dock = {
+          ...ctx.staticConfig.dock,
+          clientModuleResolution: options.clientModuleResolution,
+        }
+      }
+
       const devframes = await resolveDevframesInput(options.devframes ?? [])
       // Mount each devframe under `<base><id>/` — its SPA, its meta, and its
       // auto-registered iframe dock — after guarding the id against the
diff --git a/packages/hub/src/types/docks.ts b/packages/hub/src/types/docks.ts
index 65d4568f..6e7cc839 100644
--- a/packages/hub/src/types/docks.ts
+++ b/packages/hub/src/types/docks.ts
@@ -164,7 +164,16 @@ export interface DevframeDockEntryBase {
 
 export interface ClientScriptEntry {
   /**
-   * The filepath or module name to import from
+   * What to import — either a **URL the host serves** (a self-contained ES
+   * module, e.g. `/@fs/<abs path>` under Vite or a statically-mounted bundle
+   * path), or a **bare npm specifier** (e.g.
+   * `'vite-plugin-vue-tracer/client/vite-devtools'`).
+   *
+   * Bare specifiers are a host-runtime capability: they resolve through the
+   * host-advertised {@link DockConnectionConfig.clientModuleResolution}
+   * template (Vite hosts declare `'/@id/{specifier}'`, importing through the
+   * app's own module graph). On a host that declares no template, ship a
+   * self-contained bundle and pass its URL instead (see `DF8111`).
    */
   importFrom: string
   /**
@@ -175,6 +184,34 @@ export interface ClientScriptEntry {
   importName?: string
 }
 
+/**
+ * Static dock-layer config a hub host publishes through the connection
+ * handshake (`ConnectionMeta.configs.dock`), declared node-side via
+ * `ctx.staticConfig.dock` (or `initHub({ clientModuleResolution })`).
+ */
+export interface DockConnectionConfig {
+  /**
+   * URL template that resolves a **bare-specifier** client script
+   * (`ClientScriptEntry.importFrom`) to an importable URL on this host — the
+   * `{specifier}` token is replaced with the bare specifier (a token-less
+   * template is used as a prefix). Declaring it advertises that this host
+   * runtime can serve npm modules to the browser:
+   *
+   * - Vite hosts declare `'/@id/{specifier}'` — the request routes through
+   *   Vite's own resolution and import-analysis, so the script's transitive
+   *   bare imports work too and share the app's module graph.
+   * - Hosts without such a runtime (e.g. Next.js) leave it undeclared; client
+   *   scripts there ship as self-contained bundles served by URL.
+   */
+  clientModuleResolution?: string
+}
+
+declare module 'devframe/types' {
+  interface DevframeConnectionConfigsRegistry {
+    dock: DockConnectionConfig
+  }
+}
+
 export interface DevframeViewIframe extends DevframeDockEntryBase {
   type: 'iframe'
   url: string
diff --git a/packages/vite/src/hub.ts b/packages/vite/src/hub.ts
index 3001c51d..cea39290 100644
--- a/packages/vite/src/hub.ts
+++ b/packages/vite/src/hub.ts
@@ -32,6 +32,19 @@ export interface ViteDevframeHubOptions {
    * (e.g. the a11y inspector's in-page agent).
    */
   clientScripts?: Record<string, ClientScriptEntry>
+  /**
+   * How this host resolves **bare-specifier** client scripts (an `importFrom`
+   * naming an npm module, e.g. `'vite-plugin-vue-tracer/client/vite-devtools'`),
+   * advertised as `ConnectionMeta.configs.dock.clientModuleResolution`.
+   * Defaults to Vite's `'/@id/{specifier}'` — requests route through Vite's
+   * own resolution and import-analysis, so the script's transitive bare
+   * imports work too and share the app's module graph. Pass `false` to
+   * advertise no resolution (bare-specifier client scripts then warn
+   * `DF8111`).
+   *
+   * @default '/@id/{specifier}'
+   */
+  clientModuleResolution?: string | false
   /**
    * Prebuilt dock-renderer modules forwarded to `initHub({ renderers })` —
    * each served at `<base>__renderers/<type>.mjs` and published in the
@@ -86,6 +99,14 @@ export interface ViteDevframeHubOptions {
   quiet?: boolean
 }
 
+/**
+ * The Vite host's bare-specifier resolution template — `/@id/<specifier>`
+ * asks the Vite dev server to resolve and transform the module through its
+ * own graph. Exported for hosts (e.g. Vite DevTools) that boot their own
+ * client host or hub and want to declare the same capability.
+ */
+export const VITE_CLIENT_MODULE_RESOLUTION = '/@id/{specifier}'
+
 let recommendedViteDevtools = false
 
 function recommendViteDevtools(): void {
@@ -160,9 +181,18 @@ export function viteDevframeHub(options: ViteDevframeHubOptions = {}): Plugin {
 
       const httpServer = server.httpServer instanceof NodeHttpServer ? server.httpServer : undefined
 
+      // Bare-specifier client scripts resolve through Vite's own module graph:
+      // `/@id/<specifier>` routes the request through Vite's resolution and
+      // import-analysis, so the script's transitive bare imports work too and
+      // share module instances with the app's own code.
+      const clientModuleResolution = options.clientModuleResolution === false
+        ? undefined
+        : options.clientModuleResolution ?? VITE_CLIENT_MODULE_RESOLUTION
+
       const hub = initHub({
         base,
         cwd,
+        ...(clientModuleResolution ? { clientModuleResolution } : {}),
         origin: options.origin ?? (() => {
           const resolved = server.resolvedUrls?.local?.[0]
           return resolved ? new URL(resolved).origin : ''
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f4b7ea68..71f35f0e 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -225,6 +225,9 @@ catalogs:
     iframe-pane:
       specifier: ^1.1.0
       version: 1.1.0
+    nanoevents:
+      specifier: ^10.0.0
+      version: 10.0.0
     next:
       specifier: ^16.3.0
       version: 16.3.0
@@ -513,6 +516,22 @@ importers:
         specifier: catalog:build
         version: 8.2.1(@types/node@26.2.0)(esbuild@0.28.0)(jiti@2.7.0)(terser@5.47.1)(tsx@4.23.12)(yaml@2.9.0)
 
+  examples/demo-dock-client:
+    dependencies:
+      nanoevents:
+        specifier: catalog:frontend
+        version: 10.0.0
+    devDependencies:
+      '@devframes/hub':
+        specifier: workspace:*
+        version: link:../../packages/hub
+      '@types/node':
+        specifier: catalog:types
+        version: 26.2.0
+      tsdown:
+        specifier: catalog:build
+        version: 0.22.14(@volar/typescript@2.4.28(typescript@6.0.3))(oxc-resolver@11.24.2)(tsx@4.23.12)(typescript@6.0.3)
+
   examples/files-inspector:
     dependencies:
       '@antfu/design':
@@ -658,6 +677,9 @@ importers:
       colorjs.io:
         specifier: catalog:frontend
         version: 0.7.1
+      demo-dock-client:
+        specifier: workspace:*
+        version: link:../demo-dock-client
       devframe:
         specifier: workspace:*
         version: link:../../packages/devframe
@@ -914,6 +936,9 @@ importers:
       colorjs.io:
         specifier: catalog:frontend
         version: 0.7.1
+      demo-dock-client:
+        specifier: workspace:*
+        version: link:../demo-dock-client
       devframe:
         specifier: workspace:*
         version: link:../../packages/devframe
@@ -8327,6 +8352,10 @@ packages:
     engines: {node: ^22 || >= 24}
     hasBin: true
 
+  nanoevents@10.0.0:
+    resolution: {integrity: sha512-PmIJ3BNxOzgVgnS1r/Pvyj6eZx/xUV2JCPogh0brD6smDIwjRlr1KBl9yoRX323PlfaNrBDDnfCgC9SL00OjSg==}
+    engines: {node: ^22.0.0 || ^24.0.0 || >=26.0.0}
+
   nanoid@3.3.16:
     resolution: {integrity: sha512-bzlKTyNJ7+LdGIIwy8ijFpIqEQIvafahV7eYykJ8Cvh42EdJeODoJ6gUJXpQJvej1BddH8OqTXZNE/KfbWAu8Q==}
     engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
@@ -10123,10 +10152,6 @@ packages:
     resolution: {integrity: sha512-6M8R2xSKplkQ+0mAm07IMh548GLLPUnRQZJCCe/W4rfk/SXW2bs8ZJSWa5kjdIdsx3hLG5oLWROJ4+N5hpX08g==}
     engines: {node: '>=18.12.0'}
 
-  verkit@0.3.0:
-    resolution: {integrity: sha512-Njrh4U8UODGajoZ44QS2C/BsoEM9DTI/aCqY5swsizb+/ap0FamvnCMcZAxrR5+aoC0ZqkawEfpC/N2SBc+xeA==}
-    engines: {node: '>=18.12.0'}
-
   verkit@0.3.2:
     resolution: {integrity: sha512-zj/ob3UsvJGN0whEAKFp53REA5X66hvffVqoCtVQAakJKnKlH+/PcOfMoFwIG/o4rElqLv/ycAFlx8ZlXUorCg==}
     engines: {node: '>=18.12.0'}
@@ -16986,6 +17011,8 @@ snapshots:
 
   nano-staged@1.0.2: {}
 
+  nanoevents@10.0.0: {}
+
   nanoid@3.3.16: {}
 
   nanoid@3.3.18: {}
@@ -18165,12 +18192,12 @@ snapshots:
 
   robust-predicates@3.0.3: {}
 
-  rolldown-plugin-dts@0.27.13(@volar/typescript@2.4.28(typescript@5.9.3))(oxc-resolver@11.24.2)(rolldown@1.2.0)(typescript@5.9.3):
+  rolldown-plugin-dts@0.27.13(@volar/typescript@2.4.28(typescript@5.9.3))(oxc-resolver@11.24.2)(rolldown@1.2.3)(typescript@5.9.3):
     dependencies:
       dts-resolver: 3.0.0(oxc-resolver@11.24.2)
       get-tsconfig: 5.0.0-beta.5
       obug: 2.1.4
-      rolldown: 1.2.0
+      rolldown: 1.2.3
       yuku-ast: 0.7.4
       yuku-codegen: 0.7.4
       yuku-parser: 0.7.4
@@ -18180,12 +18207,12 @@ snapshots:
     transitivePeerDependencies:
       - oxc-resolver
 
-  rolldown-plugin-dts@0.27.13(@volar/typescript@2.4.28(typescript@6.0.3))(oxc-resolver@11.24.2)(rolldown@1.2.0)(typescript@6.0.3):
+  rolldown-plugin-dts@0.27.13(@volar/typescript@2.4.28(typescript@6.0.3))(oxc-resolver@11.24.2)(rolldown@1.2.3)(typescript@6.0.3):
     dependencies:
       dts-resolver: 3.0.0(oxc-resolver@11.24.2)
       get-tsconfig: 5.0.0-beta.5
       obug: 2.1.4
-      rolldown: 1.2.0
+      rolldown: 1.2.3
       yuku-ast: 0.7.4
       yuku-codegen: 0.7.4
       yuku-parser: 0.7.4
@@ -18878,13 +18905,13 @@ snapshots:
       import-without-cache: 0.4.0
       obug: 2.1.4
       picomatch: 4.0.5
-      rolldown: 1.2.0
-      rolldown-plugin-dts: 0.27.13(@volar/typescript@2.4.28(typescript@5.9.3))(oxc-resolver@11.24.2)(rolldown@1.2.0)(typescript@5.9.3)
-      tinyexec: 1.2.4
+      rolldown: 1.2.3
+      rolldown-plugin-dts: 0.27.13(@volar/typescript@2.4.28(typescript@5.9.3))(oxc-resolver@11.24.2)(rolldown@1.2.3)(typescript@5.9.3)
+      tinyexec: 1.3.0
       tinyglobby: 0.2.17
       tree-kill: 1.2.2
       unconfig-core: 7.5.0
-      verkit: 0.3.0
+      verkit: 0.3.2
     optionalDependencies:
       tsx: 4.23.12
       typescript: 5.9.3
@@ -18904,13 +18931,13 @@ snapshots:
       import-without-cache: 0.4.0
       obug: 2.1.4
       picomatch: 4.0.5
-      rolldown: 1.2.0
-      rolldown-plugin-dts: 0.27.13(@volar/typescript@2.4.28(typescript@6.0.3))(oxc-resolver@11.24.2)(rolldown@1.2.0)(typescript@6.0.3)
-      tinyexec: 1.2.4
+      rolldown: 1.2.3
+      rolldown-plugin-dts: 0.27.13(@volar/typescript@2.4.28(typescript@6.0.3))(oxc-resolver@11.24.2)(rolldown@1.2.3)(typescript@6.0.3)
+      tinyexec: 1.3.0
       tinyglobby: 0.2.17
       tree-kill: 1.2.2
       unconfig-core: 7.5.0
-      verkit: 0.3.0
+      verkit: 0.3.2
     optionalDependencies:
       tsx: 4.23.12
       typescript: 6.0.3
@@ -19264,8 +19291,6 @@ snapshots:
 
   verkit@0.2.0: {}
 
-  verkit@0.3.0: {}
-
   verkit@0.3.2: {}
 
   vfile-message@4.0.3:
@@ -19383,7 +19408,7 @@ snapshots:
       lightningcss: 1.33.0
       picomatch: 4.0.5
       postcss: 8.5.23
-      rolldown: 1.2.0
+      rolldown: 1.2.3
       tinyglobby: 0.2.17
     optionalDependencies:
       '@types/node': 26.2.0
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index f9d14f0a..c928edd5 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -137,6 +137,7 @@ catalogs:
     floating-vue: ^5.2.2
     fuse.js: ^7.5.0
     iframe-pane: ^1.1.0
+    nanoevents: ^10.0.0
     next: ^16.3.0
     preact: ^10.29.8
     react: ^19.2.8
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
index 14916974..22b6168c 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
@@ -26,6 +26,7 @@ export interface DevframeClientHostOptions {
   connect?: DevframeRpcClientOptions;
   clientType?: DockClientType;
   loadClientScripts?: boolean;
+  resolveClientModule?: (_: string) => string | undefined;
   renderers?: Record<string, DockRenderer<any>>;
   categoryOrder?: Record<string, number>;
 }
@@ -178,6 +179,11 @@ export interface FrameTab {
 export interface MessagesClientOptions {
   defaults?: Partial<DevframeMessageEntryInput>;
 }
+export interface ResolveClientModuleSpecifierOptions {
+  resolveClientModule?: (_: string) => string | undefined;
+  connectionMeta?: ConnectionMeta;
+  metaBaseUrl?: string;
+}
 export interface WatchFrameLocationOptions {
   iframe: FrameLocationTarget;
   onChange: (_: string) => void;
@@ -231,6 +237,7 @@ export type FrameNavHostPayload = {
 // #endregion
 
 // #region Functions
+export declare function applyClientModuleResolutionTemplate(_: string, _: string): string;
 export declare function attachFrameNavClient(_: FrameNavClientOptions): FrameNavClient;
 export declare function buildRemoteDevframeUrl(_: string, _: DevframeConnection): string;
 export declare function connectRemoteDevframe(_?: ConnectRemoteDevframeOptions): Promise<DevframeRpcClient>;
@@ -238,7 +245,9 @@ export declare function createDevframeClientHost(_?: DevframeClientHostOptions):
 export declare function createDockRenderersContext(_: CreateDockRenderersContextOptions): DockRenderersContext;
 export declare function createMessagesClient(_: DevframeRpcClient, _?: MessagesClientOptions): DevframeMessagesClient;
 export declare function getDevframeClientContext(): DevframeClientContext | undefined;
+export declare function isBareModuleSpecifier(_: string): boolean;
 export declare function parseRemoteConnection(_?: string): RemoteConnectionInfo | null;
+export declare function resolveClientModuleSpecifier(_: string, _?: ResolveClientModuleSpecifierOptions): string;
 export declare function resolveDockIcon(_: DevframeDockEntryIcon, _: DevframeConnection): DevframeDockEntryIcon;
 export declare function resolveDockUrl(_: string, _: DevframeConnection): string;
 export declare function setDevframeClientContext(_: DevframeClientContext | undefined): void;
@@ -248,6 +257,7 @@ export declare function watchFrameLocation(_: WatchFrameLocationOptions): () =>
 
 // #region Variables
 export declare const CLIENT_CONTEXT_KEY: string;
+export declare const CLIENT_MODULE_SPECIFIER_TOKEN: string;
 export declare const FRAME_NAV_CHANNEL: string;
 export declare const FRAME_NAV_VERSION: number;
 // #endregion
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js
index 6115ae75..6c216108 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js
@@ -27,5 +27,9 @@ export * from "devframe/client";
 // #endregion
 
 // #region Other
+export { applyClientModuleResolutionTemplate }
+export { CLIENT_MODULE_SPECIFIER_TOKEN }
+export { isBareModuleSpecifier }
+export { resolveClientModuleSpecifier }
 export { stripRemoteConnectionFromUrl }
 // #endregion
\ No newline at end of file
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts
index 9aff9c44..44b248f6 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts
@@ -315,6 +315,9 @@ export interface DevframeViewLauncher extends DevframeDockEntryBase {
     onLaunch?: () => Promise<void>;
   };
 }
+export interface DockConnectionConfig {
+  clientModuleResolution?: string;
+}
 export interface FrameSubTabsConfig {
   protocol: 'postmessage';
   handshakeTimeoutMs?: number;
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/initiate.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/initiate.snapshot.d.ts
index 59fd23f5..6ca00cd0 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/initiate.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/initiate.snapshot.d.ts
@@ -50,6 +50,7 @@ export interface InitHubOptions {
   mcp?: boolean | McpRouteOptions;
   origin?: string | (() => string);
   register?: boolean | Partial<DevframeInstanceRecord>;
+  clientModuleResolution?: string;
   cwd?: string;
   getStorageDir?: (_: DevframeStorageScope) => string;
   allowedOrigins?: readonly string[] | WsOriginRegistry | false;
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.d.ts
index 33011b13..68ad102b 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.d.ts
@@ -33,6 +33,7 @@ export declare class DevframeDocksHost implements DevframeDocksHost$1 {
   };
   update(_: DevframeDockUserEntry): void;
   activate(_: string, _?: Record<string, unknown>): void;
+  private warnUnresolvableClientScript;
   private validateGroupMembership;
   private prepareRemoteRegistration;
 }
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts
index 2eb67965..10c49d92 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts
@@ -70,6 +70,7 @@ export { DevframeViewHost }
 export { DevframeViewIframe }
 export { DevframeViewLauncher }
 export { DevframeViewLauncherStatus }
+export { DockConnectionConfig }
 export { EventEmitter }
 export { EventsMap }
 export { EventUnsubscribe }
diff --git a/tests/__snapshots__/tsnapi/@devframes/vite/hub.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/vite/hub.snapshot.d.ts
index ae5f1822..eca65871 100644
--- a/tests/__snapshots__/tsnapi/@devframes/vite/hub.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/vite/hub.snapshot.d.ts
@@ -8,6 +8,7 @@ export interface ViteDevframeHubOptions {
   host?: string;
   devframes?: InitHubOptions['devframes'];
   clientScripts?: Record<string, ClientScriptEntry>;
+  clientModuleResolution?: string | false;
   renderers?: readonly DockRendererRegistration[];
   rpcDeclarations?: InitHubOptions['rpcDeclarations'];
   configure?: (_: DevframeHubContext) => void | Promise<void>;
@@ -26,4 +27,8 @@ export interface ViteDevframeHubOptions {
 
 // #region Functions
 export declare function viteDevframeHub(_?: ViteDevframeHubOptions): Plugin;
+// #endregion
+
+// #region Variables
+export declare const VITE_CLIENT_MODULE_RESOLUTION: string;
 // #endregion
\ No newline at end of file
diff --git a/tests/__snapshots__/tsnapi/@devframes/vite/hub.snapshot.js b/tests/__snapshots__/tsnapi/@devframes/vite/hub.snapshot.js
index ea0e76aa..536a709c 100644
--- a/tests/__snapshots__/tsnapi/@devframes/vite/hub.snapshot.js
+++ b/tests/__snapshots__/tsnapi/@devframes/vite/hub.snapshot.js
@@ -3,4 +3,8 @@
  */
 // #region Functions
 export function viteDevframeHub(_) {}
+// #endregion
+
+// #region Variables
+export var VITE_CLIENT_MODULE_RESOLUTION /* const */
 // #endregion
\ No newline at end of file

From 865fb37a9fbd035c77e604e66cb5b0c5c3de4dd3 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Tue, 18 Aug 2026 04:24:53 +0000
Subject: [PATCH 2/3] fix(examples): serve the demo dock client from source;
 diagnose resolved-but-unservable client scripts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The hub-vite demo failed with 'Failed to fetch dynamically imported
module' whenever demo-dock-client's dist was absent (running vite
without the repo build): Vite couldn't resolve the /@id/ request's
exports target and the SPA index.html fallback answered 200 with HTML.
The package's '.' export now points at src/index.ts — a Vite host
transforms the linked source directly, so the bare-specifier path needs
no build at all; tsdown keeps building only the URL-shape artifacts
(dist/bundle.mjs + dist/node.mjs for the Next host).

Both browser loaders also gain a second diagnosis branch via the shared
clientScriptFailureHint(): when a bare specifier WAS resolved through
the host template and the import still failed, the error now points at
the module being unservable on the host (package not installed/built)
instead of leaving only the browser's opaque TypeError.
---
 examples/demo-dock-client/README.md           | 10 +++----
 examples/demo-dock-client/package.json        |  2 +-
 examples/demo-dock-client/tsdown.config.ts    | 26 +++++++------------
 .../hub-ui/src/client/state/setup-script.ts   | 14 ++++------
 packages/hub/src/client-modules.test.ts       | 19 ++++++++++++++
 packages/hub/src/client-modules.ts            | 25 ++++++++++++++++++
 packages/hub/src/client/host.ts               | 15 ++++-------
 .../@devframes/hub/client.snapshot.d.ts       |  1 +
 .../tsnapi/@devframes/hub/client.snapshot.js  |  1 +
 9 files changed, 71 insertions(+), 42 deletions(-)

diff --git a/examples/demo-dock-client/README.md b/examples/demo-dock-client/README.md
index 8f41e5b8..e41fae58 100644
--- a/examples/demo-dock-client/README.md
+++ b/examples/demo-dock-client/README.md
@@ -2,15 +2,15 @@
 
 The shared dock client script the two reference hubs consume in their two supported shapes — one package, both `importFrom` forms:
 
-- **`hub-vite`** registers it by **bare specifier** (`action: { importFrom: 'demo-dock-client' }`). The Vite host advertises `clientModuleResolution: '/@id/{specifier}'` (the `@devframes/vite/hub` default), so the client host imports `dist/index.mjs` through Vite's own module graph — its bare `nanoevents` import resolves there too.
+- **`hub-vite`** registers it by **bare specifier** (`action: { importFrom: 'demo-dock-client' }`). The Vite host advertises `clientModuleResolution: '/@id/{specifier}'` (the `@devframes/vite/hub` default), so the client host imports `src/index.ts` through Vite's own module graph — Vite transforms the linked source directly (no build needed on this path) and resolves its bare `nanoevents` import there too.
 - **`hub-next`** mounts the prebuilt **self-contained bundle** (`dist/bundle.mjs`, nanoevents inlined) statically and passes the served URL. Next declares no `clientModuleResolution`, so the URL shape is the supported one there.
 
 The script itself demonstrates the state pattern bare-specifier plugins should follow: shared state anchored on `globalThis` (`__devframes_demo_dock_client__`), the same design as `vite-plugin-vue-tracer`'s `__vue_tracer__` store — realm identity is the contract, module identity is best-effort. On each dock activation it bumps the shared counter and reports into the hub's messages feed, naming the URL it was loaded from.
 
 ## Entries
 
-| Entry | Built as | Role |
+| Entry | Resolves to | Role |
 |---|---|---|
-| `demo-dock-client` | `dist/index.mjs` (deps external) | Bare-specifier consumption through a host's module graph |
-| — | `dist/bundle.mjs` (self-contained) | URL consumption on hosts without bare-specifier resolution |
-| `demo-dock-client/node` | `dist/node.mjs` | Node helper exporting `demoDockClientBundlePath` for static mounting |
+| `demo-dock-client` | `src/index.ts` (source, deps bare) | Bare-specifier consumption through a host's module graph |
+| — | `dist/bundle.mjs` (self-contained build) | URL consumption on hosts without bare-specifier resolution |
+| `demo-dock-client/node` | `dist/node.mjs` (build) | Node helper exporting `demoDockClientBundlePath` for static mounting |
diff --git a/examples/demo-dock-client/package.json b/examples/demo-dock-client/package.json
index 0953066b..e03a0c4c 100644
--- a/examples/demo-dock-client/package.json
+++ b/examples/demo-dock-client/package.json
@@ -6,7 +6,7 @@
   "description": "Reference dock client script for the hub examples: bare npm imports and globalThis-anchored shared state.",
   "homepage": "https://github.com/devframes/devframe/tree/main/examples/demo-dock-client",
   "exports": {
-    ".": "./dist/index.mjs",
+    ".": "./src/index.ts",
     "./node": "./dist/node.mjs",
     "./package.json": "./package.json"
   },
diff --git a/examples/demo-dock-client/tsdown.config.ts b/examples/demo-dock-client/tsdown.config.ts
index e2d82604..032c9edc 100644
--- a/examples/demo-dock-client/tsdown.config.ts
+++ b/examples/demo-dock-client/tsdown.config.ts
@@ -2,16 +2,16 @@ import { defineConfig } from 'tsdown'
 
 const tsconfig = '../../tsconfig.base.json'
 
-// Two builds of the same client script, one per consumption mode the hub
-// examples demonstrate:
-//   1. `dist/index.mjs` — dependencies stay external (`import 'nanoevents'`
-//      survives as a bare import), for hosts that resolve bare specifiers
-//      through their own module graph (hub-vite imports
-//      `'demo-dock-client'` via the Vite `/@id/{specifier}` template);
-//   2. `dist/bundle.mjs` — self-contained (nanoevents inlined), for hosts
+// The bare-specifier consumption path needs no build at all: the package's
+// `.` export points straight at `src/index.ts`, which a Vite host transforms
+// like any linked workspace source (hub-vite imports `'demo-dock-client'`
+// via the `/@id/{specifier}` template). What gets built here is only the
+// **URL-shape** consumption path:
+//   1. `dist/bundle.mjs` — self-contained (nanoevents inlined), for hosts
 //      without bare-specifier resolution (hub-next mounts it statically and
-//      passes the served URL as `importFrom`).
-// Plus the node-side path helper the Next host uses to locate the bundle.
+//      passes the served URL as `importFrom`);
+//   2. `dist/node.mjs` — the node-side path helper the Next host uses to
+//      locate the bundle.
 export default defineConfig([
   {
     clean: true,
@@ -19,14 +19,6 @@ export default defineConfig([
     tsconfig,
     dts: false,
     outExtensions: () => ({ js: '.mjs' }),
-    entry: { index: 'src/index.ts' },
-  },
-  {
-    clean: false,
-    platform: 'browser',
-    tsconfig,
-    dts: false,
-    outExtensions: () => ({ js: '.mjs' }),
     entry: { bundle: 'src/index.ts' },
     deps: { alwaysBundle: ['nanoevents'] },
   },
diff --git a/packages/hub-ui/src/client/state/setup-script.ts b/packages/hub-ui/src/client/state/setup-script.ts
index f94b173f..9d804013 100644
--- a/packages/hub-ui/src/client/state/setup-script.ts
+++ b/packages/hub-ui/src/client/state/setup-script.ts
@@ -1,6 +1,6 @@
 import type { ClientScriptEntry, DevframeDockUserEntry } from '@devframes/hub'
 import type { DockClientScriptContext } from '@devframes/hub/client'
-import { isBareModuleSpecifier, resolveClientModuleSpecifier } from '@devframes/hub/client'
+import { clientScriptFailureHint, resolveClientModuleSpecifier } from '@devframes/hub/client'
 
 /**
  * Resolve the {@link ClientScriptEntry} a dock entry carries — an `action`'s
@@ -48,14 +48,10 @@ async function _executeSetupScript(
   catch (error) {
     // TODO: maybe popup a error toast here?
     // TODO: A unified logger API
-    // An unresolved bare specifier is a host-capability gap, not a plugin
-    // bug — say so instead of surfacing the browser's opaque TypeError.
-    const hint = specifier === script.importFrom && isBareModuleSpecifier(script.importFrom)
-      ? ` — "${specifier}" is a bare npm specifier and this host advertises no client-module resolution `
-      + '(`ConnectionMeta.configs.dock.clientModuleResolution`). Serve the script as a self-contained '
-      + 'bundle by URL, or run under a host that resolves bare specifiers (e.g. Vite: `/@id/{specifier}`).'
-      : ''
-    console.error(`[@devframes/hub-ui] Error executing client script${hint}`, error)
+    console.error(
+      `[@devframes/hub-ui] Error executing client script from ${specifier}${clientScriptFailureHint(script.importFrom, specifier)}`,
+      error,
+    )
     throw error
   }
 }
diff --git a/packages/hub/src/client-modules.test.ts b/packages/hub/src/client-modules.test.ts
index 4b191b14..f8940c7e 100644
--- a/packages/hub/src/client-modules.test.ts
+++ b/packages/hub/src/client-modules.test.ts
@@ -2,6 +2,7 @@ import type { ConnectionMeta } from 'devframe/types'
 import { describe, expect, it } from 'vitest'
 import {
   applyClientModuleResolutionTemplate,
+  clientScriptFailureHint,
   isBareModuleSpecifier,
   resolveClientModuleSpecifier,
 } from './client-modules'
@@ -100,3 +101,21 @@ describe('resolveClientModuleSpecifier', () => {
     expect(called).toBe(false)
   })
 })
+
+describe('clientScriptFailureHint', () => {
+  it('is silent for URL specifiers', () => {
+    expect(clientScriptFailureHint('/@fs/abs/inject.js', '/@fs/abs/inject.js')).toBe('')
+  })
+
+  it('names the capability gap for an unresolved bare specifier', () => {
+    const hint = clientScriptFailureHint('foo/bar', 'foo/bar')
+    expect(hint).toContain('clientModuleResolution')
+    expect(hint).toContain('bare npm specifier')
+  })
+
+  it('names the serving gap for a resolved-but-failed bare specifier', () => {
+    const hint = clientScriptFailureHint('foo/bar', 'http://localhost:5173/@id/foo/bar')
+    expect(hint).toContain('"foo/bar"')
+    expect(hint).toContain('could not serve the module')
+  })
+})
diff --git a/packages/hub/src/client-modules.ts b/packages/hub/src/client-modules.ts
index eb37bdc5..9b9e640a 100644
--- a/packages/hub/src/client-modules.ts
+++ b/packages/hub/src/client-modules.ts
@@ -91,3 +91,28 @@ export function resolveClientModuleSpecifier(
     return applied
   }
 }
+
+/**
+ * Diagnose a failed client-script import: name the likely cause instead of
+ * leaving only the browser's opaque `TypeError`. `importFrom` is the entry's
+ * declared specifier, `specifier` what was actually imported (after
+ * {@link resolveClientModuleSpecifier}).
+ */
+export function clientScriptFailureHint(importFrom: string, specifier: string): string {
+  if (!isBareModuleSpecifier(importFrom))
+    return ''
+  // Bare and nothing resolved it — a host-capability gap, not a plugin bug.
+  if (specifier === importFrom) {
+    return ' — the specifier is a bare npm specifier and this host advertises no client-module resolution '
+      + '(`ConnectionMeta.configs.dock.clientModuleResolution`). Serve the script as a self-contained '
+      + 'bundle by URL, pass `resolveClientModule` to this client host, or run under a host that '
+      + 'resolves bare specifiers (e.g. Vite: `/@id/{specifier}`).'
+  }
+  // Bare and resolved to a host URL, yet the import still failed — the host
+  // couldn't actually serve the module. (A dev server typically answers an
+  // unresolvable module URL with its HTML fallback, which the browser reports
+  // as "Failed to fetch dynamically imported module".)
+  return ` — the host resolved the bare specifier "${importFrom}" to this URL but could not serve the module. `
+    + 'Check the package is installed and resolvable from the host project\'s root '
+    + '(and built, if its exports point at build output).'
+}
diff --git a/packages/hub/src/client/host.ts b/packages/hub/src/client/host.ts
index d91b22b9..51160de1 100644
--- a/packages/hub/src/client/host.ts
+++ b/packages/hub/src/client/host.ts
@@ -26,7 +26,7 @@ import type {
 import type { DockRenderer, DockRendererManifest, DockRenderersContext } from './renderers'
 import { connectDevframe } from 'devframe/client'
 import { createEventEmitter } from 'devframe/utils/events'
-import { isBareModuleSpecifier, resolveClientModuleSpecifier } from '../client-modules'
+import { clientScriptFailureHint, resolveClientModuleSpecifier } from '../client-modules'
 import { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS, DOCK_RENDERERS_STATE_KEY } from '../constants'
 import { getDevframeClientContext, setDevframeClientContext } from './context'
 import { attachFrameNavClient } from './frame-nav'
@@ -546,15 +546,10 @@ export async function createDevframeClientHost(
     }
     catch (error) {
       loadedScripts.delete(entryId)
-      // An unresolved bare specifier is a host-capability gap, not a plugin
-      // bug — say so instead of surfacing the browser's opaque TypeError.
-      const hint = specifier === script.importFrom && isBareModuleSpecifier(script.importFrom)
-        ? ' — the specifier is a bare npm specifier and this host advertises no client-module resolution '
-        + '(`ConnectionMeta.configs.dock.clientModuleResolution`). Serve the script as a self-contained '
-        + 'bundle by URL, pass `resolveClientModule` to this client host, or run under a host that '
-        + 'resolves bare specifiers (e.g. Vite: `/@id/{specifier}`).'
-        : ''
-      console.error(`[@devframes/hub] failed to load client script for "${entryId}" from ${specifier}${hint}`, error)
+      console.error(
+        `[@devframes/hub] failed to load client script for "${entryId}" from ${specifier}${clientScriptFailureHint(script.importFrom, specifier)}`,
+        error,
+      )
     }
   }
 }
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
index 22b6168c..a6311d40 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
@@ -240,6 +240,7 @@ export type FrameNavHostPayload = {
 export declare function applyClientModuleResolutionTemplate(_: string, _: string): string;
 export declare function attachFrameNavClient(_: FrameNavClientOptions): FrameNavClient;
 export declare function buildRemoteDevframeUrl(_: string, _: DevframeConnection): string;
+export declare function clientScriptFailureHint(_: string, _: string): string;
 export declare function connectRemoteDevframe(_?: ConnectRemoteDevframeOptions): Promise<DevframeRpcClient>;
 export declare function createDevframeClientHost(_?: DevframeClientHostOptions): Promise<DevframeClientHost>;
 export declare function createDockRenderersContext(_: CreateDockRenderersContextOptions): DockRenderersContext;
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js
index 6c216108..195a6f6b 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js
@@ -29,6 +29,7 @@ export * from "devframe/client";
 // #region Other
 export { applyClientModuleResolutionTemplate }
 export { CLIENT_MODULE_SPECIFIER_TOKEN }
+export { clientScriptFailureHint }
 export { isBareModuleSpecifier }
 export { resolveClientModuleSpecifier }
 export { stripRemoteConnectionFromUrl }

From 919cc0c5b2029058a7a55a30c16ad4106dd02a5d Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Tue, 18 Aug 2026 05:35:50 +0000
Subject: [PATCH 3/3] refactor(hub): shrink the client-modules surface to three
 functions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Public API narrows to what consumers actually touch: the initHub
clientModuleResolution option, the createDevframeClientHost
resolveClientModule override, and — on @devframes/hub/client, for
viewers and hub-ui — resolveClientModuleSpecifier +
clientScriptFailureHint. The template token constant, the standalone
template applier, the options interface, the DockConnectionConfig type
(now inlined in the configs augmentation), and @devframes/vite/hub's
clientModuleResolution option + exported constant all fold away; the
resolver takes the template directly, so the node-side imports-module
rendering reuses it instead of its own helper pair.
---
 examples/hub-next/src/client/app/page.tsx     |  22 +---
 .../src/client/devframe/next-devframe-hub.ts  |  12 +-
 examples/hub-vite/src/client/main.ts          |  12 +-
 examples/hub-vite/vite.config.ts              |  10 +-
 .../hub-ui/src/client/state/setup-script.ts   |  10 +-
 packages/hub/src/client-modules.test.ts       | 113 ++++++------------
 packages/hub/src/client-modules.ts            |  92 ++++----------
 packages/hub/src/client/host.ts               |  28 ++---
 packages/hub/src/client/index.ts              |   2 +-
 packages/hub/src/node/diagnostics.ts          |   2 +-
 packages/hub/src/node/host-docks.ts           |   8 +-
 packages/hub/src/node/initiate.ts             |  24 ++--
 packages/hub/src/types/docks.ts               |  48 +++-----
 packages/vite/src/hub.ts                      |  34 +-----
 .../@devframes/hub/client.snapshot.d.ts       |  14 +--
 .../tsnapi/@devframes/hub/client.snapshot.js  |   3 -
 .../tsnapi/@devframes/hub/index.snapshot.d.ts |   3 -
 .../tsnapi/@devframes/hub/types.snapshot.d.ts |   1 -
 .../tsnapi/@devframes/vite/hub.snapshot.d.ts  |   5 -
 .../tsnapi/@devframes/vite/hub.snapshot.js    |   4 -
 20 files changed, 133 insertions(+), 314 deletions(-)

diff --git a/examples/hub-next/src/client/app/page.tsx b/examples/hub-next/src/client/app/page.tsx
index 4f6c2b26..8a03947e 100644
--- a/examples/hub-next/src/client/app/page.tsx
+++ b/examples/hub-next/src/client/app/page.tsx
@@ -65,13 +65,6 @@ function isRenderableDock(d: DevframeDockEntry): boolean {
   return isIframeDock(d) || !NATIVE_TYPES.has(d.type)
 }
 
-// `action` docks carry no panel: they render in the rail as momentary buttons
-// whose click fires `entry:activated` for the dock's client script (loaded by
-// the client host at boot), leaving the panel selection untouched.
-function isActionDock(d: DevframeDockEntry): boolean {
-  return d.type === 'action'
-}
-
 // One iframe is kept alive per `frameId` (shared-frame docks) or per dock id
 // (plain iframe docks), so shared-frame member docks reuse the same element and
 // soft-navigate rather than reload.
@@ -505,8 +498,8 @@ export default function Page() {
   }, [])
 
   const renderableDocks = useMemo(() => docks.filter(isRenderableDock), [docks])
-  // The rail also lists momentary `action` docks alongside the selectable ones.
-  const railDocks = useMemo(() => docks.filter(d => isRenderableDock(d) || isActionDock(d)), [docks])
+  // The rail also lists panel-less `action` docks as momentary buttons.
+  const railDocks = useMemo(() => docks.filter(d => isRenderableDock(d) || d.type === 'action'), [docks])
 
   // Wire each dock's state once so a selection change - from a click, or from
   // the frame-nav adapter reacting to in-frame navigation - updates the UI.
@@ -662,15 +655,12 @@ export default function Page() {
                       type="button"
                       onClick={() => {
                         const ctx = hostRef.current?.context
-                        if (!ctx)
-                          return
                         // Momentary action dock: fire its client script, keep
                         // the panel selection as-is.
-                        if (isActionDock(dock)) {
-                          ctx.docks.getStateById(dock.id)?.events.emit('entry:activated')
-                          return
-                        }
-                        void ctx.docks.switchEntry(dock.id)
+                        if (dock.type === 'action')
+                          ctx?.docks.getStateById(dock.id)?.events.emit('entry:activated')
+                        else
+                          void ctx?.docks.switchEntry(dock.id)
                       }}
                       className={`relative inline-flex items-center gap-1.5 max-w-52 px-2 py-1 rounded-md border border-transparent text-sm op-fade select-none cursor-pointer transition hover:op100 hover:bg-active w-full! max-w-none! gap-2.5!${dock.id === selectedDockId ? ' op100! bg-active border-base! color-base' : ''}`}
                       title={dock.title}
diff --git a/examples/hub-next/src/client/devframe/next-devframe-hub.ts b/examples/hub-next/src/client/devframe/next-devframe-hub.ts
index 93754fd3..91bef12d 100644
--- a/examples/hub-next/src/client/devframe/next-devframe-hub.ts
+++ b/examples/hub-next/src/client/devframe/next-devframe-hub.ts
@@ -141,14 +141,12 @@ interface DemoDockClientMount {
 
 /**
  * Locate the shared demo dock-client script (examples/demo-dock-client) as a
- * prebuilt **self-contained bundle** - this host declares no
+ * prebuilt **self-contained bundle**: this host declares no
  * `clientModuleResolution` (Next's bundler exposes no browser-reachable
- * on-demand module URL), so bare-specifier client scripts are unsupported
- * here and the script ships by URL instead. The Vite reference host consumes
- * the same package as a bare specifier through its `/@id/{specifier}`
- * template - the capability difference between the two hosts. Loaded through
- * the same bundler-ignored dynamic `import()` as the plugins (the package
- * resolves its bundle via `import.meta.url`). Returns `null` if unbuilt.
+ * on-demand module URL), so client scripts ship by URL here — the Vite
+ * reference host consumes the same package as a bare specifier instead.
+ * Loaded through the same bundler-ignored dynamic `import()` as the plugins.
+ * Returns `null` if unbuilt.
  */
 async function loadDemoDockClientMount(): Promise<DemoDockClientMount | null> {
   try {
diff --git a/examples/hub-vite/src/client/main.ts b/examples/hub-vite/src/client/main.ts
index 4fc57279..f19b8fb2 100644
--- a/examples/hub-vite/src/client/main.ts
+++ b/examples/hub-vite/src/client/main.ts
@@ -130,13 +130,6 @@ function isRenderableDock(d: DevframeDockEntry): boolean {
   return isIframeDock(d) || !NATIVE_TYPES.has(d.type)
 }
 
-// `action` docks carry no panel: they render in the rail as momentary buttons
-// whose click fires `entry:activated` for the dock's client script (loaded by
-// the client host at boot), leaving the panel selection untouched.
-function isActionDock(d: DevframeDockEntry): boolean {
-  return d.type === 'action'
-}
-
 // ── client-only dock content (synthesized in the browser) ───────────────────
 
 // A self-contained document for the client-only "Client Notes" dock, from a
@@ -466,7 +459,8 @@ function wireDockRail(host: Awaited<ReturnType<typeof createDevframeClientHost>>
   // (a click, or the frame-nav adapter reacting to in-frame navigation).
   const wired = new Set<string>()
   function render(): void {
-    const list = docksCtx.entries.filter(d => isRenderableDock(d) || isActionDock(d))
+    // The rail also lists panel-less `action` docks as momentary buttons.
+    const list = docksCtx.entries.filter(d => isRenderableDock(d) || d.type === 'action')
     const selectable = list.filter(isRenderableDock)
     if (!docksCtx.selectedId && selectable.length > 0)
       void docksCtx.switchEntry(selectable[0].id)
@@ -490,7 +484,7 @@ function wireDockRail(host: Awaited<ReturnType<typeof createDevframeClientHost>>
       return
     // Momentary action dock: fire its client script, keep the panel as-is.
     const state = docksCtx.getStateById(id)
-    if (state && isActionDock(state.entryMeta)) {
+    if (state?.entryMeta.type === 'action') {
       state.events.emit('entry:activated')
       return
     }
diff --git a/examples/hub-vite/vite.config.ts b/examples/hub-vite/vite.config.ts
index 4fd577ec..524f3190 100644
--- a/examples/hub-vite/vite.config.ts
+++ b/examples/hub-vite/vite.config.ts
@@ -177,12 +177,10 @@ export default defineConfig({
           category: 'app',
         }))
         // Bare-specifier client script demo: `importFrom` names the npm
-        // package itself. The Vite host advertises its default
-        // `clientModuleResolution` (`'/@id/{specifier}'`), so the client host
-        // imports the script through Vite's own module graph — its bare
-        // `nanoevents` import resolves there too. The Next reference host
-        // consumes the same package as a prebuilt self-contained bundle
-        // instead (see examples/demo-dock-client).
+        // package itself, imported through Vite's own module graph via the
+        // host's `clientModuleResolution` (`'/@id/{specifier}'`). The Next
+        // reference host consumes the same package as a prebuilt
+        // self-contained bundle instead (see examples/demo-dock-client).
         context.docks.register({
           type: 'action',
           id: 'example:demo-client-script',
diff --git a/packages/hub-ui/src/client/state/setup-script.ts b/packages/hub-ui/src/client/state/setup-script.ts
index 9d804013..c55f428f 100644
--- a/packages/hub-ui/src/client/state/setup-script.ts
+++ b/packages/hub-ui/src/client/state/setup-script.ts
@@ -26,13 +26,11 @@ async function _executeSetupScript(
   const script = clientScriptOf(entry)
   if (!script?.importFrom)
     throw new Error(`[@devframes/hub-ui] Dock entry "${entry.id}" carries no client script to run`)
-  // A bare specifier resolves through the host-advertised template
-  // (`configs.dock.clientModuleResolution`); URL specifiers pass through
-  // untouched. Mirrors `@devframes/hub`'s `createDevframeClientHost`.
+  // A bare specifier resolves through the host-advertised template; URL
+  // specifiers pass through untouched. Mirrors `@devframes/hub`'s
+  // `createDevframeClientHost` (rpc reads optional-chained for partial stubs).
   const specifier = resolveClientModuleSpecifier(script.importFrom, {
-    connectionMeta: context.rpc.connectionMeta,
-    // Optional-chained: a partial rpc stub (stories, bespoke viewers) may
-    // carry no connection record — the template then resolves page-relative.
+    template: context.rpc.connectionMeta?.configs?.dock?.clientModuleResolution,
     metaBaseUrl: context.rpc.connection?.metaBaseUrl,
   })
   try {
diff --git a/packages/hub/src/client-modules.test.ts b/packages/hub/src/client-modules.test.ts
index f8940c7e..8476b51c 100644
--- a/packages/hub/src/client-modules.test.ts
+++ b/packages/hub/src/client-modules.test.ts
@@ -1,21 +1,10 @@
-import type { ConnectionMeta } from 'devframe/types'
 import { describe, expect, it } from 'vitest'
 import {
-  applyClientModuleResolutionTemplate,
   clientScriptFailureHint,
   isBareModuleSpecifier,
   resolveClientModuleSpecifier,
 } from './client-modules'
 
-function metaWith(clientModuleResolution?: string): ConnectionMeta {
-  return {
-    backend: 'websocket',
-    ...(clientModuleResolution
-      ? { configs: { dock: { clientModuleResolution } } }
-      : {}),
-  }
-}
-
 describe('isBareModuleSpecifier', () => {
   it('recognizes npm-style names, scoped packages, and subpaths', () => {
     expect(isBareModuleSpecifier('nanoevents')).toBe(true)
@@ -24,81 +13,54 @@ describe('isBareModuleSpecifier', () => {
   })
 
   it('rejects everything the browser resolves natively', () => {
-    expect(isBareModuleSpecifier('/@fs/abs/path.js')).toBe(false)
-    expect(isBareModuleSpecifier('/@id/pkg')).toBe(false)
-    expect(isBareModuleSpecifier('./relative.js')).toBe(false)
-    expect(isBareModuleSpecifier('../up.js')).toBe(false)
-    expect(isBareModuleSpecifier('//cdn.example.com/mod.js')).toBe(false)
-    expect(isBareModuleSpecifier('https://example.com/mod.js')).toBe(false)
-    expect(isBareModuleSpecifier('data:text/javascript,export default 1')).toBe(false)
-    expect(isBareModuleSpecifier('blob:http://localhost/x')).toBe(false)
-    expect(isBareModuleSpecifier('')).toBe(false)
-    expect(isBareModuleSpecifier('   ')).toBe(false)
-  })
-})
-
-describe('applyClientModuleResolutionTemplate', () => {
-  it('replaces the {specifier} token', () => {
-    expect(applyClientModuleResolutionTemplate('/@id/{specifier}', 'foo/bar')).toBe('/@id/foo/bar')
-  })
-
-  it('uses a token-less template as a prefix', () => {
-    expect(applyClientModuleResolutionTemplate('/modules/', 'foo')).toBe('/modules/foo')
+    for (const url of [
+      '/@fs/abs/path.js',
+      '/@id/pkg',
+      './relative.js',
+      '../up.js',
+      '//cdn.example.com/mod.js',
+      'https://example.com/mod.js',
+      'data:text/javascript,export default 1',
+      'blob:http://localhost/x',
+      '',
+      '   ',
+    ]) {
+      expect(isBareModuleSpecifier(url), url).toBe(false)
+    }
   })
 })
 
 describe('resolveClientModuleSpecifier', () => {
+  const metaBaseUrl = 'http://localhost:5173/__devframes/__connection.json'
+
   it('passes URL specifiers through untouched, template or not', () => {
-    expect(resolveClientModuleSpecifier('/@fs/abs/inject.js', {
-      connectionMeta: metaWith('/@id/{specifier}'),
-      metaBaseUrl: 'http://localhost:5173/__devframes/__connection.json',
-    })).toBe('/@fs/abs/inject.js')
-    expect(resolveClientModuleSpecifier('./mod.js', {})).toBe('./mod.js')
+    expect(resolveClientModuleSpecifier('/@fs/abs/inject.js', { template: '/@id/{specifier}', metaBaseUrl }))
+      .toBe('/@fs/abs/inject.js')
+    expect(resolveClientModuleSpecifier('./mod.js')).toBe('./mod.js')
   })
 
   it('leaves a bare specifier unchanged when nothing resolves it', () => {
-    expect(resolveClientModuleSpecifier('foo/bar', { connectionMeta: metaWith() })).toBe('foo/bar')
-    expect(resolveClientModuleSpecifier('foo/bar', {})).toBe('foo/bar')
+    expect(resolveClientModuleSpecifier('foo/bar')).toBe('foo/bar')
   })
 
   it('applies the host-advertised template, resolved against metaBaseUrl', () => {
-    expect(resolveClientModuleSpecifier('vite-plugin-vue-tracer/client/vite-devtools', {
-      connectionMeta: metaWith('/@id/{specifier}'),
-      metaBaseUrl: 'http://localhost:5173/__devframes/__connection.json',
-    })).toBe('http://localhost:5173/@id/vite-plugin-vue-tracer/client/vite-devtools')
-  })
-
-  it('returns the applied template as-is without a usable base', () => {
-    expect(resolveClientModuleSpecifier('foo', {
-      connectionMeta: metaWith('/@id/{specifier}'),
-    })).toBe('/@id/foo')
-  })
-
-  it('prefers the explicit resolveClientModule option over the template', () => {
-    expect(resolveClientModuleSpecifier('foo', {
-      resolveClientModule: s => `/custom/${s}`,
-      connectionMeta: metaWith('/@id/{specifier}'),
-      metaBaseUrl: 'http://localhost:5173/__devframes/__connection.json',
-    })).toBe('/custom/foo')
+    expect(resolveClientModuleSpecifier('vite-plugin-vue-tracer/client/vite-devtools', { template: '/@id/{specifier}', metaBaseUrl }))
+      .toBe('http://localhost:5173/@id/vite-plugin-vue-tracer/client/vite-devtools')
   })
 
-  it('falls through to the template when the option returns undefined', () => {
-    expect(resolveClientModuleSpecifier('foo', {
-      resolveClientModule: () => undefined,
-      connectionMeta: metaWith('/@id/{specifier}'),
-      metaBaseUrl: 'http://localhost:5173/__devframes/__connection.json',
-    })).toBe('http://localhost:5173/@id/foo')
+  it('uses a token-less template as a prefix, verbatim without a usable base', () => {
+    expect(resolveClientModuleSpecifier('foo', { template: '/modules/' })).toBe('/modules/foo')
   })
 
-  it('never calls the option for URL specifiers', () => {
-    let called = false
-    expect(resolveClientModuleSpecifier('/already/a/url.js', {
-      resolveClientModule: (s) => {
-        called = true
-        return `/custom/${s}`
-      },
-    })).toBe('/already/a/url.js')
-    expect(called).toBe(false)
+  it('prefers resolveClientModule over the template, falling through on undefined', () => {
+    const options = { template: '/@id/{specifier}', metaBaseUrl }
+    expect(resolveClientModuleSpecifier('foo', { ...options, resolveClientModule: s => `/custom/${s}` }))
+      .toBe('/custom/foo')
+    expect(resolveClientModuleSpecifier('foo', { ...options, resolveClientModule: () => undefined }))
+      .toBe('http://localhost:5173/@id/foo')
+    // URL specifiers never reach the callback.
+    expect(resolveClientModuleSpecifier('/a/url.js', { resolveClientModule: () => '/custom' }))
+      .toBe('/a/url.js')
   })
 })
 
@@ -108,14 +70,11 @@ describe('clientScriptFailureHint', () => {
   })
 
   it('names the capability gap for an unresolved bare specifier', () => {
-    const hint = clientScriptFailureHint('foo/bar', 'foo/bar')
-    expect(hint).toContain('clientModuleResolution')
-    expect(hint).toContain('bare npm specifier')
+    expect(clientScriptFailureHint('foo/bar', 'foo/bar')).toContain('clientModuleResolution')
   })
 
   it('names the serving gap for a resolved-but-failed bare specifier', () => {
-    const hint = clientScriptFailureHint('foo/bar', 'http://localhost:5173/@id/foo/bar')
-    expect(hint).toContain('"foo/bar"')
-    expect(hint).toContain('could not serve the module')
+    expect(clientScriptFailureHint('foo/bar', 'http://localhost:5173/@id/foo/bar'))
+      .toContain('could not serve the module')
   })
 })
diff --git a/packages/hub/src/client-modules.ts b/packages/hub/src/client-modules.ts
index 9b9e640a..efd7f59d 100644
--- a/packages/hub/src/client-modules.ts
+++ b/packages/hub/src/client-modules.ts
@@ -1,92 +1,49 @@
-import type { ConnectionMeta } from 'devframe/types'
-
-/** Token a {@link DockConnectionConfig.clientModuleResolution} template replaces with the bare specifier. */
-export const CLIENT_MODULE_SPECIFIER_TOKEN = '{specifier}'
-
 const URL_SCHEME_RE = /^[a-z][a-z\d+.-]*:/i
 
 /**
  * Whether a client-script `importFrom` is a **bare module specifier** — an
- * npm-style name (`vite-plugin-vue-tracer/client/vite-devtools`) rather than a
- * URL the browser can resolve natively (root-relative, dot-relative,
- * protocol-relative, or carrying a URL scheme).
+ * npm-style name (`vite-plugin-vue-tracer/client/vite-devtools`) rather than
+ * a URL the browser can resolve natively.
  */
 export function isBareModuleSpecifier(specifier: string): boolean {
   const value = specifier.trim()
-  if (!value)
-    return false
-  return !value.startsWith('/')
+  return !!value
+    && !value.startsWith('/')
     && !value.startsWith('./')
     && !value.startsWith('../')
     && !URL_SCHEME_RE.test(value)
 }
 
-export interface ResolveClientModuleSpecifierOptions {
-  /**
-   * Explicit resolver — wins over the host-advertised template. Return a URL
-   * to import instead, or `undefined` to fall through to the template.
-   */
-  resolveClientModule?: (specifier: string) => string | undefined
-  /**
-   * The connection meta carrying the host-declared
-   * `configs.dock.clientModuleResolution` template.
-   */
-  connectionMeta?: ConnectionMeta
-  /**
-   * Absolute URL of the `__connection.json` that produced `connectionMeta`.
-   * A relative template result resolves against it, so an external viewer on
-   * another origin still imports from the host that declared the template.
-   */
-  metaBaseUrl?: string
-}
-
 /**
- * Apply a host's client-module resolution template to a bare specifier:
- * replace the `{specifier}` token (or suffix the specifier onto a token-less
- * template). The result is a URL path on the host — e.g. Vite's
- * `'/@id/{specifier}'` template maps `foo/bar` to `/@id/foo/bar`, which routes
- * through Vite's own module graph.
+ * Resolve a dock client script's `importFrom` to the URL to import. URL
+ * specifiers pass through untouched; a **bare** specifier resolves through
+ * the explicit `resolveClientModule` callback (a viewer's own policy), then
+ * the host-advertised `template` (`ConnectionMeta.configs.dock.clientModuleResolution`,
+ * its `{specifier}` token replaced — e.g. Vite's `'/@id/{specifier}'`),
+ * resolved against `metaBaseUrl` so it targets the host's origin from any
+ * viewer. With neither, it stays unchanged — a page import map may still
+ * cover it.
  */
-export function applyClientModuleResolutionTemplate(template: string, specifier: string): string {
-  return template.includes(CLIENT_MODULE_SPECIFIER_TOKEN)
-    ? template.replaceAll(CLIENT_MODULE_SPECIFIER_TOKEN, specifier)
-    : template + specifier
-}
-
-/**
- * Resolve a dock client script's `importFrom` to the URL the client host
- * should import. URL specifiers pass through untouched; a **bare** specifier
- * resolves through, in order:
- *
- * 1. the explicit {@link ResolveClientModuleSpecifierOptions.resolveClientModule}
- *    option (a viewer's own policy),
- * 2. the host-advertised template
- *    (`ConnectionMeta.configs.dock.clientModuleResolution`), resolved against
- *    `metaBaseUrl` so it targets the host's origin from any viewer,
- * 3. unchanged — the native import may still succeed if the page carries an
- *    import map for it.
- */
-export function resolveClientModuleSpecifier(
-  specifier: string,
-  options: ResolveClientModuleSpecifierOptions = {},
-): string {
+export function resolveClientModuleSpecifier(specifier: string, options: {
+  resolveClientModule?: (specifier: string) => string | undefined
+  template?: string
+  metaBaseUrl?: string
+} = {}): string {
   if (!isBareModuleSpecifier(specifier))
     return specifier
-
   const custom = options.resolveClientModule?.(specifier)
   if (custom)
     return custom
-
-  const template = options.connectionMeta?.configs?.dock?.clientModuleResolution
-  if (!template)
+  if (!options.template)
     return specifier
-
-  const applied = applyClientModuleResolutionTemplate(template, specifier)
+  const applied = options.template.includes('{specifier}')
+    ? options.template.replaceAll('{specifier}', specifier)
+    : options.template + specifier
   try {
     return new URL(applied, options.metaBaseUrl).href
   }
   catch {
-    // No usable base (same-origin host page) — let the browser resolve the
+    // No usable base (same-origin host page) — the browser resolves the
     // root-relative result against the page origin.
     return applied
   }
@@ -109,9 +66,8 @@ export function clientScriptFailureHint(importFrom: string, specifier: string):
       + 'resolves bare specifiers (e.g. Vite: `/@id/{specifier}`).'
   }
   // Bare and resolved to a host URL, yet the import still failed — the host
-  // couldn't actually serve the module. (A dev server typically answers an
-  // unresolvable module URL with its HTML fallback, which the browser reports
-  // as "Failed to fetch dynamically imported module".)
+  // couldn't actually serve the module (a dev server typically answers an
+  // unresolvable module URL with its HTML fallback).
   return ` — the host resolved the bare specifier "${importFrom}" to this URL but could not serve the module. `
     + 'Check the package is installed and resolvable from the host project\'s root '
     + '(and built, if its exports point at build output).'
diff --git a/packages/hub/src/client/host.ts b/packages/hub/src/client/host.ts
index 51160de1..87da26c7 100644
--- a/packages/hub/src/client/host.ts
+++ b/packages/hub/src/client/host.ts
@@ -60,18 +60,11 @@ export interface DevframeClientHostOptions {
   loadClientScripts?: boolean
   /**
    * Resolve a **bare-specifier** client script (`importFrom` naming an npm
-   * module, e.g. `'vite-plugin-vue-tracer/client/vite-devtools'`) to a URL
-   * this page can import — a viewer's own policy, winning over the
-   * host-advertised `ConnectionMeta.configs.dock.clientModuleResolution`
-   * template. Return `undefined` to fall through to that template. URL
-   * specifiers never reach this hook.
-   *
-   * A viewer running inside a Vite-served page can route bare specifiers
-   * through the app's own module graph:
-   *
-   * ```ts
-   * createDevframeClientHost({ resolveClientModule: s => `/@id/${s}` })
-   * ```
+   * module) to a URL this page can import — a viewer's own policy, winning
+   * over the host-advertised `ConnectionMeta.configs.dock.clientModuleResolution`
+   * template (return `undefined` to fall through to it). URL specifiers never
+   * reach this hook. E.g. on a Vite-served page:
+   * `resolveClientModule: s => `/@id/${s}``.
    */
   resolveClientModule?: (specifier: string) => string | undefined
   /**
@@ -519,13 +512,12 @@ export async function createDevframeClientHost(
 
   async function runClientScript(entryId: string, script: ClientScriptEntry): Promise<void> {
     // A bare specifier resolves through the explicit option, then the
-    // host-advertised template (`configs.dock.clientModuleResolution`); URL
-    // specifiers pass through untouched.
+    // host-advertised template; URL specifiers pass through untouched. (The
+    // rpc reads are optional-chained for partial stubs — tests, bespoke
+    // viewers — where the template then resolves page-relative.)
     const specifier = resolveClientModuleSpecifier(script.importFrom, {
-      ...(options.resolveClientModule ? { resolveClientModule: options.resolveClientModule } : {}),
-      connectionMeta: rpc.connectionMeta,
-      // Optional-chained: a partial rpc stub (tests, bespoke viewers) may
-      // carry no connection record — the template then resolves page-relative.
+      resolveClientModule: options.resolveClientModule,
+      template: rpc.connectionMeta?.configs?.dock?.clientModuleResolution,
       metaBaseUrl: rpc.connection?.metaBaseUrl,
     })
     try {
diff --git a/packages/hub/src/client/index.ts b/packages/hub/src/client/index.ts
index a2257eb8..78c06ac6 100644
--- a/packages/hub/src/client/index.ts
+++ b/packages/hub/src/client/index.ts
@@ -1,4 +1,4 @@
-export * from '../client-modules'
+export { clientScriptFailureHint, resolveClientModuleSpecifier } from '../client-modules'
 export * from './client-script'
 export * from './context'
 export * from './dock-resources'
diff --git a/packages/hub/src/node/diagnostics.ts b/packages/hub/src/node/diagnostics.ts
index 02164523..ba707bc3 100644
--- a/packages/hub/src/node/diagnostics.ts
+++ b/packages/hub/src/node/diagnostics.ts
@@ -74,7 +74,7 @@ export const diagnostics = defineDiagnostics({
     },
     DF8111: {
       why: (p: { id: string, specifier: string }) => `Dock "${p.id}" declares the bare-specifier client script "${p.specifier}", but this host advertises no client-module resolution — the browser cannot resolve a bare npm specifier natively, so the script will fail to load.`,
-      fix: 'Bare specifiers are a host-runtime capability, advertised as `ConnectionMeta.configs.dock.clientModuleResolution`. Run under a host that declares it (a Vite host resolves them through its own module graph via `initHub({ clientModuleResolution: \'/@id/{specifier}\' })` — `@devframes/vite/hub` does this by default), or ship the script as a self-contained bundle and pass a URL the host serves as `importFrom` instead. A viewer may also resolve them itself via `createDevframeClientHost({ resolveClientModule })`, in which case this warning is safe to disregard.',
+      fix: 'Run under a host that declares `initHub({ clientModuleResolution })` (e.g. Vite\'s `\'/@id/{specifier}\'`), ship the script as a self-contained bundle served by URL, or resolve it in the viewer via `createDevframeClientHost({ resolveClientModule })` (then disregard this warning).',
     },
     DF8200: {
       why: (p: { id: string }) => `Terminal session with id "${p.id}" already registered`,
diff --git a/packages/hub/src/node/host-docks.ts b/packages/hub/src/node/host-docks.ts
index e70439e9..b5b58587 100644
--- a/packages/hub/src/node/host-docks.ts
+++ b/packages/hub/src/node/host-docks.ts
@@ -134,11 +134,9 @@ export class DevframeDocksHost implements DevframeDocksHostType {
   /**
    * Warn (don't throw — a viewer-side `resolveClientModule` may still cover
    * it) when a dock declares a **bare-specifier** client script on a host
-   * that advertises no client-module resolution: the browser cannot resolve
-   * a bare npm specifier natively, so the script is doomed to fail there.
-   * On a host that declares `staticConfig.dock.clientModuleResolution`
-   * (e.g. Vite's `'/@id/{specifier}'`), bare specifiers are first-class and
-   * this stays silent.
+   * that advertises no `staticConfig.dock.clientModuleResolution`: the
+   * browser cannot resolve a bare npm specifier natively, so the script is
+   * doomed to fail there.
    */
   private warnUnresolvableClientScript(view: DevframeDockUserEntry): void {
     if (this.context.staticConfig?.dock?.clientModuleResolution)
diff --git a/packages/hub/src/node/initiate.ts b/packages/hub/src/node/initiate.ts
index c5de574a..b153fd67 100644
--- a/packages/hub/src/node/initiate.ts
+++ b/packages/hub/src/node/initiate.ts
@@ -17,7 +17,7 @@ import { mountStaticHandler } from 'devframe/utils/serve-static'
 import { H3 } from 'h3'
 import { resolve } from 'pathe'
 import { joinURL, withoutLeadingSlash, withTrailingSlash } from 'ufo'
-import { applyClientModuleResolutionTemplate, isBareModuleSpecifier } from '../client-modules'
+import { resolveClientModuleSpecifier } from '../client-modules'
 import { DEVFRAMES_HUB_BASE, DOCK_RENDERERS_STATE_KEY, normalizeHubBase } from '../constants'
 import { createHubContext } from './context'
 import { diagnostics } from './diagnostics'
@@ -269,15 +269,12 @@ export interface InitHubOptions {
    * scripts (`ClientScriptEntry.importFrom` naming an npm module) — a URL
    * template whose `{specifier}` token is replaced with the specifier,
    * published as `ConnectionMeta.configs.dock.clientModuleResolution` and
-   * applied by every client-script loader (`createDevframeClientHost`, the
-   * hub-ui viewers, `__client-imports.js`).
-   *
-   * Declare it only when the host can actually serve npm modules to the
-   * browser — a Vite host passes `'/@id/{specifier}'` (requests route through
-   * Vite's own resolution and import-analysis, sharing the app's module
-   * graph; `@devframes/vite/hub` declares this by default). Left undeclared,
-   * bare specifiers are unsupported on this host and registering one warns
-   * `DF8111` — ship a self-contained bundle and pass its URL instead.
+   * applied by every client-script loader. Declare it only when the host can
+   * actually serve npm modules to the browser — a Vite host passes
+   * `'/@id/{specifier}'` to route imports through its own module graph
+   * (`@devframes/vite/hub` does). Left undeclared, registering a
+   * bare-specifier client script warns `DF8111` — ship a self-contained
+   * bundle and pass its URL instead.
    */
   clientModuleResolution?: string
   /** Working directory for the hub context. Default: `process.cwd()`. */
@@ -382,10 +379,6 @@ function resolveRendererRegistrations(
  */
 function renderClientImportsModule(ctx: DevframeHubContext): string {
   const template = ctx.staticConfig.dock?.clientModuleResolution
-  const specifierOf = (script: ClientScriptEntry): string =>
-    template && isBareModuleSpecifier(script.importFrom)
-      ? applyClientModuleResolutionTemplate(template, script.importFrom)
-      : script.importFrom
   const entries: string[] = []
   for (const [id, view] of ctx.docks.views) {
     const scripts: ClientScriptEntry[] = []
@@ -398,7 +391,8 @@ function renderClientImportsModule(ctx: DevframeHubContext): string {
       scripts.push(anyView.renderer)
     if (scripts.length === 0)
       continue
-    const thunks = scripts.map(script => `() => import(${JSON.stringify(specifierOf(script))})`)
+    const thunks = scripts.map(script =>
+      `() => import(${JSON.stringify(resolveClientModuleSpecifier(script.importFrom, { template }))})`)
     entries.push(`  ${JSON.stringify(id)}: [${thunks.join(', ')}],`)
   }
   return `// Generated by @devframes/hub — dock client-script import map.\nexport const clientImports = {\n${entries.join('\n')}\n}\nexport default clientImports\n`
diff --git a/packages/hub/src/types/docks.ts b/packages/hub/src/types/docks.ts
index 6e7cc839..748b9d82 100644
--- a/packages/hub/src/types/docks.ts
+++ b/packages/hub/src/types/docks.ts
@@ -167,13 +167,11 @@ export interface ClientScriptEntry {
    * What to import — either a **URL the host serves** (a self-contained ES
    * module, e.g. `/@fs/<abs path>` under Vite or a statically-mounted bundle
    * path), or a **bare npm specifier** (e.g.
-   * `'vite-plugin-vue-tracer/client/vite-devtools'`).
-   *
-   * Bare specifiers are a host-runtime capability: they resolve through the
-   * host-advertised {@link DockConnectionConfig.clientModuleResolution}
-   * template (Vite hosts declare `'/@id/{specifier}'`, importing through the
-   * app's own module graph). On a host that declares no template, ship a
-   * self-contained bundle and pass its URL instead (see `DF8111`).
+   * `'vite-plugin-vue-tracer/client/vite-devtools'`), a host-runtime
+   * capability resolved through the host-advertised
+   * `ConnectionMeta.configs.dock.clientModuleResolution` template. On a host
+   * that declares no template, ship a self-contained bundle and pass its URL
+   * instead (see `DF8111`).
    */
   importFrom: string
   /**
@@ -184,31 +182,21 @@ export interface ClientScriptEntry {
   importName?: string
 }
 
-/**
- * Static dock-layer config a hub host publishes through the connection
- * handshake (`ConnectionMeta.configs.dock`), declared node-side via
- * `ctx.staticConfig.dock` (or `initHub({ clientModuleResolution })`).
- */
-export interface DockConnectionConfig {
-  /**
-   * URL template that resolves a **bare-specifier** client script
-   * (`ClientScriptEntry.importFrom`) to an importable URL on this host — the
-   * `{specifier}` token is replaced with the bare specifier (a token-less
-   * template is used as a prefix). Declaring it advertises that this host
-   * runtime can serve npm modules to the browser:
-   *
-   * - Vite hosts declare `'/@id/{specifier}'` — the request routes through
-   *   Vite's own resolution and import-analysis, so the script's transitive
-   *   bare imports work too and share the app's module graph.
-   * - Hosts without such a runtime (e.g. Next.js) leave it undeclared; client
-   *   scripts there ship as self-contained bundles served by URL.
-   */
-  clientModuleResolution?: string
-}
-
 declare module 'devframe/types' {
   interface DevframeConnectionConfigsRegistry {
-    dock: DockConnectionConfig
+    /** Static dock-layer config a hub host publishes through the connection handshake (`initHub({ clientModuleResolution })` → `ctx.staticConfig.dock`). */
+    dock: {
+      /**
+       * URL template resolving a **bare-specifier** client script to an
+       * importable URL on this host — `{specifier}` replaced with the bare
+       * specifier (a token-less template is used as a prefix). Declaring it
+       * advertises the host runtime can serve npm modules to the browser:
+       * Vite hosts declare `'/@id/{specifier}'`, routing the import (and its
+       * transitive bare imports) through the app's own module graph. Hosts
+       * without such a runtime (e.g. Next.js) leave it undeclared.
+       */
+      clientModuleResolution?: string
+    }
   }
 }
 
diff --git a/packages/vite/src/hub.ts b/packages/vite/src/hub.ts
index cea39290..52912bcf 100644
--- a/packages/vite/src/hub.ts
+++ b/packages/vite/src/hub.ts
@@ -32,19 +32,6 @@ export interface ViteDevframeHubOptions {
    * (e.g. the a11y inspector's in-page agent).
    */
   clientScripts?: Record<string, ClientScriptEntry>
-  /**
-   * How this host resolves **bare-specifier** client scripts (an `importFrom`
-   * naming an npm module, e.g. `'vite-plugin-vue-tracer/client/vite-devtools'`),
-   * advertised as `ConnectionMeta.configs.dock.clientModuleResolution`.
-   * Defaults to Vite's `'/@id/{specifier}'` — requests route through Vite's
-   * own resolution and import-analysis, so the script's transitive bare
-   * imports work too and share the app's module graph. Pass `false` to
-   * advertise no resolution (bare-specifier client scripts then warn
-   * `DF8111`).
-   *
-   * @default '/@id/{specifier}'
-   */
-  clientModuleResolution?: string | false
   /**
    * Prebuilt dock-renderer modules forwarded to `initHub({ renderers })` —
    * each served at `<base>__renderers/<type>.mjs` and published in the
@@ -99,14 +86,6 @@ export interface ViteDevframeHubOptions {
   quiet?: boolean
 }
 
-/**
- * The Vite host's bare-specifier resolution template — `/@id/<specifier>`
- * asks the Vite dev server to resolve and transform the module through its
- * own graph. Exported for hosts (e.g. Vite DevTools) that boot their own
- * client host or hub and want to declare the same capability.
- */
-export const VITE_CLIENT_MODULE_RESOLUTION = '/@id/{specifier}'
-
 let recommendedViteDevtools = false
 
 function recommendViteDevtools(): void {
@@ -181,18 +160,13 @@ export function viteDevframeHub(options: ViteDevframeHubOptions = {}): Plugin {
 
       const httpServer = server.httpServer instanceof NodeHttpServer ? server.httpServer : undefined
 
-      // Bare-specifier client scripts resolve through Vite's own module graph:
-      // `/@id/<specifier>` routes the request through Vite's resolution and
-      // import-analysis, so the script's transitive bare imports work too and
-      // share module instances with the app's own code.
-      const clientModuleResolution = options.clientModuleResolution === false
-        ? undefined
-        : options.clientModuleResolution ?? VITE_CLIENT_MODULE_RESOLUTION
-
       const hub = initHub({
         base,
         cwd,
-        ...(clientModuleResolution ? { clientModuleResolution } : {}),
+        // Bare-specifier client scripts resolve through Vite's own module
+        // graph: `/@id/<specifier>` routes the import (and its transitive
+        // bare imports) through Vite's resolution and import-analysis.
+        clientModuleResolution: '/@id/{specifier}',
         origin: options.origin ?? (() => {
           const resolved = server.resolvedUrls?.local?.[0]
           return resolved ? new URL(resolved).origin : ''
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
index a6311d40..e62aa678 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
@@ -179,11 +179,6 @@ export interface FrameTab {
 export interface MessagesClientOptions {
   defaults?: Partial<DevframeMessageEntryInput>;
 }
-export interface ResolveClientModuleSpecifierOptions {
-  resolveClientModule?: (_: string) => string | undefined;
-  connectionMeta?: ConnectionMeta;
-  metaBaseUrl?: string;
-}
 export interface WatchFrameLocationOptions {
   iframe: FrameLocationTarget;
   onChange: (_: string) => void;
@@ -237,7 +232,6 @@ export type FrameNavHostPayload = {
 // #endregion
 
 // #region Functions
-export declare function applyClientModuleResolutionTemplate(_: string, _: string): string;
 export declare function attachFrameNavClient(_: FrameNavClientOptions): FrameNavClient;
 export declare function buildRemoteDevframeUrl(_: string, _: DevframeConnection): string;
 export declare function clientScriptFailureHint(_: string, _: string): string;
@@ -246,9 +240,12 @@ export declare function createDevframeClientHost(_?: DevframeClientHostOptions):
 export declare function createDockRenderersContext(_: CreateDockRenderersContextOptions): DockRenderersContext;
 export declare function createMessagesClient(_: DevframeRpcClient, _?: MessagesClientOptions): DevframeMessagesClient;
 export declare function getDevframeClientContext(): DevframeClientContext | undefined;
-export declare function isBareModuleSpecifier(_: string): boolean;
 export declare function parseRemoteConnection(_?: string): RemoteConnectionInfo | null;
-export declare function resolveClientModuleSpecifier(_: string, _?: ResolveClientModuleSpecifierOptions): string;
+export declare function resolveClientModuleSpecifier(_: string, _?: {
+  resolveClientModule?: (_: string) => string | undefined;
+  template?: string;
+  metaBaseUrl?: string;
+}): string;
 export declare function resolveDockIcon(_: DevframeDockEntryIcon, _: DevframeConnection): DevframeDockEntryIcon;
 export declare function resolveDockUrl(_: string, _: DevframeConnection): string;
 export declare function setDevframeClientContext(_: DevframeClientContext | undefined): void;
@@ -258,7 +255,6 @@ export declare function watchFrameLocation(_: WatchFrameLocationOptions): () =>
 
 // #region Variables
 export declare const CLIENT_CONTEXT_KEY: string;
-export declare const CLIENT_MODULE_SPECIFIER_TOKEN: string;
 export declare const FRAME_NAV_CHANNEL: string;
 export declare const FRAME_NAV_VERSION: number;
 // #endregion
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js
index 195a6f6b..7cc6258b 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js
@@ -27,10 +27,7 @@ export * from "devframe/client";
 // #endregion
 
 // #region Other
-export { applyClientModuleResolutionTemplate }
-export { CLIENT_MODULE_SPECIFIER_TOKEN }
 export { clientScriptFailureHint }
-export { isBareModuleSpecifier }
 export { resolveClientModuleSpecifier }
 export { stripRemoteConnectionFromUrl }
 // #endregion
\ No newline at end of file
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts
index 44b248f6..9aff9c44 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts
@@ -315,9 +315,6 @@ export interface DevframeViewLauncher extends DevframeDockEntryBase {
     onLaunch?: () => Promise<void>;
   };
 }
-export interface DockConnectionConfig {
-  clientModuleResolution?: string;
-}
 export interface FrameSubTabsConfig {
   protocol: 'postmessage';
   handshakeTimeoutMs?: number;
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts
index 10c49d92..2eb67965 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts
@@ -70,7 +70,6 @@ export { DevframeViewHost }
 export { DevframeViewIframe }
 export { DevframeViewLauncher }
 export { DevframeViewLauncherStatus }
-export { DockConnectionConfig }
 export { EventEmitter }
 export { EventsMap }
 export { EventUnsubscribe }
diff --git a/tests/__snapshots__/tsnapi/@devframes/vite/hub.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/vite/hub.snapshot.d.ts
index eca65871..ae5f1822 100644
--- a/tests/__snapshots__/tsnapi/@devframes/vite/hub.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/vite/hub.snapshot.d.ts
@@ -8,7 +8,6 @@ export interface ViteDevframeHubOptions {
   host?: string;
   devframes?: InitHubOptions['devframes'];
   clientScripts?: Record<string, ClientScriptEntry>;
-  clientModuleResolution?: string | false;
   renderers?: readonly DockRendererRegistration[];
   rpcDeclarations?: InitHubOptions['rpcDeclarations'];
   configure?: (_: DevframeHubContext) => void | Promise<void>;
@@ -27,8 +26,4 @@ export interface ViteDevframeHubOptions {
 
 // #region Functions
 export declare function viteDevframeHub(_?: ViteDevframeHubOptions): Plugin;
-// #endregion
-
-// #region Variables
-export declare const VITE_CLIENT_MODULE_RESOLUTION: string;
 // #endregion
\ No newline at end of file
diff --git a/tests/__snapshots__/tsnapi/@devframes/vite/hub.snapshot.js b/tests/__snapshots__/tsnapi/@devframes/vite/hub.snapshot.js
index 536a709c..ea0e76aa 100644
--- a/tests/__snapshots__/tsnapi/@devframes/vite/hub.snapshot.js
+++ b/tests/__snapshots__/tsnapi/@devframes/vite/hub.snapshot.js
@@ -3,8 +3,4 @@
  */
 // #region Functions
 export function viteDevframeHub(_) {}
-// #endregion
-
-// #region Variables
-export var VITE_CLIENT_MODULE_RESOLUTION /* const */
 // #endregion
\ No newline at end of file