@vitejs/devtools-kit 0.0.0-alpha.3 → 0.0.0-alpha.31

package/dist/constants.d.mts

@@ -0,0 +1,7 @@
+import { C as DevToolsDocksUserSettings } from "./client-script-BOHKZVPh.mjs";
+
+//#region src/constants.d.ts
+declare const DEFAULT_CATEGORIES_ORDER: Record<string, number>;
+declare const DEFAULT_STATE_USER_SETTINGS: () => DevToolsDocksUserSettings;
+//#endregion
+export { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS };

package/dist/constants.mjs

@@ -0,0 +1,20 @@
+//#region src/constants.ts
+const DEFAULT_CATEGORIES_ORDER = {
+	"~viteplus": -1e3,
+	"default": 0,
+	"app": 100,
+	"framework": 200,
+	"web": 300,
+	"advanced": 400,
+	"~builtin": 1e3
+};
+const DEFAULT_STATE_USER_SETTINGS = () => ({
+	docksHidden: [],
+	docksCategoriesHidden: [],
+	docksPinned: [],
+	docksCustomOrder: {},
+	showIframeAddressBar: false
+});
+
+//#endregion
+export { DEFAULT_CATEGORIES_ORDER, DEFAULT_STATE_USER_SETTINGS };

package/dist/events-57bKw4ct.d.mts

@@ -0,0 +1,71 @@
+//#region src/types/events.d.ts
+interface EventsMap {
+  [event: string]: any;
+}
+interface EventUnsubscribe {
+  (): void;
+}
+interface EventEmitter<Events extends EventsMap> {
+  /**
+   * Calls each of the listeners registered for a given event.
+   *
+   * ```js
+   * ee.emit('tick', tickType, tickDuration)
+   * ```
+   *
+   * @param event The event name.
+   * @param args The arguments for listeners.
+   */
+  emit: <K extends keyof Events>(event: K, ...args: Parameters<Events[K]>) => void;
+  /**
+   * Calls the listeners for a given event once and then removes the listener.
+   *
+   * @param event The event name.
+   * @param args The arguments for listeners.
+   */
+  emitOnce: <K extends keyof Events>(event: K, ...args: Parameters<Events[K]>) => void;
+  /**
+   * Event names in keys and arrays with listeners in values.
+   *
+   * @internal
+   */
+  _listeners: Partial<{ [E in keyof Events]: Events[E][] }>;
+  /**
+   * Add a listener for a given event.
+   *
+   * ```js
+   * const unbind = ee.on('tick', (tickType, tickDuration) => {
+   *   count += 1
+   * })
+   *
+   * disable () {
+   *   unbind()
+   * }
+   * ```
+   *
+   * @param event The event name.
+   * @param cb The listener function.
+   * @returns Unbind listener from event.
+   */
+  on: <K extends keyof Events>(event: K, cb: Events[K]) => EventUnsubscribe;
+  /**
+   * Add a listener for a given event once.
+   *
+   * ```js
+   * const unbind = ee.once('tick', (tickType, tickDuration) => {
+   *   count += 1
+   * })
+   *
+   * disable () {
+   *   unbind()
+   * }
+   * ```
+   *
+   * @param event The event name.
+   * @param cb The listener function.
+   * @returns Unbind listener from event.
+   */
+  once: <K extends keyof Events>(event: K, cb: Events[K]) => EventUnsubscribe;
+}
+//#endregion
+export { EventUnsubscribe as n, EventsMap as r, EventEmitter as t };

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { $ as DevToolsViewAction, A as ConnectionMeta, B as DevToolsTerminalSessionBase, C as DevToolsDocksUserSettings, D as RpcFunctionsHost, E as RpcBroadcastOptions, F as DevToolsViewHost, G as DevToolsRpcSharedStates, H as DevToolsTerminalStatus, I as DevToolsChildProcessExecuteOptions, J as DevToolsDockEntryBase, K as ClientScriptEntry, L as DevToolsChildProcessTerminalSession, M as DevToolsNodeContext, N as DevToolsNodeUtils, O as RpcSharedStateGetOptions, P as DevToolsPluginOptions, Q as DevToolsDockUserEntry, R as DevToolsTerminalHost, S as Thenable, T as DevToolsNodeRpcSessionMeta, U as DevToolsRpcClientFunctions, V as DevToolsTerminalSessionStreamChunkEvent, W as DevToolsRpcServerFunctions, X as DevToolsDockEntryIcon, Y as DevToolsDockEntryCategory, Z as DevToolsDockHost, _ as RpcDefinitionsToFunctions, b as EntriesToObject, et as DevToolsViewBuiltin, g as RpcDefinitionsFilter, h as defineRpcFunction, it as DevToolsViewLauncherStatus, j as DevToolsCapabilities, k as RpcSharedStateHost, nt as DevToolsViewIframe, q as DevToolsDockEntry, rt as DevToolsViewLauncher, tt as DevToolsViewCustomRender, v as PluginWithDevTools, w as DevToolsNodeRpcSession, x as PartialWithoutId, y as ViteConfigDevtoolsOptions, z as DevToolsTerminalSession } from "./client-script-BOHKZVPh.mjs";
+import { n as EventUnsubscribe, r as EventsMap, t as EventEmitter } from "./events-57bKw4ct.mjs";
+export { ClientScriptEntry, ConnectionMeta, DevToolsCapabilities, DevToolsChildProcessExecuteOptions, DevToolsChildProcessTerminalSession, DevToolsDockEntry, DevToolsDockEntryBase, DevToolsDockEntryCategory, DevToolsDockEntryIcon, DevToolsDockHost, DevToolsDockUserEntry, DevToolsDocksUserSettings, DevToolsNodeContext, DevToolsNodeRpcSession, DevToolsNodeRpcSessionMeta, DevToolsNodeUtils, DevToolsPluginOptions, DevToolsRpcClientFunctions, DevToolsRpcServerFunctions, DevToolsRpcSharedStates, DevToolsTerminalHost, DevToolsTerminalSession, DevToolsTerminalSessionBase, DevToolsTerminalSessionStreamChunkEvent, DevToolsTerminalStatus, DevToolsViewAction, DevToolsViewBuiltin, DevToolsViewCustomRender, DevToolsViewHost, DevToolsViewIframe, DevToolsViewLauncher, DevToolsViewLauncherStatus, EntriesToObject, EventEmitter, EventUnsubscribe, EventsMap, PartialWithoutId, PluginWithDevTools, RpcBroadcastOptions, RpcDefinitionsFilter, RpcDefinitionsToFunctions, RpcFunctionsHost, RpcSharedStateGetOptions, RpcSharedStateHost, Thenable, ViteConfigDevtoolsOptions, defineRpcFunction };

package/dist/index.mjs

@@ -0,0 +1,7 @@
+import { createDefineWrapperWithContext } from "@vitejs/devtools-rpc";
+
+//#region src/utils/define.ts
+const defineRpcFunction = createDefineWrapperWithContext();
+
+//#endregion
+export { defineRpcFunction };

package/dist/utils/events.d.mts

@@ -0,0 +1,9 @@
+import { r as EventsMap, t as EventEmitter } from "../events-57bKw4ct.mjs";
+
+//#region src/utils/events.d.ts
+/**
+ * Create event emitter.
+ */
+declare function createEventEmitter<Events extends EventsMap>(): EventEmitter<Events>;
+//#endregion
+export { createEventEmitter };

package/dist/utils/events.mjs

@@ -0,0 +1,41 @@
+//#region src/utils/events.ts
+/**
+* Create event emitter.
+*/
+function createEventEmitter() {
+	const _listeners = {};
+	function emit(event, ...args) {
+		const callbacks = _listeners[event] || [];
+		for (let i = 0, length = callbacks.length; i < length; i++) {
+			const callback = callbacks[i];
+			if (callback) callback(...args);
+		}
+	}
+	function emitOnce(event, ...args) {
+		emit(event, ...args);
+		delete _listeners[event];
+	}
+	function on(event, cb) {
+		(_listeners[event] ||= []).push(cb);
+		return () => {
+			_listeners[event] = _listeners[event]?.filter((i) => cb !== i);
+		};
+	}
+	function once(event, cb) {
+		const unsubscribe = on(event, ((...args) => {
+			unsubscribe();
+			return cb(...args);
+		}));
+		return unsubscribe;
+	}
+	return {
+		_listeners,
+		emit,
+		emitOnce,
+		on,
+		once
+	};
+}
+
+//#endregion
+export { createEventEmitter };

package/dist/utils/nanoid.d.mts

@@ -0,0 +1,4 @@
+//#region src/utils/nanoid.d.ts
+declare function nanoid(size?: number): string;
+//#endregion
+export { nanoid };

package/dist/utils/nanoid.mjs

@@ -0,0 +1,11 @@
+//#region src/utils/nanoid.ts
+const urlAlphabet = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
+function nanoid(size = 21) {
+	let id = "";
+	let i = size;
+	while (i--) id += urlAlphabet[Math.random() * 64 | 0];
+	return id;
+}
+
+//#endregion
+export { nanoid };

package/dist/utils/shared-state.d.mts

@@ -0,0 +1,53 @@
+import { t as EventEmitter } from "../events-57bKw4ct.mjs";
+import { Objectish, Patch, Patch as SharedStatePatch } from "immer";
+
+//#region src/utils/shared-state.d.ts
+type ImmutablePrimitive = undefined | null | boolean | string | number | Function;
+type Immutable<T> = T extends ImmutablePrimitive ? T : T extends Array<infer U> ? ImmutableArray<U> : T extends Map<infer K, infer V> ? ImmutableMap<K, V> : T extends Set<infer M> ? ImmutableSet<M> : ImmutableObject<T>;
+type ImmutableArray<T> = ReadonlyArray<Immutable<T>>;
+type ImmutableMap<K, V> = ReadonlyMap<Immutable<K>, Immutable<V>>;
+type ImmutableSet<T> = ReadonlySet<Immutable<T>>;
+type ImmutableObject<T> = { readonly [K in keyof T]: Immutable<T[K]> };
+/**
+ * State host that is immutable by default with explicit mutate.
+ */
+interface SharedState<T> {
+  /**
+   * Get the current state. Immutable.
+   */
+  value: () => Immutable<T>;
+  /**
+   * Subscribe to state changes.
+   */
+  on: EventEmitter<SharedStateEvents<T>>['on'];
+  /**
+   * Mutate the state.
+   */
+  mutate: (fn: (state: T) => void, syncId?: string) => void;
+  /**
+   * Apply patches to the state.
+   */
+  patch: (patches: Patch[], syncId?: string) => void;
+  /**
+   * Sync IDs that have been applied to the state.
+   */
+  syncIds: Set<string>;
+}
+interface SharedStateEvents<T> {
+  updated: (fullState: T, patches: Patch[] | undefined, syncId: string) => void;
+}
+interface SharedStateOptions<T> {
+  /**
+   * Initial state.
+   */
+  initialValue: T;
+  /**
+   * Enable patches.
+   *
+   * @default false
+   */
+  enablePatches?: boolean;
+}
+declare function createSharedState<T extends Objectish>(options: SharedStateOptions<T>): SharedState<T>;
+//#endregion
+export { Immutable, ImmutableArray, ImmutableMap, ImmutableObject, ImmutableSet, SharedState, SharedStateEvents, SharedStateOptions, type SharedStatePatch, createSharedState };

package/dist/utils/shared-state.mjs

@@ -0,0 +1,38 @@
+import { createEventEmitter } from "./events.mjs";
+import { nanoid } from "./nanoid.mjs";
+import { applyPatches, enablePatches, produce, produceWithPatches } from "immer";
+
+//#region src/utils/shared-state.ts
+function createSharedState(options) {
+	const { enablePatches: enablePatches$1 = false } = options;
+	const events = createEventEmitter();
+	let state = options.initialValue;
+	const syncIds = /* @__PURE__ */ new Set();
+	return {
+		on: events.on,
+		value: () => state,
+		patch: (patches, syncId = nanoid()) => {
+			if (syncIds.has(syncId)) return;
+			enablePatches();
+			state = applyPatches(state, patches);
+			syncIds.add(syncId);
+			events.emit("updated", state, void 0, syncId);
+		},
+		mutate: (fn, syncId = nanoid()) => {
+			if (syncIds.has(syncId)) return;
+			syncIds.add(syncId);
+			if (enablePatches$1) {
+				const [newState, patches] = produceWithPatches(state, fn);
+				state = newState;
+				events.emit("updated", state, patches, syncId);
+			} else {
+				state = produce(state, fn);
+				events.emit("updated", state, void 0, syncId);
+			}
+		},
+		syncIds
+	};
+}
+
+//#endregion
+export { createSharedState };

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@vitejs/devtools-kit",
   "type": "module",
-  "version": "0.0.0-alpha.3",
+  "version": "0.0.0-alpha.31",
   "description": "Vite DevTools Kit",
   "author": "VoidZero Inc.",
   "license": "MIT",
   "homepage": "https://github.com/vitejs/devtools#readme",
   "repository": {
-    "directory": "packages/devtools-kit",
+    "directory": "packages/kit",
     "type": "git",
     "url": "git+https://github.com/vitejs/devtools.git"
   },
@@ -19,26 +19,31 @@
   ],
   "sideEffects": false,
   "exports": {
-    ".": "./dist/index.js",
-    "./client": "./dist/client.js",
+    ".": "./dist/index.mjs",
+    "./client": "./dist/client.mjs",
+    "./constants": "./dist/constants.mjs",
+    "./utils/events": "./dist/utils/events.mjs",
+    "./utils/nanoid": "./dist/utils/nanoid.mjs",
+    "./utils/shared-state": "./dist/utils/shared-state.mjs",
     "./package.json": "./package.json"
   },
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "types": "./dist/index.d.mts",
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "peerDependencies": {
-    "vite": "npm:rolldown-vite@^7.1.14"
+    "vite": "*"
   },
   "dependencies": {
-    "birpc": "^2.6.1",
-    "@vitejs/devtools-rpc": "0.0.0-alpha.3"
+    "birpc": "^4.0.0",
+    "immer": "^11.1.3",
+    "@vitejs/devtools-rpc": "0.0.0-alpha.31"
   },
   "devDependencies": {
-    "tsdown": "^0.15.6",
-    "vite": "npm:rolldown-vite@^7.1.14"
+    "my-ua-parser": "^2.0.4",
+    "tsdown": "^0.20.2",
+    "vite": "^8.0.0-beta.13"
   },
   "scripts": {
     "build": "tsdown",

package/skills/vite-devtools-kit/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: writing-vite-devtools-integrations
+description: >
+  Creates devtools integrations for Vite using @vitejs/devtools-kit.
+  Use when building Vite plugins with devtools panels, RPC functions,
+  dock entries, shared state, or any devtools-related functionality.
+  Applies to files importing from @vitejs/devtools-kit or containing
+  devtools.setup hooks in Vite plugins.
+---
+
+# Vite DevTools Kit
+
+Build custom developer tools that integrate with Vite DevTools using `@vitejs/devtools-kit`.
+
+## Core Concepts
+
+A DevTools plugin extends a Vite plugin with a `devtools.setup(ctx)` hook. The context provides:
+
+| Property | Purpose |
+|----------|---------|
+| `ctx.docks` | Register dock entries (iframe, action, custom-render) |
+| `ctx.views` | Host static files for UI |
+| `ctx.rpc` | Register RPC functions, broadcast to clients |
+| `ctx.rpc.sharedState` | Synchronized server-client state |
+| `ctx.viteConfig` | Resolved Vite configuration |
+| `ctx.viteServer` | Dev server instance (dev mode only) |
+| `ctx.mode` | `'dev'` or `'build'` |
+
+## Quick Start: Minimal Plugin
+
+```ts
+/// <reference types="@vitejs/devtools-kit" />
+import type { Plugin } from 'vite'
+
+export default function myPlugin(): Plugin {
+  return {
+    name: 'my-plugin',
+    devtools: {
+      setup(ctx) {
+        ctx.docks.register({
+          id: 'my-plugin',
+          title: 'My Plugin',
+          icon: 'ph:puzzle-piece-duotone',
+          type: 'iframe',
+          url: 'https://example.com/devtools',
+        })
+      },
+    },
+  }
+}
+```
+
+## Quick Start: Full Integration
+
+```ts
+/// <reference types="@vitejs/devtools-kit" />
+import type { Plugin } from 'vite'
+import { fileURLToPath } from 'node:url'
+import { defineRpcFunction } from '@vitejs/devtools-kit'
+
+export default function myAnalyzer(): Plugin {
+  const data = new Map<string, { size: number }>()
+
+  return {
+    name: 'my-analyzer',
+
+    // Collect data in Vite hooks
+    transform(code, id) {
+      data.set(id, { size: code.length })
+    },
+
+    devtools: {
+      setup(ctx) {
+        // 1. Host static UI
+        const clientPath = fileURLToPath(
+          new URL('../dist/client', import.meta.url)
+        )
+        ctx.views.hostStatic('/.my-analyzer/', clientPath)
+
+        // 2. Register dock entry
+        ctx.docks.register({
+          id: 'my-analyzer',
+          title: 'Analyzer',
+          icon: 'ph:chart-bar-duotone',
+          type: 'iframe',
+          url: '/.my-analyzer/',
+        })
+
+        // 3. Register RPC function
+        ctx.rpc.register(
+          defineRpcFunction({
+            name: 'my-analyzer:get-data',
+            type: 'query',
+            setup: () => ({
+              handler: async () => Array.from(data.entries()),
+            }),
+          })
+        )
+      },
+    },
+  }
+}
+```
+
+## Namespacing Convention
+
+**CRITICAL**: Always prefix RPC functions, shared state keys, and dock IDs with your plugin name:
+
+```ts
+// Good - namespaced
+'my-plugin:get-modules'
+'my-plugin:state'
+
+// Bad - may conflict
+'get-modules'
+'state'
+```
+
+## Dock Entry Types
+
+| Type | Use Case |
+|------|----------|
+| `iframe` | Full UI panels, dashboards (most common) |
+| `action` | Buttons that trigger client-side scripts (inspectors, toggles) |
+| `custom-render` | Direct DOM access in panel (framework mounting) |
+
+### Iframe Entry
+
+```ts
+ctx.docks.register({
+  id: 'my-plugin',
+  title: 'My Plugin',
+  icon: 'ph:house-duotone',
+  type: 'iframe',
+  url: '/.my-plugin/',
+})
+```
+
+### Action Entry
+
+```ts
+ctx.docks.register({
+  id: 'my-inspector',
+  title: 'Inspector',
+  icon: 'ph:cursor-duotone',
+  type: 'action',
+  action: {
+    importFrom: 'my-plugin/devtools-action',
+    importName: 'default',
+  },
+})
+```
+
+### Custom Render Entry
+
+```ts
+ctx.docks.register({
+  id: 'my-custom',
+  title: 'Custom View',
+  icon: 'ph:code-duotone',
+  type: 'custom-render',
+  renderer: {
+    importFrom: 'my-plugin/devtools-renderer',
+    importName: 'default',
+  },
+})
+```
+
+## RPC Functions
+
+### Server-Side Definition
+
+```ts
+import { defineRpcFunction } from '@vitejs/devtools-kit'
+
+const getModules = defineRpcFunction({
+  name: 'my-plugin:get-modules',
+  type: 'query', // 'query' | 'action' | 'static'
+  setup: ctx => ({
+    handler: async (filter?: string) => {
+      // ctx has full DevToolsNodeContext
+      return modules.filter(m => !filter || m.includes(filter))
+    },
+  }),
+})
+
+// Register in setup
+ctx.rpc.register(getModules)
+```
+
+### Client-Side Call (iframe)
+
+```ts
+import { getDevToolsRpcClient } from '@vitejs/devtools-kit/client'
+
+const rpc = await getDevToolsRpcClient()
+const modules = await rpc.call('my-plugin:get-modules', 'src/')
+```
+
+### Client-Side Call (action/renderer script)
+
+```ts
+import type { DevToolsClientScriptContext } from '@vitejs/devtools-kit/client'
+
+export default function setup(ctx: DevToolsClientScriptContext) {
+  ctx.current.events.on('entry:activated', async () => {
+    const data = await ctx.current.rpc.call('my-plugin:get-data')
+  })
+}
+```
+
+### Broadcasting to Clients
+
+```ts
+// Server broadcasts to all clients
+ctx.rpc.broadcast({
+  method: 'my-plugin:on-update',
+  args: [{ changedFile: '/src/main.ts' }],
+})
+```
+
+## Type Safety
+
+Extend the DevTools Kit interfaces for full type checking:
+
+```ts
+// src/types.ts
+import '@vitejs/devtools-kit'
+
+declare module '@vitejs/devtools-kit' {
+  interface DevToolsRpcServerFunctions {
+    'my-plugin:get-modules': (filter?: string) => Promise<Module[]>
+  }
+
+  interface DevToolsRpcClientFunctions {
+    'my-plugin:on-update': (data: { changedFile: string }) => void
+  }
+
+  interface DevToolsRpcSharedStates {
+    'my-plugin:state': MyPluginState
+  }
+}
+```
+
+## Shared State
+
+### Server-Side
+
+```ts
+const state = await ctx.rpc.sharedState.get('my-plugin:state', {
+  initialValue: { count: 0, items: [] },
+})
+
+// Read
+console.log(state.value())
+
+// Mutate (auto-syncs to clients)
+state.mutate((draft) => {
+  draft.count += 1
+  draft.items.push('new item')
+})
+```
+
+### Client-Side
+
+```ts
+const client = await getDevToolsRpcClient()
+const state = await client.rpc.sharedState.get('my-plugin:state')
+
+// Read
+console.log(state.value())
+
+// Subscribe to changes
+state.on('updated', (newState) => {
+  console.log('State updated:', newState)
+})
+```
+
+## Client Scripts
+
+For action buttons and custom renderers:
+
+```ts
+// src/devtools-action.ts
+import type { DevToolsClientScriptContext } from '@vitejs/devtools-kit/client'
+
+export default function setup(ctx: DevToolsClientScriptContext) {
+  ctx.current.events.on('entry:activated', () => {
+    console.log('Action activated')
+    // Your inspector/tool logic here
+  })
+
+  ctx.current.events.on('entry:deactivated', () => {
+    console.log('Action deactivated')
+    // Cleanup
+  })
+}
+```
+
+Export from package.json:
+
+```json
+{
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./devtools-action": "./dist/devtools-action.mjs"
+  }
+}
+```
+
+## Best Practices
+
+1. **Always namespace** - Prefix all identifiers with your plugin name
+2. **Use type augmentation** - Extend `DevToolsRpcServerFunctions` for type-safe RPC
+3. **Keep state serializable** - No functions or circular references in shared state
+4. **Batch mutations** - Use single `mutate()` call for multiple changes
+5. **Host static files** - Use `ctx.views.hostStatic()` for your UI assets
+6. **Use Iconify icons** - Prefer `ph:*` (Phosphor) icons: `icon: 'ph:chart-bar-duotone'`
+
+## Further Reading
+
+- [RPC Patterns](./references/rpc-patterns.md) - Advanced RPC patterns and type utilities
+- [Dock Entry Types](./references/dock-entry-types.md) - Detailed dock configuration options
+- [Shared State Patterns](./references/shared-state-patterns.md) - Framework integration examples
+- [Project Structure](./references/project-structure.md) - Recommended file organization