@vitejs/devtools-kit 0.0.0-alpha.9 → 0.1.0

package/dist/shared-state-BFKKxNt1.d.ts

@@ -0,0 +1,53 @@
+import { t as EventEmitter } from "./events-B41U-zeg.js";
+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 { ImmutableSet as a, SharedStateOptions as c, ImmutableObject as i, SharedStatePatch as l, ImmutableArray as n, SharedState as o, ImmutableMap as r, SharedStateEvents as s, Immutable as t, createSharedState as u };

package/dist/utils/events.d.ts

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

package/dist/utils/events.js

@@ -0,0 +1,40 @@
+//#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.ts

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

package/dist/utils/nanoid.js

@@ -0,0 +1,10 @@
+//#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.ts

@@ -0,0 +1,2 @@
+import { a as ImmutableSet, c as SharedStateOptions, i as ImmutableObject, l as SharedStatePatch, n as ImmutableArray, o as SharedState, r as ImmutableMap, s as SharedStateEvents, t as Immutable, u as createSharedState } from "../shared-state-BFKKxNt1.js";
+export { Immutable, ImmutableArray, ImmutableMap, ImmutableObject, ImmutableSet, SharedState, SharedStateEvents, SharedStateOptions, SharedStatePatch, createSharedState };

package/dist/utils/shared-state.js

@@ -0,0 +1,36 @@
+import { createEventEmitter } from "./events.js";
+import { nanoid } from "./nanoid.js";
+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,7 +1,7 @@
 {
   "name": "@vitejs/devtools-kit",
   "type": "module",
-  "version": "0.0.0-alpha.9",
+  "version": "0.1.0",
   "description": "Vite DevTools Kit",
   "author": "VoidZero Inc.",
   "license": "MIT",
@@ -21,24 +21,33 @@
   "exports": {
     ".": "./dist/index.js",
     "./client": "./dist/client.js",
+    "./constants": "./dist/constants.js",
+    "./utils/events": "./dist/utils/events.js",
+    "./utils/nanoid": "./dist/utils/nanoid.js",
+    "./utils/shared-state": "./dist/utils/shared-state.js",
     "./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.20"
+    "vite": "*"
   },
   "dependencies": {
-    "birpc": "^2.6.1",
-    "@vitejs/devtools-rpc": "0.0.0-alpha.9"
+    "birpc": "^4.0.0",
+    "immer": "^11.1.4",
+    "@vitejs/devtools-rpc": "0.1.0"
   },
   "devDependencies": {
-    "tsdown": "^0.15.12",
-    "vite": "npm:rolldown-vite@^7.1.20"
+    "tsdown": "^0.21.2",
+    "ua-parser-modern": "^0.1.1",
+    "vite": "^8.0.0"
+  },
+  "inlinedDependencies": {
+    "ohash": "2.0.11",
+    "ua-parser-modern": "0.1.1"
   },
   "scripts": {
     "build": "tsdown",

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

@@ -0,0 +1,436 @@
+---
+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, logs/notifications, 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, launcher) |
+| `ctx.views` | Host static files for UI |
+| `ctx.rpc` | Register RPC functions, broadcast to clients |
+| `ctx.rpc.sharedState` | Synchronized server-client state |
+| `ctx.logs` | Emit structured log entries and toast notifications |
+| `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) |
+| `launcher` | Actionable setup cards for initialization tasks |
+
+### 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',
+  },
+})
+```
+
+### Launcher Entry
+
+```ts
+const entry = ctx.docks.register({
+  id: 'my-setup',
+  title: 'My Setup',
+  icon: 'ph:rocket-launch-duotone',
+  type: 'launcher',
+  launcher: {
+    title: 'Initialize My Plugin',
+    description: 'Run initial setup before using the plugin',
+    buttonStart: 'Start Setup',
+    buttonLoading: 'Setting up...',
+    onLaunch: async () => {
+      // Run initialization logic
+    },
+  },
+})
+```
+
+## Logs & Notifications
+
+Plugins can emit structured log entries from both server and client contexts. Logs appear in the built-in **Logs** panel and can optionally show as toast notifications.
+
+### Fire-and-Forget
+
+```ts
+// No await needed
+context.logs.add({
+  message: 'Plugin initialized',
+  level: 'info',
+})
+```
+
+### With Handle
+
+```ts
+const handle = await context.logs.add({
+  id: 'my-build',
+  message: 'Building...',
+  level: 'info',
+  status: 'loading',
+})
+
+// Update later
+await handle.update({
+  message: 'Build complete',
+  level: 'success',
+  status: 'idle',
+})
+
+// Or dismiss
+await handle.dismiss()
+```
+
+### Key Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `message` | `string` | Short title (required) |
+| `level` | `'info' \| 'warn' \| 'error' \| 'success' \| 'debug'` | Severity (required) |
+| `description` | `string` | Detailed description |
+| `notify` | `boolean` | Show as toast notification |
+| `filePosition` | `{ file, line?, column? }` | Source file location (clickable) |
+| `elementPosition` | `{ selector?, boundingBox?, description? }` | DOM element position |
+| `id` | `string` | Explicit id for deduplication |
+| `status` | `'loading' \| 'idle'` | Shows spinner when loading |
+| `category` | `string` | Grouping (e.g., `'a11y'`, `'lint'`) |
+| `labels` | `string[]` | Tags for filtering |
+| `autoDismiss` | `number` | Toast auto-dismiss time in ms (default: 5000) |
+| `autoDelete` | `number` | Auto-delete time in ms |
+
+The `from` field is automatically set to `'server'` or `'browser'`.
+
+### Deduplication
+
+Re-adding with the same `id` updates the existing entry instead of creating a duplicate:
+
+```ts
+context.logs.add({ id: 'my-scan', message: 'Scanning...', level: 'info', status: 'loading' })
+context.logs.add({ id: 'my-scan', message: 'Scan complete', level: 'success', status: 'idle' })
+```
+
+## 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"
+  }
+}
+```
+
+## Debugging with Self-Inspect
+
+Use `@vitejs/devtools-self-inspect` to debug your DevTools plugin. It shows registered RPC functions, dock entries, client scripts, and plugins in a meta-introspection UI at `/.devtools-self-inspect/`.
+
+```ts
+import DevTools from '@vitejs/devtools'
+import DevToolsSelfInspect from '@vitejs/devtools-self-inspect'
+
+export default defineConfig({
+  plugins: [
+    DevTools(),
+    DevToolsSelfInspect(),
+  ],
+})
+```
+
+## 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'`
+7. **Deduplicate logs** - Use explicit `id` for logs representing ongoing operations
+8. **Use Self-Inspect** - Add `@vitejs/devtools-self-inspect` during development to debug your plugin
+
+## Example Plugins
+
+Real-world example plugins in the repo — reference their code structure and patterns when building new integrations:
+
+- **A11y Checker** ([`examples/plugin-a11y-checker`](https://github.com/vitejs/devtools/tree/main/examples/plugin-a11y-checker)) — Action dock entry, client-side axe-core audits, logs with severity levels and element positions, log handle updates
+- **File Explorer** ([`examples/plugin-file-explorer`](https://github.com/vitejs/devtools/tree/main/examples/plugin-file-explorer)) — Iframe dock entry, RPC functions (static/query/action), hosted UI panel, RPC dump for static builds, backend mode detection
+
+## 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
+- [Logs Patterns](./references/logs-patterns.md) - Log entries, toast notifications, and handle patterns