feat(kit): basic launcher support

antfu · antfu · commit d4e22b5e2e9f · 2025-11-13T16:51:23.000+09:00
diff --git a/packages/core/playground/vite.config.ts b/packages/core/playground/vite.config.ts
@@ -94,6 +94,27 @@ export default defineConfig({
             action: ctx.utils.createSimpleClientScript(() => {}),
           })
 
+          ctx.docks.register({
+            id: 'launcher',
+            type: 'launcher',
+            icon: 'ph:rocket-launch-duotone',
+            title: 'Launcher',
+            launcher: {
+              title: 'Launcher My Cool App',
+              onLaunch: async () => {
+                await new Promise(resolve => setTimeout(resolve, 1000))
+
+                ctx.docks.update({
+                  id: 'launcher',
+                  icon: 'ph:rocket-launch-fill',
+                  type: 'iframe',
+                  title: 'My Cool App is Ready',
+                  url: 'https://antfu.me',
+                })
+              },
+            },
+          })
+
           let count = 1
           // eslint-disable-next-line unimport/auto-insert
           setInterval(() => {
diff --git a/packages/core/src/client/standalone/App.vue b/packages/core/src/client/standalone/App.vue
@@ -23,7 +23,7 @@ const context: DocksContext = await createDocksContext(
   rpcReturn,
 )
 
-context.docks.selected ||= context.docks.entries[0] || null
+context.docks.selectedId ||= context.docks.entries[0]?.id ?? null
 
 const { selectDockEntry } = useStateHandlers(context)
 </script>
@@ -43,7 +43,7 @@ const { selectDockEntry } = useStateHandlers(context)
       />
     </div>
     <div>
-      <div id="vite-devtools-views-container" ref="viewsContainer" />
+      <div id="vite-devtools-views-container" ref="viewsContainer" class="pointer-events-auto" />
       <ViewEntry
         v-if="context.docks.selected && viewsContainer"
         :key="context.docks.selected.id"
diff --git a/packages/core/src/client/webcomponents/.generated/css.ts b/packages/core/src/client/webcomponents/.generated/css.ts
diff --git a/packages/core/src/client/webcomponents/components/Dock.vue b/packages/core/src/client/webcomponents/components/Dock.vue
@@ -245,6 +245,12 @@ onMounted(() => {
       id="vite-devtools-glowing"
       :class="context.panel.isDragging ? 'op60!' : ''"
     />
+    <slot
+      :context="context"
+      :dock-el="dockEl"
+      :selected="context.docks.selected"
+      :panel-margins="panelMargins"
+    />
     <div
       id="vite-devtools-dock-container"
       ref="dockEl"
@@ -275,11 +281,5 @@ onMounted(() => {
         />
       </div>
     </div>
-    <slot
-      :context="context"
-      :dock-el="dockEl"
-      :selected="context.docks.selected"
-      :panel-margins="panelMargins"
-    />
   </div>
 </template>
diff --git a/packages/core/src/client/webcomponents/components/DockPanel.vue b/packages/core/src/client/webcomponents/components/DockPanel.vue
@@ -102,7 +102,6 @@ const panelStyle = computed(() => {
 
   const style: CSSProperties = {
     position: 'fixed',
-    zIndex: -1,
     pointerEvents: (panel.isDragging || panel.isResizing) ? 'none' : 'auto',
     width: `min(${store.width}vw, calc(100vw - ${marginHorizontal}px))`,
     height: `min(${store.height}vh, calc(100vh - ${marginVertical}px))`,
@@ -178,12 +177,11 @@ onMounted(() => {
         border: '1px solid #8883',
         borderRadius: '0.5rem',
       }"
-      rounded
     />
     <div
       id="vite-devtools-views-container"
       ref="viewsContainer"
-      class="absolute inset-0"
+      class="absolute inset-0 pointer-events-none"
     />
   </div>
 </template>
diff --git a/packages/core/src/client/webcomponents/components/DockPanelResizer.vue b/packages/core/src/client/webcomponents/components/DockPanelResizer.vue
@@ -82,7 +82,7 @@ watch(
   <div
     id="vite-devtools-resize-container"
     ref="container"
-    class="w-full h-full absolute left-0 right-0 bottom-0 top-0 antialiased"
+    class="w-full h-full absolute left-0 right-0 bottom-0 top-0 antialiased pointer-events-auto"
   >
     <!-- Handlers -->
     <div
diff --git a/packages/core/src/client/webcomponents/components/ViewEntry.vue b/packages/core/src/client/webcomponents/components/ViewEntry.vue
@@ -5,6 +5,7 @@ import type { CSSProperties } from 'vue'
 import type { PresistedDomViewsManager } from '../utils/PresistedDomViewsManager'
 import ViewCustomRenderer from './ViewCustomRenderer.vue'
 import ViewIframe from './ViewIframe.vue'
+import ViewLauncher from './ViewLauncher.vue'
 
 defineProps<{
   context: DocksContext
@@ -31,6 +32,11 @@ defineProps<{
     :presisted-doms="presistedDoms"
     :div-style="divStyle"
   />
+  <ViewLauncher
+    v-else-if="entry.type === 'launcher'"
+    :context
+    :entry
+  />
   <div v-else>
     Unknown entry: {{ entry }}
   </div>
diff --git a/packages/core/src/client/webcomponents/components/ViewLauncher.vue b/packages/core/src/client/webcomponents/components/ViewLauncher.vue
@@ -0,0 +1,28 @@
+<script setup lang="ts">
+import type { DevToolsViewLauncher } from '@vitejs/devtools-kit'
+import type { DocksContext } from '@vitejs/devtools-kit/client'
+import DockIcon from './DockIcon.vue'
+
+const props = defineProps<{
+  context: DocksContext
+  entry: DevToolsViewLauncher
+}>()
+
+function onLaunch() {
+  props.context.rpc.$call('vite:core:on-dock-launch', props.entry.id)
+}
+</script>
+
+<template>
+  <div class="flex flex-col gap-4 items-center justify-center h-full relative">
+    <DockIcon :icon="entry.icon" class="w-10 h-10" />
+    <h1 class="text-2xl font-bold">
+      {{ entry.launcher.title }}
+    </h1>
+    <p>{{ entry.launcher.description }}</p>
+    <button class="bg-lime6 px4 py1 rounded hover:bg-lime7 transition-all duration-300" @click="onLaunch">
+      Launch
+    </button>
+    <p>{{ entry.launcher.status }}</p>
+  </div>
+</template>
diff --git a/packages/core/src/client/webcomponents/state/dock.ts b/packages/core/src/client/webcomponents/state/dock.ts
@@ -82,8 +82,9 @@ export async function createDocksContext(
     return _docksContext
   }
 
-  const selected = ref<DevToolsDockEntry | null>(null)
+  const selectedId = ref<string | null>(null)
   const dockEntries = await useDocksEntries(rpcReturn)
+  const selected = computed(() => dockEntries.value.find(entry => entry.id === selectedId.value) ?? null)
 
   const dockEntryStateMap: Map<string, DockEntryState> = reactive(new Map())
   watchEffect(() => {
@@ -109,19 +110,20 @@ export async function createDocksContext(
       isVertical: computed(() => panelStore.value.position === 'left' || panelStore.value.position === 'right'),
     },
     docks: {
+      selectedId,
       selected,
       entries: dockEntries,
       entryToStateMap: markRaw(dockEntryStateMap),
       getStateById: (id: string) => dockEntryStateMap.get(id),
       switchEntry: async (id: string | null) => {
         if (id === null) {
-          selected.value = null
+          selectedId.value = null
           return true
         }
         const entry = dockEntries.value.find(e => e.id === id)
         if (!entry)
           return false
-        selected.value = entry
+        selectedId.value = entry.id
         // TODO: run action
         return true
       },
diff --git a/packages/core/src/client/webcomponents/state/state.ts b/packages/core/src/client/webcomponents/state/state.ts
@@ -39,10 +39,10 @@ export function useStateHandlers(
   async function selectDockEntry(entry?: DevToolsDockEntry) {
     if (!entry) {
       context.panel.store.open = false
-      context.docks.selected = null
+      context.docks.selectedId = null
       return
     }
-    if (context.docks.selected?.id === entry.id) {
+    if (context.docks.selectedId === entry.id) {
       return
     }
 
@@ -62,7 +62,7 @@ export function useStateHandlers(
       await setupScript(entry, scriptContext)
     }
 
-    context.docks.selected = entry
+    context.docks.selectedId = entry.id
     context.panel.store.open = true
   }
 
diff --git a/packages/core/src/node/rpc/index.ts b/packages/core/src/node/rpc/index.ts
@@ -1,6 +1,7 @@
 import type { RpcDefinitionsFilter, RpcDefinitionsToFunctions } from '@vitejs/devtools-kit'
 import { listDockEntries } from './list-dock-entries'
 import { listRpcFunctions } from './list-rpc-functions'
+import { onDockLaunch } from './on-dock-launch'
 import { openInEditor } from './open-in-editor'
 import { openInFinder } from './open-in-finder'
 
@@ -9,6 +10,7 @@ export const builtinRpcFunctions = [
   listDockEntries,
   openInEditor,
   openInFinder,
+  onDockLaunch,
 ] as const
 
 export type ServerFunctions = RpcDefinitionsToFunctions<typeof builtinRpcFunctions>
diff --git a/packages/core/src/node/rpc/on-dock-launch.ts b/packages/core/src/node/rpc/on-dock-launch.ts
@@ -0,0 +1,58 @@
+import { defineRpcFunction } from '@vitejs/devtools-kit'
+
+export const onDockLaunch = defineRpcFunction({
+  name: 'vite:core:on-dock-launch',
+  type: 'action',
+  setup: (context) => {
+    const launchMap = new Map<string, Promise<void>>()
+    return {
+      handler: async (entryId: string) => {
+        if (launchMap.has(entryId)) {
+          return launchMap.get(entryId)!
+        }
+
+        const entry = context.docks.values().find(entry => entry.id === entryId)
+        if (!entry) {
+          throw new Error(`Dock entry with id "${entryId}" not found`)
+        }
+        if (entry.type !== 'launcher') {
+          throw new Error(`Dock entry with id "${entryId}" is not a launcher`)
+        }
+        try {
+          context.docks.update({
+            ...entry,
+            launcher: {
+              ...entry.launcher,
+              status: 'loading',
+            },
+          })
+          const promise = entry.launcher.onLaunch()
+          launchMap.set(entryId, promise)
+          const result = await promise
+          const newEntry = context.docks.values().find(entry => entry.id === entryId) || entry
+          if (newEntry.type === 'launcher') {
+            context.docks.update({
+              ...newEntry,
+              launcher: {
+                ...newEntry.launcher,
+                status: 'success',
+              },
+            })
+          }
+          return result
+        }
+        catch (error) {
+          console.error(`[VITE DEVTOOLS] Error launching dock entry "${entryId}"`, error)
+          context.docks.update({
+            ...entry,
+            launcher: {
+              ...entry.launcher,
+              status: 'error',
+              error: error instanceof Error ? error.message : String(error),
+            },
+          })
+        }
+      },
+    }
+  },
+})
diff --git a/packages/kit/src/client/docks.ts b/packages/kit/src/client/docks.ts
@@ -55,7 +55,8 @@ export interface DocksPanelContext {
 }
 
 export interface DocksEntriesContext {
-  selected: DevToolsDockEntry | null
+  selectedId: string | null
+  readonly selected: DevToolsDockEntry | null
   entries: DevToolsDockEntry[]
   entryToStateMap: Map<string, DockEntryState>
   /**
diff --git a/packages/kit/src/types/docks.ts b/packages/kit/src/types/docks.ts
@@ -0,0 +1,78 @@
+// TODO: refine categories more clearly
+
+export interface DevToolsDockHost {
+  views: Map<string, DevToolsDockEntry>
+  register: (entry: DevToolsDockEntry) => void
+  update: (entry: DevToolsDockEntry) => void
+  values: () => DevToolsDockEntry[]
+}
+
+export type DevToolsDockEntryCategory = 'app' | 'framework' | 'web' | 'advanced' | 'default'
+
+export interface DevToolsDockEntryBase {
+  id: string
+  title: string
+  icon: string | { light: string, dark: string }
+  /**
+   * The default order of the entry in the dock.
+   * The higher the number the earlier it appears.
+   * @default 0
+   */
+  defaultOrder?: number
+  /**
+   * The category of the entry
+   * @default 'default'
+   */
+  category?: DevToolsDockEntryCategory
+}
+
+export interface ClientScriptEntry {
+  /**
+   * The filepath or module name to import from
+   */
+  importFrom: string
+  /**
+   * The name to import the module as
+   *
+   * @default 'default'
+   */
+  importName?: string
+}
+
+export interface DevToolsViewIframe extends DevToolsDockEntryBase {
+  type: 'iframe'
+  url: string
+  /**
+   * The id of the iframe, if multiple tabs is assigned with the same id, the iframe will be shared.
+   *
+   * When not provided, it would be treated as a unique frame.
+   */
+  frameId?: string
+  /**
+   * Optional client script to import into the iframe
+   */
+  clientScript?: ClientScriptEntry
+}
+
+export interface DevToolsViewLauncher extends DevToolsDockEntryBase {
+  type: 'launcher'
+  launcher: {
+    title: string
+    status?: 'idle' | 'loading' | 'success' | 'error'
+    error?: string
+    description?: string
+    onLaunch: () => Promise<void>
+  }
+}
+
+export interface DevToolsViewAction extends DevToolsDockEntryBase {
+  type: 'action'
+  action: ClientScriptEntry
+}
+
+export interface DevToolsViewCustomRender extends DevToolsDockEntryBase {
+  type: 'custom-render'
+  renderer: ClientScriptEntry
+}
+
+export type DevToolsDockEntry = DevToolsViewIframe | DevToolsViewAction | DevToolsViewCustomRender | DevToolsViewLauncher
diff --git a/packages/kit/src/types/index.ts b/packages/kit/src/types/index.ts
@@ -1,3 +1,4 @@
+export * from './docks'
 export * from './rpc'
 export * from './rpc-augments'
 export * from './utils'
diff --git a/packages/kit/src/types/views.ts b/packages/kit/src/types/views.ts
diff --git a/packages/kit/src/types/vite-plugin.ts b/packages/kit/src/types/vite-plugin.ts

Original file line number	Diff line number	Diff line change
`@@ -82,7 +82,7 @@ watch(`
`82`	`82`	`<div`
`83`	`83`	`id="vite-devtools-resize-container"`
`84`	`84`	`ref="container"`
`85`		`- class="w-full h-full absolute left-0 right-0 bottom-0 top-0 antialiased"`
	`85`	`+ class="w-full h-full absolute left-0 right-0 bottom-0 top-0 antialiased pointer-events-auto"`
`86`	`86`	`>`
`87`	`87`	`<!-- Handlers -->`
`88`	`88`	`<div`
Original file line number	Diff line number	Diff line change
`@@ -39,10 +39,10 @@ export function useStateHandlers(`
`39`	`39`	`async function selectDockEntry(entry?: DevToolsDockEntry) {`
`40`	`40`	`if (!entry) {`
`41`	`41`	`context.panel.store.open = false`
`42`		`- context.docks.selected = null`
	`42`	`+ context.docks.selectedId = null`
`43`	`43`	`return`
`44`	`44`	`}`
`45`		`- if (context.docks.selected?.id === entry.id) {`
	`45`	`+ if (context.docks.selectedId === entry.id) {`
`46`	`46`	`return`
`47`	`47`	`}`
`48`	`48`
`@@ -62,7 +62,7 @@ export function useStateHandlers(`
`62`	`62`	`await setupScript(entry, scriptContext)`
`63`	`63`	`}`
`64`	`64`
`65`		`- context.docks.selected = entry`
	`65`	`+ context.docks.selectedId = entry.id`
`66`	`66`	`context.panel.store.open = true`
`67`	`67`	`}`
`68`	`68`