fix(hub): limit eager scripts to existing dock entry points

Author: dvcolomban

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

@@ -67,16 +67,16 @@ 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?, eager? }`. `importName` defaults to `'default'` and `eager` defaults to `false`. Every dock entry can carry a page-level `clientScript`, including JSON-render entries. By default, it runs inside the host page when the dock entry is first activated, before its activation script. An `action` entry also runs its `action` on each activation, while a `custom-render` entry initializes its `renderer` after selection so it can mount into the panel.
+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. Page setup and activation scripts initialize independently, even when they import the same export. Both the reference hub UI and `createDevframeClientRuntime()` honor these settings ([Hub API reference](/references/hub-api#dock-client-script-fields)).
+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)).
 
 The exported function (`DockClientScriptContext`) receives the client context and two dock-scoped extras:
 
 - **`current`** holds this entry's state: `entryMeta`, `isActive`, `domElements`, `events` (`entry:activated`, `entry:deactivated`, `entry:updated`, `dom:panel:mounted`, `dom:iframe:mounted`).
 - **`messages`**: an entry-scoped messages client (`category` defaults to the entry id; `info`/`warn`/`error`/`success`/`debug` shortcuts for `add()`).
 
-Failed setup retries on the next activation, or on a dock update for eager scripts. Setup is cached per RPC connection, dock, script role and import descriptor. Action clicks always execute again.
+Failed setup retries on the next activation, or on a dock update for eager scripts. Setup is cached per RPC connection, dock and import descriptor. Action clicks always execute again.
 
 ### Shipping a client script
 

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

@@ -131,9 +131,9 @@ 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 |
-| Every user dock entry | `clientScript` (optional) | inside the host page on first activation, before the activation script |
+| `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. Page setup and activation scripts have separate caches; action clicks execute on every 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.
 
 ## Frame-nav messages
 

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

@@ -1,6 +1,5 @@
 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'
@@ -84,7 +83,7 @@ describe('dock client scripts', () => {
   })
 })
 
-it.each(['iframe', 'json-render'] as const)('starts a %s page script before dock activation, once per RPC client', async (type) => {
+it('starts an eager iframe script before dock activation, once per RPC client', async () => {
   expect.assertions(3)
   let attempts = 0
   globalThis.__DEVFRAME_CLIENT_SCRIPT_ATTEMPT__ = () => {
@@ -93,7 +92,7 @@ it.each(['iframe', 'json-render'] as const)('starts a %s page script before dock
   const { rpc, sharedStates } = createStubRpc()
   const context = await createDocksContext('embedded', rpc)
   const clientScript = { eager: true, 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
+  const entry = { id: 'background-iframe', type: 'iframe', title: 'Background page script', icon: 'ph:browser', url: '/fixture', clientScript } satisfies DevframeDockEntry
   sharedStates.get('devframe:docks')!.push([entry])
   await expect.poll(() => attempts).toBe(1)
   expect(context.docks.selectedId).toBeNull()
@@ -180,35 +179,6 @@ it.each([undefined, false] as const)('keeps page setup lazy when eager is %s', a
   expect(attempt).toHaveBeenCalledOnce()
 })
 
-it.each(['action', 'custom-render'] as const)('keeps the %s activation independent of its eager page script', async (type) => {
-  expect.assertions(5)
-  const attempt = vi.fn()
-  globalThis.__DEVFRAME_CLIENT_SCRIPT_ATTEMPT__ = attempt
-  const { rpc, sharedStates } = createStubRpc()
-  const context = await createDocksContext('embedded', rpc)
-  const script = { importFrom: 'data:text/javascript,export default () => globalThis.__DEVFRAME_CLIENT_SCRIPT_ATTEMPT__()' }
-  const entry = {
-    id: `two-scripts-${type}`,
-    type,
-    title: 'Independent scripts',
-    icon: 'ph:play',
-    action: script,
-    renderer: script,
-    clientScript: { ...script, eager: true },
-  } satisfies DevframeDockEntry
-  sharedStates.get('devframe:docks')!.push([entry])
-  await expect.poll(() => attempt.mock.calls.length).toBe(1)
-  expect(context.docks.selectedId).toBeNull()
-  await context.docks.switchEntry(entry.id)
-  expect(attempt).toHaveBeenCalledTimes(2)
-  await context.docks.switchEntry(null)
-  await context.docks.switchEntry(entry.id)
-  expect(attempt).toHaveBeenCalledTimes(type === 'action' ? 3 : 2)
-  sharedStates.get('devframe:docks')!.push([{ ...entry }])
-  await nextTick()
-  expect(attempt).toHaveBeenCalledTimes(type === 'action' ? 3 : 2)
-})
-
 it('awaits an eager page setup before activation and retries it after failure', async () => {
   expect.assertions(5)
   vi.spyOn(console, 'error').mockImplementation(() => {})
@@ -225,11 +195,11 @@ it('awaits an eager page setup before activation and retries it after failure',
   const context = await createDocksContext('embedded', rpc)
   const script = { importFrom: 'data:text/javascript,export default () => globalThis.__DEVFRAME_CLIENT_SCRIPT_ATTEMPT__()' }
   const entry = {
-    id: 'retry-page-before-renderer',
-    type: 'custom-render',
+    id: 'retry-page-before-activation',
+    type: 'iframe',
     title: 'Retry page',
     icon: 'ph:play',
-    renderer: script,
+    url: '/fixture',
     clientScript: { ...script, eager: true },
   } satisfies DevframeDockEntry
   sharedStates.get('devframe:docks')!.push([entry])
@@ -239,5 +209,5 @@ it('awaits an eager page setup before activation and retries it after failure',
   expect(context.docks.selectedId).toBeNull()
   complete()
   await expect(activation).resolves.toBe(true)
-  expect(attempts).toBe(3)
+  expect(attempts).toBe(2)
 })

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 { dockScript, executeSetupScript } from './setup-script'
+import { clientScriptOf, executeSetupScript } from './setup-script'
 
 const docksContextByRpc = new WeakMap<DevframeRpcClient, DocksContext>()
 export async function createDocksContext(
@@ -238,16 +238,14 @@ export async function createDocksContext(
   }
 
   async function runPageScript(entry: DevframeDockEntry): Promise<void> {
-    if (entry.type === '~builtin' || !entry.clientScript)
+    if (entry.type !== 'iframe' || !entry.clientScript)
       return
-    await executeSetupScript(entry, scriptContext(entry), 'clientScript')
+    await executeSetupScript(entry, scriptContext(entry))
   }
 
   async function runActivationScript(entry: DevframeDockEntry): Promise<void> {
-    if (entry.type === 'action')
-      await executeSetupScript(entry, scriptContext(entry), 'action')
-    else if (entry.type === 'custom-render')
-      await executeSetupScript(entry, scriptContext(entry), 'renderer')
+    if (entry.type === 'action' || entry.type === 'custom-render')
+      await executeSetupScript(entry, scriptContext(entry))
   }
 
   /** Only explicitly eager descriptors run before activation, after the RPC connection is trusted. */
@@ -257,12 +255,10 @@ export async function createDocksContext(
     for (const entry of entries.value) {
       if (entry.type === '~builtin')
         continue
-      for (const role of ['clientScript', 'action', 'renderer'] as const) {
-        if (!dockScript(entry, role)?.eager)
-          continue
-        /** Setup reports failures and allows the next activation or publication to retry. */
-        void executeSetupScript(entry, scriptContext(entry), role, true).catch(() => {})
-      }
+      if (!clientScriptOf(entry)?.eager)
+        continue
+      /** Setup reports failures and allows the next activation or publication to retry. */
+      void executeSetupScript(entry, scriptContext(entry), true).catch(() => {})
     }
   }
 

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

@@ -2,15 +2,13 @@ import type { ClientScriptEntry, DevframeDockUserEntry } from '@devframes/hub'
 import type { DevframeRpcClient, DockClientScriptContext } from '@devframes/hub/client'
 import { clientScriptFailureHint, resolveClientModuleSpecifier } from '@devframes/hub/client'
 
-export type DockScriptRole = 'clientScript' | 'action' | 'renderer'
-
-/** Page setup and activation scripts have independent initialization lifetimes. */
-export function dockScript(entry: DevframeDockUserEntry, role: DockScriptRole): ClientScriptEntry | undefined {
-  if (role === 'clientScript')
+/** Resolve the existing script field for this dock kind. */
+export function clientScriptOf(entry: DevframeDockUserEntry): ClientScriptEntry | undefined {
+  if (entry.type === 'iframe')
     return entry.clientScript
-  if (role === 'action' && entry.type === 'action')
+  if (entry.type === 'action')
     return entry.action
-  if (role === 'renderer' && entry.type === 'custom-render')
+  if (entry.type === 'custom-render')
     return entry.renderer
 }
 
@@ -50,20 +48,19 @@ async function _executeSetupScript(
 }
 const setupPromisesByRpc = new WeakMap<DevframeRpcClient, Map<string, Promise<void>>>()
 
-/** Cache setup per RPC connection, dock and role; explicit action clicks always run again. */
+/** Cache setup per RPC connection and dock; explicit action clicks always run again. */
 export function executeSetupScript(
   entry: DevframeDockUserEntry,
   context: DockClientScriptContext,
-  role: DockScriptRole,
-  cache = role !== 'action',
+  cache = entry.type !== 'action',
 ): Promise<void> {
-  const script = dockScript(entry, role)
+  const script = clientScriptOf(entry)
   let setupPromises = setupPromisesByRpc.get(context.rpc)
   if (!setupPromises) {
     setupPromises = new Map()
     setupPromisesByRpc.set(context.rpc, setupPromises)
   }
-  const key = JSON.stringify([entry.id, role, script?.importFrom, script?.importName ?? 'default'])
+  const key = JSON.stringify([entry.id, script?.importFrom, script?.importName ?? 'default'])
   const existing = setupPromises.get(key)
   if (cache && existing)
     return existing

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

@@ -425,41 +425,6 @@ describe('createDevframeClientRuntime', () => {
   })
 })
 
-it.each(['action', 'custom-render'] as const)('loads independent page and activation scripts in the headless %s runtime', async (type) => {
-  expect.assertions(5)
-  const { rpc, states } = createStubRpc()
-  const runtime = await createDevframeClientRuntime({ rpc })
-  const attempt = vi.fn()
-  const fixture = globalThis as typeof globalThis & { __DF_ROLE_TEST__?: () => void }
-  fixture.__DF_ROLE_TEST__ = attempt
-  const script = { importFrom: 'data:text/javascript,export default () => globalThis.__DF_ROLE_TEST__()' }
-  const entry = {
-    id: 'independent-scripts',
-    type,
-    title: 'Independent scripts',
-    icon: 'ph:play',
-    clientScript: { ...script, eager: true },
-    action: script,
-    renderer: script,
-  } as DevframeDockEntry
-  try {
-    states.get('devframe:docks')!.push([entry])
-    await expect.poll(() => attempt.mock.calls.length).toBe(1)
-    expect(runtime.context.docks.selectedId).toBeNull()
-    await runtime.context.docks.switchEntry(entry.id)
-    expect(attempt).toHaveBeenCalledTimes(2)
-    await runtime.context.docks.switchEntry(null)
-    await runtime.context.docks.switchEntry(entry.id)
-    expect(attempt).toHaveBeenCalledTimes(type === 'action' ? 3 : 2)
-    states.get('devframe:docks')!.push([{ ...entry }])
-    expect(attempt).toHaveBeenCalledTimes(type === 'action' ? 3 : 2)
-  }
-  finally {
-    runtime.dispose()
-    delete fixture.__DF_ROLE_TEST__
-  }
-})
-
 it('waits for trust for eager setup and activation for lazy setup in the headless runtime', async () => {
   expect.assertions(5)
   const { rpc, states } = createStubRpc()

packages/hub/src/client/host.ts

@@ -424,16 +424,16 @@ export async function createDevframeClientRuntime(
   async function preparePageScript(entry: DevframeDockEntry): Promise<boolean> {
     if (!rpc.isTrusted)
       return false
-    if (entry.type !== '~builtin' && entry.clientScript)
-      await setupClientScript(entry.id, entry.clientScript, 'clientScript')
+    if (entry.type === 'iframe' && entry.clientScript)
+      await setupClientScript(entry.id, entry.clientScript)
     return !disposed && entryToStateMap.get(entry.id)?.entryMeta === entry
   }
 
   async function runActivationScript(entry: DevframeDockEntry): Promise<void> {
     if (entry.type === 'action')
-      await setupClientScript(entry.id, entry.action, 'action', false)
+      await setupClientScript(entry.id, entry.action, false)
     else if (entry.type === 'custom-render')
-      await setupClientScript(entry.id, entry.renderer, 'renderer')
+      await setupClientScript(entry.id, entry.renderer)
   }
 
   async function switchEntry(id?: string | null): Promise<boolean> {
@@ -446,7 +446,7 @@ export async function createDevframeClientRuntime(
     const entry = entryToStateMap.get(next ?? '')?.entryMeta
     if (entry && loadScriptsEnabled && !rpc.isTrusted)
       return false
-    if (entry?.type !== '~builtin' && entry?.clientScript && loadScriptsEnabled && !await preparePageScript(entry))
+    if (entry?.type === 'iframe' && entry.clientScript && loadScriptsEnabled && !await preparePageScript(entry))
       return false
 
     const previous = selectedId
@@ -557,22 +557,23 @@ export async function createDevframeClientRuntime(
     for (const entry of currentEntries()) {
       if (entry.type === '~builtin')
         continue
-      startEagerScript(entry.id, entry.clientScript, 'clientScript')
+      if (entry.type === 'iframe')
+        startEagerScript(entry.id, entry.clientScript)
       if (entry.type === 'action')
-        startEagerScript(entry.id, entry.action, 'action')
+        startEagerScript(entry.id, entry.action)
       else if (entry.type === 'custom-render')
-        startEagerScript(entry.id, entry.renderer, 'renderer')
+        startEagerScript(entry.id, entry.renderer)
     }
   }
 
-  function startEagerScript(entryId: string, script: ClientScriptEntry | undefined, role: string): void {
+  function startEagerScript(entryId: string, script: ClientScriptEntry | undefined): void {
     if (script?.eager)
-      void setupClientScript(entryId, script, role).catch(() => {})
+      void setupClientScript(entryId, script).catch(() => {})
   }
 
-  /** Keep page and activation setup separate even when they import the same export. */
-  function setupClientScript(entryId: string, script: ClientScriptEntry, role: string, cache = true): Promise<void> {
-    const key = JSON.stringify([entryId, role, script.importFrom, script.importName ?? 'default'])
+  /** Share eager and activation setup; explicit action invocations bypass the cache. */
+  function setupClientScript(entryId: string, script: ClientScriptEntry, cache = true): Promise<void> {
+    const key = JSON.stringify([entryId, script.importFrom, script.importName ?? 'default'])
     const existing = loadedScripts.get(key)
     if (cache && existing)
       return existing

packages/hub/src/types/docks.ts

@@ -81,8 +81,6 @@ export type DevframeDockEntryIcon = string | { light: string, dark: string }
 export type DevframeDockBadgeVariant = 'default' | 'info' | 'success' | 'warning' | 'danger'
 
 export interface DevframeDockEntryBase {
-  /** Page script run in the host page when activated, or after trust when `eager: true`. */
-  clientScript?: ClientScriptEntry
   id: string
   title: string
   icon: DevframeDockEntryIcon
@@ -238,6 +236,8 @@ export interface DevframeViewIframe extends DevframeDockEntryBase {
    * share a `frameId` may live in one group, several groups, or none.
    */
   frameId?: string
+  /** Optional page script, initialized on activation or after trust when `eager: true`. */
+  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

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