From 634b1e7125b144410efcad192fcd68b3542620f8 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Thu, 2 Jul 2026 09:03:43 +0000
Subject: [PATCH 1/5] =?UTF-8?q?feat(hub):=20client-context=20parity=20?=
 =?UTF-8?q?=E2=80=94=20iframe=20skip=20guard,=20entry-scoped=20messages,?=
 =?UTF-8?q?=20level=20shortcuts?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../hub/src/client/__tests__/host.test.ts     | 79 +++++++++++++++++--
 .../hub/src/client/__tests__/messages.test.ts | 45 +++++++++++
 packages/hub/src/client/client-script.ts      |  3 +-
 packages/hub/src/client/context.ts            |  8 +-
 packages/hub/src/client/host.ts               | 51 +++++++++++-
 packages/hub/src/client/messages.ts           | 33 ++++++--
 .../src/node/__tests__/host-messages.test.ts  | 16 ++++
 packages/hub/src/node/host-messages.ts        | 21 +++++
 packages/hub/src/types/messages.ts            | 28 ++++++-
 .../@devframes/hub/client.snapshot.d.ts       | 17 +++-
 .../tsnapi/@devframes/hub/client.snapshot.js  |  2 +-
 .../tsnapi/@devframes/hub/index.snapshot.d.ts |  2 +
 .../tsnapi/@devframes/hub/node.snapshot.d.ts  |  5 ++
 .../tsnapi/@devframes/hub/node.snapshot.js    |  5 ++
 .../tsnapi/@devframes/hub/types.snapshot.d.ts |  2 +
 15 files changed, 291 insertions(+), 26 deletions(-)
 create mode 100644 packages/hub/src/client/__tests__/messages.test.ts

diff --git a/packages/hub/src/client/__tests__/host.test.ts b/packages/hub/src/client/__tests__/host.test.ts
index ed92708..8ee790d 100644
--- a/packages/hub/src/client/__tests__/host.test.ts
+++ b/packages/hub/src/client/__tests__/host.test.ts
@@ -1,11 +1,20 @@
 import type { DevframeRpcClient } from 'devframe/client'
 import type { SharedState } from 'devframe/utils/shared-state'
 import type { DevframeDockEntry } from '../../types/docks'
+import type { DevframeClientHost, DevframeClientHostOptions } from '../host'
 import { createEventEmitter } from 'devframe/utils/events'
 import { describe, expect, it, vi } from 'vitest'
 import { getDevframeClientContext } from '../context'
 import { createDevframeClientHost } from '../host'
 
+/** Boot a host that is expected to actually boot (narrow away the skipped arm). */
+async function boot(options: DevframeClientHostOptions): Promise<DevframeClientHost> {
+  const host = await createDevframeClientHost(options)
+  if (host.skipped)
+    throw new Error('expected the client host to boot, but it skipped')
+  return host
+}
+
 interface StubSharedState<T> extends SharedState<T> {
   /** Replace the state wholesale and emit `updated` (simulates a server patch). */
   push: (next: T) => void
@@ -43,6 +52,8 @@ function createStubRpc() {
     },
     call: async (...args: any[]) => {
       calls.push(args)
+      if (args[0] === 'hub:messages:add')
+        return { id: 'msg-1', timestamp: 1, from: 'browser', ...args[1] }
       return `rpc:${args[0]}`
     },
   } as unknown as DevframeRpcClient
@@ -56,7 +67,7 @@ function iframeEntry(id: string, extra?: Record<string, unknown>): DevframeDockE
 describe('createDevframeClientHost', () => {
   it('publishes the global client context with the full surface', async () => {
     const { rpc } = createStubRpc()
-    const host = await createDevframeClientHost({ rpc })
+    const host = await boot({ rpc })
 
     expect(getDevframeClientContext()).toBe(host.context)
     expect(host.context.clientType).toBe('standalone')
@@ -73,7 +84,7 @@ describe('createDevframeClientHost', () => {
 
   it('reconciles dock entries from shared state and tracks per-entry state', async () => {
     const { rpc, states } = createStubRpc()
-    const host = await createDevframeClientHost({ rpc })
+    const host = await boot({ rpc })
     const docksState = states.get('devframe:docks')!
 
     docksState.push([iframeEntry('one'), iframeEntry('two')])
@@ -88,7 +99,7 @@ describe('createDevframeClientHost', () => {
 
   it('switches entries with activation/deactivation events and when-context updates', async () => {
     const { rpc, states } = createStubRpc()
-    const host = await createDevframeClientHost({ rpc })
+    const host = await boot({ rpc })
     states.get('devframe:docks')!.push([iframeEntry('one'), iframeEntry('two')])
 
     const activated: string[] = []
@@ -115,7 +126,7 @@ describe('createDevframeClientHost', () => {
 
   it('executes client commands locally and server commands over hub:commands:execute', async () => {
     const { rpc, calls } = createStubRpc()
-    const host = await createDevframeClientHost({ rpc })
+    const host = await boot({ rpc })
 
     const ran: any[] = []
     const off = host.context.commands.register({
@@ -139,8 +150,8 @@ describe('createDevframeClientHost', () => {
   })
 
   it('imports a dock entry client script and hands it the script context', async () => {
-    const { rpc, states } = createStubRpc()
-    const host = await createDevframeClientHost({ rpc })
+    const { rpc, states, calls } = createStubRpc()
+    const host = await boot({ rpc })
 
     const received: any[] = []
     ;(globalThis as any).__DF_TEST_SCRIPT__ = (ctx: any) => received.push(ctx)
@@ -153,8 +164,62 @@ describe('createDevframeClientHost', () => {
     const scriptCtx = received[0]
     expect(scriptCtx.current.entryMeta.id).toBe('scripted')
     expect(scriptCtx.rpc).toBe(rpc)
-    expect(typeof scriptCtx.messages.add).toBe('function')
+
+    // The messages client is scoped to the entry: `category` defaults to the
+    // entry id, and the doc'd per-level shortcuts delegate to add().
+    await scriptCtx.messages.add({ message: 'hello', level: 'info' })
+    expect(calls.at(-1)).toEqual(['hub:messages:add', { message: 'hello', level: 'info', category: 'scripted' }])
+    await scriptCtx.messages.warn('careful', { category: 'a11y' })
+    expect(calls.at(-1)).toEqual(['hub:messages:add', { message: 'careful', level: 'warn', category: 'a11y' }])
+
     delete (globalThis as any).__DF_TEST_SCRIPT__
     host.dispose()
   })
+
+  it('skips boot inside an iframe for embedded hosts, overridable via skipInIframe', async () => {
+    vi.stubGlobal('window', { self: {}, top: {} })
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      const { rpc } = createStubRpc()
+      const skipped = await createDevframeClientHost({ rpc, clientType: 'embedded' })
+      expect(skipped.skipped).toBe(true)
+      expect(skipped.context).toBeUndefined()
+      expect(getDevframeClientContext()).toBeUndefined()
+      skipped.dispose()
+
+      // Standalone hosts (and an explicit opt-out) still boot inside iframes.
+      const standalone = await createDevframeClientHost({ rpc })
+      expect(standalone.skipped).toBe(false)
+      standalone.dispose()
+      const optOut = await createDevframeClientHost({ rpc, clientType: 'embedded', skipInIframe: false })
+      expect(optOut.skipped).toBe(false)
+      optOut.dispose()
+    }
+    finally {
+      vi.unstubAllGlobals()
+      warn.mockRestore()
+    }
+  })
+
+  it('warns when a second host replaces a published context; dispose unpublishes it', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      const { rpc } = createStubRpc()
+      const first = await boot({ rpc })
+      expect(warn).not.toHaveBeenCalled()
+
+      const second = await boot({ rpc })
+      expect(warn).toHaveBeenCalledOnce()
+      expect(getDevframeClientContext()).toBe(second.context)
+
+      // The first host no longer owns the published context — leave it alone.
+      first.dispose()
+      expect(getDevframeClientContext()).toBe(second.context)
+      second.dispose()
+      expect(getDevframeClientContext()).toBeUndefined()
+    }
+    finally {
+      warn.mockRestore()
+    }
+  })
 })
diff --git a/packages/hub/src/client/__tests__/messages.test.ts b/packages/hub/src/client/__tests__/messages.test.ts
new file mode 100644
index 0000000..3a3a2d9
--- /dev/null
+++ b/packages/hub/src/client/__tests__/messages.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest'
+import { createMessagesClient } from '../messages'
+
+function createStubRpc() {
+  const calls: any[][] = []
+  const rpc = {
+    call: async (...args: any[]) => {
+      calls.push(args)
+      if (args[0] === 'hub:messages:add')
+        return { id: 'msg-1', timestamp: 1, from: 'browser', ...args[1] }
+      if (args[0] === 'hub:messages:update')
+        return { id: args[1], timestamp: 1, from: 'browser', ...args[2] }
+      return undefined
+    },
+  } as any
+  return { rpc, calls }
+}
+
+describe('createMessagesClient', () => {
+  it('merges defaults beneath the input; explicit input fields win', async () => {
+    const { rpc, calls } = createStubRpc()
+    const messages = createMessagesClient(rpc, { defaults: { category: 'my-entry' } })
+
+    await messages.add({ message: 'hello', level: 'info' })
+    expect(calls.at(-1)).toEqual(['hub:messages:add', { message: 'hello', level: 'info', category: 'my-entry' }])
+
+    await messages.add({ message: 'custom', level: 'info', category: 'a11y' })
+    expect(calls.at(-1)?.[1].category).toBe('a11y')
+  })
+
+  it('provides per-level shortcuts that delegate to add()', async () => {
+    const { rpc, calls } = createStubRpc()
+    const messages = createMessagesClient(rpc)
+
+    const handle = await messages.info('hi')
+    expect(calls.at(-1)).toEqual(['hub:messages:add', { message: 'hi', level: 'info' }])
+    expect(handle.id).toBe('msg-1')
+
+    await messages.error('boom', { notify: true })
+    expect(calls.at(-1)).toEqual(['hub:messages:add', { message: 'boom', level: 'error', notify: true }])
+
+    await handle.dismiss()
+    expect(calls.at(-1)).toEqual(['hub:messages:remove', 'msg-1'])
+  })
+})
diff --git a/packages/hub/src/client/client-script.ts b/packages/hub/src/client/client-script.ts
index 86d2f8f..fee5958 100644
--- a/packages/hub/src/client/client-script.ts
+++ b/packages/hub/src/client/client-script.ts
@@ -10,7 +10,8 @@ export interface DockClientScriptContext extends DocksContext {
    */
   current: DockEntryState
   /**
-   * Messages client scoped to this dock entry's source
+   * Messages client scoped to this dock entry — messages it adds default
+   * their `category` to the entry id, so the feed can attribute them.
    */
   messages: DevframeMessagesClient
 }
diff --git a/packages/hub/src/client/context.ts b/packages/hub/src/client/context.ts
index d97cd94..e7ba0a3 100644
--- a/packages/hub/src/client/context.ts
+++ b/packages/hub/src/client/context.ts
@@ -10,11 +10,11 @@ export function getDevframeClientContext(): DevframeClientContext | undefined {
 }
 
 /**
- * Publish the global Devframe client context. Called by
- * {@link import('./host').createDevframeClientHost}; a dock client script or a
- * viewer reads it back with {@link getDevframeClientContext}.
+ * Publish the global Devframe client context (or clear it with `undefined`).
+ * Called by {@link import('./host').createDevframeClientHost}; a dock client
+ * script or a viewer reads it back with {@link getDevframeClientContext}.
  */
-export function setDevframeClientContext(ctx: DevframeClientContext): void {
+export function setDevframeClientContext(ctx: DevframeClientContext | undefined): void {
   (globalThis as any)[CLIENT_CONTEXT_KEY] = ctx
 }
 
diff --git a/packages/hub/src/client/host.ts b/packages/hub/src/client/host.ts
index a37c8e8..e785567 100644
--- a/packages/hub/src/client/host.ts
+++ b/packages/hub/src/client/host.ts
@@ -25,7 +25,7 @@ import type {
 import { connectDevframe } from 'devframe/client'
 import { createEventEmitter } from 'devframe/utils/events'
 import { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS } from '../constants'
-import { setDevframeClientContext } from './context'
+import { getDevframeClientContext, setDevframeClientContext } from './context'
 import { createMessagesClient } from './messages'
 
 const DOCKS_STATE_KEY = 'devframe:docks'
@@ -52,15 +52,34 @@ export interface DevframeClientHostOptions {
    * `custom-render`, and iframe `clientScript`). Default `true`.
    */
   loadClientScripts?: boolean
+  /**
+   * Skip booting when the page runs inside an iframe, so a nested frame never
+   * publishes a second context or re-runs every dock client script. Defaults
+   * to `true` for `'embedded'` hosts (dock iframe panels and nested copies of
+   * the app skip themselves) and `false` for `'standalone'` hosts (a hub UI
+   * page stays bootable when intentionally iframed).
+   */
+  skipInIframe?: boolean
 }
 
 export interface DevframeClientHost {
+  /** The host booted and published its context. */
+  skipped: false
   /** The assembled, globally-registered client host context. */
   context: DevframeClientContext
   /** Tear down listeners and stop tracking newly-registered client scripts. */
   dispose: () => void
 }
 
+export interface DevframeClientHostSkipped {
+  /** Boot was skipped — the page runs inside an iframe (see `skipInIframe`). */
+  skipped: true
+  context: undefined
+  dispose: () => void
+}
+
+export type DevframeClientHostResult = DevframeClientHost | DevframeClientHostSkipped
+
 /**
  * Boot the framework-level client host: connect RPC, assemble the full
  * {@link DevframeClientContext} (panel, docks, commands, when) from the hub's
@@ -73,8 +92,13 @@ export interface DevframeClientHost {
  */
 export async function createDevframeClientHost(
   options: DevframeClientHostOptions = {},
-): Promise<DevframeClientHost> {
+): Promise<DevframeClientHostResult> {
   const clientType: DockClientType = options.clientType ?? 'standalone'
+  if ((options.skipInIframe ?? clientType === 'embedded') && isInsideIframe()) {
+    console.warn('[@devframes/hub] Skipping client host in iframe')
+    return { skipped: true, context: undefined, dispose: () => {} }
+  }
+
   const rpc = options.rpc ?? await connectDevframe(options.connect)
 
   const [docksState, commandsState, settings] = await Promise.all([
@@ -115,9 +139,14 @@ export async function createDevframeClientHost(
   reconcileEntries()
   disposers.push(docksState.on('updated', reconcileEntries))
 
+  if (getDevframeClientContext()) {
+    console.warn(
+      '[@devframes/hub] A client host context is already published on this page — replacing it. '
+      + 'Boot createDevframeClientHost() once per page (e.g. HTML injection combined with a manual import boots it twice).',
+    )
+  }
   setDevframeClientContext(context)
 
-  const messages = createMessagesClient(rpc)
   const loadedScripts = new Set<string>()
   if (options.loadClientScripts ?? true) {
     loadClientScripts()
@@ -125,9 +154,12 @@ export async function createDevframeClientHost(
   }
 
   return {
+    skipped: false,
     context,
     dispose() {
       for (const off of disposers.splice(0)) off()
+      if (getDevframeClientContext() === context)
+        setDevframeClientContext(undefined)
     },
   }
 
@@ -277,6 +309,9 @@ export async function createDevframeClientHost(
       const current = entryToStateMap.get(entryId)
       if (!current)
         return
+      // Scope the messages client to this entry: its messages default their
+      // `category` to the entry id, so the feed can attribute and group them.
+      const messages = createMessagesClient(rpc, { defaults: { category: entryId } })
       const scriptContext: DockClientScriptContext = { ...context, current, messages }
       await fn(scriptContext)
     }
@@ -289,6 +324,16 @@ export async function createDevframeClientHost(
 
 // ── shared helpers ─────────────────────────────────────────────────────────
 
+function isInsideIframe(): boolean {
+  try {
+    return typeof window !== 'undefined' && window.self !== window.top
+  }
+  catch {
+    // Cross-origin access threw — we are definitely inside a foreign frame.
+    return true
+  }
+}
+
 function createPanelContext(clientType: DockClientType): DocksPanelContext {
   const store: DocksPanelContext['store'] = {
     mode: 'edge',
diff --git a/packages/hub/src/client/messages.ts b/packages/hub/src/client/messages.ts
index e84220e..da20601 100644
--- a/packages/hub/src/client/messages.ts
+++ b/packages/hub/src/client/messages.ts
@@ -3,16 +3,27 @@ import type {
   DevframeMessageEntry,
   DevframeMessageEntryInput,
   DevframeMessageHandle,
+  DevframeMessageLevel,
   DevframeMessagesClient,
+  DevframeMessageShortcutInput,
 } from '../types/messages'
 
+export interface MessagesClientOptions {
+  /**
+   * Default fields merged beneath every `add()` input — the client host passes
+   * `{ category: entry.id }` to scope a dock client script's messages to its
+   * entry. Fields set on the input itself win.
+   */
+  defaults?: Partial<DevframeMessageEntryInput>
+}
+
 /**
  * Build a browser-side {@link DevframeMessagesClient} that writes into the
  * hub's messages subsystem over the `hub:messages:*` built-in RPCs. The handle
  * returned by `add` proxies `update`/`dismiss` back through the same RPCs, so a
  * dock client script reports into the very feed the server writes to.
  */
-export function createMessagesClient(rpc: DevframeRpcClient): DevframeMessagesClient {
+export function createMessagesClient(rpc: DevframeRpcClient, options: MessagesClientOptions = {}): DevframeMessagesClient {
   // The `hub:messages:*` ids aren't in the statically-typed server map.
   const call = rpc.call as (name: string, ...args: any[]) => Promise<any>
 
@@ -35,12 +46,24 @@ export function createMessagesClient(rpc: DevframeRpcClient): DevframeMessagesCl
     }
   }
 
+  async function add(input: DevframeMessageEntryInput): Promise<DevframeMessageHandle> {
+    const entry = await call('hub:messages:add', { ...options.defaults, ...input }) as DevframeMessageEntry
+    return makeHandle(entry)
+  }
+
+  function levelShortcut(level: DevframeMessageLevel) {
+    return (message: string, extra?: DevframeMessageShortcutInput) =>
+      add({ ...extra, message, level })
+  }
+
   return {
-    async add(input: DevframeMessageEntryInput) {
-      const entry = await call('hub:messages:add', input) as DevframeMessageEntry
-      return makeHandle(entry)
-    },
+    add,
     remove: id => call('hub:messages:remove', id) as Promise<void>,
     clear: () => call('hub:messages:clear') as Promise<void>,
+    info: levelShortcut('info'),
+    warn: levelShortcut('warn'),
+    error: levelShortcut('error'),
+    success: levelShortcut('success'),
+    debug: levelShortcut('debug'),
   }
 }
diff --git a/packages/hub/src/node/__tests__/host-messages.test.ts b/packages/hub/src/node/__tests__/host-messages.test.ts
index 903de4b..a40ff45 100644
--- a/packages/hub/src/node/__tests__/host-messages.test.ts
+++ b/packages/hub/src/node/__tests__/host-messages.test.ts
@@ -20,4 +20,20 @@ describe('devframeMessagesHost', () => {
     expect(host.removals[0].id).toBe('message:5')
     expect(host.removals.at(-1)?.id).toBe('message:1004')
   })
+
+  it('provides per-level shortcuts that delegate to add()', async () => {
+    const host = new DevframeMessagesHost({} as DevframeHubContext)
+
+    const handle = await host.info('booted', { category: 'lifecycle' })
+    expect(handle.entry).toMatchObject({
+      message: 'booted',
+      level: 'info',
+      category: 'lifecycle',
+      from: 'server',
+    })
+
+    await host.error('boom')
+    const levels = [...host.entries.values()].map(e => e.level)
+    expect(levels).toEqual(['info', 'error'])
+  })
 })
diff --git a/packages/hub/src/node/host-messages.ts b/packages/hub/src/node/host-messages.ts
index 592db29..c8334a7 100644
--- a/packages/hub/src/node/host-messages.ts
+++ b/packages/hub/src/node/host-messages.ts
@@ -2,6 +2,7 @@ import type {
   DevframeMessageEntry,
   DevframeMessageEntryInput,
   DevframeMessageHandle,
+  DevframeMessageShortcutInput,
   DevframeMessagesHost as DevframeMessagesHostType,
 } from '../types/messages'
 import type { DevframeHubContext } from './context'
@@ -120,6 +121,26 @@ export class DevframeMessagesHost implements DevframeMessagesHostType {
     this.events.emit('message:removed', id)
   }
 
+  info(message: string, extra?: DevframeMessageShortcutInput): Promise<DevframeMessageHandle> {
+    return this.add({ ...extra, message, level: 'info' })
+  }
+
+  warn(message: string, extra?: DevframeMessageShortcutInput): Promise<DevframeMessageHandle> {
+    return this.add({ ...extra, message, level: 'warn' })
+  }
+
+  error(message: string, extra?: DevframeMessageShortcutInput): Promise<DevframeMessageHandle> {
+    return this.add({ ...extra, message, level: 'error' })
+  }
+
+  success(message: string, extra?: DevframeMessageShortcutInput): Promise<DevframeMessageHandle> {
+    return this.add({ ...extra, message, level: 'success' })
+  }
+
+  debug(message: string, extra?: DevframeMessageShortcutInput): Promise<DevframeMessageHandle> {
+    return this.add({ ...extra, message, level: 'debug' })
+  }
+
   async clear(): Promise<void> {
     for (const timer of this._autoDeleteTimers.values())
       clearTimeout(timer)
diff --git a/packages/hub/src/types/messages.ts b/packages/hub/src/types/messages.ts
index 43ba3c9..a0c1cf9 100644
--- a/packages/hub/src/types/messages.ts
+++ b/packages/hub/src/types/messages.ts
@@ -105,7 +105,31 @@ export interface DevframeMessageHandle {
   dismiss: () => Promise<void>
 }
 
-export interface DevframeMessagesClient {
+/**
+ * Extra fields accepted by the per-level message shortcuts —
+ * everything on {@link DevframeMessageEntryInput} except the
+ * `message` and `level` the shortcut itself provides.
+ */
+export type DevframeMessageShortcutInput = Omit<DevframeMessageEntryInput, 'message' | 'level'>
+
+/**
+ * Per-level shortcuts shared by the client and the node host —
+ * `messages.info('...')` is `messages.add({ message: '...', level: 'info' })`.
+ */
+export interface DevframeMessagesLevelShortcuts {
+  /** Shortcut for `add({ message, level: 'info', ...extra })` */
+  info: (message: string, extra?: DevframeMessageShortcutInput) => Promise<DevframeMessageHandle>
+  /** Shortcut for `add({ message, level: 'warn', ...extra })` */
+  warn: (message: string, extra?: DevframeMessageShortcutInput) => Promise<DevframeMessageHandle>
+  /** Shortcut for `add({ message, level: 'error', ...extra })` */
+  error: (message: string, extra?: DevframeMessageShortcutInput) => Promise<DevframeMessageHandle>
+  /** Shortcut for `add({ message, level: 'success', ...extra })` */
+  success: (message: string, extra?: DevframeMessageShortcutInput) => Promise<DevframeMessageHandle>
+  /** Shortcut for `add({ message, level: 'debug', ...extra })` */
+  debug: (message: string, extra?: DevframeMessageShortcutInput) => Promise<DevframeMessageHandle>
+}
+
+export interface DevframeMessagesClient extends DevframeMessagesLevelShortcuts {
   /**
    * Add a message entry. Returns a Promise resolving to a handle for subsequent updates/dismissal.
    * Can be used without `await` for fire-and-forget usage.
@@ -117,7 +141,7 @@ export interface DevframeMessagesClient {
   clear: () => Promise<void>
 }
 
-export interface DevframeMessagesHost {
+export interface DevframeMessagesHost extends DevframeMessagesLevelShortcuts {
   readonly entries: Map<string, DevframeMessageEntry>
   readonly events: EventEmitter<{
     'message:added': (entry: DevframeMessageEntry) => void
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
index 9af8e57..98a3fb8 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
@@ -12,6 +12,7 @@ export interface CommandsContext {
   paletteOpen: boolean;
 }
 export interface DevframeClientHost {
+  skipped: false;
   context: DevframeClientContext;
   dispose: () => void;
 }
@@ -20,6 +21,12 @@ export interface DevframeClientHostOptions {
   connect?: DevframeRpcClientOptions;
   clientType?: DockClientType;
   loadClientScripts?: boolean;
+  skipInIframe?: boolean;
+}
+export interface DevframeClientHostSkipped {
+  skipped: true;
+  context: undefined;
+  dispose: () => void;
 }
 export interface DockClientScriptContext extends DocksContext {
   current: DockEntryState;
@@ -75,6 +82,9 @@ export interface DocksPanelContext {
   isResizing: boolean;
   readonly isVertical: boolean;
 }
+export interface MessagesClientOptions {
+  defaults?: Partial<DevframeMessageEntryInput>;
+}
 export interface WhenClauseContext {
   readonly context: WhenContext;
 }
@@ -83,16 +93,17 @@ export interface WhenClauseContext {
 // #region Types
 export type ConnectRemoteDevframeOptions = Omit<DevframeRpcClientOptions, 'connectionMeta' | 'authToken'>;
 export type DevframeClientContext = DocksContext;
+export type DevframeClientHostResult = DevframeClientHost | DevframeClientHostSkipped;
 export type DockClientType = 'embedded' | 'standalone';
 // #endregion
 
 // #region Functions
 export declare function connectRemoteDevframe(_?: ConnectRemoteDevframeOptions): Promise<DevframeRpcClient>;
-export declare function createDevframeClientHost(_?: DevframeClientHostOptions): Promise<DevframeClientHost>;
-export declare function createMessagesClient(_: DevframeRpcClient): DevframeMessagesClient;
+export declare function createDevframeClientHost(_?: DevframeClientHostOptions): Promise<DevframeClientHostResult>;
+export declare function createMessagesClient(_: DevframeRpcClient, _?: MessagesClientOptions): DevframeMessagesClient;
 export declare function getDevframeClientContext(): DevframeClientContext | undefined;
 export declare function parseRemoteConnection(_?: string): RemoteConnectionInfo | null;
-export declare function setDevframeClientContext(_: DevframeClientContext): void;
+export declare function setDevframeClientContext(_: DevframeClientContext | undefined): void;
 // #endregion
 
 // #region Variables
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js
index f1f4c6a..79c9f6e 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.js
@@ -4,7 +4,7 @@
 // #region Functions
 export async function connectRemoteDevframe(_) {}
 export async function createDevframeClientHost(_) {}
-export function createMessagesClient(_) {}
+export function createMessagesClient(_, _) {}
 export function getDevframeClientContext() {}
 export function parseRemoteConnection(_) {}
 export function setDevframeClientContext(_) {}
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts
index 5fd55dd..eeee1a1 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts
@@ -51,7 +51,9 @@ export { DevframeMessageFilePosition }
 export { DevframeMessageHandle }
 export { DevframeMessageLevel }
 export { DevframeMessagesClient }
+export { DevframeMessageShortcutInput }
 export { DevframeMessagesHost }
+export { DevframeMessagesLevelShortcuts }
 export { DevframeNodeRpcSession }
 export { DevframeRpcClientFunctions }
 export { DevframeRpcServerFunctions }
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.d.ts
index 452a6e1..136a109 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.d.ts
@@ -59,6 +59,11 @@ export declare class DevframeMessagesHost implements DevframeMessagesHost$1 {
   add(_: DevframeMessageEntryInput): Promise<DevframeMessageHandle>;
   update(_: string, _: Partial<DevframeMessageEntryInput>): Promise<DevframeMessageEntry | undefined>;
   remove(_: string): Promise<void>;
+  info(_: string, _?: DevframeMessageShortcutInput): Promise<DevframeMessageHandle>;
+  warn(_: string, _?: DevframeMessageShortcutInput): Promise<DevframeMessageHandle>;
+  error(_: string, _?: DevframeMessageShortcutInput): Promise<DevframeMessageHandle>;
+  success(_: string, _?: DevframeMessageShortcutInput): Promise<DevframeMessageHandle>;
+  debug(_: string, _?: DevframeMessageShortcutInput): Promise<DevframeMessageHandle>;
   clear(): Promise<void>;
   private _createHandle;
 }
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.js b/tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.js
index 8933bd2..cac7f89 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.js
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/node.snapshot.js
@@ -43,6 +43,11 @@ export class DevframeMessagesHost {
   async add(_) {}
   async update(_, _) {}
   async remove(_) {}
+  info(_, _) {}
+  warn(_, _) {}
+  error(_, _) {}
+  success(_, _) {}
+  debug(_, _) {}
   async clear() {}
   _createHandle(_) {}
 }
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts
index 946c6d5..ce01ea4 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/types.snapshot.d.ts
@@ -37,7 +37,9 @@ export { DevframeMessageFilePosition }
 export { DevframeMessageHandle }
 export { DevframeMessageLevel }
 export { DevframeMessagesClient }
+export { DevframeMessageShortcutInput }
 export { DevframeMessagesHost }
+export { DevframeMessagesLevelShortcuts }
 export { DevframeNodeRpcSession }
 export { DevframeRpcClientFunctions }
 export { DevframeRpcServerFunctions }

From 4ffa6dd72f83f4b65587a54e2e019a3954d7df0a Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Thu, 2 Jul 2026 09:34:39 +0000
Subject: [PATCH 2/5] =?UTF-8?q?feat(plugin-a11y):=20consume=20the=20hub=20?=
 =?UTF-8?q?client-script=20context=20=E2=80=94=20mirror=20scans=20into=20t?=
 =?UTF-8?q?he=20messages=20feed?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 plugins/a11y/README.md                     |  14 ++-
 plugins/a11y/src/inject/index.ts           |  36 ++++--
 plugins/a11y/src/inject/messages.ts        | 131 +++++++++++++++++++
 plugins/a11y/src/inject/scanner.ts         |   1 +
 plugins/a11y/src/shared/protocol.ts        |   2 +
 plugins/a11y/tests/inject-messages.test.ts | 139 +++++++++++++++++++++
 6 files changed, 309 insertions(+), 14 deletions(-)
 create mode 100644 plugins/a11y/src/inject/messages.ts
 create mode 100644 plugins/a11y/tests/inject-messages.test.ts

diff --git a/plugins/a11y/README.md b/plugins/a11y/README.md
index bdca90c..f502375 100644
--- a/plugins/a11y/README.md
+++ b/plugins/a11y/README.md
@@ -35,10 +35,14 @@ 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
 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, where it scans,
-reports, and highlights on demand. Both minimal hub examples do exactly this.
-Outside a hub, one `<script type="module">` for the same bundle does the job —
-the demo below shows it.
+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
+mirrors each 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 element's
+selector. Both minimal hub examples do exactly this. Outside a hub, one
+`<script type="module">` for the same bundle does the job — the demo below
+shows it (no hub context, so the feed mirror simply stays off).
 
 ## Run the demo
 
@@ -74,7 +78,7 @@ pnpm -C plugins/a11y dev         # panel only, at /__devframe-a11y-inspector/
 | `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) → `dist/inject/inject.js` |
+| `src/inject/` | — | the host-page agent (axe scan, highlight overlay, hub messages mirror) → `dist/inject/inject.js` |
 | `src/spa/` | — | the Solid panel SPA → `dist/spa` |
 | `demo/` | — | same-origin host page + server (dev + static modes) |
 | `tests/` | — | dev-server RPC + static-build dump |
diff --git a/plugins/a11y/src/inject/index.ts b/plugins/a11y/src/inject/index.ts
index d6c6fc0..6cc960c 100644
--- a/plugins/a11y/src/inject/index.ts
+++ b/plugins/a11y/src/inject/index.ts
@@ -7,16 +7,21 @@
  * server — the loop works the same in dev and in a static build.
  *
  * Load it from the host page with a single module script, e.g.
- * `<script type="module" src="/__df-inject/inject.js"></script>`.
+ * `<script type="module" src="/__df-inject/inject.js"></script>` — or let a
+ * hub load it as the a11y dock's client script, in which case the default
+ * export receives the hub's client-script context and additionally mirrors
+ * each scan into the hub's messages feed.
  */
 import type { A11yMessage, ScanReport } from '../shared/protocol.ts'
+import type { A11yAgentContext } from './messages.ts'
 import { A11Y_CHANNEL } from '../shared/protocol.ts'
+import { createMessagesReporter } from './messages.ts'
 import { createOverlay } from './overlay.ts'
 import { resolveElement, scan } from './scanner.ts'
 
 const GLOBAL_FLAG = '__DF_A11Y_AGENT__'
 
-function start() {
+function start(context?: A11yAgentContext) {
   const w = window as unknown as Record<string, unknown>
   if (w[GLOBAL_FLAG])
     return
@@ -26,6 +31,10 @@ function start() {
   const overlay = createOverlay()
   document.documentElement.appendChild(overlay.root)
 
+  // Booted as a hub dock client script — mirror every scan into the hub's
+  // messages feed. Standalone boots have no context and skip the mirror.
+  const reporter = context?.messages ? createMessagesReporter(context.messages) : undefined
+
   let lastReport: ScanReport | null = null
   let scanning = false
   let rescanQueued = false
@@ -62,15 +71,18 @@ function start() {
     }
     scanning = true
     post({ type: 'a11y:scanning' })
+    reporter?.scanning()
     // Suspend observation so attribute-stamping during the scan doesn't
     // retrigger us.
     observer.disconnect()
     try {
       lastReport = await scan()
       post({ type: 'a11y:report', report: lastReport })
+      reporter?.report(lastReport)
     }
     catch (error) {
       console.error('[a11y-inspector] scan failed', error)
+      reporter?.failed(error)
     }
     finally {
       observe()
@@ -130,14 +142,20 @@ function findRule(report: ScanReport | null, nodeId: string) {
 }
 
 /**
- * Client-script entry the hub runtime calls after importing this module. The
- * agent needs no context — it talks to the panel over the same-origin
- * BroadcastChannel — so this just boots it. `start()` is idempotent.
+ * 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
+ * additionally mirrors each scan into the hub's messages feed. `start()` is
+ * idempotent.
  */
-export default function runA11yAgent(): void {
-  start()
+export default function runA11yAgent(context?: A11yAgentContext): 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.
-start()
+// (the standalone demo, any non-hub host) starts the agent 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.
+setTimeout(start, 0)
diff --git a/plugins/a11y/src/inject/messages.ts b/plugins/a11y/src/inject/messages.ts
new file mode 100644
index 0000000..f7d34a6
--- /dev/null
+++ b/plugins/a11y/src/inject/messages.ts
@@ -0,0 +1,131 @@
+/**
+ * Mirrors scan results into the hub's messages feed when the agent is booted
+ * as a dock **client script** (`createDevframeClientHost()` calls the agent'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
+ * 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`.
+ */
+import type { Impact, ScanReport } from '../shared/protocol.ts'
+
+/** Structural slice of the hub's `DevframeMessageEntryInput` the agent emits. */
+export interface HubMessageInput {
+  id?: string
+  message: string
+  description?: string
+  level: 'info' | 'warn' | 'error' | 'success' | 'debug'
+  labels?: string[]
+  elementPosition?: {
+    selector?: string
+    description?: string
+  }
+  status?: 'loading' | 'idle'
+}
+
+/** Structural slice of the hub's `DevframeMessagesClient` the agent 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.
+ */
+export interface A11yAgentContext {
+  messages?: HubMessagesClient
+}
+
+/** One deduplicated summary entry tracks the scan lifecycle. */
+const SCAN_MESSAGE_ID = 'devframe-a11y-inspector:scan'
+/** One deduplicated entry per violated rule; removed when the rule clears. */
+const RULE_MESSAGE_PREFIX = 'devframe-a11y-inspector:rule:'
+
+const IMPACT_LEVEL: Record<Impact, HubMessageInput['level']> = {
+  critical: 'error',
+  serious: 'error',
+  moderate: 'warn',
+  minor: 'info',
+}
+
+export interface MessagesReporter {
+  /** A scan started — surface the deduplicated summary entry as loading. */
+  scanning: () => void
+  /** A scan finished — update the summary and the per-rule entries. */
+  report: (report: ScanReport) => void
+  /** A scan failed — settle the summary entry as an error. */
+  failed: (error: unknown) => void
+}
+
+/**
+ * Build the reporter that projects each {@link ScanReport} onto the messages
+ * feed: a summary entry driven through the loading → idle lifecycle, plus one
+ * entry per violated rule (stable ids, so re-scans update in place) carrying
+ * the impact-mapped level, WCAG tags as labels, and the first offending
+ * element's selector. Rules that no longer violate are removed.
+ */
+export function createMessagesReporter(messages: HubMessagesClient): MessagesReporter {
+  let reportedRules = new Set<string>()
+  // Fire-and-forget: the feed is a mirror, never a gate for the scan loop.
+  const send = (input: HubMessageInput) => void messages.add(input).catch(() => {})
+  const drop = (id: string) => void messages.remove(id).catch(() => {})
+
+  return {
+    scanning() {
+      send({
+        id: SCAN_MESSAGE_ID,
+        message: 'Scanning page for accessibility issues…',
+        level: 'info',
+        status: 'loading',
+      })
+    },
+
+    report(report) {
+      const nodeCount = report.violations.reduce((n, v) => n + v.nodes.length, 0)
+      const ruleCount = report.violations.length
+      send({
+        id: SCAN_MESSAGE_ID,
+        message: nodeCount === 0
+          ? 'No accessibility issues found'
+          : `${nodeCount} accessibility issue${nodeCount === 1 ? '' : 's'} across ${ruleCount} rule${ruleCount === 1 ? '' : 's'}`,
+        description: report.url,
+        level: nodeCount === 0 ? 'success' : 'warn',
+        status: 'idle',
+      })
+
+      const seen = new Set<string>()
+      for (const violation of report.violations) {
+        seen.add(violation.ruleId)
+        const first = violation.nodes[0]
+        send({
+          id: RULE_MESSAGE_PREFIX + violation.ruleId,
+          message: `${violation.help} (${violation.nodes.length})`,
+          description: `${violation.description}\n${violation.helpUrl}`,
+          level: IMPACT_LEVEL[violation.impact],
+          labels: [violation.impact, ...(violation.tags ?? [])],
+          elementPosition: first
+            ? { selector: first.target.join(' '), description: first.failureSummary }
+            : undefined,
+        })
+      }
+      for (const ruleId of reportedRules) {
+        if (!seen.has(ruleId))
+          drop(RULE_MESSAGE_PREFIX + ruleId)
+      }
+      reportedRules = seen
+    },
+
+    failed(error) {
+      send({
+        id: SCAN_MESSAGE_ID,
+        message: 'Accessibility scan failed',
+        description: String(error),
+        level: 'error',
+        status: 'idle',
+      })
+    },
+  }
+}
diff --git a/plugins/a11y/src/inject/scanner.ts b/plugins/a11y/src/inject/scanner.ts
index c499f36..17a4da0 100644
--- a/plugins/a11y/src/inject/scanner.ts
+++ b/plugins/a11y/src/inject/scanner.ts
@@ -88,6 +88,7 @@ export async function scan(): Promise<ScanReport> {
       help: rule.help,
       description: rule.description,
       helpUrl: rule.helpUrl,
+      tags: rule.tags.filter(tag => tag.startsWith('wcag')),
       nodes,
     }
   })
diff --git a/plugins/a11y/src/shared/protocol.ts b/plugins/a11y/src/shared/protocol.ts
index f96e17f..9aba196 100644
--- a/plugins/a11y/src/shared/protocol.ts
+++ b/plugins/a11y/src/shared/protocol.ts
@@ -62,6 +62,8 @@ export interface Violation {
   description: string
   /** Deque University rule documentation. */
   helpUrl: string
+  /** WCAG tags the rule maps to, e.g. `["wcag2a", "wcag111"]`. */
+  tags?: string[]
   nodes: ViolationNode[]
 }
 
diff --git a/plugins/a11y/tests/inject-messages.test.ts b/plugins/a11y/tests/inject-messages.test.ts
new file mode 100644
index 0000000..adf2080
--- /dev/null
+++ b/plugins/a11y/tests/inject-messages.test.ts
@@ -0,0 +1,139 @@
+import type { HubMessageInput } from '../src/inject/messages.ts'
+import type { ScanReport, Violation } from '../src/shared/protocol.ts'
+import { describe, expect, it } from 'vitest'
+import { createMessagesReporter } from '../src/inject/messages.ts'
+import { emptyCounts } from '../src/shared/protocol.ts'
+
+function createStubMessages() {
+  const added: HubMessageInput[] = []
+  const removed: string[] = []
+  return {
+    added,
+    removed,
+    client: {
+      add: async (input: HubMessageInput) => {
+        added.push(input)
+      },
+      remove: async (id: string) => {
+        removed.push(id)
+      },
+    },
+  }
+}
+
+function violation(ruleId: string, impact: Violation['impact'], nodes = 1): Violation {
+  return {
+    ruleId,
+    impact,
+    help: `Fix ${ruleId}`,
+    description: `Ensures ${ruleId}`,
+    helpUrl: `https://dequeuniversity.com/rules/axe/${ruleId}`,
+    tags: ['wcag2a'],
+    nodes: Array.from({ length: nodes }, (_, i) => ({
+      id: `${ruleId}-${i}`,
+      target: [`#${ruleId}-${i}`],
+      html: `<div id="${ruleId}-${i}">`,
+      failureSummary: `Fix the ${ruleId} element`,
+    })),
+  }
+}
+
+function report(violations: Violation[]): ScanReport {
+  return {
+    url: 'https://example.test/',
+    scannedAt: 1,
+    engine: 'axe-test',
+    violations,
+    counts: emptyCounts(),
+  }
+}
+
+describe('createMessagesReporter', () => {
+  it('drives the summary entry through the loading → idle lifecycle', () => {
+    const { client, added } = createStubMessages()
+    const reporter = createMessagesReporter(client)
+
+    reporter.scanning()
+    expect(added.at(-1)).toMatchObject({
+      id: 'devframe-a11y-inspector:scan',
+      level: 'info',
+      status: 'loading',
+    })
+
+    reporter.report(report([]))
+    expect(added.at(-1)).toMatchObject({
+      id: 'devframe-a11y-inspector:scan',
+      message: 'No accessibility issues found',
+      level: 'success',
+      status: 'idle',
+    })
+  })
+
+  it('emits one entry per violated rule with impact-mapped level, WCAG labels, and element position', () => {
+    const { client, added } = createStubMessages()
+    const reporter = createMessagesReporter(client)
+
+    reporter.report(report([violation('image-alt', 'critical', 2), violation('label', 'moderate')]))
+
+    const summary = added.find(m => m.id === 'devframe-a11y-inspector:scan')
+    expect(summary).toMatchObject({
+      message: '3 accessibility issues across 2 rules',
+      level: 'warn',
+    })
+
+    const imageAlt = added.find(m => m.id === 'devframe-a11y-inspector:rule:image-alt')
+    expect(imageAlt).toMatchObject({
+      message: 'Fix image-alt (2)',
+      level: 'error',
+      labels: ['critical', 'wcag2a'],
+      elementPosition: { selector: '#image-alt-0', description: 'Fix the image-alt element' },
+    })
+    expect(added.find(m => m.id === 'devframe-a11y-inspector:rule:label')).toMatchObject({
+      level: 'warn',
+      labels: ['moderate', 'wcag2a'],
+    })
+  })
+
+  it('removes entries for rules that no longer violate on re-scan', () => {
+    const { client, added, removed } = createStubMessages()
+    const reporter = createMessagesReporter(client)
+
+    reporter.report(report([violation('image-alt', 'critical'), violation('label', 'minor')]))
+    reporter.report(report([violation('label', 'minor')]))
+
+    expect(removed).toEqual(['devframe-a11y-inspector:rule:image-alt'])
+    // The surviving rule was re-added (dedup by stable id updates in place).
+    expect(added.filter(m => m.id === 'devframe-a11y-inspector:rule:label')).toHaveLength(2)
+  })
+
+  it('settles the summary entry as an error when a scan fails', () => {
+    const { client, added } = createStubMessages()
+    const reporter = createMessagesReporter(client)
+
+    reporter.failed(new Error('axe exploded'))
+    expect(added.at(-1)).toMatchObject({
+      id: 'devframe-a11y-inspector:scan',
+      message: 'Accessibility scan failed',
+      description: 'Error: axe exploded',
+      level: 'error',
+      status: 'idle',
+    })
+  })
+
+  it('never lets a rejected feed call escape the scan loop', () => {
+    const reporter = createMessagesReporter({
+      add: async () => {
+        throw new Error('not trusted')
+      },
+      remove: async () => {
+        throw new Error('not trusted')
+      },
+    })
+    expect(() => {
+      reporter.scanning()
+      reporter.report(report([violation('image-alt', 'critical')]))
+      reporter.report(report([]))
+      reporter.failed(new Error('boom'))
+    }).not.toThrow()
+  })
+})

From 73741759b139ac06fcebac7bf17412bd16220eb3 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Fri, 3 Jul 2026 03:10:08 +0000
Subject: [PATCH 3/5] feat(plugin-a11y): report element bounding boxes for the
 messages panel

---
 plugins/a11y/README.md                     |  3 ++-
 plugins/a11y/src/inject/index.ts           | 16 ++++++++++++++-
 plugins/a11y/src/inject/messages.ts        | 24 +++++++++++++++++++---
 plugins/a11y/tests/inject-messages.test.ts | 14 +++++++++++--
 4 files changed, 50 insertions(+), 7 deletions(-)

diff --git a/plugins/a11y/README.md b/plugins/a11y/README.md
index f502375..4b4168c 100644
--- a/plugins/a11y/README.md
+++ b/plugins/a11y/README.md
@@ -40,7 +40,8 @@ default export with the client-script context. Booted that way, the agent also
 mirrors each 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 element's
-selector. Both minimal hub examples do exactly this. Outside a hub, one
+selector and bounding box (rendered by `@devframes/plugin-messages` when the
+hub mounts it). Both minimal hub examples do exactly this. Outside a hub, one
 `<script type="module">` for the same bundle does the job — the demo below
 shows it (no hub context, so the feed mirror simply stays off).
 
diff --git a/plugins/a11y/src/inject/index.ts b/plugins/a11y/src/inject/index.ts
index 6cc960c..94f9b68 100644
--- a/plugins/a11y/src/inject/index.ts
+++ b/plugins/a11y/src/inject/index.ts
@@ -33,7 +33,21 @@ function start(context?: A11yAgentContext) {
 
   // Booted as a hub dock client script — mirror every scan into the hub's
   // messages feed. Standalone boots have no context and skip the mirror.
-  const reporter = context?.messages ? createMessagesReporter(context.messages) : undefined
+  const reporter = context?.messages
+    ? createMessagesReporter(context.messages, {
+        resolveBoundingBox: (target) => {
+          const rect = resolveElement(target)?.getBoundingClientRect()
+          if (!rect)
+            return undefined
+          return {
+            x: Math.round(rect.x),
+            y: Math.round(rect.y),
+            width: Math.round(rect.width),
+            height: Math.round(rect.height),
+          }
+        },
+      })
+    : undefined
 
   let lastReport: ScanReport | null = null
   let scanning = false
diff --git a/plugins/a11y/src/inject/messages.ts b/plugins/a11y/src/inject/messages.ts
index f7d34a6..691e3eb 100644
--- a/plugins/a11y/src/inject/messages.ts
+++ b/plugins/a11y/src/inject/messages.ts
@@ -20,6 +20,7 @@ export interface HubMessageInput {
   labels?: string[]
   elementPosition?: {
     selector?: string
+    boundingBox?: { x: number, y: number, width: number, height: number }
     description?: string
   }
   status?: 'loading' | 'idle'
@@ -60,14 +61,27 @@ export interface MessagesReporter {
   failed: (error: unknown) => void
 }
 
+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
+   * box is fine: each re-scan refreshes the entry.
+   */
+  resolveBoundingBox?: (target: string[]) => { x: number, y: number, width: number, height: number } | undefined
+}
+
 /**
  * Build the reporter that projects each {@link ScanReport} onto the messages
  * feed: a summary entry driven through the loading → idle lifecycle, plus one
  * entry per violated rule (stable ids, so re-scans update in place) carrying
  * the impact-mapped level, WCAG tags as labels, and the first offending
- * element's selector. Rules that no longer violate are removed.
+ * element's selector and bounding box. Rules that no longer violate are
+ * removed.
  */
-export function createMessagesReporter(messages: HubMessagesClient): MessagesReporter {
+export function createMessagesReporter(
+  messages: HubMessagesClient,
+  options: MessagesReporterOptions = {},
+): MessagesReporter {
   let reportedRules = new Set<string>()
   // Fire-and-forget: the feed is a mirror, never a gate for the scan loop.
   const send = (input: HubMessageInput) => void messages.add(input).catch(() => {})
@@ -107,7 +121,11 @@ export function createMessagesReporter(messages: HubMessagesClient): MessagesRep
           level: IMPACT_LEVEL[violation.impact],
           labels: [violation.impact, ...(violation.tags ?? [])],
           elementPosition: first
-            ? { selector: first.target.join(' '), description: first.failureSummary }
+            ? {
+                selector: first.target.join(' '),
+                boundingBox: options.resolveBoundingBox?.(first.target),
+                description: first.failureSummary,
+              }
             : undefined,
         })
       }
diff --git a/plugins/a11y/tests/inject-messages.test.ts b/plugins/a11y/tests/inject-messages.test.ts
index adf2080..ef697ef 100644
--- a/plugins/a11y/tests/inject-messages.test.ts
+++ b/plugins/a11y/tests/inject-messages.test.ts
@@ -71,7 +71,10 @@ describe('createMessagesReporter', () => {
 
   it('emits one entry per violated rule with impact-mapped level, WCAG labels, and element position', () => {
     const { client, added } = createStubMessages()
-    const reporter = createMessagesReporter(client)
+    const reporter = createMessagesReporter(client, {
+      resolveBoundingBox: target =>
+        target[0] === '#image-alt-0' ? { x: 1, y: 2, width: 30, height: 40 } : undefined,
+    })
 
     reporter.report(report([violation('image-alt', 'critical', 2), violation('label', 'moderate')]))
 
@@ -86,12 +89,19 @@ describe('createMessagesReporter', () => {
       message: 'Fix image-alt (2)',
       level: 'error',
       labels: ['critical', 'wcag2a'],
-      elementPosition: { selector: '#image-alt-0', description: 'Fix the image-alt element' },
+      elementPosition: {
+        selector: '#image-alt-0',
+        boundingBox: { x: 1, y: 2, width: 30, height: 40 },
+        description: 'Fix the image-alt element',
+      },
     })
     expect(added.find(m => m.id === 'devframe-a11y-inspector:rule:label')).toMatchObject({
       level: 'warn',
       labels: ['moderate', 'wcag2a'],
     })
+    // No resolver hit — the box is simply absent, never a throw.
+    expect(added.find(m => m.id === 'devframe-a11y-inspector:rule:label')?.elementPosition?.boundingBox)
+      .toBeUndefined()
   })
 
   it('removes entries for rules that no longer violate on re-scan', () => {

From 8a67086d8866f93faf05ce91b4b3c2acacdc2c4e Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Fri, 3 Jul 2026 04:57:23 +0000
Subject: [PATCH 4/5] refactor(hub): drop the skipped/iframe-guard concept from
 the client host

---
 .../hub/src/client/__tests__/host.test.ts     | 48 +++----------------
 packages/hub/src/client/host.ts               | 37 +-------------
 .../@devframes/hub/client.snapshot.d.ts       | 10 +---
 3 files changed, 9 insertions(+), 86 deletions(-)

diff --git a/packages/hub/src/client/__tests__/host.test.ts b/packages/hub/src/client/__tests__/host.test.ts
index 8ee790d..d3472aa 100644
--- a/packages/hub/src/client/__tests__/host.test.ts
+++ b/packages/hub/src/client/__tests__/host.test.ts
@@ -1,20 +1,11 @@
 import type { DevframeRpcClient } from 'devframe/client'
 import type { SharedState } from 'devframe/utils/shared-state'
 import type { DevframeDockEntry } from '../../types/docks'
-import type { DevframeClientHost, DevframeClientHostOptions } from '../host'
 import { createEventEmitter } from 'devframe/utils/events'
 import { describe, expect, it, vi } from 'vitest'
 import { getDevframeClientContext } from '../context'
 import { createDevframeClientHost } from '../host'
 
-/** Boot a host that is expected to actually boot (narrow away the skipped arm). */
-async function boot(options: DevframeClientHostOptions): Promise<DevframeClientHost> {
-  const host = await createDevframeClientHost(options)
-  if (host.skipped)
-    throw new Error('expected the client host to boot, but it skipped')
-  return host
-}
-
 interface StubSharedState<T> extends SharedState<T> {
   /** Replace the state wholesale and emit `updated` (simulates a server patch). */
   push: (next: T) => void
@@ -67,7 +58,7 @@ function iframeEntry(id: string, extra?: Record<string, unknown>): DevframeDockE
 describe('createDevframeClientHost', () => {
   it('publishes the global client context with the full surface', async () => {
     const { rpc } = createStubRpc()
-    const host = await boot({ rpc })
+    const host = await createDevframeClientHost({ rpc })
 
     expect(getDevframeClientContext()).toBe(host.context)
     expect(host.context.clientType).toBe('standalone')
@@ -84,7 +75,7 @@ describe('createDevframeClientHost', () => {
 
   it('reconciles dock entries from shared state and tracks per-entry state', async () => {
     const { rpc, states } = createStubRpc()
-    const host = await boot({ rpc })
+    const host = await createDevframeClientHost({ rpc })
     const docksState = states.get('devframe:docks')!
 
     docksState.push([iframeEntry('one'), iframeEntry('two')])
@@ -99,7 +90,7 @@ describe('createDevframeClientHost', () => {
 
   it('switches entries with activation/deactivation events and when-context updates', async () => {
     const { rpc, states } = createStubRpc()
-    const host = await boot({ rpc })
+    const host = await createDevframeClientHost({ rpc })
     states.get('devframe:docks')!.push([iframeEntry('one'), iframeEntry('two')])
 
     const activated: string[] = []
@@ -126,7 +117,7 @@ describe('createDevframeClientHost', () => {
 
   it('executes client commands locally and server commands over hub:commands:execute', async () => {
     const { rpc, calls } = createStubRpc()
-    const host = await boot({ rpc })
+    const host = await createDevframeClientHost({ rpc })
 
     const ran: any[] = []
     const off = host.context.commands.register({
@@ -151,7 +142,7 @@ describe('createDevframeClientHost', () => {
 
   it('imports a dock entry client script and hands it the script context', async () => {
     const { rpc, states, calls } = createStubRpc()
-    const host = await boot({ rpc })
+    const host = await createDevframeClientHost({ rpc })
 
     const received: any[] = []
     ;(globalThis as any).__DF_TEST_SCRIPT__ = (ctx: any) => received.push(ctx)
@@ -176,39 +167,14 @@ describe('createDevframeClientHost', () => {
     host.dispose()
   })
 
-  it('skips boot inside an iframe for embedded hosts, overridable via skipInIframe', async () => {
-    vi.stubGlobal('window', { self: {}, top: {} })
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
-    try {
-      const { rpc } = createStubRpc()
-      const skipped = await createDevframeClientHost({ rpc, clientType: 'embedded' })
-      expect(skipped.skipped).toBe(true)
-      expect(skipped.context).toBeUndefined()
-      expect(getDevframeClientContext()).toBeUndefined()
-      skipped.dispose()
-
-      // Standalone hosts (and an explicit opt-out) still boot inside iframes.
-      const standalone = await createDevframeClientHost({ rpc })
-      expect(standalone.skipped).toBe(false)
-      standalone.dispose()
-      const optOut = await createDevframeClientHost({ rpc, clientType: 'embedded', skipInIframe: false })
-      expect(optOut.skipped).toBe(false)
-      optOut.dispose()
-    }
-    finally {
-      vi.unstubAllGlobals()
-      warn.mockRestore()
-    }
-  })
-
   it('warns when a second host replaces a published context; dispose unpublishes it', async () => {
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
     try {
       const { rpc } = createStubRpc()
-      const first = await boot({ rpc })
+      const first = await createDevframeClientHost({ rpc })
       expect(warn).not.toHaveBeenCalled()
 
-      const second = await boot({ rpc })
+      const second = await createDevframeClientHost({ rpc })
       expect(warn).toHaveBeenCalledOnce()
       expect(getDevframeClientContext()).toBe(second.context)
 
diff --git a/packages/hub/src/client/host.ts b/packages/hub/src/client/host.ts
index e785567..777aa4b 100644
--- a/packages/hub/src/client/host.ts
+++ b/packages/hub/src/client/host.ts
@@ -52,34 +52,15 @@ export interface DevframeClientHostOptions {
    * `custom-render`, and iframe `clientScript`). Default `true`.
    */
   loadClientScripts?: boolean
-  /**
-   * Skip booting when the page runs inside an iframe, so a nested frame never
-   * publishes a second context or re-runs every dock client script. Defaults
-   * to `true` for `'embedded'` hosts (dock iframe panels and nested copies of
-   * the app skip themselves) and `false` for `'standalone'` hosts (a hub UI
-   * page stays bootable when intentionally iframed).
-   */
-  skipInIframe?: boolean
 }
 
 export interface DevframeClientHost {
-  /** The host booted and published its context. */
-  skipped: false
   /** The assembled, globally-registered client host context. */
   context: DevframeClientContext
   /** Tear down listeners and stop tracking newly-registered client scripts. */
   dispose: () => void
 }
 
-export interface DevframeClientHostSkipped {
-  /** Boot was skipped — the page runs inside an iframe (see `skipInIframe`). */
-  skipped: true
-  context: undefined
-  dispose: () => void
-}
-
-export type DevframeClientHostResult = DevframeClientHost | DevframeClientHostSkipped
-
 /**
  * Boot the framework-level client host: connect RPC, assemble the full
  * {@link DevframeClientContext} (panel, docks, commands, when) from the hub's
@@ -92,13 +73,8 @@ export type DevframeClientHostResult = DevframeClientHost | DevframeClientHostSk
  */
 export async function createDevframeClientHost(
   options: DevframeClientHostOptions = {},
-): Promise<DevframeClientHostResult> {
+): Promise<DevframeClientHost> {
   const clientType: DockClientType = options.clientType ?? 'standalone'
-  if ((options.skipInIframe ?? clientType === 'embedded') && isInsideIframe()) {
-    console.warn('[@devframes/hub] Skipping client host in iframe')
-    return { skipped: true, context: undefined, dispose: () => {} }
-  }
-
   const rpc = options.rpc ?? await connectDevframe(options.connect)
 
   const [docksState, commandsState, settings] = await Promise.all([
@@ -154,7 +130,6 @@ export async function createDevframeClientHost(
   }
 
   return {
-    skipped: false,
     context,
     dispose() {
       for (const off of disposers.splice(0)) off()
@@ -324,16 +299,6 @@ export async function createDevframeClientHost(
 
 // ── shared helpers ─────────────────────────────────────────────────────────
 
-function isInsideIframe(): boolean {
-  try {
-    return typeof window !== 'undefined' && window.self !== window.top
-  }
-  catch {
-    // Cross-origin access threw — we are definitely inside a foreign frame.
-    return true
-  }
-}
-
 function createPanelContext(clientType: DockClientType): DocksPanelContext {
   const store: DocksPanelContext['store'] = {
     mode: 'edge',
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
index 98a3fb8..0a04848 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/client.snapshot.d.ts
@@ -12,7 +12,6 @@ export interface CommandsContext {
   paletteOpen: boolean;
 }
 export interface DevframeClientHost {
-  skipped: false;
   context: DevframeClientContext;
   dispose: () => void;
 }
@@ -21,12 +20,6 @@ export interface DevframeClientHostOptions {
   connect?: DevframeRpcClientOptions;
   clientType?: DockClientType;
   loadClientScripts?: boolean;
-  skipInIframe?: boolean;
-}
-export interface DevframeClientHostSkipped {
-  skipped: true;
-  context: undefined;
-  dispose: () => void;
 }
 export interface DockClientScriptContext extends DocksContext {
   current: DockEntryState;
@@ -93,13 +86,12 @@ export interface WhenClauseContext {
 // #region Types
 export type ConnectRemoteDevframeOptions = Omit<DevframeRpcClientOptions, 'connectionMeta' | 'authToken'>;
 export type DevframeClientContext = DocksContext;
-export type DevframeClientHostResult = DevframeClientHost | DevframeClientHostSkipped;
 export type DockClientType = 'embedded' | 'standalone';
 // #endregion
 
 // #region Functions
 export declare function connectRemoteDevframe(_?: ConnectRemoteDevframeOptions): Promise<DevframeRpcClient>;
-export declare function createDevframeClientHost(_?: DevframeClientHostOptions): Promise<DevframeClientHostResult>;
+export declare function createDevframeClientHost(_?: DevframeClientHostOptions): Promise<DevframeClientHost>;
 export declare function createMessagesClient(_: DevframeRpcClient, _?: MessagesClientOptions): DevframeMessagesClient;
 export declare function getDevframeClientContext(): DevframeClientContext | undefined;
 export declare function parseRemoteConnection(_?: string): RemoteConnectionInfo | null;

From 54b71b542f529cfdd5b39b7a7a34f951ed77aa74 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Fri, 3 Jul 2026 05:17:18 +0000
Subject: [PATCH 5/5] =?UTF-8?q?docs(guide):=20client=20scripts=20&=20clien?=
 =?UTF-8?q?t=20context=20=E2=80=94=20host=20runtime=20boot,=20dock-script?=
 =?UTF-8?q?=20contract,=20injection=20story?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/.vitepress/config.ts    |   1 +
 docs/guide/client-context.md | 117 +++++++++++++++++++++++++++++++++++
 docs/guide/hub.md            |   4 ++
 docs/plugins/a11y.md         |  14 +++++
 4 files changed, 136 insertions(+)
 create mode 100644 docs/guide/client-context.md

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 9827faf..27ae96a 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -31,6 +31,7 @@ function guideItems(prefix: string): DefaultTheme.NavItemWithLink[] {
     { text: 'Security', link: `${prefix}/guide/security` },
     { text: 'Standalone CLI', link: `${prefix}/guide/standalone-cli` },
     { text: 'Hub (multi-tool)', link: `${prefix}/guide/hub` },
+    { text: 'Client Scripts & Context', link: `${prefix}/guide/client-context` },
     { text: 'Agent-Native (experimental)', link: `${prefix}/guide/agent-native` },
   ]
 }
diff --git a/docs/guide/client-context.md b/docs/guide/client-context.md
new file mode 100644
index 0000000..2ff9b96
--- /dev/null
+++ b/docs/guide/client-context.md
@@ -0,0 +1,117 @@
+---
+outline: deep
+---
+
+# Client Scripts & Client Context
+
+In a hub, a plugin can run code inside the **host page** — the page being inspected — through a dock **client script**. The **client context** is the object every client-side surface (dock client scripts, viewer UIs, your own app code) uses to talk to the hub: RPC, dock state, the command palette, and the when-clause context.
+
+> [!WARNING] Experimental
+> The hub API surface is still being refined. Names may change before 1.0.
+
+## The client host runtime
+
+`createDevframeClientHost()` from `@devframes/hub/client` is the headless browser runtime a host page boots. When it runs it:
+
+1. Connects an RPC client — or adopts one you already made.
+2. Assembles the `DevframeClientContext` (panel, docks, commands, when) from the hub's shared state.
+3. Publishes the context to a global slot, so `getDevframeClientContext()` can read it from anywhere in the page.
+4. Imports each dock entry's client script into the page and calls it with the context.
+
+The host page owns the boot — one import from its own browser entry starts the runtime, and your HTML stays untouched:
+
+```ts
+// main.ts — the host app / hub page's browser entry
+import { connectDevframe, createDevframeClientHost } from '@devframes/hub/client'
+
+const rpc = await connectDevframe({ baseURL: '/__hub/' })
+const { context, dispose } = await createDevframeClientHost({ rpc })
+```
+
+Viewers with an HTML pipeline layer injection on top: `@vitejs/devtools` wraps this boot in the client entry its Vite plugin injects through `transformIndexHtml`, while the devframe examples import it from the app entry directly. Either way the same runtime executes in the page.
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `rpc` | An already-connected `DevframeRpcClient`. When omitted, one is created via `connectDevframe(connect)`. |
+| `connect` | Options forwarded to `connectDevframe` when `rpc` is not supplied — pass `baseURL` to point at the hub's connection-meta mount (e.g. `/__hub/`). |
+| `clientType` | `'standalone'` (default) — the runtime owns the whole page (a hub UI). `'embedded'` — the runtime lives inside a user app alongside a panel. |
+| `loadClientScripts` | Import and run dock entries' client scripts. Default `true`. |
+
+Boot the host once per page: a second boot replaces the published context and logs a warning. `dispose()` tears down its listeners and unpublishes the context it owns.
+
+## The client context
+
+`DevframeClientContext` is the client-side counterpart of the hub's node context: one object carrying everything a client surface needs.
+
+| Property | Description |
+|----------|-------------|
+| `rpc` | The [RPC client](./client) — call server functions, register client-side functions, access shared state. |
+| `clientType` | `'embedded'` (runtime inside your app) or `'standalone'` (independent hub page). |
+| `docks` | Dock entries and selection — `entries`, `selected`, `groupedEntries`, `switchEntry()`, `toggleEntry()`, `getStateById()`. |
+| `panel` | Dock panel state: position, size, drag/resize flags. |
+| `commands` | The command palette: `register()`, `execute()`, `getKeybindings()`. |
+| `when` | The [when-clause](./when-clauses) evaluation context. |
+
+### Accessing the context
+
+From anywhere in the host page, use `getDevframeClientContext()`. It returns `undefined` until the client host finishes booting:
+
+```ts
+import { getDevframeClientContext } from '@devframes/hub/client'
+
+const ctx = getDevframeClientContext()
+if (ctx) {
+  const modules = await ctx.rpc.call('my-plugin:get-modules')
+  ctx.docks.switchEntry('my-plugin')
+}
+```
+
+## Dock client scripts
+
+A dock entry declares its client script as a `ClientScriptEntry` — `{ importFrom, importName? }`, where `importName` defaults to `'default'`. The field depends on the entry kind:
+
+| Entry kind | Field | Runs |
+|---|---|---|
+| `action` | `action` | when the dock button is activated |
+| `custom-render` | `renderer` | to render the entry's panel |
+| `iframe` | `clientScript` (optional) | alongside the iframe panel, inside the host page |
+
+The client host imports `importFrom` with a native dynamic import at runtime — the specifier is a URL served by the host, not a build-time module — and calls the exported function with the client context, extended with two dock-scoped extras:
+
+- **`current`** — this entry's state: `entryMeta`, `isActive`, `domElements`, and `events` (`entry:activated`, `entry:deactivated`, `entry:updated`, `dom:panel:mounted`, `dom:iframe:mounted`).
+- **`messages`** — a messages client scoped to the entry: messages it adds default their `category` to the entry id, and the per-level shortcuts (`info` / `warn` / `error` / `success` / `debug`) delegate to `add()`.
+
+```ts
+import type { DockClientScriptContext } from '@devframes/hub/client'
+
+export default async function setup(ctx: DockClientScriptContext) {
+  ctx.current.events.on('entry:activated', async () => {
+    const data = await ctx.rpc.call('my-plugin:get-modules')
+    ctx.messages.info(`Loaded ${data.length} modules`)
+  })
+}
+```
+
+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:
+
+```ts
+await mountDevframe(ctx, myDevframe, {
+  dock: { clientScript: { importFrom: `/@fs/${myAgentBundlePath}` } },
+})
+```
+
+Under Vite, `/@fs/<absolute path>` serves the built bundle directly; other hosts mount the bundle's directory statically and pass that URL instead.
+
+### 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.
+
+## Iframe panels
+
+Dock iframes are their own documents, so they connect themselves instead of reading the host page's context: the panel SPA calls `connectDevframe()`, which discovers `./__connection.json` relative to its own base — `mountDevframe` serves the hub's connection meta under every dock base for exactly this. The client script (host page) and the iframe panel then share the server through RPC and shared state, or a same-origin `BroadcastChannel` when the loop must survive static builds.
diff --git a/docs/guide/hub.md b/docs/guide/hub.md
index d039810..446584e 100644
--- a/docs/guide/hub.md
+++ b/docs/guide/hub.md
@@ -143,6 +143,10 @@ A hub-aware UI doesn't import any hub classes; it reads three shared-state keys
 
 Plus broadcast notifications (`devframe:terminals:updated`, `devframe:messages:updated`) that a UI can subscribe to via `rpc.client.register(...)`.
 
+## Running plugin code in the host page
+
+The hub also ships a headless browser runtime, `createDevframeClientHost()` from `@devframes/hub/client`. Booted in the host page, it assembles the shared client context from the protocol above and imports each dock entry's client script into that page — how a plugin like the a11y inspector runs code inside the page being inspected. See [Client Scripts & Client Context](./client-context) for the boot flow, the context surface, and the dock-script contract.
+
 ## Example
 
 Two minimal, copyable hubs mount every built-in plugin (git, terminals, code-server, inspect, a11y) behind an icon dock — the same shape [vite-devtools](https://github.com/vitejs/devtools) wears as the full Vite viewer, shrunk to the smallest thing you can build your own viewer from:
diff --git a/docs/plugins/a11y.md b/docs/plugins/a11y.md
index f22c8b7..8ef086b 100644
--- a/docs/plugins/a11y.md
+++ b/docs/plugins/a11y.md
@@ -20,6 +20,20 @@ The plugin is three pieces, two of them browser-side:
 
 The agent and panel talk over a same-origin `BroadcastChannel` rather than the RPC backend, so the scan-and-highlight loop works identically whether the plugin runs as a live dev server or as a baked static build. Devframe deliberately provides no access to the host application's DOM, so the agent is the author-provided bridge: load one module script in the page you want to check and it scans, reports, and highlights on demand.
 
+## In a hub
+
+The agent is the a11y dock's [client script](/guide/client-context): attach the exported `a11yAgentBundlePath` as the dock's `clientScript` and the hub's client host imports it into the host page, calling its default export with the client-script context. Booted that way, the agent also mirrors each 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 offending element's selector and bounding box:
+
+```ts
+import a11yDevframe, { a11yAgentBundlePath } from '@devframes/plugin-a11y'
+
+await mountDevframe(ctx, a11yDevframe, {
+  dock: { clientScript: { importFrom: `/@fs/${a11yAgentBundlePath}` } },
+})
+```
+
+Outside a hub, one `<script type="module">` for the same bundle boots the agent standalone — the scan loop is identical, with the feed mirror simply absent.
+
 ## Run the demo
 
 The Accessibility Inspector lives in the repository as a reference plugin. Its demo serves an intentionally-broken host page and the panel from one origin so they share the channel: