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..e41fae58
--- /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 `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 | Resolves to | Role |
+|---|---|---|
+| `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
new file mode 100644
index 00000000..e03a0c4c
--- /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": {
+    ".": "./src/index.ts",
+    "./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..032c9edc
--- /dev/null
+++ b/examples/demo-dock-client/tsdown.config.ts
@@ -0,0 +1,33 @@
+import { defineConfig } from 'tsdown'
+
+const tsconfig = '../../tsconfig.base.json'
+
+// 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`);
+//   2. `dist/node.mjs` — 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: { 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..8a03947e 100644
--- a/examples/hub-next/src/client/app/page.tsx
+++ b/examples/hub-next/src/client/app/page.tsx
@@ -498,6 +498,8 @@ export default function Page() {
   }, [])
 
   const renderableDocks = useMemo(() => docks.filter(isRenderableDock), [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.
@@ -645,13 +647,21 @@ 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
+                        // Momentary action dock: fire its client script, keep
+                        // the panel selection as-is.
+                        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 7c5c7939..91bef12d 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,42 @@ 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 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 {
+    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 +222,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 +330,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..f19b8fb2 100644
--- a/examples/hub-vite/src/client/main.ts
+++ b/examples/hub-vite/src/client/main.ts
@@ -459,9 +459,11 @@ 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)
+    // 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)
 
     for (const entry of list) {
       if (wired.has(entry.id))
@@ -478,7 +480,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?.entryMeta.type === 'action') {
+      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..524f3190 100644
--- a/examples/hub-vite/vite.config.ts
+++ b/examples/hub-vite/vite.config.ts
@@ -176,6 +176,20 @@ export default defineConfig({
           icon: 'ph:layout-duotone',
           category: 'app',
         }))
+        // Bare-specifier client script demo: `importFrom` names the npm
+        // 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',
+          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..c55f428f 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 { clientScriptFailureHint, resolveClientModuleSpecifier } from '@devframes/hub/client'
 
 /**
  * Resolve the {@link ClientScriptEntry} a dock entry carries — an `action`'s
@@ -25,20 +26,30 @@ 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; URL
+  // specifiers pass through untouched. Mirrors `@devframes/hub`'s
+  // `createDevframeClientHost` (rpc reads optional-chained for partial stubs).
+  const specifier = resolveClientModuleSpecifier(script.importFrom, {
+    template: context.rpc.connectionMeta?.configs?.dock?.clientModuleResolution,
+    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)
+    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
new file mode 100644
index 00000000..8476b51c
--- /dev/null
+++ b/packages/hub/src/client-modules.test.ts
@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest'
+import {
+  clientScriptFailureHint,
+  isBareModuleSpecifier,
+  resolveClientModuleSpecifier,
+} from './client-modules'
+
+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', () => {
+    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', { 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')).toBe('foo/bar')
+  })
+
+  it('applies the host-advertised template, resolved against metaBaseUrl', () => {
+    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('uses a token-less template as a prefix, verbatim without a usable base', () => {
+    expect(resolveClientModuleSpecifier('foo', { template: '/modules/' })).toBe('/modules/foo')
+  })
+
+  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')
+  })
+})
+
+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', () => {
+    expect(clientScriptFailureHint('foo/bar', 'foo/bar')).toContain('clientModuleResolution')
+  })
+
+  it('names the serving gap for a resolved-but-failed bare specifier', () => {
+    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
new file mode 100644
index 00000000..efd7f59d
--- /dev/null
+++ b/packages/hub/src/client-modules.ts
@@ -0,0 +1,74 @@
+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.
+ */
+export function isBareModuleSpecifier(specifier: string): boolean {
+  const value = specifier.trim()
+  return !!value
+    && !value.startsWith('/')
+    && !value.startsWith('./')
+    && !value.startsWith('../')
+    && !URL_SCHEME_RE.test(value)
+}
+
+/**
+ * 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 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
+  if (!options.template)
+    return 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) — the browser resolves the
+    // root-relative result against the page origin.
+    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).
+  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 c16d3884..87da26c7 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 { 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'
@@ -57,6 +58,15 @@ export interface DevframeClientHostOptions {
    * `custom-render`, and iframe `clientScript`). Default `true`.
    */
   loadClientScripts?: boolean
+  /**
+   * Resolve a **bare-specifier** client script (`importFrom` naming an npm
+   * 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
   /**
    * Dock renderers to register at boot, keyed by dock `type`. The host
    * application injects the ones it wants (e.g.
@@ -501,10 +511,19 @@ 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; 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, {
+      resolveClientModule: options.resolveClientModule,
+      template: rpc.connectionMeta?.configs?.dock?.clientModuleResolution,
+      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 +538,10 @@ export async function createDevframeClientHost(
     }
     catch (error) {
       loadedScripts.delete(entryId)
-      console.error(`[@devframes/hub] failed to load client script for "${entryId}" from ${script.importFrom}`, error)
+      console.error(
+        `[@devframes/hub] failed to load client script for "${entryId}" from ${specifier}${clientScriptFailureHint(script.importFrom, specifier)}`,
+        error,
+      )
     }
   }
 }
diff --git a/packages/hub/src/client/index.ts b/packages/hub/src/client/index.ts
index 97bdfebd..78c06ac6 100644
--- a/packages/hub/src/client/index.ts
+++ b/packages/hub/src/client/index.ts
@@ -1,3 +1,4 @@
+export { clientScriptFailureHint, resolveClientModuleSpecifier } 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..ba707bc3 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: '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 4f1769a6..b5b58587 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,23 @@ 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 `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)
+      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..b153fd67 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 { resolveClientModuleSpecifier } 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,19 @@ 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. 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()`. */
   cwd?: string
   /** Override where persisted devframe state lives. */
@@ -360,9 +374,11 @@ 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 entries: string[] = []
   for (const [id, view] of ctx.docks.views) {
     const scripts: ClientScriptEntry[] = []
@@ -375,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(script.importFrom)})`)
+    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`
@@ -470,6 +487,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..748b9d82 100644
--- a/packages/hub/src/types/docks.ts
+++ b/packages/hub/src/types/docks.ts
@@ -164,7 +164,14 @@ 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'`), 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
   /**
@@ -175,6 +182,24 @@ export interface ClientScriptEntry {
   importName?: string
 }
 
+declare module 'devframe/types' {
+  interface DevframeConnectionConfigsRegistry {
+    /** 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
+    }
+  }
+}
+
 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..52912bcf 100644
--- a/packages/vite/src/hub.ts
+++ b/packages/vite/src/hub.ts
@@ -163,6 +163,10 @@ export function viteDevframeHub(options: ViteDevframeHubOptions = {}): Plugin {
       const hub = initHub({
         base,
         cwd,
+        // 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/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..e62aa678 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>;
 }
@@ -233,12 +234,18 @@ export type FrameNavHostPayload = {
 // #region Functions
 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;
 export declare function createMessagesClient(_: DevframeRpcClient, _?: MessagesClientOptions): DevframeMessagesClient;
 export declare function getDevframeClientContext(): DevframeClientContext | undefined;
 export declare function parseRemoteConnection(_?: string): RemoteConnectionInfo | null;
+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;
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js
index 6115ae75..7cc6258b 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js
@@ -27,5 +27,7 @@ export * from "devframe/client";
 // #endregion
 
 // #region Other
+export { clientScriptFailureHint }
+export { resolveClientModuleSpecifier }
 export { stripRemoteConnectionFromUrl }
 // #endregion
\ No newline at end of file
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;
 }