fix(hub-ui): initialize dock page scripts before activation

Author: dvcolomban

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

@@ -131,7 +131,7 @@ Which `ClientScriptEntry` field carries an entry's client script, and when it ru
 |---|---|---|
 | `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 |
+| `iframe` and renderer-backed dock entries | `clientScript` (optional) | inside the host page, after trust and before dock activation |
 
 ## Frame-nav messages
 

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

@@ -1,6 +1,8 @@
 import type { DevframeDockEntry } from '@devframes/hub'
 import type { DevframeRpcClient } from '@devframes/hub/client'
+import type {} from '@devframes/json-render/hub'
 import type { SharedState } from 'devframe/utils/shared-state'
+import { DEVFRAME_EVENTS } from 'devframe/constants'
 import { createEventEmitter } from 'devframe/utils/events'
 import { createSharedState } from 'devframe/utils/shared-state'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -52,6 +54,7 @@ afterEach(() => {
 
 describe('dock client scripts', () => {
   it('retries setup on a later activation after it fails', async () => {
+    expect.assertions(3)
     vi.spyOn(console, 'error').mockImplementation(() => {})
     let attempts = 0
     globalThis.__DEVFRAME_CLIENT_SCRIPT_ATTEMPT__ = () => {
@@ -63,11 +66,10 @@ describe('dock client scripts', () => {
     const context = await createDocksContext('embedded', rpc)
     const entry = {
       id: 'retry-client-script',
-      type: 'iframe',
+      type: 'custom-render',
       title: 'Retry client script',
       icon: 'ph:play',
-      url: '/retry',
-      clientScript: {
+      renderer: {
         importFrom: 'data:text/javascript,export default () => globalThis.__DEVFRAME_CLIENT_SCRIPT_ATTEMPT__()',
       },
     } satisfies DevframeDockEntry
@@ -81,3 +83,75 @@ describe('dock client scripts', () => {
     expect(attempts).toBe(2)
   })
 })
+
+it.each(['iframe', 'json-render'] as const)('starts a %s page script before dock activation, once per RPC client', async (type) => {
+  expect.assertions(3)
+  let attempts = 0
+  globalThis.__DEVFRAME_CLIENT_SCRIPT_ATTEMPT__ = () => {
+    attempts++
+  }
+  const { rpc, sharedStates } = createStubRpc()
+  const context = await createDocksContext('embedded', rpc)
+  const clientScript = { importFrom: 'data:text/javascript,export default () => globalThis.__DEVFRAME_CLIENT_SCRIPT_ATTEMPT__()' }
+  const entry = { id: `background-${type}`, type, title: 'Background page script', icon: 'ph:browser', url: '/fixture', view: { stateKey: 'fixture:view' }, clientScript } satisfies DevframeDockEntry
+  sharedStates.get('devframe:docks')!.push([entry])
+  await expect.poll(() => attempts).toBe(1)
+  expect(context.docks.selectedId).toBeNull()
+  await context.docks.switchEntry(entry.id)
+  expect(attempts).toBe(1)
+})
+
+it('waits for trust and keeps the same dock script bound separately to each RPC client', async () => {
+  expect.assertions(4)
+  let attempts = 0
+  globalThis.__DEVFRAME_CLIENT_SCRIPT_ATTEMPT__ = () => {
+    attempts++
+  }
+  const first = createStubRpc()
+  const second = createStubRpc()
+  Object.assign(first.rpc, { isTrusted: false })
+  await createDocksContext('embedded', first.rpc)
+  await createDocksContext('embedded', second.rpc)
+  const entry = {
+    id: 'per-rpc-page-script',
+    type: 'iframe',
+    title: 'Page commands',
+    icon: 'ph:browser',
+    url: '/fixture',
+    clientScript: { importFrom: 'data:text/javascript,export default () => globalThis.__DEVFRAME_CLIENT_SCRIPT_ATTEMPT__()' },
+  } satisfies DevframeDockEntry
+  first.sharedStates.get('devframe:docks')!.push([entry])
+  await nextTick()
+  expect(attempts).toBe(0)
+  second.sharedStates.get('devframe:docks')!.push([entry])
+  await expect.poll(() => attempts).toBe(1)
+  Object.assign(first.rpc, { isTrusted: true })
+  first.rpc.events.emit(DEVFRAME_EVENTS.client.isTrustedUpdated, true)
+  await expect.poll(() => attempts).toBe(2)
+  first.sharedStates.get('devframe:docks')!.push([{ ...entry }])
+  second.sharedStates.get('devframe:docks')!.push([{ ...entry }])
+  await nextTick()
+  expect(attempts).toBe(2)
+})
+
+it('does not invoke action docks while initializing page scripts', 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: 'explicit-action-script',
+    type: 'action',
+    title: 'Explicit action',
+    icon: 'ph:play',
+    action: { importFrom: 'data:text/javascript,export default () => globalThis.__DEVFRAME_CLIENT_SCRIPT_ATTEMPT__()' },
+  } satisfies DevframeDockEntry
+  sharedStates.get('devframe:docks')!.push([entry])
+  await nextTick()
+  expect(attempts).toBe(0)
+  await context.docks.switchEntry(entry.id)
+  expect(attempts).toBe(1)
+})

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

@@ -10,7 +10,8 @@ import { nextTick, ref } from 'vue'
 import { createDocksContext } from './context'
 import { executeSetupScript } from './setup-script'
 
-vi.mock('./setup-script', () => ({
+vi.mock('./setup-script', async importOriginal => ({
+  ...await importOriginal<typeof import('./setup-script')>(),
   executeSetupScript: vi.fn(async () => {}),
 }))
 

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

@@ -17,7 +17,7 @@ import { createDockEntryState, DEFAULT_DOCK_PANEL_STORE, DEFAULT_DOCK_SESSION_ST
 import { createClientMessagesClient } from './messages-client'
 import { dockCommandId } from './palette'
 import { registerMainFrameDockActionHandler, triggerMainFrameDockAction, useIsDockPopupOpen } from './popup'
-import { executeSetupScript } from './setup-script'
+import { clientScriptOf, executeSetupScript } from './setup-script'
 
 const docksContextByRpc = new WeakMap<DevframeRpcClient, DocksContext>()
 export async function createDocksContext(
@@ -229,17 +229,30 @@ export async function createDocksContext(
     return null
   }
 
-  const runDockSetupScript = async (entry: DevframeDockEntry) => {
-    const hasScript = entry.type === 'action' || entry.type === 'custom-render' || (entry.type === 'iframe' && entry.clientScript)
-    if (!hasScript)
-      return
-    const messagesClient = createClientMessagesClient(rpc)
-    const scriptContext: DockClientScriptContext = reactive({
+  function scriptContext(entry: DevframeDockEntry): DockClientScriptContext {
+    return reactive({
       ...toRefs(docksContext) as any,
       current: dockEntryStateMap.get(entry.id)!,
-      messages: messagesClient,
+      messages: createClientMessagesClient(rpc),
     })
-    await executeSetupScript(entry, scriptContext)
+  }
+
+  async function runDockSetupScript(entry: DevframeDockEntry): Promise<void> {
+    if (entry.type === '~builtin' || !clientScriptOf(entry))
+      return
+    await executeSetupScript(entry, scriptContext(entry))
+  }
+
+  /** Page scripts register commands before any dock panel opens; actions and renderers remain activation-driven. */
+  function startPageScripts(): void {
+    if (!rpc.isTrusted)
+      return
+    for (const entry of entries.value) {
+      if (entry.type === '~builtin' || entry.type === 'action' || !entry.clientScript)
+        continue
+      // executeSetupScript reports failures and permits a later activation or publication to retry.
+      void executeSetupScript(entry, scriptContext(entry), entry.clientScript).catch(() => {})
+    }
   }
 
   // Remember selection redirects: a member tab as its frame's live tab, and a
@@ -707,6 +720,9 @@ export async function createDocksContext(
   )
   void restoreAfterInitialization()
 
+  watch(entries, startPageScripts, { immediate: true })
+  rpc.events.on(DEVFRAME_EVENTS.client.isTrustedUpdated, startPageScripts)
+
   docksContextByRpc.set(rpc, docksContext)
   return docksContext
 }

packages/hub-ui/src/client/state/setup-script.ts

@@ -1,29 +1,27 @@
 import type { ClientScriptEntry, DevframeDockUserEntry } from '@devframes/hub'
-import type { DockClientScriptContext } from '@devframes/hub/client'
+import type { DevframeRpcClient, DockClientScriptContext } from '@devframes/hub/client'
 import { clientScriptFailureHint, resolveClientModuleSpecifier } from '@devframes/hub/client'
 
 /**
  * Resolve the {@link ClientScriptEntry} a dock entry carries: an `action`'s
- * `action`, a `custom-render`'s `renderer`, or an iframe's `clientScript`.
+ * `action`, a `custom-render`'s `renderer`, or another dock entry's `clientScript`.
  */
-function clientScriptOf(entry: DevframeDockUserEntry): ClientScriptEntry | undefined {
+export function clientScriptOf(entry: DevframeDockUserEntry): ClientScriptEntry | undefined {
   switch (entry.type) {
     case 'action':
       return entry.action
     case 'custom-render':
       return entry.renderer
-    case 'iframe':
-      return entry.clientScript
     default:
-      return undefined
+      return entry.clientScript
   }
 }
 
 async function _executeSetupScript(
   entry: DevframeDockUserEntry,
   context: DockClientScriptContext,
+  script: ClientScriptEntry | undefined,
 ): Promise<void> {
-  const script = clientScriptOf(entry)
   if (!script?.importFrom)
     throw new Error(`[@devframes/hub-ui] Dock entry "${entry.id}" carries no client script to run`)
   // A bare specifier resolves through the host-advertised template; URL
@@ -53,22 +51,29 @@ async function _executeSetupScript(
     throw error
   }
 }
-const _setupPromises = new Map<string, Promise<void>>()
+const setupPromisesByRpc = new WeakMap<DevframeRpcClient, Map<string, Promise<void>>>()
 export function executeSetupScript(
   entry: DevframeDockUserEntry,
   context: DockClientScriptContext,
+  script = clientScriptOf(entry),
 ): Promise<void> {
+  let setupPromises = setupPromisesByRpc.get(context.rpc)
+  if (!setupPromises) {
+    setupPromises = new Map()
+    setupPromisesByRpc.set(context.rpc, setupPromises)
+  }
+  const key = JSON.stringify([entry.id, script?.importFrom, script?.importName ?? 'default'])
   // Actions should re-execute on every click; only cache non-action scripts
-  if (entry.type !== 'action' && _setupPromises.has(entry.id))
-    return _setupPromises.get(entry.id)!
-  const promise = _executeSetupScript(entry, context)
+  if (entry.type !== 'action' && setupPromises.has(key))
+    return setupPromises.get(key)!
+  const promise = _executeSetupScript(entry, context, script)
   if (entry.type !== 'action') {
-    _setupPromises.set(entry.id, promise)
+    setupPromises.set(key, promise)
     promise.catch(() => {
       // A failed setup must not poison this entry permanently. The caller still
       // receives the rejection, while a later activation or update may retry.
-      if (_setupPromises.get(entry.id) === promise)
-        _setupPromises.delete(entry.id)
+      if (setupPromises.get(key) === promise)
+        setupPromises.delete(key)
     })
   }
   return promise

packages/hub/src/types/docks.ts

@@ -81,6 +81,8 @@ export type DevframeDockEntryIcon = string | { light: string, dark: string }
 export type DevframeDockBadgeVariant = 'default' | 'info' | 'success' | 'warning' | 'danger'
 
 export interface DevframeDockEntryBase {
+  /** Page script initialized in the host page independently of dock activation or renderer type. */
+  clientScript?: ClientScriptEntry
   id: string
   title: string
   icon: DevframeDockEntryIcon
@@ -231,10 +233,6 @@ export interface DevframeViewIframe extends DevframeDockEntryBase {
    * share a `frameId` may live in one group, several groups, or none.
    */
   frameId?: string
-  /**
-   * Optional client script to import into the iframe
-   */
-  clientScript?: ClientScriptEntry
   /**
    * Soft-navigation target within a shared frame. Set on a **member** dock
    * (one of several docks sharing a {@link frameId}) to describe which internal

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

@@ -82,6 +82,7 @@ export interface DevframeDockActivation {
   params?: Record<string, unknown>;
 }
 export interface DevframeDockEntryBase {
+  clientScript?: ClientScriptEntry;
   id: string;
   title: string;
   icon: DevframeDockEntryIcon;
@@ -315,7 +316,6 @@ export interface DevframeViewIframe extends DevframeDockEntryBase {
     openExternal?: boolean;
   };
   frameId?: string;
-  clientScript?: ClientScriptEntry;
   navTarget?: NavTarget;
   subTabs?: FrameSubTabsConfig;
   remote?: boolean | RemoteDockOptions;