@vitejs/devtools-kit 0.1.8 → 0.1.9

package/dist/client.d.ts

@@ -1,2 +1,2 @@
-import { _ as DevToolsRpcClientCallOptional, a as DevToolsClientRpcHost, b as getDevToolsRpcClient, c as DockEntryStateEvents, d as DocksEntriesContext, f as DocksPanelContext, g as DevToolsRpcClientCallEvent, h as DevToolsRpcClientCall, i as DevToolsClientContext, l as DockPanelStorage, m as DevToolsRpcClient, n as getDevToolsClientContext, o as DockClientType, p as RpcClientEvents, r as DockClientScriptContext, s as DockEntryState, t as CLIENT_CONTEXT_KEY, u as DocksContext, v as DevToolsRpcClientMode, y as DevToolsRpcClientOptions } from "./index-BSLgRVfr.js";
-export { CLIENT_CONTEXT_KEY, DevToolsClientContext, DevToolsClientRpcHost, DevToolsRpcClient, DevToolsRpcClientCall, DevToolsRpcClientCallEvent, DevToolsRpcClientCallOptional, DevToolsRpcClientMode, DevToolsRpcClientOptions, DockClientScriptContext, DockClientType, DockEntryState, DockEntryStateEvents, DockPanelStorage, DocksContext, DocksEntriesContext, DocksPanelContext, RpcClientEvents, getDevToolsClientContext, getDevToolsRpcClient };
+import { S as getDevToolsRpcClient, _ as DevToolsRpcClientCall, a as DevToolsClientContext, b as DevToolsRpcClientMode, c as DockEntryState, d as DocksContext, f as DocksEntriesContext, g as DevToolsRpcClient, h as WhenClauseContext, i as CommandsContext, l as DockEntryStateEvents, m as RpcClientEvents, n as getDevToolsClientContext, o as DevToolsClientRpcHost, p as DocksPanelContext, r as DockClientScriptContext, s as DockClientType, t as CLIENT_CONTEXT_KEY, u as DockPanelStorage, v as DevToolsRpcClientCallEvent, x as DevToolsRpcClientOptions, y as DevToolsRpcClientCallOptional } from "./index-BMTnY3zc.js";
+export { CLIENT_CONTEXT_KEY, CommandsContext, DevToolsClientContext, DevToolsClientRpcHost, DevToolsRpcClient, DevToolsRpcClientCall, DevToolsRpcClientCallEvent, DevToolsRpcClientCallOptional, DevToolsRpcClientMode, DevToolsRpcClientOptions, DockClientScriptContext, DockClientType, DockEntryState, DockEntryStateEvents, DockPanelStorage, DocksContext, DocksEntriesContext, DocksPanelContext, RpcClientEvents, WhenClauseContext, getDevToolsClientContext, getDevToolsRpcClient };

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-import { D as DevToolsDocksUserSettings } from "./index-BSLgRVfr.js";
+import { k as DevToolsDocksUserSettings } from "./index-BMTnY3zc.js";
 
 //#region src/constants.d.ts
 declare const DEVTOOLS_MOUNT_PATH = "/.devtools/";

package/dist/{index-BSLgRVfr.d.ts → index-BMTnY3zc.d.ts}

@@ -1,5 +1,6 @@
 import { t as EventEmitter } from "./events-BTCXlxeC.js";
-import { o as SharedState } from "./shared-state-NxkOZ3u0.js";
+import { t as WhenContext } from "./when-snfIizvo.js";
+import { o as SharedState } from "./shared-state-CQAciU8Y.js";
 import { RpcDefinitionsFilter, RpcDefinitionsToFunctions, RpcFunctionsCollector, RpcFunctionsCollectorBase } from "@vitejs/devtools-rpc";
 import { WebSocketRpcClientOptions } from "@vitejs/devtools-rpc/presets/ws/client";
 import { DevToolsNodeRpcSessionMeta } from "@vitejs/devtools-rpc/presets/ws/server";
@@ -150,6 +151,127 @@ interface DevToolsLogsHost {
   clear: () => Promise<void>;
 }
 //#endregion
+//#region src/types/commands.d.ts
+interface DevToolsCommandKeybinding {
+  /**
+   * Keyboard shortcut string.
+   * Use "Mod" for platform-aware modifier (Cmd on macOS, Ctrl elsewhere).
+   * Examples: "Mod+K", "Mod+Shift+P", "Alt+N"
+   */
+  key: string;
+}
+interface DevToolsCommandBase {
+  /**
+   * Unique namespaced ID, e.g. "vite:open-in-editor"
+   */
+  id: string;
+  title: string;
+  description?: string;
+  /**
+   * Iconify icon string, e.g. "ph:pencil-duotone"
+   */
+  icon?: string;
+  category?: string;
+  /**
+   * Whether to show in command palette. Default: true
+   *
+   * - `true` — show the command and flatten its children into search results
+   * - `false` — hide the command entirely from the palette
+   * - `'without-children'` — show the command but don't flatten children into top-level search (children are still accessible via drill-down)
+   */
+  showInPalette?: boolean | 'without-children';
+  /**
+   * Optional context expression for conditional visibility.
+   * When set, the command is only shown in the palette and only executable
+   * when the expression evaluates to true.
+   *
+   * Uses the same syntax as keybinding `when` clauses.
+   * @example 'clientType == embedded'
+   * @example 'dockOpen && !paletteOpen'
+   */
+  when?: string;
+  /**
+   * Default keyboard shortcut(s) for this command
+   */
+  keybindings?: DevToolsCommandKeybinding[];
+}
+/**
+ * Server command input — what plugins pass to `ctx.commands.register()`.
+ */
+interface DevToolsServerCommandInput extends DevToolsCommandBase {
+  /**
+   * Handler for this command. Optional if the command only serves as a group for children.
+   */
+  handler?: (...args: any[]) => any | Promise<any>;
+  /**
+   * Static sub-commands. Two levels max (parent → children).
+   * Each child must have a globally unique `id`.
+   */
+  children?: DevToolsServerCommandInput[];
+}
+/**
+ * Serializable server command entry — sent over RPC (no handler).
+ */
+interface DevToolsServerCommandEntry extends DevToolsCommandBase {
+  source: 'server';
+  children?: DevToolsServerCommandEntry[];
+}
+/**
+ * Client command — registered in the webcomponent context.
+ */
+interface DevToolsClientCommand extends DevToolsCommandBase {
+  source: 'client';
+  /**
+   * Action for this command. Optional if the command only serves as a group for children.
+   * Return sub-commands for dynamic nested palette menus (runtime submenus).
+   */
+  action?: (...args: any[]) => void | DevToolsClientCommand[] | Promise<void | DevToolsClientCommand[]>;
+  /**
+   * Static sub-commands. Two levels max (parent → children).
+   */
+  children?: DevToolsClientCommand[];
+}
+/**
+ * Union of command entries visible in the palette.
+ */
+type DevToolsCommandEntry = DevToolsServerCommandEntry | DevToolsClientCommand;
+interface DevToolsCommandHandle {
+  readonly id: string;
+  update: (patch: Partial<Omit<DevToolsServerCommandInput, 'id'>>) => void;
+  unregister: () => void;
+}
+interface DevToolsCommandsHostEvents {
+  'command:registered': (command: DevToolsServerCommandEntry) => void;
+  'command:unregistered': (id: string) => void;
+}
+interface DevToolsCommandsHost {
+  readonly commands: Map<string, DevToolsServerCommandInput>;
+  readonly events: EventEmitter<DevToolsCommandsHostEvents>;
+  /**
+   * Register a command (with optional children).
+   */
+  register: (command: DevToolsServerCommandInput) => DevToolsCommandHandle;
+  /**
+   * Unregister a command by ID (removes parent and all children).
+   */
+  unregister: (id: string) => boolean;
+  /**
+   * Execute a command by ID. Searches top-level and children.
+   * Throws if not found or if command has no handler.
+   */
+  execute: (id: string, ...args: any[]) => Promise<unknown>;
+  /**
+   * Returns serializable list (no handlers), preserving tree structure.
+   */
+  list: () => DevToolsServerCommandEntry[];
+}
+interface DevToolsCommandShortcutOverrides {
+  /**
+   * Command ID → keybinding overrides. Empty array = shortcut disabled.
+   */
+  [commandId: string]: DevToolsCommandKeybinding[];
+}
+//#endregion
 //#region src/types/docks.d.ts
 interface DevToolsDockHost {
   readonly views: Map<string, DevToolsDockUserEntry>;
@@ -185,10 +307,16 @@ interface DevToolsDockEntryBase {
    */
   category?: DevToolsDockEntryCategory;
   /**
-   * Whether the entry should be hidden from the user.
-   * @default false
+   * Conditional visibility expression.
+   * When set, the dock entry is only visible when the expression evaluates to true.
+   * Uses the same syntax as command `when` clauses.
+   *
+   * Set to `'false'` to unconditionally hide the entry.
+   *
+   * @example 'clientType == embedded'
+   * @see {@link import('../utils/when').evaluateWhen}
    */
-  isHidden?: boolean;
+  when?: string;
   /**
    * Badge text to display on the dock icon (e.g., unread count)
    */
@@ -414,6 +542,10 @@ interface DevToolsNodeContext {
    * Logs host, for emitting and managing structured log entries
    */
   logs: DevToolsLogsHost;
+  /**
+   * Commands host, for registering and executing commands
+   */
+  commands: DevToolsCommandsHost;
   /**
    * Create a JsonRenderer handle for building json-render powered UIs.
    * Pass the returned handle as `ui` when registering a `json-render` dock entry.
@@ -616,6 +748,21 @@ interface DocksContext extends DevToolsClientContext {
    * The docks entries context
    */
   readonly docks: DocksEntriesContext;
+  /**
+   * The commands context for command palette and shortcuts
+   */
+  readonly commands: CommandsContext;
+  /**
+   * The when-clause context for conditional visibility
+   */
+  readonly when: WhenClauseContext;
+}
+interface WhenClauseContext {
+  /**
+   * Get the current when-clause context snapshot.
+   * Returns a reactive object with built-in variables and any custom plugin variables.
+   */
+  readonly context: WhenContext;
 }
 type DevToolsClientRpcHost = RpcFunctionsCollector<DevToolsRpcClientFunctions, DevToolsClientContext>;
 interface DocksPanelContext {
@@ -667,6 +814,36 @@ interface DockEntryStateEvents {
 interface RpcClientEvents {
   'rpc:is-trusted:updated': (isTrusted: boolean) => void;
 }
+interface CommandsContext {
+  /**
+   * All commands (server + client)
+   */
+  readonly commands: DevToolsCommandEntry[];
+  /**
+   * Palette-visible commands only (filtered by `showInPalette !== false`)
+   */
+  readonly paletteCommands: DevToolsCommandEntry[];
+  /**
+   * Register client-side command(s). Returns cleanup function.
+   */
+  register: (cmd: DevToolsClientCommand | DevToolsClientCommand[]) => () => void;
+  /**
+   * Execute a command by ID. Delegates to RPC for server commands.
+   */
+  execute: (id: string, ...args: any[]) => Promise<unknown>;
+  /**
+   * Get effective keybindings for a command (defaults merged with overrides)
+   */
+  getKeybindings: (id: string) => DevToolsCommandKeybinding[];
+  /**
+   * Shortcut overrides (persisted via shared state)
+   */
+  shortcutOverrides: SharedState<DevToolsCommandShortcutOverrides>;
+  /**
+   * Whether the command palette is open
+   */
+  paletteOpen: boolean;
+}
 //#endregion
 //#region src/client/client-script.d.ts
 /**
@@ -690,4 +867,4 @@ declare const CLIENT_CONTEXT_KEY = "__VITE_DEVTOOLS_CLIENT_CONTEXT__";
  */
 declare function getDevToolsClientContext(): DevToolsClientContext | undefined;
 //#endregion
-export { DevToolsDockEntryBase as $, RpcBroadcastOptions as A, DevToolsChildProcessExecuteOptions as B, PluginWithDevTools as C, DevToolsDocksUserSettings as D, Thenable as E, DevToolsCapabilities as F, DevToolsTerminalSessionStreamChunkEvent as G, DevToolsTerminalHost as H, DevToolsNodeContext as I, DevToolsRpcServerFunctions as J, DevToolsTerminalStatus as K, DevToolsNodeUtils as L, RpcSharedStateGetOptions as M, RpcSharedStateHost as N, DevToolsNodeRpcSession as O, ConnectionMeta as P, DevToolsDockEntry as Q, DevToolsPluginOptions as R, RpcDefinitionsToFunctions as S, DevToolsLogsHost as St, PartialWithoutId as T, DevToolsTerminalSession as U, DevToolsChildProcessTerminalSession as V, DevToolsTerminalSessionBase as W, ClientScriptEntry as X, DevToolsRpcSharedStates as Y, DevToolsDockEntriesGrouped as Z, DevToolsRpcClientCallOptional as _, DevToolsLogEntryInput as _t, DevToolsClientRpcHost as a, DevToolsViewBuiltin as at, getDevToolsRpcClient as b, DevToolsLogLevel as bt, DockEntryStateEvents as c, DevToolsViewJsonRender as ct, DocksEntriesContext as d, JsonRenderElement as dt, DevToolsDockEntryCategory as et, DocksPanelContext as f, JsonRenderSpec as ft, DevToolsRpcClientCallEvent as g, DevToolsLogEntryFrom as gt, DevToolsRpcClientCall as h, DevToolsLogEntry as ht, DevToolsClientContext as i, DevToolsViewAction as it, RpcFunctionsHost as j, DevToolsNodeRpcSessionMeta as k, DockPanelStorage as l, DevToolsViewLauncher as lt, DevToolsRpcClient as m, DevToolsLogElementPosition as mt, getDevToolsClientContext as n, DevToolsDockHost as nt, DockClientType as o, DevToolsViewCustomRender as ot, RpcClientEvents as p, JsonRenderer as pt, DevToolsRpcClientFunctions as q, DockClientScriptContext as r, DevToolsDockUserEntry as rt, DockEntryState as s, DevToolsViewIframe as st, CLIENT_CONTEXT_KEY as t, DevToolsDockEntryIcon as tt, DocksContext as u, DevToolsViewLauncherStatus as ut, DevToolsRpcClientMode as v, DevToolsLogFilePosition as vt, EntriesToObject as w, RpcDefinitionsFilter as x, DevToolsLogsClient as xt, DevToolsRpcClientOptions as y, DevToolsLogHandle as yt, DevToolsViewHost as z };
+export { DevToolsDockEntriesGrouped as $, DevToolsNodeRpcSession as A, DevToolsLogFilePosition as At, DevToolsPluginOptions as B, RpcDefinitionsFilter as C, DevToolsCommandsHostEvents as Ct, PartialWithoutId as D, DevToolsLogEntry as Dt, EntriesToObject as E, DevToolsLogElementPosition as Et, RpcSharedStateHost as F, DevToolsTerminalSession as G, DevToolsChildProcessExecuteOptions as H, ConnectionMeta as I, DevToolsTerminalStatus as J, DevToolsTerminalSessionBase as K, DevToolsCapabilities as L, RpcBroadcastOptions as M, DevToolsLogLevel as Mt, RpcFunctionsHost as N, DevToolsLogsClient as Nt, Thenable as O, DevToolsLogEntryFrom as Ot, RpcSharedStateGetOptions as P, DevToolsLogsHost as Pt, ClientScriptEntry as Q, DevToolsNodeContext as R, getDevToolsRpcClient as S, DevToolsCommandsHost as St, PluginWithDevTools as T, DevToolsServerCommandInput as Tt, DevToolsChildProcessTerminalSession as U, DevToolsViewHost as V, DevToolsTerminalHost as W, DevToolsRpcServerFunctions as X, DevToolsRpcClientFunctions as Y, DevToolsRpcSharedStates as Z, DevToolsRpcClientCall as _, DevToolsCommandBase as _t, DevToolsClientContext as a, DevToolsDockUserEntry as at, DevToolsRpcClientMode as b, DevToolsCommandKeybinding as bt, DockEntryState as c, DevToolsViewCustomRender as ct, DocksContext as d, DevToolsViewLauncher as dt, DevToolsDockEntry as et, DocksEntriesContext as f, DevToolsViewLauncherStatus as ft, DevToolsRpcClient as g, DevToolsClientCommand as gt, WhenClauseContext as h, JsonRenderer as ht, CommandsContext as i, DevToolsDockHost as it, DevToolsNodeRpcSessionMeta as j, DevToolsLogHandle as jt, DevToolsDocksUserSettings as k, DevToolsLogEntryInput as kt, DockEntryStateEvents as l, DevToolsViewIframe as lt, RpcClientEvents as m, JsonRenderSpec as mt, getDevToolsClientContext as n, DevToolsDockEntryCategory as nt, DevToolsClientRpcHost as o, DevToolsViewAction as ot, DocksPanelContext as p, JsonRenderElement as pt, DevToolsTerminalSessionStreamChunkEvent as q, DockClientScriptContext as r, DevToolsDockEntryIcon as rt, DockClientType as s, DevToolsViewBuiltin as st, CLIENT_CONTEXT_KEY as t, DevToolsDockEntryBase as tt, DockPanelStorage as u, DevToolsViewJsonRender as ut, DevToolsRpcClientCallEvent as v, DevToolsCommandEntry as vt, RpcDefinitionsToFunctions as w, DevToolsServerCommandEntry as wt, DevToolsRpcClientOptions as x, DevToolsCommandShortcutOverrides as xt, DevToolsRpcClientCallOptional as y, DevToolsCommandHandle as yt, DevToolsNodeUtils as z };

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { n as EventUnsubscribe, r as EventsMap, t as EventEmitter } from "./events-BTCXlxeC.js";
-import { $ as DevToolsDockEntryBase, A as RpcBroadcastOptions, B as DevToolsChildProcessExecuteOptions, C as PluginWithDevTools, D as DevToolsDocksUserSettings, E as Thenable, F as DevToolsCapabilities, G as DevToolsTerminalSessionStreamChunkEvent, H as DevToolsTerminalHost, I as DevToolsNodeContext, J as DevToolsRpcServerFunctions, K as DevToolsTerminalStatus, L as DevToolsNodeUtils, M as RpcSharedStateGetOptions, N as RpcSharedStateHost, O as DevToolsNodeRpcSession, P as ConnectionMeta, Q as DevToolsDockEntry, R as DevToolsPluginOptions, S as RpcDefinitionsToFunctions, St as DevToolsLogsHost, T as PartialWithoutId, U as DevToolsTerminalSession, V as DevToolsChildProcessTerminalSession, W as DevToolsTerminalSessionBase, X as ClientScriptEntry, Y as DevToolsRpcSharedStates, Z as DevToolsDockEntriesGrouped, _t as DevToolsLogEntryInput, at as DevToolsViewBuiltin, bt as DevToolsLogLevel, ct as DevToolsViewJsonRender, dt as JsonRenderElement, et as DevToolsDockEntryCategory, ft as JsonRenderSpec, gt as DevToolsLogEntryFrom, ht as DevToolsLogEntry, it as DevToolsViewAction, j as RpcFunctionsHost, k as DevToolsNodeRpcSessionMeta, lt as DevToolsViewLauncher, mt as DevToolsLogElementPosition, nt as DevToolsDockHost, ot as DevToolsViewCustomRender, pt as JsonRenderer, q as DevToolsRpcClientFunctions, rt as DevToolsDockUserEntry, st as DevToolsViewIframe, tt as DevToolsDockEntryIcon, ut as DevToolsViewLauncherStatus, vt as DevToolsLogFilePosition, w as EntriesToObject, x as RpcDefinitionsFilter, xt as DevToolsLogsClient, yt as DevToolsLogHandle, z as DevToolsViewHost } from "./index-BSLgRVfr.js";
+import { $ as DevToolsDockEntriesGrouped, A as DevToolsNodeRpcSession, At as DevToolsLogFilePosition, B as DevToolsPluginOptions, C as RpcDefinitionsFilter, Ct as DevToolsCommandsHostEvents, D as PartialWithoutId, Dt as DevToolsLogEntry, E as EntriesToObject, Et as DevToolsLogElementPosition, F as RpcSharedStateHost, G as DevToolsTerminalSession, H as DevToolsChildProcessExecuteOptions, I as ConnectionMeta, J as DevToolsTerminalStatus, K as DevToolsTerminalSessionBase, L as DevToolsCapabilities, M as RpcBroadcastOptions, Mt as DevToolsLogLevel, N as RpcFunctionsHost, Nt as DevToolsLogsClient, O as Thenable, Ot as DevToolsLogEntryFrom, P as RpcSharedStateGetOptions, Pt as DevToolsLogsHost, Q as ClientScriptEntry, R as DevToolsNodeContext, St as DevToolsCommandsHost, T as PluginWithDevTools, Tt as DevToolsServerCommandInput, U as DevToolsChildProcessTerminalSession, V as DevToolsViewHost, W as DevToolsTerminalHost, X as DevToolsRpcServerFunctions, Y as DevToolsRpcClientFunctions, Z as DevToolsRpcSharedStates, _t as DevToolsCommandBase, at as DevToolsDockUserEntry, bt as DevToolsCommandKeybinding, ct as DevToolsViewCustomRender, dt as DevToolsViewLauncher, et as DevToolsDockEntry, ft as DevToolsViewLauncherStatus, gt as DevToolsClientCommand, ht as JsonRenderer, it as DevToolsDockHost, j as DevToolsNodeRpcSessionMeta, jt as DevToolsLogHandle, k as DevToolsDocksUserSettings, kt as DevToolsLogEntryInput, lt as DevToolsViewIframe, mt as JsonRenderSpec, nt as DevToolsDockEntryCategory, ot as DevToolsViewAction, pt as JsonRenderElement, q as DevToolsTerminalSessionStreamChunkEvent, rt as DevToolsDockEntryIcon, st as DevToolsViewBuiltin, tt as DevToolsDockEntryBase, ut as DevToolsViewJsonRender, vt as DevToolsCommandEntry, w as RpcDefinitionsToFunctions, wt as DevToolsServerCommandEntry, xt as DevToolsCommandShortcutOverrides, yt as DevToolsCommandHandle, z as DevToolsNodeUtils } from "./index-BMTnY3zc.js";
+import { t as WhenContext } from "./when-snfIizvo.js";
 import * as _vitejs_devtools_rpc0 from "@vitejs/devtools-rpc";
 
-//#region src/utils/define.d.ts
+//#region src/define.d.ts
 declare const defineRpcFunction: <NAME extends string, TYPE extends _vitejs_devtools_rpc0.RpcFunctionType, ARGS extends any[], RETURN = void, const AS extends _vitejs_devtools_rpc0.RpcArgsSchema | undefined = undefined, const RS extends _vitejs_devtools_rpc0.RpcReturnSchema | undefined = undefined>(definition: _vitejs_devtools_rpc0.RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevToolsNodeContext>) => _vitejs_devtools_rpc0.RpcFunctionDefinition<NAME, TYPE, ARGS, RETURN, AS, RS, DevToolsNodeContext>;
-//#endregion
-//#region src/utils/json-render.d.ts
+declare function defineCommand(command: DevToolsServerCommandInput): DevToolsServerCommandInput;
 declare function defineJsonRenderSpec(spec: JsonRenderSpec): JsonRenderSpec;
 //#endregion
-export { ClientScriptEntry, ConnectionMeta, DevToolsCapabilities, DevToolsChildProcessExecuteOptions, DevToolsChildProcessTerminalSession, DevToolsDockEntriesGrouped, DevToolsDockEntry, DevToolsDockEntryBase, DevToolsDockEntryCategory, DevToolsDockEntryIcon, DevToolsDockHost, DevToolsDockUserEntry, DevToolsDocksUserSettings, DevToolsLogElementPosition, DevToolsLogEntry, DevToolsLogEntryFrom, DevToolsLogEntryInput, DevToolsLogFilePosition, DevToolsLogHandle, DevToolsLogLevel, DevToolsLogsClient, DevToolsLogsHost, DevToolsNodeContext, DevToolsNodeRpcSession, DevToolsNodeRpcSessionMeta, DevToolsNodeUtils, DevToolsPluginOptions, DevToolsRpcClientFunctions, DevToolsRpcServerFunctions, DevToolsRpcSharedStates, DevToolsTerminalHost, DevToolsTerminalSession, DevToolsTerminalSessionBase, DevToolsTerminalSessionStreamChunkEvent, DevToolsTerminalStatus, DevToolsViewAction, DevToolsViewBuiltin, DevToolsViewCustomRender, DevToolsViewHost, DevToolsViewIframe, DevToolsViewJsonRender, DevToolsViewLauncher, DevToolsViewLauncherStatus, EntriesToObject, EventEmitter, EventUnsubscribe, EventsMap, JsonRenderElement, JsonRenderSpec, JsonRenderer, PartialWithoutId, PluginWithDevTools, RpcBroadcastOptions, RpcDefinitionsFilter, RpcDefinitionsToFunctions, RpcFunctionsHost, RpcSharedStateGetOptions, RpcSharedStateHost, Thenable, defineJsonRenderSpec, defineRpcFunction };
+export { ClientScriptEntry, ConnectionMeta, DevToolsCapabilities, DevToolsChildProcessExecuteOptions, DevToolsChildProcessTerminalSession, DevToolsClientCommand, DevToolsCommandBase, DevToolsCommandEntry, DevToolsCommandHandle, DevToolsCommandKeybinding, DevToolsCommandShortcutOverrides, DevToolsCommandsHost, DevToolsCommandsHostEvents, DevToolsDockEntriesGrouped, DevToolsDockEntry, DevToolsDockEntryBase, DevToolsDockEntryCategory, DevToolsDockEntryIcon, DevToolsDockHost, DevToolsDockUserEntry, DevToolsDocksUserSettings, DevToolsLogElementPosition, DevToolsLogEntry, DevToolsLogEntryFrom, DevToolsLogEntryInput, DevToolsLogFilePosition, DevToolsLogHandle, DevToolsLogLevel, DevToolsLogsClient, DevToolsLogsHost, DevToolsNodeContext, DevToolsNodeRpcSession, DevToolsNodeRpcSessionMeta, DevToolsNodeUtils, DevToolsPluginOptions, DevToolsRpcClientFunctions, DevToolsRpcServerFunctions, DevToolsRpcSharedStates, DevToolsServerCommandEntry, DevToolsServerCommandInput, DevToolsTerminalHost, DevToolsTerminalSession, DevToolsTerminalSessionBase, DevToolsTerminalSessionStreamChunkEvent, DevToolsTerminalStatus, DevToolsViewAction, DevToolsViewBuiltin, DevToolsViewCustomRender, DevToolsViewHost, DevToolsViewIframe, DevToolsViewJsonRender, DevToolsViewLauncher, DevToolsViewLauncherStatus, EntriesToObject, EventEmitter, EventUnsubscribe, EventsMap, JsonRenderElement, JsonRenderSpec, JsonRenderer, PartialWithoutId, PluginWithDevTools, RpcBroadcastOptions, RpcDefinitionsFilter, RpcDefinitionsToFunctions, RpcFunctionsHost, RpcSharedStateGetOptions, RpcSharedStateHost, Thenable, WhenContext, defineCommand, defineJsonRenderSpec, defineRpcFunction };

package/dist/index.js

@@ -1,10 +1,11 @@
 import { createDefineWrapperWithContext } from "@vitejs/devtools-rpc";
-//#region src/utils/define.ts
+//#region src/define.ts
 const defineRpcFunction = createDefineWrapperWithContext();
-//#endregion
-//#region src/utils/json-render.ts
+function defineCommand(command) {
+	return command;
+}
 function defineJsonRenderSpec(spec) {
 	return spec;
 }
 //#endregion
-export { defineJsonRenderSpec, defineRpcFunction };
+export { defineCommand, defineJsonRenderSpec, defineRpcFunction };

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

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

package/dist/utils/when.d.ts

@@ -0,0 +1,2 @@
+import { n as evaluateWhen, r as getContextValue, t as WhenContext } from "../when-snfIizvo.js";
+export { WhenContext, evaluateWhen, getContextValue };

package/dist/utils/when.js

@@ -0,0 +1,66 @@
+//#region src/utils/when.ts
+/**
+* Evaluate a `when` expression against a context object.
+*
+* Supported syntax:
+* - Bare truthy: `dockOpen` → true if value is truthy
+* - Literal booleans: `true`, `false`
+* - Negation: `!paletteOpen`
+* - Equality: `clientType == embedded`
+* - Inequality: `clientType != standalone`
+* - AND: `dockOpen && !paletteOpen`
+* - OR: `paletteOpen || dockOpen`
+* - Namespaced keys: `vite.mode == development`, `vite:buildMode`
+*
+* Precedence: `||` (lowest) → `&&` → unary `!`
+*/
+function evaluateWhen(expression, ctx) {
+	return expression.split("||").map((s) => s.trim()).some((orPart) => {
+		return orPart.split("&&").map((s) => s.trim()).every((part) => {
+			const trimmed = part.trim();
+			if (trimmed === "true") return true;
+			if (trimmed === "false") return false;
+			if (trimmed.startsWith("!")) {
+				const key = trimmed.slice(1).trim();
+				if (key === "true") return false;
+				if (key === "false") return true;
+				return !getContextValue(key, ctx);
+			}
+			const eqIdx = trimmed.indexOf("==");
+			const neqIdx = trimmed.indexOf("!=");
+			if (eqIdx !== -1 || neqIdx !== -1) {
+				const isNeq = neqIdx !== -1 && (eqIdx === -1 || neqIdx < eqIdx);
+				const opIdx = isNeq ? neqIdx : eqIdx;
+				const opLen = isNeq ? 2 : 2;
+				const key = trimmed.slice(0, opIdx).trim();
+				const value = trimmed.slice(opIdx + opLen).trim();
+				const actual = String(getContextValue(key, ctx));
+				return isNeq ? actual !== value : actual === value;
+			}
+			return !!getContextValue(trimmed, ctx);
+		});
+	});
+}
+/**
+* Get a context value by key. Supports namespaced keys with `.` or `:` separators.
+*
+* Lookup order:
+* 1. Exact match — `ctx['vite.mode']` or `ctx['vite:mode']`
+* 2. Nested path — for `vite.mode`: `ctx.vite?.mode`; for `vite:mode`: `ctx.vite?.mode`
+*/
+function getContextValue(key, ctx) {
+	const record = ctx;
+	if (key in record) return record[key];
+	const separator = key.includes(".") ? "." : key.includes(":") ? ":" : null;
+	if (separator) {
+		const segments = key.split(separator);
+		let current = record;
+		for (const segment of segments) {
+			if (current == null || typeof current !== "object") return void 0;
+			current = current[segment];
+		}
+		return current;
+	}
+}
+//#endregion
+export { evaluateWhen, getContextValue };

package/dist/when-snfIizvo.d.ts

@@ -0,0 +1,47 @@
+//#region src/utils/when.d.ts
+/**
+ * Context object for evaluating `when` expressions.
+ *
+ * Built-in variables:
+ * - `clientType` — `'embedded' | 'standalone'`
+ * - `dockOpen` — whether the dock panel is open
+ * - `paletteOpen` — whether the command palette is open
+ * - `dockSelectedId` — ID of the selected dock entry (empty string if none)
+ *
+ * Plugins can add namespaced variables using dot or colon separators:
+ * - `vite.mode`, `vite:mode` — stored as `{ 'vite.mode': 'development' }` or nested `{ vite: { mode: 'development' } }`
+ */
+interface WhenContext {
+  clientType: 'embedded' | 'standalone';
+  dockOpen: boolean;
+  paletteOpen: boolean;
+  dockSelectedId: string;
+  /** Allow custom context variables from plugins */
+  [key: string]: unknown;
+}
+/**
+ * Evaluate a `when` expression against a context object.
+ *
+ * Supported syntax:
+ * - Bare truthy: `dockOpen` → true if value is truthy
+ * - Literal booleans: `true`, `false`
+ * - Negation: `!paletteOpen`
+ * - Equality: `clientType == embedded`
+ * - Inequality: `clientType != standalone`
+ * - AND: `dockOpen && !paletteOpen`
+ * - OR: `paletteOpen || dockOpen`
+ * - Namespaced keys: `vite.mode == development`, `vite:buildMode`
+ *
+ * Precedence: `||` (lowest) → `&&` → unary `!`
+ */
+declare function evaluateWhen(expression: string, ctx: WhenContext): boolean;
+/**
+ * Get a context value by key. Supports namespaced keys with `.` or `:` separators.
+ *
+ * Lookup order:
+ * 1. Exact match — `ctx['vite.mode']` or `ctx['vite:mode']`
+ * 2. Nested path — for `vite.mode`: `ctx.vite?.mode`; for `vite:mode`: `ctx.vite?.mode`
+ */
+declare function getContextValue(key: string, ctx: WhenContext): unknown;
+//#endregion
+export { evaluateWhen as n, getContextValue as r, WhenContext as t };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vitejs/devtools-kit",
   "type": "module",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Vite DevTools Kit",
   "author": "VoidZero Inc.",
   "license": "MIT",
@@ -26,6 +26,7 @@
     "./utils/human-id": "./dist/utils/human-id.js",
     "./utils/nanoid": "./dist/utils/nanoid.js",
     "./utils/shared-state": "./dist/utils/shared-state.js",
+    "./utils/when": "./dist/utils/when.js",
     "./package.json": "./package.json"
   },
   "types": "./dist/index.d.mts",
@@ -39,14 +40,14 @@
   "dependencies": {
     "birpc": "^4.0.0",
     "ohash": "^2.0.11",
-    "@vitejs/devtools-rpc": "0.1.8"
+    "@vitejs/devtools-rpc": "0.1.9"
   },
   "devDependencies": {
     "human-id": "^4.1.3",
     "immer": "^11.1.4",
     "tsdown": "^0.21.4",
     "ua-parser-modern": "^0.1.1",
-    "vite": "^8.0.1"
+    "vite": "^8.0.2"
   },
   "inlinedDependencies": {
     "human-id": "4.1.3",

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

@@ -25,6 +25,7 @@ A DevTools plugin extends a Vite plugin with a `devtools.setup(ctx)` hook. The c
 | `ctx.logs` | Emit structured log entries and toast notifications |
 | `ctx.terminals` | Spawn and manage child processes with streaming terminal output |
 | `ctx.createJsonRenderer` | Create server-side JSON render specs for zero-client-code UIs |
+| `ctx.commands` | Register executable commands with keyboard shortcuts and palette visibility |
 | `ctx.viteConfig` | Resolved Vite configuration |
 | `ctx.viteServer` | Dev server instance (dev mode only) |
 | `ctx.mode` | `'dev'` or `'build'` |
@@ -107,12 +108,13 @@ export default function myAnalyzer(): Plugin {
 
 ## Namespacing Convention
 
-**CRITICAL**: Always prefix RPC functions, shared state keys, and dock IDs with your plugin name:
+**CRITICAL**: Always prefix RPC functions, shared state keys, dock IDs, and command IDs with your plugin name:
 
 ```ts
 // Good - namespaced
 'my-plugin:get-modules'
 'my-plugin:state'
+'my-plugin:clear-cache'  // command ID
 
 // Bad - may conflict
 'get-modules'
@@ -254,6 +256,27 @@ await session.restart()
 
 A common pattern is combining with launcher docks — see [Terminals Patterns](./references/terminals-patterns.md).
 
+## Commands & Command Palette
+
+Register executable commands discoverable via `Mod+K` palette:
+
+```ts
+import { defineCommand } from '@vitejs/devtools-kit'
+
+ctx.commands.register(defineCommand({
+  id: 'my-plugin:clear-cache',
+  title: 'Clear Build Cache',
+  icon: 'ph:trash-duotone',
+  keybindings: [{ key: 'Mod+Shift+C' }],
+  when: 'clientType == embedded',
+  handler: async () => { /* ... */ },
+}))
+```
+
+Commands support sub-commands (two-level hierarchy), conditional visibility via `when` clauses, and user-customizable keyboard shortcuts.
+
+See [Commands Patterns](./references/commands-patterns.md) and [When Clauses](./references/when-clauses.md) for full details.
+
 ## 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.
@@ -498,6 +521,8 @@ export default defineConfig({
 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
+9. **Namespace command IDs** - Use `my-plugin:action` pattern for command IDs, same as RPC and state
+10. **Use `when` clauses** - Conditionally show commands/docks with `when` expressions instead of programmatic show/hide
 
 ## Example Plugins
 
@@ -516,3 +541,5 @@ Real-world example plugins in the repo — reference their code structure and pa
 - [JSON Render Patterns](./references/json-render-patterns.md) - Server-side JSON specs, components, state binding
 - [Terminals Patterns](./references/terminals-patterns.md) - Child processes, custom streams, session lifecycle
 - [Logs Patterns](./references/logs-patterns.md) - Log entries, toast notifications, and handle patterns
+- [Commands Patterns](./references/commands-patterns.md) - Command registration, sub-commands, keybindings, palette integration
+- [When Clauses](./references/when-clauses.md) - Conditional expression syntax, context variables, API reference

package/skills/vite-devtools-kit/references/commands-patterns.md

@@ -0,0 +1,241 @@
+# Commands & Command Palette
+
+Register executable commands discoverable through a built-in palette with keyboard shortcuts.
+
+## Defining Commands
+
+```ts
+import { defineCommand } from '@vitejs/devtools-kit'
+
+const clearCache = defineCommand({
+  id: 'my-plugin:clear-cache',
+  title: 'Clear Build Cache',
+  description: 'Remove all cached build artifacts',
+  icon: 'ph:trash-duotone',
+  category: 'tools',
+  handler: async () => {
+    await fs.rm('.cache', { recursive: true })
+  },
+})
+
+// Register in plugin setup
+ctx.commands.register(clearCache)
+```
+
+## Command Options
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | **Required.** Unique namespaced ID (e.g. `my-plugin:action`) |
+| `title` | `string` | **Required.** Human-readable title shown in the palette |
+| `description` | `string` | Optional description text |
+| `icon` | `string` | Iconify icon string (e.g. `ph:trash-duotone`) |
+| `category` | `string` | Category for grouping |
+| `showInPalette` | `boolean \| 'without-children'` | Whether to show in command palette (default: `true`). `'without-children'` shows the command but doesn't flatten children into search — only accessible via drill-down. |
+| `when` | `string` | Conditional visibility expression — see [When Clauses](./when-clauses.md) |
+| `keybindings` | `DevToolsCommandKeybinding[]` | Default keyboard shortcuts |
+| `handler` | `Function` | Server-side handler. Optional if the command is a group for children. |
+| `children` | `DevToolsServerCommandInput[]` | Static sub-commands (two levels max) |
+
+## Command Handle
+
+`register()` returns a handle for live updates:
+
+```ts
+const handle = ctx.commands.register({
+  id: 'my-plugin:status',
+  title: 'Show Status',
+  handler: () => { /* ... */ },
+})
+
+// Update later
+handle.update({ title: 'Show Status (3 items)' })
+
+// Remove
+handle.unregister()
+```
+
+## Sub-Commands
+
+Two-level hierarchy. Selecting a parent in the palette drills down into its children.
+
+```ts
+ctx.commands.register({
+  id: 'git',
+  title: 'Git',
+  icon: 'ph:git-branch-duotone',
+  category: 'tools',
+  // No handler — group-only parent
+  children: [
+    {
+      id: 'git:commit',
+      title: 'Commit',
+      icon: 'ph:check-duotone',
+      keybindings: [{ key: 'Mod+Shift+G' }],
+      handler: async () => { /* ... */ },
+    },
+    {
+      id: 'git:push',
+      title: 'Push',
+      handler: async () => { /* ... */ },
+    },
+  ],
+})
+```
+
+Each child must have a globally unique `id`. Use the pattern `parentId:childAction` (e.g. `git:commit`).
+
+Sub-commands with keybindings can be executed directly via the shortcut without opening the palette.
+
+## Keyboard Shortcuts
+
+### Key Format
+
+Use `Mod` as a platform-aware modifier — maps to `Cmd` on macOS and `Ctrl` on other platforms.
+
+| Key string | macOS | Windows/Linux |
+|------------|-------|---------------|
+| `Mod+K` | `Cmd+K` | `Ctrl+K` |
+| `Mod+Shift+P` | `Cmd+Shift+P` | `Ctrl+Shift+P` |
+| `Alt+N` | `Option+N` | `Alt+N` |
+
+```ts
+ctx.commands.register(defineCommand({
+  id: 'my-plugin:toggle-overlay',
+  title: 'Toggle Overlay',
+  keybindings: [{ key: 'Mod+Shift+O' }],
+  handler: () => { /* ... */ },
+}))
+```
+
+### User Overrides
+
+Users can customize shortcuts in Settings > **Keyboard Shortcuts**. Overrides persist across sessions. Setting an empty array disables a shortcut.
+
+The shortcut editor includes:
+- **Key capture** — click the input and press any key combination
+- **Modifier toggles** — toggle Cmd/Ctrl, Alt, Shift individually
+- **Conflict detection** — warns on browser shortcut conflicts, duplicate bindings, and weak shortcuts (single key without modifiers)
+
+`KNOWN_BROWSER_SHORTCUTS` is exported from `@vitejs/devtools-kit` and maps key combinations to human-readable descriptions.
+
+## Conditional Visibility
+
+Commands support a `when` expression for conditional visibility:
+
+```ts
+ctx.commands.register(defineCommand({
+  id: 'my-plugin:embedded-only',
+  title: 'Embedded-Only Action',
+  when: 'clientType == embedded',
+  handler: async () => { /* ... */ },
+}))
+```
+
+When set, the command only appears in the palette and is only triggerable via shortcuts when the expression evaluates to `true`.
+
+See [When Clauses](./when-clauses.md) for full syntax reference and context variables.
+
+## Client-Side Commands
+
+Client commands register in the webcomponent context and execute directly in the browser:
+
+```ts
+context.commands.register({
+  id: 'devtools:theme',
+  source: 'client',
+  title: 'Theme',
+  icon: 'ph:palette-duotone',
+  children: [
+    {
+      id: 'devtools:theme:light',
+      source: 'client',
+      title: 'Light',
+      action: () => setTheme('light'),
+    },
+    {
+      id: 'devtools:theme:dark',
+      source: 'client',
+      title: 'Dark',
+      action: () => setTheme('dark'),
+    },
+  ],
+})
+```
+
+Client commands can return dynamic sub-items:
+
+```ts
+context.commands.register({
+  id: 'devtools:docs',
+  source: 'client',
+  title: 'Documentation',
+  action: async () => {
+    const docs = await fetchDocs()
+    return docs.map(doc => ({
+      id: `docs:${doc.slug}`,
+      source: 'client' as const,
+      title: doc.title,
+      action: () => window.open(doc.url, '_blank'),
+    }))
+  },
+})
+```
+
+## Command Palette
+
+Built-in palette toggled with `Mod+K`. Features:
+
+- **Fuzzy search** across all registered commands (including sub-commands)
+- **Keyboard navigation** — Arrow keys, Enter to select, Escape to close
+- **Drill-down** — Commands with children show breadcrumb navigation
+- **Server command execution** — via RPC with loading indicator
+- **Dynamic sub-menus** — Client commands can return sub-items at runtime
+
+## Complete Example
+
+```ts
+/// <reference types="@vitejs/devtools-kit" />
+import type { Plugin } from 'vite'
+import { defineCommand } from '@vitejs/devtools-kit'
+
+export default function myPlugin(): Plugin {
+  return {
+    name: 'my-plugin',
+
+    devtools: {
+      setup(ctx) {
+        // Simple command with keybinding
+        ctx.commands.register(defineCommand({
+          id: 'my-plugin:restart',
+          title: 'Restart Dev Server',
+          icon: 'ph:arrow-clockwise-duotone',
+          keybindings: [{ key: 'Mod+Shift+R' }],
+          handler: async () => {
+            await ctx.viteServer?.restart()
+          },
+        }))
+
+        // Command group with sub-commands
+        ctx.commands.register(defineCommand({
+          id: 'my-plugin:cache',
+          title: 'Cache',
+          icon: 'ph:database-duotone',
+          children: [
+            {
+              id: 'my-plugin:cache:clear',
+              title: 'Clear Cache',
+              handler: async () => { /* ... */ },
+            },
+            {
+              id: 'my-plugin:cache:inspect',
+              title: 'Inspect Cache',
+              handler: async () => { /* ... */ },
+            },
+          ],
+        }))
+      },
+    },
+  }
+}
+```

package/skills/vite-devtools-kit/references/dock-entry-types.md

@@ -13,7 +13,7 @@ interface DockEntryBase {
   icon: string // URL, data URI, or Iconify name
   category?: string // Grouping category
   defaultOrder?: number // Sort order (higher = earlier)
-  isHidden?: boolean // Hide from dock
+  when?: string // Conditional visibility expression — see [When Clauses](./when-clauses.md)
   badge?: string // Badge text on dock icon (e.g., count)
 }
 ```

package/skills/vite-devtools-kit/references/when-clauses.md

@@ -0,0 +1,160 @@
+# When Clauses
+
+Conditional expressions controlling visibility and activation of commands and dock entries.
+
+## Usage
+
+### On Commands
+
+Controls whether the command appears in the palette and can be triggered via shortcuts:
+
+```ts
+ctx.commands.register(defineCommand({
+  id: 'my-plugin:embedded-only',
+  title: 'Embedded-Only Action',
+  when: 'clientType == embedded',
+  handler: async () => { /* ... */ },
+}))
+```
+
+### On Dock Entries
+
+Controls whether a dock entry is visible in the dock bar:
+
+```ts
+ctx.docks.register({
+  id: 'my-plugin:inspector',
+  title: 'Inspector',
+  type: 'action',
+  icon: 'ph:cursor-duotone',
+  when: 'clientType == embedded',
+  action: { importFrom: 'my-plugin/inspector' },
+})
+```
+
+Set `when: 'false'` to unconditionally hide a dock entry.
+
+## Expression Syntax
+
+### Operators
+
+| Operator | Example | Description |
+|----------|---------|-------------|
+| bare truthy | `dockOpen` | True if the value is truthy |
+| `true` / `false` | `true` | Literal boolean values |
+| `!` | `!paletteOpen` | Negation |
+| `==` | `clientType == embedded` | Equality (string comparison) |
+| `!=` | `clientType != standalone` | Inequality |
+| `&&` | `dockOpen && !paletteOpen` | Logical AND |
+| `\|\|` | `paletteOpen \|\| dockOpen` | Logical OR |
+
+### Precedence
+
+`||` (lowest) → `&&` → unary `!`
+
+Each `||` branch is evaluated as a chain of `&&` parts: `a && b || c && d` = `(a AND b) OR (c AND d)`.
+
+### Examples
+
+```ts
+// Always visible
+when: 'true'
+
+// Never visible (unconditionally hidden)
+when: 'false'
+
+// Only in embedded mode
+when: 'clientType == embedded'
+
+// Only when dock is open and palette is closed
+when: 'dockOpen && !paletteOpen'
+
+// When a specific dock is selected
+when: 'dockSelectedId == my-plugin'
+
+// Plugin-specific context
+when: 'vite.mode == development'
+
+// Compound: either in embedded with dock open, or in standalone
+when: 'clientType == embedded && dockOpen || clientType == standalone'
+```
+
+## Built-in Context Variables
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `clientType` | `'embedded' \| 'standalone'` | Current client mode |
+| `dockOpen` | `boolean` | Whether the dock panel is currently open |
+| `paletteOpen` | `boolean` | Whether the command palette is currently open |
+| `dockSelectedId` | `string` | ID of the currently selected dock entry. Empty string (falsy) when none selected. |
+
+## Namespaced Context Keys
+
+Plugins can register context variables using namespaced keys with `.` or `:` separators:
+
+```ts
+// Flat key (recommended)
+context['vite.mode'] = 'development'
+context['vite:buildMode'] = 'lib'
+
+// Nested object (also supported)
+context.vite = { mode: 'development', ssr: true }
+```
+
+Both styles work in `when` expressions:
+
+```ts
+when: 'vite.mode == development'
+when: 'vite:buildMode == lib'
+when: 'vite.ssr'
+```
+
+### Lookup Order
+
+When resolving a namespaced key like `vite.mode`:
+
+1. **Exact match** — looks for `ctx['vite.mode']` first
+2. **Nested path** — falls back to `ctx.vite?.mode`
+
+Flat keys take priority over nested objects if both exist. Use your plugin name as namespace prefix: `my-plugin.featureEnabled`, `rolldown:buildStep`.
+
+## API Reference
+
+```ts
+import type { WhenContext } from '@vitejs/devtools-kit'
+import { evaluateWhen, getContextValue } from '@vitejs/devtools-kit/utils/when'
+
+const ctx: WhenContext = {
+  'clientType': 'embedded',
+  'dockOpen': true,
+  'paletteOpen': false,
+  'dockSelectedId': 'my-dock',
+  'vite.mode': 'development',
+}
+
+evaluateWhen('dockOpen && vite.mode == development', ctx) // true
+evaluateWhen('clientType == standalone', ctx) // false
+
+getContextValue('vite.mode', ctx) // 'development'
+getContextValue('dockOpen', ctx) // true
+```
+
+### `evaluateWhen(expression, ctx)`
+
+Evaluates a when-clause expression string against a context object. Returns `boolean`.
+
+### `getContextValue(key, ctx)`
+
+Resolves a single context key (including namespaced keys) from the context object. Returns `unknown`.
+
+### `WhenContext`
+
+```ts
+interface WhenContext {
+  clientType: 'embedded' | 'standalone'
+  dockOpen: boolean
+  paletteOpen: boolean
+  dockSelectedId: string
+  [key: string]: unknown // custom plugin variables
+}
+```