fix(examples): serve the demo dock client from source; diagnose resolved-but-unservable client scripts

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.

Author: antfubot

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 |

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"
   },

examples/demo-dock-client/tsdown.config.ts

@@ -2,31 +2,23 @@ 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,
     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'] },
   },

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
   }
 }

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')
+  })
+})

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).'
+}

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,
+      )
     }
   }
 }

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;

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 }