refactor(plugin-a11y): rename the injected script's internals off "agent"

The injected half is now the page script, talking to the panel over the
in-page channel, so "agent" stays reserved for coding agents. Internal
types, the wire message (a11y:page-script-ready), and UI copy follow;
the public export a11yAgentBundlePath keeps its name.

Author: antfubot

plugins/a11y/README.md

@@ -1,15 +1,15 @@
 # @devframes/plugin-a11y
 
 > [!WARNING] Experimental
-> This plugin is experimental and may change without a major version bump until
+> This devframe is experimental and may change without a major version bump until
 > it stabilizes.
 
 An accessibility inspector built on [devframe](../../packages/devframe). It runs
-[axe-core](https://github.com/dequelabs/axe-core) against a host application and
+[axe-core](https://github.com/dequelabs/axe-core) against a user app and
 surfaces the violations in a [Solid](https://www.solidjs.com/) panel:
 
 - **Route-aware tracking** — buckets violations by `location.pathname` and tracks
-  them as you navigate the app (History-API patched, framework-neutral), persisted
+  them as you navigate the user app (History-API patched, framework-neutral), persisted
   in `sessionStorage` so history survives reloads within a tab session.
 - **Dashboard + grouped violations** — a Dashboard tab (totals, severity
   breakdown, per-route inventory, scan controls) and a Violations tab listing
@@ -28,7 +28,7 @@ surfaces the violations in a [Solid](https://www.solidjs.com/) panel:
 - **Console logging** — newly-appeared violations are logged (deduped) to the
   browser console.
 
-The scan + highlight loop works the same whether the plugin runs as a live dev
+The scan + highlight loop works the same whether the devframe runs as a live dev
 server or as a baked static build.
 
 ## How it works
@@ -37,28 +37,28 @@ Three pieces, two of them browser-side:
 
 | Piece | Runs in | Role |
 |-------|---------|------|
-| **Agent** (`src/inject`) | the host app's page | runs axe-core, tracks routes, broadcasts the aggregate state, draws the preview + pinned rings |
+| **Page script** (`src/inject`) | the user app's page | runs axe-core, tracks routes, broadcasts the aggregate state, draws the preview + pinned rings |
 | **Panel** (`src/spa`) | the devtools iframe | Solid SPA: Dashboard + grouped violations, fires preview/pin/rescan |
-| **Node** (`src/index.ts`, `src/node`, `src/rpc`) | the devframe backend | `get-config` RPC (impact taxonomy + runtime config) — live in dev, baked in a static build |
+| **Node** (`src/index.ts`, `src/node`, `src/rpc`) | the node side | `get-config` RPC (impact taxonomy + runtime config) — live in dev, baked in a static build |
 
-The agent and panel talk over a same-origin
-[`BroadcastChannel`](src/shared/protocol.ts), not the devframe RPC backend. That
+The page script and panel talk over the in-page channel (a same-origin
+[`BroadcastChannel`](src/shared/protocol.ts)), not the devframe RPC backend. That
 is what keeps the live loop working in **both modes**: neither half needs a
 server to reach the other, only a shared browser origin (host page + panel
-iframe). The agent owns the authoritative route → report map and broadcasts the
+iframe). The page script owns the authoritative route → report map and broadcasts the
 whole aggregate on every change, so the panel stays a pure render of it. devframe
 RPC carries the data model on top — `get-config` is a `static` function, so it
 resolves over WebSocket in dev and from the baked dump in a static build; the
-panel forwards its runtime-config slice to the agent over the channel, keeping the
-agent itself free of any RPC dependency.
+panel forwards its runtime-config slice to the page script over the channel, keeping the
+page script itself free of any RPC dependency.
 
-devframe deliberately provides no access to the host application's DOM, so the
-agent is the author-provided bridge into the page being checked. In a hub, the
-agent is the a11y dock's **client script**: attach `a11yAgentBundlePath` as the
+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**: attach `a11yAgentBundlePath` as the
 dock's `clientScript` (resolved to an importable URL — `/@fs/…` under Vite, or a
 statically-served path) and the hub's client runtime (`createDevframeClientHost`
 from `@devframes/hub/client`) imports it into the host page and calls its
-default export with the client-script context. Booted that way, the agent also
+default export with the client-script context. 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
@@ -73,7 +73,7 @@ shows it (no hub context, so the feed mirror simply stays off).
 ## Configuration
 
 Pass options to `createA11yDevframe()` (surfaced through `get-config`, so they
-reach both the panel and the agent):
+reach both the panel and the page script):
 
 ```ts
 createA11yDevframe({
@@ -93,7 +93,7 @@ The demo serves an intentionally-broken host page and the panel from **one
 origin** so they share the channel.
 
 ```sh
-pnpm -C plugins/a11y build       # build the panel + the agent bundle
+pnpm -C plugins/a11y build       # build the panel + the page-script bundle
 pnpm -C plugins/a11y demo        # dev: live WebSocket RPC → http://localhost:4477/
 
 pnpm -C plugins/a11y cli:build   # bake the static deploy (dist/static)
@@ -104,7 +104,7 @@ Open the URL, then hover any row in the panel — the matching element in the pa
 gets a focus ring (and scrolls into view if it's off-screen). Both demo modes
 behave identically; the panel's `websocket` / `static` tag is the only tell.
 
-Standalone, without a host app:
+Standalone, without a user app:
 
 ```sh
 pnpx @devframes/plugin-a11y      # the published package, panel only, at /__devframes_plugin_a11y/
@@ -115,13 +115,13 @@ pnpm -C plugins/a11y dev         # from source: same, at /__devframes_plugin_a11
 
 | Path | Export | Purpose |
 |------|--------|---------|
-| `src/index.ts` | `.` | `createA11yDevframe()` (also the default export); `a11yAgentBundlePath` — the agent module a hub attaches as this dock's client script |
+| `src/index.ts` | `.` | `createA11yDevframe()` (also the default export); `a11yAgentBundlePath` — the page-script module a hub attaches as this dock's client script |
 | `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 |
 | `src/rpc/` | — | `get-config` static RPC + the type-safe client registry |
-| `src/shared/protocol.ts` | — | the agent ↔ panel `BroadcastChannel` contract |
-| `src/inject/` | — | the host-page agent (axe scan, highlight overlay, hub messages mirror) → `dist/inject/inject.js` |
+| `src/shared/protocol.ts` | — | the page script ↔ panel in-page channel (`BroadcastChannel`) contract |
+| `src/inject/` | — | the page script (axe scan, highlight overlay, hub messages mirror) → `dist/inject/inject.js` |
 | `src/spa/` | — | the Solid panel SPA → `assets-pkg/dist` (ships in `@devframes/plugin-a11y--assets`) |
 | `demo/` | — | same-origin host page + server (dev + static modes) |
 | `tests/` | — | dev-server RPC + static-build dump |

plugins/a11y/demo/index.html

@@ -160,7 +160,7 @@ <h2>This week's roasts</h2>
       <iframe class="df-dock__frame" title="A11y Inspector panel" src="/__devframes_plugin_a11y/"></iframe>
     </aside>
 
-    <!-- The injected a11y agent: scans this page and answers the panel. -->
+    <!-- The a11y page script: scans this page and answers the panel. -->
     <script type="module" src="/__df-inject/inject.js"></script>
   </body>
 </html>

plugins/a11y/demo/server.mjs

@@ -2,11 +2,11 @@
 /**
  * Same-origin demo host for the a11y inspector.
  *
- * Serves three things off one origin so the injected agent (host page) and the
+ * Serves three things off one origin so the page script (host page) and the
  * panel (devtools iframe) share a BroadcastChannel:
  *
  *   GET  /                              → the demo page (intentional a11y bugs)
- *   GET  /__df-inject/inject.js         → the injected agent bundle
+ *   GET  /__df-inject/inject.js         → the page script bundle
  *   GET  /__devframes_plugin_a11y/**  → the Solid panel SPA
  *
  * Two modes prove the plugin works either way:
@@ -76,7 +76,7 @@ async function main() {
     return demoHtml
   })
 
-  // 2. The injected agent bundle.
+  // 2. The page script bundle.
   mountStaticHandler(app, '/__df-inject/', injectDir)
 
   if (mode === 'dev') {

plugins/a11y/package.json

@@ -2,7 +2,7 @@
   "name": "@devframes/plugin-a11y",
   "type": "module",
   "version": "0.9.5",
-  "description": "Devframe plugin that audits the host app with axe and highlights accessibility issues in the page.",
+  "description": "Built-in devframe that audits the user app with axe and highlights accessibility issues in the page.",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
   "homepage": "https://github.com/devframes/devframe#readme",

plugins/a11y/src/index.ts

@@ -12,16 +12,16 @@ const BASE_PATH = '/__devframes_plugin_a11y/'
 // package, served on demand through devframe's remote-assets back-proxy. The
 // definition's `importMetaUrl` (below) supplies the default `resolveFrom`, so a
 // locally installed copy (a workspace link here) is served with zero network.
-// The host-page agent bundle (`dist/inject`, below) stays here.
+// The page-script bundle (`dist/inject`, below) stays here.
 const distDir: RemoteAssets = {
   package: `${pkg.name}--assets`,
   version: pkg.version,
 }
 
 /**
- * Absolute path to the built in-page **agent** module (`dist/inject/inject.js`)
- * — the dock **client script** the hub runtime imports into the host page to
- * scan it (its default export boots the agent; importing it does too).
+ * Absolute path to the built **page script** module (`dist/inject/inject.js`)
+ * — 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).
  *
  * A hub attaches this as the a11y dock's `clientScript`, resolved to a URL the
  * page can import: `/@fs/${a11yAgentBundlePath}` for a Vite host, or a
@@ -69,8 +69,8 @@ export interface A11yDevframeOptions {
 /**
  * Build a {@link DevframeDefinition} for the a11y inspector. The same
  * definition runs standalone (`/cli`, `/build`) and mounts into a host
- * (`/vite`, hub). The panel talks to the in-page agent over a same-origin
- * BroadcastChannel, so the scan/highlight loop works identically in dev
+ * (`/vite`, hub). The panel talks to the page script over the in-page channel
+ * (a same-origin BroadcastChannel), so the scan/highlight loop works identically in dev
  * (live WebSocket RPC) and in a baked static build.
  *
  * @experimental This plugin is experimental and may change without a major

plugins/a11y/src/inject/index.ts

@@ -1,5 +1,5 @@
 /**
- * The a11y inspector **agent** — injected into the host application's page.
+ * The a11y inspector **page script** — injected into the user app's page.
  *
  * It runs axe-core against the live DOM, tracks violations per route, broadcasts
  * the whole {@link A11yState} aggregate to the panel, and draws transient +
@@ -16,11 +16,11 @@
 import type {
   A11yMessage,
   A11yState,
-  AgentConfig,
+  PageScriptConfig,
   PinTarget,
   ScanReport,
 } from '../shared/protocol.ts'
-import type { A11yAgentContext } from './messages.ts'
+import type { A11yPageScriptContext } from './messages.ts'
 import type { PinInfo } from './overlay.ts'
 import {
   A11Y_CHANNEL,
@@ -34,7 +34,7 @@ import { resolveElement, scan } from './scanner.ts'
 
 const GLOBAL_FLAG = '__DF_A11Y_AGENT__'
 
-function start(context?: A11yAgentContext) {
+function start(context?: A11yPageScriptContext) {
   const w = window as unknown as Record<string, unknown>
   if (w[GLOBAL_FLAG])
     return
@@ -46,7 +46,7 @@ function start(context?: A11yAgentContext) {
 
   // Booted as a hub dock client script — mirror the active route's scan into
   // the hub's messages feed. Standalone boots have no context and skip it.
-  const config: AgentConfig = { logIssues: true, autoScan: true }
+  const config: PageScriptConfig = { logIssues: true, autoScan: true }
 
   const reporter = context?.messages
     ? createMessagesReporter(context.messages, {
@@ -251,7 +251,7 @@ function start(context?: A11yAgentContext) {
     const message = event.data
     switch (message.type) {
       case 'a11y:panel-ready':
-        post({ type: 'a11y:agent-ready', url: location.href, route: activeRoute })
+        post({ type: 'a11y:page-script-ready', url: location.href, route: activeRoute })
         if (routes.size > 0)
           broadcastState()
         else
@@ -312,7 +312,7 @@ function start(context?: A11yAgentContext) {
     }
   })
 
-  function applyConfig(next: AgentConfig) {
+  function applyConfig(next: PageScriptConfig) {
     config.logIssues = next.logIssues
     config.axeTags = next.axeTags
     config.axeRunOptions = next.axeRunOptions
@@ -327,7 +327,7 @@ function start(context?: A11yAgentContext) {
   bindInteractions()
 
   // Announce ourselves and run the first scan once the page has settled.
-  post({ type: 'a11y:agent-ready', url: location.href, route: activeRoute })
+  post({ type: 'a11y:page-script-ready', url: location.href, route: activeRoute })
   if (routes.size > 0)
     broadcastState()
   if (document.readyState === 'complete')
@@ -347,16 +347,16 @@ function findRule(report: ScanReport | null, nodeId: string) {
  * Client-script entry the hub runtime calls after importing this module,
  * passing its `DockClientScriptContext`. The live scan/highlight loop rides
  * the same-origin BroadcastChannel either way; when the context carries a
- * `messages` client (duck-typed — see {@link A11yAgentContext}), the agent
+ * `messages` client (duck-typed — see {@link A11yPageScriptContext}), the page script
  * additionally mirrors each scan into the hub's messages feed. `start()` is
  * idempotent.
  */
-export default function runA11yAgent(context?: A11yAgentContext): void {
+export default function runA11yPageScript(context?: A11yPageScriptContext): void {
   start(context)
 }
 
 // Also self-boot so a plain `<script type="module" src=".../inject.js">`
-// (the standalone demo, any non-hub host) starts the agent on load — deferred
+// (the standalone demo, any non-hub host page) starts the page script on load — deferred
 // one macrotask so a hub host that imports this module calls the default
 // export (microtask-chained after the import) first, letting the context-ful
 // boot win the `__DF_A11Y_AGENT__` guard.

plugins/a11y/src/inject/messages.ts

@@ -1,10 +1,10 @@
 /**
- * Mirrors scan results into the hub's messages feed when the agent is booted
- * as a dock **client script** (`createDevframeClientHost()` calls the agent's
+ * Mirrors scan results into the hub's messages feed when the page script is booted
+ * as a dock **client script** (`createDevframeClientHost()` calls the page script's
  * default export with its `DockClientScriptContext`).
  *
  * The hub context is consumed by duck-typing a minimal structural slice, so
- * the agent keeps no build- or runtime dependency on `@devframes/hub` and the
+ * the page script keeps no build- or runtime dependency on `@devframes/hub` and the
  * bundle stays self-contained — a standalone `<script type="module">` boot
  * simply has no messages client and skips the feed. Mirrors the pattern used
  * by the terminals and code-server plugins for `ctx.terminals`.
@@ -13,7 +13,7 @@ import type { Impact, ScanReport } from '../shared/protocol.ts'
 import { A11Y_DEFAULT_DOCK_ID } from '../shared/protocol.ts'
 
 /**
- * Structural slice of the hub's `DevframeMessageAction` the agent emits — a
+ * Structural slice of the hub's `DevframeMessageAction` the page script emits — a
  * labeled control that, when clicked in the messages panel, activates a dock
  * (deep-linking via `params`). Kept as a discriminated union so future action
  * kinds can be added without reshaping the field.
@@ -25,7 +25,7 @@ interface HubMessageAction {
   activate: { dockId: string, params?: Record<string, unknown> }
 }
 
-/** Structural slice of the hub's `DevframeMessageEntryInput` the agent emits. */
+/** Structural slice of the hub's `DevframeMessageEntryInput` the page script emits. */
 export interface HubMessageInput {
   id?: string
   message: string
@@ -47,17 +47,17 @@ export interface HubMessageInput {
   status?: 'loading' | 'idle'
 }
 
-/** Structural slice of the hub's `DevframeMessagesClient` the agent calls. */
+/** Structural slice of the hub's `DevframeMessagesClient` the page script calls. */
 export interface HubMessagesClient {
   add: (input: HubMessageInput) => Promise<unknown>
   remove: (id: string) => Promise<void>
 }
 
 /**
- * Structural slice of the hub's `DockClientScriptContext` the agent accepts.
- * Every field is optional so any argument — or none — boots the agent.
+ * Structural slice of the hub's `DockClientScriptContext` the page script accepts.
+ * Every field is optional so any argument — or none — boots the page script.
  */
-export interface A11yAgentContext {
+export interface A11yPageScriptContext {
   messages?: HubMessagesClient
 }
 
@@ -87,7 +87,7 @@ export interface MessagesReporter {
 export interface MessagesReporterOptions {
   /**
    * Resolve the current bounding box of a violating element from its axe
-   * target selectors — the agent supplies a live-DOM implementation. A stale
+   * target selectors — the page script supplies a live-DOM implementation. A stale
    * box is fine: each re-scan refreshes the entry.
    */
   resolveBoundingBox?: (target: string[]) => { x: number, y: number, width: number, height: number } | undefined

plugins/a11y/src/inject/vite.config.ts

@@ -1,7 +1,7 @@
 import { fileURLToPath } from 'node:url'
 import { defineConfig } from 'vite'
 
-// Builds the host-page agent into a single self-contained ES module
+// Builds the page script into a single self-contained ES module
 // (`dist/inject/inject.js`) with axe-core bundled in. Loaded by the host app
 // via `<script type="module" src=".../inject.js">`, so it must not rely on a
 // chunk graph or an import map.

plugins/a11y/src/rpc/functions/get-config.ts

@@ -1,4 +1,4 @@
-import type { AgentConfig } from '../../shared/protocol.ts'
+import type { PageScriptConfig } from '../../shared/protocol.ts'
 import { defineRpcFunction } from 'devframe'
 import { A11Y_CHANNEL, A11Y_DEFAULT_DOCK_ID, A11Y_NODE_ATTR, IMPACT_ORDER } from '../../shared/protocol.ts'
 
@@ -44,12 +44,12 @@ export interface A11yRuntimeConfig {
  * Build the `get-config` RPC function from author options. Declared `static`,
  * so the value resolves live over WebSocket in dev and is baked into the RPC
  * dump for static builds — the panel's legend + runtime config render the same
- * in both modes. The panel forwards the `agent` slice to the in-page agent over
- * the BroadcastChannel, keeping the agent free of any RPC dependency.
+ * in both modes. The panel forwards the `pageScript` slice to the page script over
+ * the BroadcastChannel, keeping the page script free of any RPC dependency.
  */
 export function createGetConfig(options: A11yRuntimeConfig = {}) {
   const dockId = options.dockId ?? A11Y_DEFAULT_DOCK_ID
-  const agent: AgentConfig = {
+  const pageScript: PageScriptConfig = {
     logIssues: options.logIssues ?? true,
     autoScan: options.autoScan ?? true,
     axeTags: options.axe?.tags,
@@ -66,7 +66,7 @@ export function createGetConfig(options: A11yRuntimeConfig = {}) {
       docsBase: 'https://dequeuniversity.com/rules/axe/',
       dockId,
       defaultHighlight: options.defaultHighlight ?? false,
-      agent,
+      pageScript,
       impacts: IMPACT_ORDER.map(id => ({ id, ...IMPACT_COPY[id] })),
     }),
   })