devframe 0.1.21 → 0.1.22

package/dist/utils/shared-state.mjs

@@ -1,36 +1,2 @@
-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
+import { t as createSharedState } from "../shared-state-DCDs0e7y.mjs";
 export { createSharedState };

package/dist/utils/streaming-channel.d.mts

@@ -1,2 +1,2 @@
-import { C as StreamErrorPayload, D as createStreamReader, E as StreamSinkEvents, O as createStreamSink, S as CreateStreamSinkOptions, T as StreamSink, b as BufferedChunk, w as StreamReader, x as CreateStreamReaderOptions } from "../devtool-CNvLs2_Y.mjs";
+import { A as CreateStreamSinkOptions, F as createStreamReader, I as createStreamSink, M as StreamReader, N as StreamSink, O as BufferedChunk, P as StreamSinkEvents, j as StreamErrorPayload, k as CreateStreamReaderOptions } from "../devframe-DulcIxwu.mjs";
 export { BufferedChunk, CreateStreamReaderOptions, CreateStreamSinkOptions, StreamErrorPayload, StreamReader, StreamSink, StreamSinkEvents, createStreamReader, createStreamSink };

package/dist/utils/structured-clone.d.mts

@@ -0,0 +1,21 @@
+//#region src/utils/structured-clone.d.ts
+/**
+ * Serialize a structured-cloneable value (`Map`, `Set`, `Date`, `BigInt`,
+ * cycles, class instances, …) into a JSON-safe records array.
+ */
+declare function structuredCloneSerialize(value: unknown): unknown[];
+/**
+ * Inverse of {@link structuredCloneSerialize}.
+ */
+declare function structuredCloneDeserialize<T = unknown>(value: unknown[]): T;
+/**
+ * Serialize a structured-cloneable value to a single string. Equivalent
+ * to `JSON.stringify(structuredCloneSerialize(value))`.
+ */
+declare function structuredCloneStringify(value: unknown): string;
+/**
+ * Inverse of {@link structuredCloneStringify}.
+ */
+declare function structuredCloneParse<T = unknown>(value: string): T;
+//#endregion
+export { structuredCloneDeserialize, structuredCloneParse, structuredCloneSerialize, structuredCloneStringify };

package/dist/utils/structured-clone.mjs

@@ -0,0 +1,2 @@
+import { i as structuredCloneStringify, n as structuredCloneParse, r as structuredCloneSerialize, t as structuredCloneDeserialize } from "../structured-clone-DcDc2Dds.mjs";
+export { structuredCloneDeserialize, structuredCloneParse, structuredCloneSerialize, structuredCloneStringify };

package/dist/utils/when.d.mts

@@ -325,50 +325,8 @@ type ValidateExpression<S extends string, T> = string extends S ? S : Tokenize<S
  * defineCommand({ name: 'x', title: 'X', when: 'typo' })
  * //                                            ^^^^^ type error
  */
-type WhenExpression<T, S extends string> = S & ValidateExpression<S, T>; //#endregion
+type WhenExpression$1<T, S extends string> = S & ValidateExpression<S, T>; //#endregion
 //#region src/index.d.ts
-interface EvaluateOptions {
-  /**
-   * If `true`, throw when the expression references a context key that does
-   * not exist. Defaults to `false`, where unknown keys evaluate to `undefined`.
-   */
-  strict?: boolean;
-}
-/**
- * Evaluate a when-clause expression string against a context object.
- * Equivalent to `evaluate(parse(expression), ctx, options)`.
- *
- * Supports a JS-expression subset:
- * - Literals: booleans, numbers, strings (quoted with `"` or `'`)
- * - Identifiers: bare keys, including namespaced (`vite.mode`, `vite:buildMode`)
- * - Logical: `&&`, `||`, `!`
- * - Equality: `==`, `!=` (string comparison, bare identifier RHS treated as string),
- *             `===`, `!==` (JS strict equality with full expression RHS)
- * - Relational: `<`, `<=`, `>`, `>=`
- * - Arithmetic: `+`, `-`, `*`, `/`, `%`, unary `-` / `+`
- * - Grouping: `(` … `)`
- *
- * When `ctx` has a specific type with known keys, the expression string is
- * **statically validated** — unknown context keys and syntax errors surface
- * as TypeScript errors at the call site. Pass `ctx` typed as
- * `Record<string, unknown>`, or the expression as `string`, to opt out of
- * static checking (e.g. for dynamic expressions).
- *
- * With `{ strict: true }`, referencing an unknown context key at runtime
- * throws. Short-circuit evaluation still applies — keys not reached are not
- * checked.
- */
-declare function evaluateWhen<T extends object, const E extends string>(expression: E & ValidateExpression<E, T>, ctx: T, options?: EvaluateOptions): boolean;
-/**
- * Resolve a context value by key. Supports namespaced keys with `.` or `:` separators.
- *
- * Lookup order:
- * 1. Exact match — `ctx['plugin.mode']` or `ctx['plugin:mode']`
- * 2. Nested path — e.g. `plugin.mode` falls back to `ctx.plugin?.mode`
- *
- * Returns `undefined` for unknown keys.
- */
-declare function resolveContextValue<T extends Record<string, unknown>>(key: string, ctx: T): unknown; //#endregion
 //#endregion
 //#region src/utils/when.d.ts
 /**
@@ -383,11 +341,9 @@ declare function resolveContextValue<T extends Record<string, unknown>>(key: str
  * Plugins can add namespaced variables using dot or colon separators:
  * - `vite.mode`, `vite:mode` — stored as `{ 'vite.mode': 'development' }` or nested `{ vite: { mode: 'development' } }`
  *
- * The expression language — including all operators and precedence — is provided by
- * the [`whenexpr`](https://github.com/antfu/whenexpr) package. In addition to the
- * VS-Code-style `!`/`==`/`!=`/`&&`/`||` operators, parentheses, strict equality
- * (`===`/`!==`), relational (`<`/`<=`/`>`/`>=`), arithmetic (`+ - * / %`), and
- * number/string literals are supported.
+ * Supported operators: `!`, `==`, `!=`, `===`, `!==`, `<`, `<=`, `>`, `>=`,
+ * `&&`, `||`, `+`, `-`, `*`, `/`, `%`. Parentheses, number and string literals
+ * are also supported.
  */
 interface WhenContext {
   clientType: 'embedded' | 'standalone';
@@ -397,5 +353,32 @@ interface WhenContext {
   /** Allow custom context variables from plugins */
   [key: string]: unknown;
 }
+/**
+ * A statically-validated `when` expression string. Used inside `define*`
+ * helpers to surface unknown context keys and syntax errors as TypeScript
+ * errors at the call site.
+ */
+type WhenExpression<T, S extends string> = WhenExpression$1<T, S>;
+/** Options for `evaluateWhen`. */
+interface EvaluateWhenOptions {
+  /**
+   * Throw when the expression references a context key that does not exist.
+   *
+   * @default false
+   */
+  strict?: boolean;
+}
+/**
+ * Evaluate a when-clause expression string against a context object.
+ *
+ * @example
+ * evaluateWhen('dockOpen && clientType == embedded', ctx)
+ */
+declare function evaluateWhen<T extends object, const E extends string>(expression: E & WhenExpression$1<T, E>, context: T, options?: EvaluateWhenOptions): boolean;
+/**
+ * Resolve a context value by key. Supports namespaced keys with `.` or `:`
+ * separators. Returns `undefined` for unknown keys.
+ */
+declare function resolveContextValue<T extends Record<string, unknown>>(key: string, context: T): unknown;
 //#endregion
-export { WhenContext, type WhenExpression, evaluateWhen, resolveContextValue };
+export { EvaluateWhenOptions, WhenContext, type WhenExpression, evaluateWhen, resolveContextValue };

package/dist/utils/when.mjs

@@ -369,7 +369,7 @@ function runBinary(node, ctx, strict) {
 * throws. Short-circuit evaluation still applies — keys not reached are not
 * checked.
 */
-function evaluateWhen(expression, ctx, options) {
+function evaluateWhen$1(expression, ctx, options) {
 	return evaluate(parse(expression), ctx, options);
 }
 /**
@@ -381,7 +381,7 @@ function evaluateWhen(expression, ctx, options) {
 *
 * Returns `undefined` for unknown keys.
 */
-function resolveContextValue(key, ctx) {
+function resolveContextValue$1(key, ctx) {
 	return resolve(key, ctx).value;
 }
 function lookup(key, ctx, strict) {
@@ -421,4 +421,22 @@ function resolve(key, ctx) {
 	};
 }
 //#endregion
+//#region src/utils/when.ts
+/**
+* Evaluate a when-clause expression string against a context object.
+*
+* @example
+* evaluateWhen('dockOpen && clientType == embedded', ctx)
+*/
+function evaluateWhen(expression, context, options) {
+	return evaluateWhen$1(expression, context, options);
+}
+/**
+* Resolve a context value by key. Supports namespaced keys with `.` or `:`
+* separators. Returns `undefined` for unknown keys.
+*/
+function resolveContextValue(key, context) {
+	return resolveContextValue$1(key, context);
+}
+//#endregion
 export { evaluateWhen, resolveContextValue };

package/dist/{ws-client-CjPuPFbA.d.mts → ws-client-Bavoya6-.d.mts}

@@ -1,4 +1,4 @@
-import { g as RpcFunctionDefinitionAny } from "./types-C5OVe4AC.mjs";
+import { g as RpcFunctionDefinitionAny } from "./types-4rdUEi2R.mjs";
 import { ChannelOptions } from "birpc";
 
 //#region src/rpc/transports/ws-client.d.ts

package/dist/{ws-server-C7LnhOHi.d.mts → ws-server-DjvlwLuM.d.mts}

@@ -1,4 +1,4 @@
-import { g as RpcFunctionDefinitionAny } from "./types-C5OVe4AC.mjs";
+import { g as RpcFunctionDefinitionAny } from "./types-4rdUEi2R.mjs";
 import { BirpcGroup, ChannelOptions } from "birpc";
 import { ServerOptions } from "node:https";
 import { WebSocket, WebSocketServer } from "ws";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "devframe",
   "type": "module",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Framework for building generic DevTools",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -28,8 +28,9 @@
     "./adapters/vite": "./dist/adapters/vite.mjs",
     "./client": "./dist/client/index.mjs",
     "./constants": "./dist/constants.mjs",
-    "./internal": "./dist/internal/index.mjs",
     "./node": "./dist/node/index.mjs",
+    "./node/auth": "./dist/node/auth.mjs",
+    "./node/internal": "./dist/node/internal.mjs",
     "./recipes/open-helpers": "./dist/recipes/open-helpers.mjs",
     "./rpc": "./dist/rpc/index.mjs",
     "./rpc/client": "./dist/rpc/client.mjs",
@@ -37,13 +38,18 @@
     "./rpc/transports/ws-client": "./dist/rpc/transports/ws-client.mjs",
     "./rpc/transports/ws-server": "./dist/rpc/transports/ws-server.mjs",
     "./types": "./dist/types/index.mjs",
+    "./utils/colors": "./dist/utils/colors.mjs",
     "./utils/events": "./dist/utils/events.mjs",
+    "./utils/hash": "./dist/utils/hash.mjs",
     "./utils/human-id": "./dist/utils/human-id.mjs",
+    "./utils/launch-editor": "./dist/utils/launch-editor.mjs",
     "./utils/nanoid": "./dist/utils/nanoid.mjs",
+    "./utils/open": "./dist/utils/open.mjs",
     "./utils/promise": "./dist/utils/promise.mjs",
+    "./utils/serve-static": "./dist/utils/serve-static.mjs",
     "./utils/shared-state": "./dist/utils/shared-state.mjs",
-    "./utils/state": "./dist/utils/state.mjs",
     "./utils/streaming-channel": "./dist/utils/streaming-channel.mjs",
+    "./utils/structured-clone": "./dist/utils/structured-clone.mjs",
     "./utils/when": "./dist/utils/when.mjs",
     "./package.json": "./package.json"
   },
@@ -62,43 +68,50 @@
   },
   "dependencies": {
     "@valibot/to-json-schema": "^1.7.0",
-    "ansis": "^4.2.0",
     "birpc": "^4.0.0",
     "cac": "^7.0.0",
     "h3": "^1.15.11",
-    "immer": "^11.1.7",
-    "launch-editor": "^2.13.2",
     "logs-sdk": "^0.0.6",
-    "ohash": "^2.0.11",
+    "mrmime": "^2.0.1",
     "pathe": "^2.0.3",
-    "sirv": "^3.0.2",
-    "structured-clone-es": "^2.0.0",
     "valibot": "^1.4.0",
     "ws": "^8.20.0"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "ansis": "^4.2.0",
+    "immer": "^11.1.8",
     "launch-editor": "^2.13.2",
-    "tsdown": "^0.21.10",
+    "ohash": "^2.0.11",
+    "open": "^11.0.0",
+    "structured-clone-es": "^2.0.0",
+    "tsdown": "^0.22.0",
     "whenexpr": "^0.1.2"
   },
   "inlinedDependencies": {
+    "ansis": "4.2.0",
     "bundle-name": "4.1.0",
     "default-browser": "5.4.0",
     "default-browser-id": "5.0.1",
     "define-lazy-prop": "3.0.0",
     "get-port-please": "3.2.0",
     "human-id": "4.1.3",
+    "immer": "11.1.8",
     "is-docker": "3.0.0",
     "is-in-ssh": "1.0.0",
     "is-inside-container": "1.0.0",
     "is-wsl": "3.1.0",
+    "launch-editor": "2.13.2",
     "obug": "2.1.1",
+    "ohash": "2.0.11",
     "open": "11.0.0",
     "p-limit": "7.3.0",
     "perfect-debounce": "2.1.0",
+    "picocolors": "1.1.1",
     "powershell-utils": "0.1.0",
     "run-applescript": "7.1.0",
+    "shell-quote": "1.8.3",
+    "structured-clone-es": "2.0.0",
     "ua-parser-modern": "0.1.1",
     "whenexpr": "0.1.2",
     "wsl-utils": "0.3.1",

package/skills/devframe/SKILL.md

@@ -3,21 +3,21 @@ name: devframe
 description: >
   Use when building one devtool integration with devframe — the
   portable, framework-neutral container for a single tool. Covers
-  DevtoolDefinition, picking the right deployment adapter
+  DevframeDefinition, picking the right deployment adapter
   (cli / build / spa / vite / embedded / mcp), designing RPC
   contracts, exposing an agent-native surface over MCP, and wiring
   the author's SPA client. Hub-only concerns (docks, terminals,
   commands, the unified messages dock) belong to
   `@vitejs/devtools-kit` — see the `vite-devtools-kit` skill for
-  those. Triggers on `devframe` imports, `defineDevtool`,
-  `createCli`, `createMcpServer`, `connectDevtool`, and on
+  those. Triggers on `devframe` imports, `defineDevframe`,
+  `createCli`, `createMcpServer`, `connectDevframe`, and on
   migrations of existing inspectors (eslint-config-inspector,
   unocss-inspector, node-modules-inspector-style tools) to devframe.
 ---
 
 # devframe skill
 
-**Devframe is the container for one devtool integration, portable across viewers.** A devtool built on devframe is a single `DevtoolDefinition` plus an author-provided SPA — the same definition deploys as a standalone CLI, a static report, an embedded SPA, an MCP server, or as a dock entry inside the Vite DevTools hub via `createPluginFromDevframe`.
+**Devframe is the container for one devtool integration, portable across viewers.** A devtool built on devframe is a single `DevframeDefinition` plus an author-provided SPA — the same definition deploys as a standalone CLI, a static report, an embedded SPA, an MCP server, or as a dock entry inside the Vite DevTools hub via `createPluginFromDevframe`.
 
 Devframe deliberately stops at the boundary of one tool. Anything that only matters across multiple integrations — docks, terminals, command palette, cross-tool toasts — lives in `@vitejs/devtools-kit`, the hub layer. `devframe` must not depend on Vite, any `@vitejs/*` package, or hub-only concepts; it's the lowest-level layer in the monorepo.
 
@@ -25,7 +25,7 @@ Full reference: [devfra.me/](https://devfra.me/).
 
 ## When to use devframe
 
-All adapter factories share the shape `createXxx(devtoolDef, options?)`.
+All adapter factories share the shape `createXxx(devframeDef, options?)`.
 
 | Author goal | Factory | Entry |
 |-------------|---------|-------|
@@ -37,14 +37,14 @@ All adapter factories share the shape `createXxx(devtoolDef, options?)`.
 | Register dynamically at runtime | `createEmbedded(def, { ctx })` | `devframe/adapters/embedded` |
 | Expose to coding agents (MCP) | `createMcpServer(def, options?)` | `devframe/adapters/mcp` *(experimental)* |
 
-The same `DevtoolDefinition` runs under every adapter — pick based on deployment, not on what the tool does.
+The same `DevframeDefinition` runs under every adapter — pick based on deployment, not on what the tool does.
 
-## Minimum viable devtool
+## Minimum viable devframe
 
 ```ts
-import { defineDevtool, defineRpcFunction } from 'devframe'
+import { defineDevframe, defineRpcFunction } from 'devframe'
 
-export default defineDevtool({
+export default defineDevframe({
   id: 'my-inspector',
   name: 'My Inspector',
   icon: 'ph:magnifying-glass-duotone',
@@ -61,16 +61,16 @@ export default defineDevtool({
 
 `setup(ctx)` registers RPC functions, shared state, diagnostics, and any other devframe-level wiring. It does **not** receive `docks` / `terminals` / `messages` / `commands` — those are hub features. When mounted into Vite DevTools via `createPluginFromDevframe(d)`, the kit auto-derives an iframe dock entry from `id` / `name` / `icon` / `basePath`; for richer hub-side behaviour (custom-render, terminals, palette commands) pass `options.setup` to `createPluginFromDevframe`.
 
-See `templates/counter-devtool.ts` for a runnable counter example, `templates/spa-devtool.ts` for an SPA-ready shape, and `templates/vite-client.ts` for the author's client entry.
+See `templates/counter-devframe.ts` for a runnable counter example, `templates/spa-devframe.ts` for an SPA-ready shape, and `templates/vite-client.ts` for the author's client entry.
 
 ## Namespacing
 
-**Always prefix** RPC names, dock IDs, command IDs, shared-state keys, and agent tool IDs with the devtool `id`:
+**Always prefix** RPC names, dock IDs, command IDs, shared-state keys, and agent tool IDs with the devframe `id`:
 
 ```ts
 'my-inspector:get-modules' // ✓
 'my-inspector:state' // ✓
-'get-modules' // ✗ — may collide with other devtools sharing the host
+'get-modules' // ✗ — may collide with other devframes sharing the host
 ```
 
 ## DevToolsNodeContext at a glance
@@ -86,7 +86,7 @@ See `templates/counter-devtool.ts` for a runnable counter example, `templates/sp
 | `ctx.host` | Runtime abstraction — `mountStatic`, `resolveOrigin`, `getStorageDir` |
 | `ctx.mode` | `'dev'` or `'build'` — gate setup work per runtime |
 
-> Hub-only hosts (`ctx.docks`, `ctx.terminals`, `ctx.messages`, `ctx.commands`) only exist when the devtool is mounted into Vite DevTools via `createPluginFromDevframe`. See the [`vite-devtools-kit` skill](../../skills/vite-devtools-kit) for those.
+> Hub-only hosts (`ctx.docks`, `ctx.terminals`, `ctx.messages`, `ctx.commands`, `ctx.createJsonRenderer`) only exist when the devframe is mounted into Vite DevTools via `createPluginFromDevframe`. See the [`vite-devtools-kit` skill](../../skills/vite-devtools-kit) for those.
 
 ## RPC contracts
 
@@ -267,7 +267,7 @@ The kit auto-derives an iframe dock entry from `id` / `name` / `icon` / `basePat
 
 ## When clauses
 
-Gate kit-side dock / command visibility with VS Code-style expressions evaluated by the external `whenexpr` package. The runtime + types ship from `devframe/utils/when`, but the consumers (`when` field on docks and commands) live in the kit:
+Gate kit-side dock / command visibility with VS Code-style expressions. The runtime + types ship bundled from `devframe/utils/when` — no separate install. The consumers (`when` field on docks and commands) live in the kit:
 
 ```ts
 when: 'clientType == embedded'
@@ -275,7 +275,7 @@ when: 'dockOpen && !paletteOpen'
 when: 'my-inspector.ready && count >= 10'
 ```
 
-Built-in context: `clientType` (`'embedded' | 'standalone'`), `dockOpen`, `paletteOpen`, `dockSelectedId`. Plugins can add namespaced keys (`.` or `:` separators). Both the types (`WhenExpression<Ctx, S>`) and runtime (`evaluateWhen`, `resolveContextValue`) are re-exported from `devframe/utils/when`.
+Built-in context: `clientType` (`'embedded' | 'standalone'`), `dockOpen`, `paletteOpen`, `dockSelectedId`. Plugins can add namespaced keys (`.` or `:` separators). Both the types (`WhenExpression<Ctx, S>`) and runtime (`evaluateWhen`, `resolveContextValue`) come from `devframe/utils/when`.
 
 ## Agent-native surface (experimental)
 
@@ -319,25 +319,25 @@ Expose via MCP:
 ```ts
 import { createMcpServer } from 'devframe/adapters/mcp'
 
-await createMcpServer(devtool, { transport: 'stdio' })
+await createMcpServer(devframe, { transport: 'stdio' })
 ```
 
-`@modelcontextprotocol/sdk` is a peer dependency. The CLI adapter also exposes `my-devtool mcp` — route host logs to stderr (stdout is the MCP transport). Safety classifications (`'read' | 'action' | 'destructive'`) drive MCP hint annotations that agent clients use to prompt for confirmation.
+`@modelcontextprotocol/sdk` is a peer dependency. The CLI adapter also exposes `my-devframe mcp` — route host logs to stderr (stdout is the MCP transport). Safety classifications (`'read' | 'action' | 'destructive'`) drive MCP hint annotations that agent clients use to prompt for confirmation.
 
 ## Author SPA
 
 Authors bring their own SPA (any framework or plain HTML). Client entry:
 
 ```ts
-import { connectDevtool } from 'devframe/client'
+import { connectDevframe } from 'devframe/client'
 
-const rpc = await connectDevtool()
+const rpc = await connectDevframe()
 // await rpc.ensureTrusted() // WS mode only — blocks until server accepts
 
 const data = await rpc.call('my-inspector:get-stats', { limit: 10 })
 ```
 
-`connectDevtool` auto-detects the backend via `/.devtools/.connection.json`:
+`connectDevframe` auto-detects the backend via `/.devtools/.connection.json`:
 
 - **websocket** (dev mode) — full read/write, requires auth handshake. Listen for token updates on the `vite-devtools-auth` BroadcastChannel.
 - **static** (build / spa output) — read-only, resolves calls from the baked RPC dump.
@@ -366,7 +366,7 @@ At runtime, static clients look up the argument hash in the dump; misses resolve
 
 ## CLI adapter subcommands
 
-`createCli(devtool).parse()` gives the tool four subcommands out of the box:
+`createCli(devframe).parse()` gives the tool four subcommands out of the box:
 
 | Subcommand | Action |
 |------------|--------|
@@ -377,23 +377,45 @@ At runtime, static clients look up the argument hash in the dump; misses resolve
 
 **Bring your own CLI framework?** `createCli` is just a cac wrapper around three peer factories — `createDevServer` (`devframe/adapters/dev`), `createBuild` (`devframe/adapters/build`), and `createMcpServer` (`devframe/adapters/mcp`). Use them directly with commander/yargs/oclif when `createCli`'s baked-in command structure doesn't fit. `createDevServer` returns a `StartedServer` handle (`origin`, `port`, `app`, `wss`, `close()`) so you can wire SIGINT / hot-reload teardown into the surrounding program. `parseCliFlags(schema, raw)` and `defineCliFlags(...)` (both from `devframe/adapters/cli`) validate an arbitrary flag bag against a `CliFlagsSchema` — typed flags aren't tied to cac.
 
+## Bundled utilities
+
+Devframe re-exports a curated set of helpers under `devframe/utils/*`. They are bundled — never add the underlying packages to a devtool's own `package.json`:
+
+| Import | Wraps | Use for |
+|--------|-------|---------|
+| `colors` from `devframe/utils/colors` | `ansis` | Terminal ANSI colors (`c.red`, `c.green`, tagged templates) |
+| `open` from `devframe/utils/open` | `open` | Open URLs / files in the OS default handler |
+| `launchEditor` from `devframe/utils/launch-editor` | `launch-editor` | Open `file:line:column` in the user's editor (optional `editor` arg) |
+| `hash` from `devframe/utils/hash` | `ohash` | Stable structural hash — cache keys, dedup |
+| `structuredClone{Serialize,Deserialize,Stringify,Parse}` from `devframe/utils/structured-clone` | `structured-clone-es` | JSON-safe round-trip of `Map` / `Set` / `Date` / `BigInt` / cycles |
+| `humanId` from `devframe/utils/human-id` | `human-id` | Human-readable IDs (`bright-orange-tiger`) |
+| `nanoid` from `devframe/utils/nanoid` | (vendored) | URL-safe random IDs |
+| `promiseWithResolver` from `devframe/utils/promise` | — | Externally-controlled `Promise` |
+| `createEventEmitter` from `devframe/utils/events` | — | Typed event bus |
+| `createSharedState` from `devframe/utils/shared-state` | (immer internal) | Immutable state container (see `ctx.rpc.sharedState`) |
+| `createStreamSink` / `createStreamReader` from `devframe/utils/streaming-channel` | — | Low-level streaming primitives |
+| `evaluateWhen` / `WhenExpression` from `devframe/utils/when` | `whenexpr` | When-clause expressions |
+
+For "open file in editor" + "reveal in finder", prefer the prebuilt `openHelpers` RPC recipe — it wires the two utilities into named RPC functions ready to register.
+
 ## Testing
 
 - Unit-test host classes with fake contexts.
-- Run `templates/counter-devtool.ts` under each adapter for integration coverage.
+- Run `templates/counter-devframe.ts` under each adapter for integration coverage.
 - Snapshot the build-static RPC dump (`<outDir>/.devtools/.rpc-dump/index.json`) to catch accidental drift in `static` function outputs.
 
 ## Further reading
 
 Devframe-level pages (one-tool, portable surface):
 
-- [Devtool Definition](https://devfra.me/devtool-definition) — fields, runtime flags, multi-adapter wiring
+- [Devframe Definition](https://devfra.me/devframe-definition) — fields, runtime flags, multi-adapter wiring
 - [Adapters](https://devfra.me/adapters) — full reference for all deployment adapters
 - [RPC](https://devfra.me/rpc) — types, schema, broadcasts, dumps
 - [Shared State](https://devfra.me/shared-state) — patches, events, client-side mutation
 - [Streaming](https://devfra.me/streaming) — chunked feeds, uploads, replay, Web/Node Streams interop
 - [When Clauses](https://devfra.me/when-clauses) — syntax, context, type-safe wrappers
 - [Structured Diagnostics](https://devfra.me/diagnostics) — coded errors via `ctx.diagnostics`, register custom codes
+- [Utilities](https://devfra.me/utilities) — bundled `devframe/utils/*` helpers (colors, hash, launchEditor, structured-clone, …)
 - [Client](https://devfra.me/client) — auth handshake, modes, discovery
 - [Agent-Native](https://devfra.me/agent-native) — agent field, tools/resources, MCP + Claude Desktop
 

package/skills/devframe/templates/{counter-devtool.ts → counter-devframe.ts}

@@ -1,11 +1,11 @@
-// Smallest possible devtool. The dock entry is auto-derived from
+// Smallest possible devframe. The dock entry is auto-derived from
 // `id` / `name` / `icon` when this definition is mounted into Vite
-// DevTools via `createPluginFromDevframe(devtool)`.
-import { defineDevtool, defineRpcFunction } from 'devframe'
+// DevTools via `createPluginFromDevframe(devframe)`.
+import { defineDevframe, defineRpcFunction } from 'devframe'
 
 let counter = 0
 
-export default defineDevtool({
+export default defineDevframe({
   id: 'counter',
   name: 'Counter',
   icon: 'ph:counter-duotone',

package/skills/devframe/templates/{spa-devtool.ts → spa-devframe.ts}

@@ -1,10 +1,10 @@
-// Devtool with setupBrowser + SPA query-loader — deployable as a static site.
+// Devframe with setupBrowser + SPA query-loader — deployable as a static site.
 // When mounted into Vite DevTools via `createPluginFromDevframe`, the kit
 // auto-derives an iframe dock from `id` / `name` / `icon`.
-import { defineDevtool, defineRpcFunction } from 'devframe'
+import { defineDevframe, defineRpcFunction } from 'devframe'
 import * as v from 'valibot'
 
-export default defineDevtool({
+export default defineDevframe({
   id: 'my-inspector',
   name: 'My Inspector',
   icon: 'ph:magnifying-glass-duotone',

package/skills/devframe/templates/vite-client.ts

@@ -1,8 +1,8 @@
 // Minimum SPA client that talks to a devframe-hosted RPC.
-import { connectDevtool } from 'devframe/client'
+import { connectDevframe } from 'devframe/client'
 
 async function main() {
-  const rpc = await connectDevtool()
+  const rpc = await connectDevframe()
   // The method names below are just examples — replace with your own.
   const data = await rpc.call('my-inspector:getStats' as any)
   document.getElementById('root')!.textContent = JSON.stringify(data)

package/dist/internal/index.mjs

@@ -1,3 +0,0 @@
-import { n as internalContextMap, t as getInternalContext } from "../context-internal-Dx_NoSv1.mjs";
-import { n as resolveBasePath, t as normalizeBasePath } from "../_shared-iZy45oG3.mjs";
-export { getInternalContext, internalContextMap, normalizeBasePath, resolveBasePath };

package/dist/utils/state.d.mts

@@ -1,50 +0,0 @@
-import { ct as EventEmitter } from "../devtool-CNvLs2_Y.mjs";
-import { Objectish, Patch } from "immer";
-
-//#region src/utils/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.
-   */
-  get: () => Immutable<T>;
-  /**
-   * Subscribe to state changes.
-   */
-  on: EventEmitter<SharedStateEvents<T>>['on'];
-  /**
-   * Mutate the state.
-   */
-  mutate: (fn: (state: T) => void) => void;
-  /**
-   * Apply patches to the state.
-   */
-  patch: (patches: Patch[]) => void;
-}
-interface SharedStateEvents<T> {
-  updated: (state: T) => void;
-  patches: (patches: Patch[]) => void;
-}
-interface SharedStateOptions<T> {
-  /**
-   * Initial state.
-   */
-  initialState: 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, createSharedState };

package/dist/utils/state.mjs

@@ -1,26 +0,0 @@
-import { createEventEmitter } from "./events.mjs";
-import { applyPatches, produce, produceWithPatches } from "immer";
-//#region src/utils/state.ts
-function createSharedState(options) {
-	const { enablePatches = false } = options;
-	const events = createEventEmitter();
-	let state = options.initialState;
-	return {
-		on: events.on,
-		get: () => state,
-		patch: (patches) => {
-			state = applyPatches(state, patches);
-			events.emit("updated", state);
-		},
-		mutate: (fn) => {
-			if (enablePatches) {
-				const [newState, patches] = produceWithPatches(state, fn);
-				state = newState;
-				events.emit("patches", patches);
-			} else state = produce(state, fn);
-			events.emit("updated", state);
-		}
-	};
-}
-//#endregion
-export { createSharedState };