feat(hub): support eager iframe client scripts

Author: posva

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

@@ -67,7 +67,9 @@ A client-only dock can also carry `type: 'json-render'` with an inline [JSON-ren
 
 ## Dock client scripts
 
-A client script is a `ClientScriptEntry`: `{ importFrom, importName? }` (`importName` defaults `'default'`). The field varies by entry kind: an `action` entry's `action` runs when the dock button is activated, a `custom-render` entry's `renderer` renders its panel, and an `iframe` entry's optional `clientScript` runs alongside the iframe panel inside the host page ([Hub API reference](/references/hub-api#dock-client-script-fields)).
+A client script is a `ClientScriptEntry`: `{ importFrom, importName?, eager? }` (`importName` defaults `'default'`). The field varies by entry kind: an `action` entry's `action` runs when the dock button is activated, a `custom-render` entry's `renderer` renders its panel, and an `iframe` entry's optional `clientScript` runs alongside the iframe panel inside the host page ([Hub API reference](/references/hub-api#dock-client-script-fields)).
+
+Hub UI normally imports an iframe's client script when its dock is first activated. Set `eager: true` when the script must start observing the host app earlier: the module is imported and its exported function runs once, as soon as both the client context and dock entry are available. This is execution timing, not module preloading; it does not wait for the dock panel to open.
 
 The exported function (`DockClientScriptContext`) receives the client context and two dock-scoped extras:
 

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

@@ -127,6 +127,8 @@ The properties of `DevframeClientContext`: [The client context](/guide/client-co
 
 Which `ClientScriptEntry` field carries an entry's client script, and when it runs: [Dock client scripts](/guide/client-context#dock-client-scripts).
 
+Every client script specifies `importFrom` and may specify `importName` (default: `default`). An iframe `clientScript` may additionally set `eager: true` to import and execute once as soon as the client context and dock entry are available, before activation.
+
 | Entry kind | Field | Runs |
 |---|---|---|
 | `action` | `action` | when the dock button is activated |

packages/devframe/src/types/devframe.ts

@@ -336,6 +336,13 @@ export interface DevframeDockDefaults {
      * @default 'default'
      */
     importName?: string
+    /**
+     * Import and execute this script as soon as the client context and dock
+     * entry are available, without waiting for the dock to be activated.
+     *
+     * When omitted, the client runtime keeps its normal loading policy.
+     */
+    eager?: boolean
   }
 }
 

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

@@ -76,6 +76,45 @@ async function flushRestore(): Promise<void> {
 }
 
 describe('createDocksContext', () => {
+  it('runs eager iframe client scripts before activation', async () => {
+    const { rpc, sharedStates } = createStubRpc()
+    const executeSetupScriptMock = vi.mocked(executeSetupScript)
+    executeSetupScriptMock.mockClear()
+    const context = await createDocksContext('embedded', rpc)
+    const eagerEntry = {
+      id: 'eager',
+      type: 'iframe',
+      title: 'Eager',
+      icon: 'ph:play',
+      url: '/eager',
+      clientScript: { importFrom: '/eager-client.js', eager: true },
+    } satisfies DevframeDockEntry
+    const activationEntry = {
+      id: 'activation',
+      type: 'iframe',
+      title: 'Activation',
+      icon: 'ph:play',
+      url: '/activation',
+      clientScript: { importFrom: '/activation-client.js' },
+    } satisfies DevframeDockEntry
+
+    sharedStates.get('devframe:docks')!.push([eagerEntry, activationEntry])
+    await flushRestore()
+
+    expect(executeSetupScriptMock).toHaveBeenCalledOnce()
+    expect(executeSetupScriptMock).toHaveBeenLastCalledWith(
+      eagerEntry,
+      expect.objectContaining({ current: expect.objectContaining({ entryMeta: eagerEntry }) }),
+    )
+
+    await context.docks.switchEntry('activation')
+    expect(executeSetupScriptMock).toHaveBeenCalledTimes(2)
+    expect(executeSetupScriptMock).toHaveBeenLastCalledWith(
+      activationEntry,
+      expect.objectContaining({ current: expect.objectContaining({ entryMeta: activationEntry }) }),
+    )
+  })
+
   it('exposes restored panel state and emits selected, hidden, and closed changes', async () => {
     expect.assertions(9)
 

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

@@ -641,6 +641,25 @@ export async function createDocksContext(
     clientType,
   })
 
+  // Hub UI normally loads an iframe client script on first activation. Some
+  // page integrations need to observe the host app sooner, so start explicitly
+  // eager scripts once the entry and complete client context are available.
+  // executeSetupScript caches non-action scripts, preventing activation from
+  // executing the same script again.
+  watch(
+    entries,
+    (list) => {
+      for (const entry of list) {
+        if (entry.type !== 'iframe' || !entry.clientScript?.eager)
+          continue
+        runDockSetupScript(entry).catch(() => {
+          // executeSetupScript already reports import and execution failures.
+        })
+      }
+    },
+    { immediate: true, flush: 'post' },
+  )
+
   registerMainFrameDockActionHandler(clientType, async (id) => {
     const entry = entries.value.find(e => e.id === id)
     if (!entry || entry.type !== 'action')

packages/hub/src/types/docks.ts

@@ -188,6 +188,13 @@ export interface ClientScriptEntry {
    * @default 'default'
    */
   importName?: string
+  /**
+   * Import and execute this script as soon as the client context and dock entry
+   * are available, without waiting for the dock to be activated.
+   *
+   * When omitted, the client runtime keeps its normal loading policy.
+   */
+  eager?: boolean
 }
 
 declare module 'devframe/types' {

tests/__snapshots__/tsnapi/@devframes/hub/index.snapshot.d.ts

@@ -5,6 +5,7 @@
 export interface ClientScriptEntry {
   importFrom: string;
   importName?: string;
+  eager?: boolean;
 }
 export interface CreateHubContextOptions extends CreateHostContextOptions {}
 export interface DevframeChildProcessExecuteOptions {

tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts

@@ -173,6 +173,7 @@ export interface DevframeDockDefaults {
   clientScript?: {
     importFrom: string;
     importName?: string;
+    eager?: boolean;
   };
 }
 export interface DevframeHost {