fix(hub): keep custom-render renderers activation-gated and enable eager demo docks

A `custom-render` renderer needs its mounted panel, so running it eagerly
before the panel exists left it cached against a missing container and never
re-ran on activation. Restrict eager execution to panel-independent iframe
page scripts and action scripts in both the headless runtime and the
reference hub UI.

Guard the fire-and-forget switchEntry call sites so a failed lazy client
script no longer surfaces as an unhandled rejection while its cache entry
stays retryable.

Opt the demo dock-client into eager initialization in both reference hosts so
it subscribes to entry:activated before the first click, and document that a
renderer always initializes on activation regardless of eager.

Co-authored-by: agent <agent@opencode>

Author: antfubot

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

@@ -69,7 +69,7 @@ A client-only dock can also carry `type: 'json-render'` with an inline [JSON-ren
 
 A client script is a `ClientScriptEntry`: `{ importFrom, importName?, eager? }`. `importName` defaults to `'default'` and `eager` defaults to `false`. An `iframe` entry's optional `clientScript` runs inside the host page when the dock entry is first activated. An `action` entry runs its `action` on each activation, while a `custom-render` entry initializes its `renderer` after selection so it can mount into the panel.
 
-Set `eager: true` on a descriptor to initialize it as soon as the RPC connection is trusted, before opening a dock panel. This suits background subscriptions and page commands. Both the reference hub UI and `createDevframeClientRuntime()` honor these settings ([Hub API reference](/references/hub-api#dock-client-script-fields)).
+Set `eager: true` on an `iframe` `clientScript` or an `action` to initialize it as soon as the RPC connection is trusted, before opening a dock panel. This suits background subscriptions and page commands, such as an `action` that registers page commands or subscribes to `entry:activated` before its first click. A `custom-render` `renderer` needs its mounted panel, so it always initializes on activation. Both the reference hub UI and `createDevframeClientRuntime()` honor these settings ([Hub API reference](/references/hub-api#dock-client-script-fields)).
 
 The exported function (`DockClientScriptContext`) receives the client context and two dock-scoped extras:
 

docs/content/8.references/6.hub-api.md

@@ -133,7 +133,7 @@ Which `ClientScriptEntry` field carries an entry's client script, and when it ru
 | `custom-render` | `renderer` | to render the entry's panel |
 | `iframe` | `clientScript` (optional) | inside the host page on first activation |
 
-`ClientScriptEntry.eager` defaults to `false`. Set it to `true` to initialize that script after RPC trust, before dock activation. Setup is cached per RPC connection and dock; action clicks execute on every activation.
+`ClientScriptEntry.eager` defaults to `false`. Set it to `true` on an `iframe` `clientScript` or an `action` to initialize it after RPC trust, before dock activation. A `custom-render` `renderer` needs its mounted panel, so it always initializes on activation regardless of `eager`. Setup is cached per RPC connection and dock; action clicks execute on every activation.
 
 ## Frame-nav messages
 

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

@@ -287,7 +287,8 @@ export async function nextDevframeHub(
 
       // The demo dock-client script - the same package the Vite reference
       // host loads via a bare specifier - mounted statically and attached as
-      // a momentary `action` dock by its served URL.
+      // a momentary `action` dock by its served URL. `eager: true` runs it on
+      // trust so it subscribes to `entry:activated` before the first click.
       if (demoDockClient) {
         await ctx.host.mountStatic(DEMO_CLIENT_MOUNT_BASE, demoDockClient.dir)
         ctx.docks.register({
@@ -296,7 +297,7 @@ export async function nextDevframeHub(
           title: 'Client Script Demo',
           icon: 'ph:plugs-connected-duotone',
           category: 'app',
-          action: { importFrom: demoDockClient.importFrom },
+          action: { importFrom: demoDockClient.importFrom, eager: true },
         })
       }
 

examples/custom-hub-vite/vite.config.ts

@@ -176,15 +176,16 @@ export default defineConfig({
         // Bare-specifier client script demo: `importFrom` names the npm
         // package itself, imported through Vite's own module graph via the
         // host's `clientModuleResolution` (`'/@id/{specifier}'`). The Next
-        // reference host consumes the same package as a prebuilt
-        // self-contained bundle instead (see examples/demo-dock-client).
+        // host uses the same package as a prebuilt bundle (see
+        // examples/demo-dock-client). `eager: true` runs it on trust so it
+        // subscribes to `entry:activated` before the first click.
         context.docks.register({
           type: 'action',
           id: 'example:demo-client-script',
           title: 'Client Script Demo',
           icon: 'ph:plugs-connected-duotone',
           category: 'app',
-          action: { importFrom: 'demo-dock-client' },
+          action: { importFrom: 'demo-dock-client', eager: true },
         })
 
         // Witness the missing-renderer path: a dock type nothing covers, so

packages/hub-ui/src/client/state/client-script.integration.test.ts

@@ -155,6 +155,29 @@ it('does not invoke action docks while initializing page scripts', async () => {
   expect(attempts).toBe(1)
 })
 
+it('keeps an eager custom-render renderer activation-gated so it mounts into its panel', async () => {
+  expect.assertions(2)
+  let attempts = 0
+  globalThis.__DEVFRAME_CLIENT_SCRIPT_ATTEMPT__ = () => {
+    attempts++
+  }
+  const { rpc, sharedStates } = createStubRpc()
+  const context = await createDocksContext('embedded', rpc)
+  const entry = {
+    id: 'eager-renderer',
+    type: 'custom-render',
+    title: 'Eager renderer',
+    icon: 'ph:play',
+    renderer: { eager: true, importFrom: 'data:text/javascript,export default () => globalThis.__DEVFRAME_CLIENT_SCRIPT_ATTEMPT__()' },
+  } satisfies DevframeDockEntry
+  sharedStates.get('devframe:docks')!.push([entry])
+  await nextTick()
+  // A renderer needs its mounted panel, so `eager` must not run it before activation.
+  expect(attempts).toBe(0)
+  await context.docks.switchEntry(entry.id)
+  expect(attempts).toBe(1)
+})
+
 it.each([undefined, false] as const)('keeps page setup lazy when eager is %s', async (eager) => {
   expect.assertions(3)
   const attempt = vi.fn()

packages/hub-ui/src/client/state/context.ts

@@ -253,7 +253,9 @@ export async function createDocksContext(
     if (!rpc.isTrusted)
       return
     for (const entry of entries.value) {
-      if (entry.type === '~builtin')
+      // A `custom-render` renderer needs its mounted panel, so it stays
+      // activation-gated; only panel-independent page and action scripts run eagerly.
+      if (entry.type !== 'iframe' && entry.type !== 'action')
         continue
       if (!clientScriptOf(entry)?.eager)
         continue
@@ -398,8 +400,10 @@ export async function createDocksContext(
     name: HUB_EVENTS.broadcast.docksActivate satisfies keyof DevframeRpcClientFunctions,
     type: 'action',
     handler: (activation: { dockId: string, params?: Record<string, unknown> }) => {
+      // `switchEntry` rejects when a lazy client script fails so its cache entry
+      // stays retryable; the failure is already logged, so swallow it here.
       if (activation?.dockId)
-        switchEntry(activation.dockId)
+        void switchEntry(activation.dockId).catch(() => {})
     },
   })
 

packages/hub/src/client/__tests__/host.test.ts

@@ -455,6 +455,35 @@ it('waits for trust for eager setup and activation for lazy setup in the headles
   }
 })
 
+it('keeps an eager custom-render renderer activation-gated in the headless runtime', async () => {
+  expect.assertions(2)
+  const { rpc, states } = createStubRpc()
+  const runtime = await createDevframeClientRuntime({ rpc })
+  const attempt = vi.fn()
+  const fixture = globalThis as typeof globalThis & { __DF_RENDERER_TEST__?: () => void }
+  fixture.__DF_RENDERER_TEST__ = attempt
+  const entry = {
+    id: 'eager-renderer',
+    title: 'Eager renderer',
+    icon: 'ph:cube',
+    type: 'custom-render',
+    renderer: { eager: true, importFrom: 'data:text/javascript,export default () => globalThis.__DF_RENDERER_TEST__()' },
+  } satisfies DevframeDockEntry
+  try {
+    states.get('devframe:docks')!.push([entry])
+    // Give any eager import a chance to resolve; a renderer needs its mounted
+    // panel, so `eager` must not run it before activation.
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(attempt).not.toHaveBeenCalled()
+    await runtime.context.docks.switchEntry(entry.id)
+    expect(attempt).toHaveBeenCalledTimes(1)
+  }
+  finally {
+    runtime.dispose()
+    delete fixture.__DF_RENDERER_TEST__
+  }
+})
+
 it.each([false, true])('retries setup after trust is revoked during import (eager: %s)', async (eager) => {
   expect.assertions(6)
   const reportError = vi.spyOn(console, 'error').mockImplementation(() => {})

packages/hub/src/client/host.ts

@@ -200,8 +200,10 @@ export async function createDevframeClientRuntime(
   // unknown ids. Chain onto any handler a co-consumer already registered on
   // this rpc client rather than replacing it.
   const activateHandler = (activation: { dockId?: string } | undefined): void => {
+    // `switchEntry` rejects when a lazy client script fails so its cache entry
+    // stays retryable; the failure is already logged, so swallow it here.
     if (activation?.dockId)
-      void switchEntry(activation.dockId)
+      void switchEntry(activation.dockId).catch(() => {})
   }
   const existingActivate = rpc.client.definitions.get(DOCKS_ACTIVATE_EVENT)
   if (existingActivate) {
@@ -367,7 +369,9 @@ export async function createDevframeClientRuntime(
         return selectedId
       },
       set selectedId(id: string | null) {
-        void switchEntry(id)
+        // Setter can't surface a rejection; `switchEntry` already logs a failed
+        // client script and keeps its cache entry retryable.
+        void switchEntry(id).catch(() => {})
       },
       /**
        * A mirror of the session field, so a persisting host reads and writes the
@@ -554,15 +558,13 @@ export async function createDevframeClientRuntime(
   function loadClientScripts(): void {
     if (disposed || !rpc.isTrusted)
       return
+    // A `custom-render` renderer needs its mounted panel, so it stays
+    // activation-gated; only panel-independent page and action scripts run eagerly.
     for (const entry of currentEntries()) {
-      if (entry.type === '~builtin')
-        continue
       if (entry.type === 'iframe')
         startEagerScript(entry.id, entry.clientScript)
-      if (entry.type === 'action')
+      else if (entry.type === 'action')
         startEagerScript(entry.id, entry.action)
-      else if (entry.type === 'custom-render')
-        startEagerScript(entry.id, entry.renderer)
     }
   }