docs: tighten prose and jsdocs; reorder client-script shapes

Move the absolute-path shape to the third bullet and drop the a11y
parenthetical (review). Make the page-script docs, jsdocs, and comments
as concise as possible.

Author: antfubot

docs/content/1.guide/17.client-context.md

@@ -78,11 +78,11 @@ A failed import retries on the next dock update.
 
 `importFrom` accepts three shapes:
 
-- **An absolute filesystem path** to a built, self-contained ES module — declared on the definition's `dock.clientScript`. The hub install path serves the file's directory under the devframe's mount base (`<base>__page-script/`) and rewrites `importFrom` to that served URL, so a definition names its own client script and mounting by package name works with no host wiring (this is how the [a11y inspector](/plugins/a11y) ships its page script).
 - **A URL served by the host framework** — a self-contained ES module; works on every host framework.
 - **A bare npm specifier** (`'vite-plugin-vue-tracer/client/vite-devtools'`) — resolved through the host framework.
+- **An absolute filesystem path**, declared on the definition's `dock.clientScript`. The hub serves its directory under `<base>__page-script/` and rewrites `importFrom` to that URL, so mounting by package name needs no host wiring.
 
-A definition declares its own by path on `dock: { clientScript: { importFrom } }`. Per-mount, attach a URL via `ctx.install(myDevframe, { dock: { clientScript: { importFrom } } })`; under Vite `/@fs/<absolute path>` serves it, and other host frameworks mount the directory statically.
+Per-mount, attach a URL via `ctx.install(myDevframe, { dock: { clientScript: { importFrom } } })`; under Vite `/@fs/<absolute path>` serves it, and other host frameworks mount the directory statically.
 
 ### Bare npm specifiers
 

docs/content/5.plugins/4.a11y.md

@@ -31,15 +31,15 @@ The page script and the panel talk over the [in-page channel](/guide/in-page-cha
 
 ## In a hub
 
-The definition declares the page script as its dock [client script](/guide/client-context), so mounting by package name works everywhere with no extra wiring:
+The definition declares the page script as its dock [client script](/guide/client-context), so mounting by package name just works:
 
 ```ts
 initHub({ devframes: ['@devframes/plugin-a11y'] })
 ```
 
-The hub serves the page-script bundle same-origin under the a11y mount base and rewrites the dock's `clientScript` to that URL; a client runtime (`createDevframeClientRuntime()`) then imports it into the host page. Each scan also mirrors into the hub's messages feed — a summary plus one per rule.
+The hub serves the bundle same-origin and a client runtime imports it into the host page. Each scan also mirrors into the hub's messages feed — a summary plus one per rule.
 
-A host that mounts the module itself still can — for example, a Vite host serving it via `/@fs/` — by attaching `a11yPageScriptBundlePath` as the dock's `clientScript`:
+A host can also mount the module itself — e.g. a Vite host via `/@fs/`:
 
 ```ts
 import createA11yDevframe, { a11yPageScriptBundlePath } from '@devframes/plugin-a11y'

examples/a11y-messages-playground/README.md

@@ -55,8 +55,8 @@ The window is split in two:
 ## How it's wired
 
 `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, so the host passes only the devframes:
+that runs `@devframes/hub` in the dev server and mounts the two devframes as docks
+(the a11y inspector declares its own page script):
 
 ```ts
 a11yMessagesPlayground({

examples/hub-next/README.md

@@ -20,7 +20,7 @@ Open the printed URL. The dock rail on the left lists every mounted tool with it
 
 Selecting a tool loads its SPA in the stage. The bottom drawer mirrors the hub's **Commands**, **Messages**, and **Terminals** subsystems, plus a button that dispatches a command through `hub:commands:execute`, and a **Transport** section showing which RPC transport the connection runs on (`websocket` or `sse`) with a segmented Auto / WS / SSE toggle - the choice rides a `?transport=` URL param and reconnects the whole client runtime on the pinned transport.
 
-The A11y Inspector shows a live axe-core report of this hub's own page: the devframe declares its own page-script module as the a11y dock's `clientScript`, so the hub serves it same-origin inside the hub namespace and rewrites the entry to that URL with no host wiring; the hub client runtime - `createDevframeClientRuntime()` booted in `app/page.tsx` - imports it into the page, so the docked panel and the page script share the origin and tab their in-page channel handshakes across.
+The A11y Inspector shows a live axe-core report of this hub's own page: the devframe declares its own page-script module as the a11y dock's `clientScript`, so the hub serves it same-origin with no host wiring; the hub client runtime - `createDevframeClientRuntime()` booted in `app/page.tsx` - imports it into the page, so the docked panel and the page script share the origin and tab their in-page channel handshakes across.
 
 The **RPC & State Inspector** carries an **Instances** tab that lists every devframe dev server running on your machine. The hub registers itself in the shared registry (`~/.devframe/instances/`) on startup via `registerDevframeInstance()`, so it shows up as "this instance"; start another example (e.g. `pnpm --filter hub-vite dev`, or any `node bin.mjs` CLI example) in a second terminal and it appears there too, each linking to its own SPA.
 

packages/devframe/src/types/devframe.ts

@@ -264,16 +264,13 @@ export interface DevframeDockDefaults {
   /** Id of the dock group this entry collapses under, if any. */
   groupId?: string
   /**
-   * A client script the hub imports into the host page for this devframe (its
-   * **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.
+   * A client script the hub imports into the host page (this devframe's **page
+   * script**). An absolute-path `importFrom` is served by the hub under the
+   * mount base and rewritten to that URL, so mounting by package name needs no
+   * host wiring; a URL or bare specifier passes through untouched.
    */
   clientScript?: {
-    /** What to import: an absolute filesystem path, a served URL, or a bare npm specifier. */
+    /** An absolute filesystem path, a served URL, or a bare npm specifier. */
     importFrom: string
     /**
      * The name to import the module as.

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

@@ -40,11 +40,9 @@ function nextAvailableDockId(views: DevframeHubContext['docks']['views'], baseId
 }
 
 /**
- * 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.
+ * When a dock's `clientScript.importFrom` is an absolute filesystem path, serve
+ * its directory under `<base>__page-script/` and rewrite `importFrom` to that
+ * URL. A URL or bare specifier (not existing on disk) passes through untouched.
  */
 async function resolvePageScriptClientScript(
   ctx: DevframeHubContext,
@@ -111,9 +109,8 @@ export async function prepareDevframe(
       ? resolveBasePath(d, 'hosted')
       : resolveBasePath({ ...d, id, basePath: undefined }, 'hosted'))
 
-  // 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.
+  // Definition `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)
@@ -146,9 +143,8 @@ export async function prepareDevframe(
     id,
     title: d.name,
     icon: d.icon,
-    // 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` sits above the name/icon defaults; `type`/`url`/`id` stay
+    // locked, derived from the definition.
     ...dockDefaults,
     type: 'iframe',
     url: base,

plugins/a11y/README.md

@@ -57,14 +57,12 @@ page script itself free of any RPC dependency.
 devframe deliberately provides no access to the user app's DOM, so the
 page script is the author-provided bridge into the user app's page. In a hub, the
 page script is the a11y dock's **client script**, and the definition declares it by
-path (`dock.clientScript.importFrom = a11yPageScriptBundlePath`): the hub install
-path serves the bundle same-origin under the a11y mount base and rewrites the entry
-to that URL, so `devframes: ['@devframes/plugin-a11y']` works everywhere with no host
-wiring. The hub's client runtime (`createDevframeClientRuntime` from
-`@devframes/hub/client`) then imports it into the host page and calls its default
-export with the client-script context. A host that prefers to serve the module
-itself (e.g. via `/@fs/…` under Vite) can still attach `a11yPageScriptBundlePath` as
-a per-mount `clientScript`. Booted that way, the page script also
+path, so the hub serves it same-origin and `devframes: ['@devframes/plugin-a11y']`
+works with no host wiring. The hub's client runtime (`createDevframeClientRuntime`
+from `@devframes/hub/client`) then imports it into the host page and calls its default
+export with the client-script context. A host can also serve the module itself (e.g.
+via `/@fs/…` under Vite) by attaching `a11yPageScriptBundlePath` as a per-mount
+`clientScript`. Booted that way, the page script also
 mirrors the active route's scan into the hub's **messages feed** — a summary entry
 driven through the loading → idle lifecycle plus one entry per violated rule,
 carrying the impact-mapped level, WCAG tags as labels, and the first offending
@@ -121,7 +119,7 @@ pnpm -C plugins/a11y dev         # from source: same, at /__devframes_plugin_a11
 
 | Path | Export | Purpose |
 |------|--------|---------|
-| `src/index.ts` | `.` | `createA11yDevframe()` (also the default export), declaring the page script as its dock's client script by path; `a11yPageScriptBundlePath` — that page-script module, for hosts that serve it themselves |
+| `src/index.ts` | `.` | `createA11yDevframe()` (also the default export), declaring the page script as its dock's client script; `a11yPageScriptBundlePath` — that module, for hosts that serve it themselves |
 | `src/node/index.ts` | `/node` | `setupA11y(ctx, options?)` — registers the RPC functions with the runtime config |
 | `src/cli.ts` | `/cli` | `createA11yCli()` — backs the `devframes_plugin_a11y` bin |
 | `src/client/index.ts` | `/client` | `connectA11y()` — typed browser RPC client wrapper |

plugins/a11y/src/index.ts

@@ -23,11 +23,10 @@ const distDir: RemoteAssets = {
  * — the dock **client script** the client runtime imports into the host page to
  * scan it (its default export boots the page script; importing it does too).
  *
- * The definition already declares this path as its dock `clientScript`, so a
- * hub serves it same-origin and boots it with no host wiring. Exported for
- * hosts that mount the module themselves (e.g. via `/@fs/` under Vite).
- * Resolves under `<pkg>/dist/inject/inject.js` from both the source and the
- * published entry. Requires the built bundle (`pnpm -C plugins/a11y build`).
+ * The definition already declares this as its dock `clientScript`, so a hub
+ * serves it with no host wiring. Exported for hosts that mount the module
+ * themselves (e.g. via `/@fs/` under Vite). Requires the built bundle
+ * (`pnpm -C plugins/a11y build`).
  */
 export const a11yPageScriptBundlePath: string = fileURLToPath(new URL('../dist/inject/inject.js', import.meta.url))
 
@@ -91,8 +90,7 @@ export function createA11yDevframe(options: A11yDevframeOptions = {}): DevframeD
     description: pkg.description,
     icon: options.icon ?? 'ph:person-simple-circle-duotone',
     basePath: options.basePath ?? BASE_PATH,
-    // Declare the page script by path; the hub serves it same-origin and boots
-    // it with no per-host wiring.
+    // Declare the page script by path; the hub serves it with no host wiring.
     dock: {
       category: '~builtin',
       clientScript: { importFrom: a11yPageScriptBundlePath },