test: make page-script mount assertion cross-platform; trim comments

Use pathe consistently in the install-devframe test so the served-dir
assertion matches the implementation's normalized path on Windows.
Trim the verbose comments/descriptions added across the change per review.

Author: antfubot

examples/a11y-messages-playground/README.md

@@ -56,8 +56,7 @@ The window is split in two:
 
 `src/a11y-messages-playground.ts` is the entire host-framework integration - a ~120-line Vite plugin
 that runs `@devframes/hub` in the dev server and mounts the two devframes as docks.
-The a11y inspector declares its own page script as the a11y dock's `clientScript`, so
-the hub serves it same-origin and boots it - the host passes only the devframes:
+The a11y inspector declares its own page script, so the host passes only the devframes:
 
 ```ts
 a11yMessagesPlayground({
@@ -77,7 +76,7 @@ the focused dock - the same path a manual dock click takes.
 | File | Role |
 |---|---|
 | `src/a11y-messages-playground.ts` | The Vite host - hub context, static + connection-meta mounts, side-car WS, instance-registry registration |
-| `vite.config.ts` | Mounts a11y + messages (the a11y page script rides along as its dock's declared `clientScript`) |
+| `vite.config.ts` | Mounts a11y + messages |
 | `src/client/main.ts` | Boots the client runtime, renders the dock rail + iframe stage |
 | `src/client/app-under-test.ts` | The intentionally-broken, multi-route app the page script scans |
 | `src/client/icons.ts` | Offline Phosphor icons for the dock rail |

examples/a11y-messages-playground/src/a11y-messages-playground.ts

@@ -21,9 +21,7 @@ export interface A11yMessagesPlaygroundOptions {
  * playground pairs (a11y + messages). One `initHub()` call assembles the whole
  * hub: it mounts each devframe as a dock, shares the WebSocket with Vite's own
  * server, serves the discovery endpoints, and registers the playground in the
- * global instance registry. The a11y inspector declares its own page script
- * (its dock's `clientScript`), so the hub serves it same-origin and boots it -
- * no client-script wiring here.
+ * global instance registry.
  */
 export function a11yMessagesPlayground(options: A11yMessagesPlaygroundOptions = {}): Plugin {
   const base = normalizeBase(options.base ?? '/__hub/')

examples/a11y-messages-playground/vite.config.ts

@@ -14,9 +14,6 @@ export default defineConfig({
   optimizeDeps: { exclude: ['@antfu/design'] },
   plugins: [
     UnoCSS(),
-    // The a11y inspector ships its own page script (its dock's `clientScript`),
-    // so the hub serves it same-origin and boots it - the panel scans this page
-    // live with no wiring here.
     a11yMessagesPlayground({
       devframes: [a11yDevframe, messagesDevframe],
     }),

examples/hub-next/README.md

@@ -57,7 +57,7 @@ The built-in devframes run node-side (child processes, the native `zigpty` PTY b
 
 | File | Role |
 |---|---|
-| `src/client/devframe/next-devframe-hub.ts` | The Next host - one `initHub()` call: devframes (the a11y page script rides along automatically as its dock's declared `clientScript`), hub RPCs, commands, the json-render dock + renderer manifest, instance-registry registration |
+| `src/client/devframe/next-devframe-hub.ts` | The Next host - one `initHub()` call: devframes, 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` |

examples/hub-next/src/client/devframe/next-devframe-hub.ts

@@ -186,15 +186,11 @@ export async function nextDevframeHub(
   // way so its `import.meta.url` bundle path resolves to the published `dist`.
   const jsonRenderRenderer = await loadJsonRenderUiRenderer()
 
-  // Demo devframes alongside the dogfooded built-in plugin packages. The a11y
-  // inspector declares its own page script (its dock's `clientScript`) by path,
-  // so the hub serves it same-origin and the hub client runtime booted in
-  // `app/page.tsx` imports it into the host page automatically - it scans this
-  // hub live with no host-side wiring. The shared-iframe soft-navigation demo
-  // mounts as a `subTabs` anchor (a shared `frameId` + the postmessage
-  // protocol) so the client host attaches the frame-nav adapter, materializing
-  // one client-only dock per tab the SPA's shim reports - all sharing one
-  // iframe.
+  // Demo devframes alongside the dogfooded built-in plugin packages. The
+  // shared-iframe soft-navigation demo mounts as a `subTabs` anchor (a shared
+  // `frameId` + the postmessage protocol) so the client host attaches the
+  // frame-nav adapter, materializing one client-only dock per tab the SPA's
+  // shim reports - all sharing one iframe.
   const devframes: (DevframeDefinition | HubDevframeEntry)[] = [
     demoDevframe,
     ...await loadBuiltinPlugins(),

examples/hub-vite/README.md

@@ -45,7 +45,7 @@ The dock UI is plain DOM in `src/client/`. To skin your own hub UI provider, rea
 | File | Role |
 |---|---|
 | `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 and demo devframes to the hub's `devframes` option (the a11y page script rides along automatically as its dock's declared `clientScript`); composes the json-render frontend via `renderers` |
+| `vite.config.ts` | Passes the built-in and demo devframes to the hub's `devframes` option; 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 |

examples/hub-vite/vite.config.ts

@@ -142,11 +142,6 @@ export default defineConfig({
           },
         },
       ],
-      // The a11y inspector declares its own page script (its dock's
-      // `clientScript`) by path, so the hub serves it same-origin and the hub
-      // client runtime (booted in src/client/main.ts) imports it into this page
-      // automatically - the docked panel scans the host live with no host-side
-      // wiring.
       // Serve the reference json-render frontend as a prebuilt renderer
       // module: the hub publishes it in the renderer manifest and the client
       // (src/client/main.ts) imports it lazily the first time a

packages/devframe/src/types/devframe.ts

@@ -265,22 +265,12 @@ export interface DevframeDockDefaults {
   groupId?: string
   /**
    * A client script the hub imports into the host page for this devframe (its
-   * **page script**) — the mechanism a devframe like the a11y inspector uses to
-   * run its scan loop in the user app's page. `importFrom` is one of:
-   *
-   * - an **absolute filesystem path** to a built, self-contained ES module (e.g.
-   *   the plugin's `dist/inject/inject.js`, named from its own `import.meta.url`).
-   *   The hub install path serves the file's directory under the devframe's mount
-   *   base and rewrites `importFrom` to that served URL, so a definition can name
-   *   its page script itself and `devframes: ['@devframes/plugin-x']` works with
-   *   no host-side wiring;
-   * - a **URL** the host already serves (`/@fs/<abs>` under Vite, a
-   *   statically-mounted bundle path); or
-   * - a **bare npm specifier**, resolved through the host-advertised
-   *   `clientModuleResolution` template.
-   *
-   * URL and bare-specifier values pass through untouched — only an absolute path
-   * is mounted and rewritten.
+   * **page script**). `importFrom` is an **absolute filesystem path** to a built
+   * ES module, a **URL** the host serves, or a **bare npm specifier**. An
+   * absolute path is served by the hub install path (its directory mounted under
+   * the devframe's mount base, `importFrom` rewritten to the served URL), so a
+   * definition names its own page script and mounting by package name needs no
+   * host wiring; URL and bare-specifier values pass through untouched.
    */
   clientScript?: {
     /** What to import: an absolute filesystem path, a served URL, or a bare npm specifier. */

packages/hub/src/node/__tests__/install-devframe.test.ts

@@ -2,8 +2,8 @@ import type { DevframeDefinition, DevframeDuplicationStrategy } from 'devframe/t
 import type { DevframeHubContext } from '../context'
 import { mkdtempSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
 import { defineDevframe } from 'devframe'
+import { dirname, join } from 'pathe'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { DevframeDocksHost } from '../host-docks'
 import { installDevframe } from '../install-devframe'
@@ -165,15 +165,14 @@ describe('ctx.install', () => {
 
   it('serves an absolute-path page script under the mount base and rewrites it to the served URL', async () => {
     const ctx = createContext()
-    const dir = mkdtempSync(join(tmpdir(), 'devframe-page-script-'))
-    const scriptPath = join(dir, 'inject.js')
+    const scriptPath = join(mkdtempSync(join(tmpdir(), 'devframe-page-script-')), 'inject.js')
     writeFileSync(scriptPath, 'export default () => {}')
 
     await ctx.install(makeDevframe({
       dock: { clientScript: { importFrom: scriptPath } },
     }))
 
-    expect(ctx.host.mountStatic).toHaveBeenCalledWith('/__demo/__page-script/', dir)
+    expect(ctx.host.mountStatic).toHaveBeenCalledWith('/__demo/__page-script/', dirname(scriptPath))
     expect(ctx.docks.views.get('demo')).toMatchObject({
       clientScript: { importFrom: '/__demo/__page-script/inject.js' },
     })

packages/hub/src/node/install-devframe.ts

@@ -40,17 +40,11 @@ function nextAvailableDockId(views: DevframeHubContext['docks']['views'], baseId
 }
 
 /**
- * Resolve a dock's `clientScript` (its **page script**) into one importable by
- * the host page. When `importFrom` names an **absolute filesystem path** to a
- * built module, serve its directory under the devframe's mount base
- * (`<base>__page-script/`) and rewrite `importFrom` to that served URL — so a
- * definition can name its page script by path and every host gets a URL for
- * free. A URL or bare-specifier `importFrom` (or no client script) passes
- * through untouched.
- *
- * The distinction between a filesystem path and an already-servable root path
- * (`/@fs/…`, `/mounted/bundle.js`) is that only the former exists on disk, so
- * that is the test used.
+ * When a dock's `clientScript.importFrom` names an **absolute filesystem path**
+ * to a built module, serve its directory under the devframe's mount base
+ * (`<base>__page-script/`) and rewrite `importFrom` to that served URL. A URL or
+ * bare specifier (distinguished by not existing on disk) passes through
+ * untouched, as does an absent client script.
  */
 async function resolvePageScriptClientScript(
   ctx: DevframeHubContext,
@@ -117,9 +111,9 @@ export async function prepareDevframe(
       ? resolveBasePath(d, 'hosted')
       : resolveBasePath({ ...d, id, basePath: undefined }, 'hosted'))
 
-  // The effective dock defaults: definition-level `dock` beneath per-mount
-  // `options.dock`. Resolved here (before the SPA mount) so a page script
-  // declared as an absolute path can be served ahead of the SPA catch-all.
+  // Definition-level `dock` beneath per-mount `options.dock`. Resolved before
+  // the SPA mount so an absolute-path page script is served ahead of the SPA
+  // catch-all.
   const dockDefaults = { ...d.dock, ...options.dock }
   const clientScript = await resolvePageScriptClientScript(ctx, dockDefaults.clientScript, base)
   if (clientScript)
@@ -152,11 +146,9 @@ export async function prepareDevframe(
     id,
     title: d.name,
     icon: d.icon,
-    // Definition-level `dock` defaults sit above the name/icon-derived
-    // defaults; per-mount `options.dock` overrides them (both folded into
-    // `dockDefaults`, with an absolute-path page script already served and
-    // rewritten to a URL); `type`/`url` (and `id`) stay locked, derived from
-    // the definition.
+    // Dock defaults (definition + per-mount, folded into `dockDefaults`) sit
+    // above the name/icon-derived defaults; `type`/`url` (and `id`) stay locked,
+    // derived from the definition.
     ...dockDefaults,
     type: 'iframe',
     url: base,