devframe 0.5.3 → 0.6.0-beta.1

package/dist/utils/crypto-token.mjs

@@ -0,0 +1,45 @@
+//#region src/utils/crypto-token.ts
+const HEX = "0123456789abcdef";
+/**
+* Generate a high-entropy, URL-safe (hex) random token suitable for use as a
+* bearer credential — e.g. the persistent client auth token or an ephemeral
+* remote-dock token. Defaults to 16 bytes (128 bits) of entropy.
+*/
+function randomToken(byteLength = 16) {
+	const bytes = new Uint8Array(byteLength);
+	globalThis.crypto.getRandomValues(bytes);
+	let out = "";
+	for (let i = 0; i < bytes.length; i++) out += HEX[bytes[i] >> 4] + HEX[bytes[i] & 15];
+	return out;
+}
+/**
+* Generate a uniformly-distributed string of decimal digits using rejection
+* sampling to avoid modulo bias. Intended for short, human-typed one-time
+* codes (e.g. a 6-digit authentication code). Leading zeros are preserved.
+*/
+function randomDigits(length) {
+	const limit = 250;
+	const buf = new Uint8Array(1);
+	let out = "";
+	while (out.length < length) {
+		globalThis.crypto.getRandomValues(buf);
+		if (buf[0] < limit) out += String(buf[0] % 10);
+	}
+	return out;
+}
+/**
+* Constant-time string equality. Compares every character so the comparison
+* time does not depend on the position of the first mismatch, mitigating
+* timing side-channels when verifying secrets.
+*
+* Length is treated as public (it short-circuits on differing lengths), which
+* is appropriate for fixed-length codes and tokens.
+*/
+function timingSafeEqual(a, b) {
+	if (a.length !== b.length) return false;
+	let mismatch = 0;
+	for (let i = 0; i < a.length; i++) mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return mismatch === 0;
+}
+//#endregion
+export { randomDigits, randomToken, timingSafeEqual };

package/dist/utils/events.d.mts

@@ -1,4 +1,4 @@
-import { ct as EventsMap, ot as EventEmitter } from "../devframe-BuR6n9ZD.mjs";
+import { St as EventsMap, bt as EventEmitter } from "../devframe-BwfavB78.mjs";
 
 //#region src/utils/events.d.ts
 /**

package/dist/utils/hash.mjs

@@ -1,2 +1,2 @@
-import { t as hash } from "../hash-bwOD8RgU.mjs";
+import { t as hash } from "../hash-DFc5WwhO.mjs";
 export { hash };

package/dist/utils/launch-editor.mjs

@@ -1,2 +1,2 @@
-import { t as launchEditor } from "../launch-editor-BbNhtg7b.mjs";
+import { t as launchEditor } from "../launch-editor-CgXBgviI.mjs";
 export { launchEditor };

package/dist/utils/open.mjs

@@ -1,2 +1,2 @@
-import { t as open } from "../open-DiQn6zCH.mjs";
+import { t as open } from "../open-Dusa2Zzd.mjs";
 export { open };

package/dist/utils/scope.d.mts

@@ -0,0 +1,11 @@
+//#region src/utils/scope.d.ts
+/** Whether a name is already namespaced (contains a `:` separator). */
+declare function isQualifiedName(name: string): boolean;
+/**
+ * Prefix a bare name with `<namespace>:`. Names that already contain a
+ * `:` are returned unchanged, so callers can reference another scope's
+ * ids explicitly (e.g. `ctx.rpc.call('other-plugin:fn')`).
+ */
+declare function qualifyName(namespace: string, name: string): string;
+//#endregion
+export { isQualifiedName, qualifyName };

package/dist/utils/scope.mjs

@@ -0,0 +1,15 @@
+//#region src/utils/scope.ts
+/** Whether a name is already namespaced (contains a `:` separator). */
+function isQualifiedName(name) {
+	return name.includes(":");
+}
+/**
+* Prefix a bare name with `<namespace>:`. Names that already contain a
+* `:` are returned unchanged, so callers can reference another scope's
+* ids explicitly (e.g. `ctx.rpc.call('other-plugin:fn')`).
+*/
+function qualifyName(namespace, name) {
+	return isQualifiedName(name) ? name : `${namespace}:${name}`;
+}
+//#endregion
+export { isQualifiedName, qualifyName };

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

@@ -1,2 +1,2 @@
-import { A as ImmutableArray, F as SharedStateEvents, I as SharedStateOptions, L as SharedStatePatch, M as ImmutableObject, N as ImmutableSet, P as SharedState, R as createSharedState, j as ImmutableMap, k as Immutable } from "../devframe-BuR6n9ZD.mjs";
+import { B as SharedStatePatch, F as ImmutableObject, I as ImmutableSet, L as SharedState, M as Immutable, N as ImmutableArray, P as ImmutableMap, R as SharedStateEvents, V as createSharedState, z as SharedStateOptions } from "../devframe-BwfavB78.mjs";
 export { Immutable, ImmutableArray, ImmutableMap, ImmutableObject, ImmutableSet, SharedState, SharedStateEvents, SharedStateOptions, SharedStatePatch, createSharedState };

package/dist/utils/shared-state.mjs

@@ -1,2 +1,2 @@
-import { t as createSharedState } from "../shared-state-u0y123fi.mjs";
+import { t as createSharedState } from "../shared-state-D4PPieA0.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 "../devframe-BuR6n9ZD.mjs";
+import { A as createStreamReader, C as BufferedChunk, D as StreamReader, E as StreamErrorPayload, O as StreamSink, T as CreateStreamSinkOptions, j as createStreamSink, k as StreamSinkEvents, w as CreateStreamReaderOptions } from "../devframe-BwfavB78.mjs";
 export { BufferedChunk, CreateStreamReaderOptions, CreateStreamSinkOptions, StreamErrorPayload, StreamReader, StreamSink, StreamSinkEvents, createStreamReader, createStreamSink };

package/dist/utils/structured-clone.mjs

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

package/dist/{ws-client-CVYX9niP.d.mts → ws-client-D0z0pOhn.d.mts}

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

package/dist/ws-server-BVVMDo2n.d.mts

@@ -0,0 +1,103 @@
+import { v as RpcFunctionDefinitionAny } from "./types-DZEx4ffs.mjs";
+import { BirpcGroup, ChannelOptions } from "birpc";
+import { Peer } from "crossws";
+import { NodeAdapter } from "crossws/adapters/node";
+import { Server } from "node:http";
+import { Server as Server$1, ServerOptions } from "node:https";
+
+//#region src/rpc/transports/ws-server.d.ts
+interface DevframeNodeRpcSessionMeta {
+  id: number;
+  /** The crossws peer backing this session's socket. */
+  peer?: Peer;
+  clientAuthToken?: string;
+  isTrusted?: boolean;
+  subscribedStates: Set<string>;
+  /**
+   * Streams this session has subscribed to via
+   * `rpc.streaming.subscribe(channel, id)`. Tracked here for O(1) cleanup
+   * on disconnect; the wire format is `${channel}\x1F${id}`.
+   */
+  subscribedStreams?: Set<string>;
+  /**
+   * Inbound streams this session is currently uploading to (via
+   * `rpc.streaming.upload(channel, id)`). Tracked for cleanup on
+   * disconnect; same wire format as `subscribedStreams`.
+   */
+  uploadingStreams?: Set<string>;
+}
+interface WsRpcTransportOptions {
+  /**
+   * Attach to an existing HTTP(S) server, sharing its port. Combine with
+   * `path` to bind the WS endpoint to a single route so it coexists with
+   * other upgrade handlers on the same server (e.g. a Vite dev server's HMR
+   * socket). The shared server's lifecycle is owned by the caller — closing
+   * this transport detaches the upgrade listener without closing the server.
+   */
+  server?: Server | Server$1;
+  /** Port for a newly-created standalone WS server. */
+  port?: number;
+  /** Host for a newly-created standalone WS server. Defaults to `localhost`. */
+  host?: string;
+  /**
+   * Restrict the WS endpoint to a single upgrade route (e.g. `/__devframe_ws`). When
+   * sharing a `server`, non-matching upgrade requests are left untouched for
+   * other listeners to handle, so devframe's socket can sit alongside
+   * framework sockets (Vite HMR, etc.).
+   */
+  path?: string;
+  /**
+   * Destroy upgrade requests that don't match `path` instead of leaving them
+   * for other listeners. Enable this when devframe owns the shared server
+   * outright (nothing else handles its upgrades), so an off-route client is
+   * rejected promptly rather than left hanging. Default: `false`
+   * (coexist-friendly); servers this transport creates itself always
+   * destroy unmatched upgrades.
+   */
+  destroyUnmatched?: boolean;
+  /** When set, a new https.Server is created and the WS endpoint is attached to it. */
+  https?: ServerOptions;
+  /**
+   * RPC function definitions, used by the per-call wire serializer to
+   * dispatch between strict-JSON and structured-clone encoding based
+   * on each function's `jsonSerializable` flag.
+   *
+   * When omitted, all messages fall back to structured-clone — safe but
+   * loses dev-time validation for `jsonSerializable: true` declarations.
+   */
+  definitions?: ReadonlyMap<string, Pick<RpcFunctionDefinitionAny, 'jsonSerializable'>>;
+  onConnected?: (peer: Peer, meta: DevframeNodeRpcSessionMeta) => void;
+  onDisconnected?: (peer: Peer, meta: DevframeNodeRpcSessionMeta) => void;
+  /** Override the default per-call serializer. Most callers should leave this unset. */
+  serialize?: ChannelOptions['serialize'];
+  /** Override the default per-call deserializer. Most callers should leave this unset. */
+  deserialize?: ChannelOptions['deserialize'];
+}
+interface WsRpcTransport {
+  /**
+   * The crossws node adapter driving the socket — exposes the connected
+   * `peers` and pub/sub. See https://crossws.h3.dev.
+   */
+  ws: NodeAdapter;
+  /** Remove the upgrade listener from a shared `server` (a no-op otherwise). */
+  detach: () => void;
+  /**
+   * Tear the transport down deterministically: detach from a shared server,
+   * force-terminate every connected peer, and close any server this
+   * transport created itself (`port` / `https` modes).
+   */
+  close: () => Promise<void>;
+}
+/**
+ * Attach a WebSocket transport to an existing RPC group, powered by
+ * [crossws](https://crossws.h3.dev). Either attach to an existing HTTP(S)
+ * `server` (sharing its port, optionally scoped to a `path`), or let this
+ * helper create a standalone server from `port` / `host` / `https`.
+ *
+ * Returns the crossws node adapter plus `detach` (remove the upgrade
+ * listener from a shared `server`) and `close` (full deterministic
+ * teardown).
+ */
+declare function attachWsRpcTransport<ClientFunctions extends object, ServerFunctions extends object>(rpcGroup: BirpcGroup<ClientFunctions, ServerFunctions, false>, options?: WsRpcTransportOptions): WsRpcTransport;
+//#endregion
+export { attachWsRpcTransport as i, WsRpcTransport as n, WsRpcTransportOptions as r, DevframeNodeRpcSessionMeta as t };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "devframe",
   "type": "module",
-  "version": "0.5.3",
+  "version": "0.6.0-beta.1",
   "description": "Framework for building generic devframes",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -40,13 +40,14 @@
     "./rpc/transports/ws-server": "./dist/rpc/transports/ws-server.mjs",
     "./types": "./dist/types/index.mjs",
     "./utils/colors": "./dist/utils/colors.mjs",
+    "./utils/crypto-token": "./dist/utils/crypto-token.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/scope": "./dist/utils/scope.mjs",
     "./utils/serve-static": "./dist/utils/serve-static.mjs",
     "./utils/shared-state": "./dist/utils/shared-state.mjs",
     "./utils/streaming-channel": "./dist/utils/streaming-channel.mjs",
@@ -71,12 +72,14 @@
     "@valibot/to-json-schema": "^1.7.0",
     "birpc": "^4.0.0",
     "cac": "^7.0.0",
+    "crossws": "^0.4.8",
+    "destr": "^2.0.5",
     "h3": "2.0.1-rc.22",
     "mrmime": "^2.0.1",
-    "nostics": "^0.2.0",
+    "nostics": "^1.1.4",
     "pathe": "^2.0.3",
-    "valibot": "^1.4.1",
-    "ws": "^8.21.0"
+    "ufo": "^1.6.4",
+    "valibot": "^1.4.1"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -93,7 +96,8 @@
     "tinyglobby": "^0.2.16",
     "tsdown": "^0.22.0",
     "ua-parser-modern": "^0.1.1",
-    "whenexpr": "^0.1.2"
+    "whenexpr": "^0.1.2",
+    "ws": "^8.21.0"
   },
   "inlinedDependencies": {
     "bundle-name": "4.1.0",
@@ -124,6 +128,7 @@
   },
   "scripts": {
     "build": "tsdown",
-    "watch": "tsdown --watch"
+    "watch": "tsdown --watch",
+    "typecheck": "tsc --noEmit"
   }
 }

package/skills/devframe/SKILL.md

@@ -50,11 +50,16 @@ import { defineDevframe, defineRpcFunction } from 'devframe'
 export default defineDevframe({
   id: 'my-inspector',
   name: 'My Inspector',
+  version: '1.0.0',
+  packageName: 'my-inspector',
+  homepage: 'https://github.com/me/my-inspector',
+  description: 'Inspects things and reports stats.',
   icon: 'ph:magnifying-glass-duotone',
   cli: { distDir: './client/dist' },
   setup(ctx) {
-    ctx.rpc.register(defineRpcFunction({
-      name: 'my-inspector:get-stats',
+    const my = ctx.scope('my-inspector') // preferred — auto-namespaces ids
+    my.rpc.register(defineRpcFunction({
+      name: 'get-stats', // stored as `my-inspector:get-stats`
       type: 'static',
       handler: () => ({ count: 42 }),
     }))
@@ -62,13 +67,77 @@ export default defineDevframe({
 })
 ```
 
+**Recommended:** keep `version` / `packageName` / `homepage` / `description` in sync with your published package by sourcing them from `package.json` rather than hardcoding. The package's `name` maps to `packageName`; the devframe `name` is a separate display label. Use the JSON import-attribute form so it resolves under both bundlers and Node's native TypeScript execution:
+
+```ts
+import pkg from '../package.json' with { type: 'json' }
+
+export default defineDevframe({
+  id: 'my-inspector',
+  name: 'My Inspector',
+  version: pkg.version,
+  packageName: pkg.name,
+  homepage: pkg.homepage,
+  description: pkg.description,
+  // …
+})
+```
+
 `setup(ctx)` registers RPC functions, shared state, diagnostics, and any other devframe-level wiring. Host adapters can augment `ctx` with extra surfaces — for example, mounting into Vite DevTools via `createPluginFromDevframe(d)` exposes `docks`, `terminals`, `messages`, and `commands` on the augmented context, and the kit auto-derives an iframe dock entry from `id` / `name` / `icon` / `basePath`. For richer host-side behaviour (custom-render, terminals, palette commands) pass `options.setup` to `createPluginFromDevframe`.
 
 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.
 
+## Scoped context (preferred)
+
+`ctx.scope(id)` (server) and `client.scope(id)` (browser) return a namespace-scoped view that auto-prefixes every RPC id, shared-state key, and streaming channel with `id:`, and adds a top-level persisted `settings` store. Prefer it over the raw `ctx.rpc` / client — you name the namespace once and register / call by bare name.
+
+```ts
+// server — setup(ctx)
+const my = ctx.scope('my-inspector')
+my.rpc.register(getStats) //              -> my-inspector:get-stats
+await my.rpc.call('get-stats') //         invokeLocal, namespaced
+const state = await my.rpc.sharedState('view') // -> my-inspector:view
+await my.settings.project.set('theme', 'dark')
+
+// browser — connectDevframe()
+const my = (await connectDevframe()).scope('my-inspector')
+const stats = await my.rpc.call('get-stats')
+```
+
+- **Auto-namespacing.** Bare names get `id:` prepended; a name already containing `:` is treated as fully-qualified and passed through (so `my.rpc.call('other-tool:fn')` works). `register` only accepts bare names — passing a namespaced one throws `DF0034`.
+- **Typed bare calls.** Define functions with bare names and augment the registry with `RpcDefinitionsToFunctionsWithNamespace<'my-inspector', typeof serverFunctions>` so the registry keys match the namespaced runtime ids; scoped `call('get-stats')` then stays typed.
+- **`base`.** The scoped context keeps the raw context as `my.base` (and re-exposes `views` / `diagnostics` / `agent` / `host` / `cwd` / `mode` on the server).
+
+### Settings
+
+`my.settings` is a persisted key-value store at the **top level** of the scoped context (a sibling of `my.rpc`, not under it). Two scopes:
+
+- `project` — per-workspace, persisted under the host's `workspace` storage dir.
+- `global` — per-user, persisted under the host's `global` storage dir.
+
+Both are file-backed on the server and synced to clients over the shared-state protocol, so a `set` on either side propagates everywhere and survives restarts. All methods are async.
+
+```ts
+await my.settings.project.set('theme', 'dark')
+await my.settings.project.get('theme') // 'dark'
+await my.settings.global.all()
+await my.settings.project.delete('theme')
+const off = await my.settings.global.onChange(value => apply(value))
+```
+
+Type a namespace's settings shape by augmenting `DevframeSettingsRegistry`:
+
+```ts
+declare module 'devframe' {
+  interface DevframeSettingsRegistry {
+    'my-inspector': { theme: 'light' | 'dark', recentFiles: string[] }
+  }
+}
+```
+
 ## Project layout
 
-Once a devframe grows past a handful of RPC functions, split them out — one file per function under `src/rpc/functions/`, with `src/rpc/index.ts` as the barrel. The `functions/` subdirectory leaves room for sibling files like `src/rpc/utils.ts` (helpers, type aliases) as the surface grows. Each function file exports a named const; the barrel collects them into a `const serverFunctions = [...] as const` that feeds the type-safe client registry recipe (`RpcDefinitionsToFunctions<typeof serverFunctions>`).
+Once a devframe grows past a handful of RPC functions, split them out — one file per function under `src/rpc/functions/`, with `src/rpc/index.ts` as the barrel. The `functions/` subdirectory leaves room for sibling files like `src/rpc/utils.ts` (helpers, type aliases) as the surface grows. Each function file exports a named const with a **bare** name; the barrel collects them into a `const serverFunctions = [...] as const` and feeds the type-safe client registry recipe with the namespace-aware helper `RpcDefinitionsToFunctionsWithNamespace<'my-tool', typeof serverFunctions>` (it prefixes each bare name to match the namespaced runtime id the scope registers).
 
 ```ts
 // src/rpc/functions/list-files.ts
@@ -76,7 +145,7 @@ import { defineRpcFunction } from 'devframe'
 import { getMyToolContext } from '../../context'
 
 export const listFiles = defineRpcFunction({
-  name: 'my-tool:list-files',
+  name: 'list-files', // bare — the scope namespaces it to `my-tool:list-files`
   type: 'query',
   jsonSerializable: true,
   setup: (ctx) => {
@@ -95,25 +164,34 @@ export const serverFunctions = [getCwd, listFiles] as const
 
 declare module 'devframe' {
   interface DevframeRpcServerFunctions
-    extends import('devframe/rpc').RpcDefinitionsToFunctions<typeof serverFunctions> {}
+    extends import('devframe/rpc').RpcDefinitionsToFunctionsWithNamespace<'my-tool', typeof serverFunctions> {}
 }
 ```
 
 ```ts
 // src/devframe.ts
 import { defineDevframe } from 'devframe/types'
+import pkg from '../package.json' with { type: 'json' }
 import { setMyToolContext } from './context'
 import { serverFunctions } from './rpc'
 
 export default defineDevframe({
   id: 'my-tool',
+  name: 'My Tool',
+  version: pkg.version,
+  packageName: pkg.name,
+  homepage: pkg.homepage,
+  description: pkg.description,
   setup(ctx) {
+    const my = ctx.scope('my-tool')
     setMyToolContext(ctx, { loaders: createLoaders() })
-    serverFunctions.forEach(fn => ctx.rpc.register(fn))
+    serverFunctions.forEach(fn => my.rpc.register(fn))
   },
 })
 ```
 
+Note `setMyToolContext(ctx, …)` keys off the raw `ctx` (the same object the function `setup(ctx)` receives) — store the per-tool context on `ctx`, register through `my.rpc`.
+
 ### Sharing setup-time state via `src/context.ts`
 
 When per-file RPCs need access to runtime values that `setup(ctx)` constructs once — streaming channels, shared state handles, watchers, loaders, caches — expose them through a `WeakMap<DevframeNodeContext, T>` in a sibling `src/context.ts`. This mirrors the framework's own `internalContextMap` in `packages/devframe/src/node/hub-internals/context.ts`. The WeakMap keys off the existing `DevframeNodeContext` so contexts are garbage-collected automatically when the host tears down.
@@ -153,12 +231,15 @@ Stateless RPCs and tiny demos can keep the inline shorthand inside `setup(ctx)`
 'get-modules' // ✗ — may collide with other devframes sharing the host
 ```
 
+A [scoped context](#scoped-context-preferred) applies this prefix for you — `ctx.scope('my-inspector').rpc.register({ name: 'get-modules' })` registers `my-inspector:get-modules`. Define and call by bare name through the scope; reach for full ids only via `ctx.base` or when targeting another tool. Dock / command IDs are host-level (not part of the scoped `rpc` surface) — prefix those by hand.
+
 ## DevframeNodeContext at a glance
 
 `setup(ctx)` receives the framework-neutral server-side surface. Each host corresponds to a [docs](https://devfra.me/) page:
 
 | Host | Purpose |
 |------|---------|
+| `ctx.scope(id)` | **Preferred** namespace-scoped view — auto-prefixed `rpc` + top-level `settings` store |
 | `ctx.rpc` | Register RPC functions, broadcast, shared state, streaming channels |
 | `ctx.views` | Serve static files via `hostStatic(base, distDir)` |
 | `ctx.diagnostics` | Structured diagnostics host (nostics) — register custom error codes |
@@ -175,7 +256,7 @@ import { defineRpcFunction } from 'devframe'
 import * as v from 'valibot'
 
 const getModules = defineRpcFunction({
-  name: 'my-inspector:get-modules',
+  name: 'get-modules', // bare — registered via `ctx.scope('my-inspector').rpc.register`
   type: 'query',
   jsonSerializable: true,
   args: [v.object({ limit: v.number() })],
@@ -208,12 +289,13 @@ Set `jsonSerializable: true` when your handler returns plain JSON shapes — the
 
 `agent: {...}` requires `jsonSerializable: true` (registration throws `DF0019` otherwise). MCP tools speak JSON — opting into the agent surface is also opting into JSON-only data.
 
-`ctx.rpc.broadcast({ method, args, optional?, event?, filter? })` pushes to every connected client. `ctx.rpc.invokeLocal(name, ...args)` calls a server function without going through transport (useful for cross-function composition).
+Through the scope, `my.rpc.broadcast({ method, args, optional?, event?, filter? })` pushes to every connected client (method name namespaced), and `my.rpc.call(name, ...args)` invokes a server function locally without going through transport (the scoped form of `ctx.rpc.invokeLocal`, useful for cross-function composition).
 
 ## Shared state
 
 ```ts
-const state = await ctx.rpc.sharedState.get('my-inspector:state', {
+const my = ctx.scope('my-inspector')
+const state = await my.rpc.sharedState('state', { // -> my-inspector:state
   initialValue: { count: 0, items: [] as string[] },
 })
 
@@ -232,7 +314,8 @@ state.mutate((draft) => {
 For chunk-style data flowing in either direction — LLM deltas, log tails, build progress, file uploads, mic / screen-share frames — use a streaming channel instead of inventing `action + delta/end` events. The same `channel` object handles both directions:
 
 ```ts
-const channel = ctx.rpc.streaming.create<string>('my-inspector:tokens', {
+const my = ctx.scope('my-inspector')
+const channel = my.rpc.streaming.create<string>('tokens', { // -> my-inspector:tokens
   replayWindow: 256, // server keeps last N chunks per stream id
   closedStreamRetention: 30_000, // ms to hold finished streams for late subscribers
 })
@@ -252,8 +335,8 @@ stream.writable // WritableStream<T> for `pipeTo`-style consumption
 // Convenience — start + pipe in one call:
 await channel.pipeFrom(sourceReadable, { id: 'optional' })
 
-// Client
-const reader = rpc.streaming.subscribe<string>('my-inspector:tokens', streamId)
+// Client — my = (await connectDevframe()).scope('my-inspector')
+const reader = my.rpc.streaming.subscribe<string>('tokens', streamId) // -> my-inspector:tokens
 for await (const token of reader) renderToken(token)
 // Or: reader.readable.pipeTo(domWritable)
 reader.cancel() // server `stream.signal` aborts
@@ -264,9 +347,9 @@ reader.cancel() // server `stream.signal` aborts
 The same channel exposes `openInbound()` for the server side of a client→server upload. Pair it with a normal action that returns the id:
 
 ```ts
-// Server
-ctx.rpc.register(defineRpcFunction({
-  name: 'my-inspector:upload-file',
+// Server — my = ctx.scope('my-inspector')
+my.rpc.register(defineRpcFunction({
+  name: 'upload-file', // -> my-inspector:upload-file
   type: 'action',
   args: [v.object({ name: v.string() })],
   returns: v.object({ uploadId: v.string() }),
@@ -279,9 +362,9 @@ ctx.rpc.register(defineRpcFunction({
   },
 }))
 
-// Client
-const { uploadId } = await rpc.call('my-inspector:upload-file', { name: 'foo' })
-const upload = rpc.streaming.upload<Uint8Array>('my-inspector:files', uploadId)
+// Client — my = (await connectDevframe()).scope('my-inspector')
+const { uploadId } = await my.rpc.call('upload-file', { name: 'foo' })
+const upload = my.rpc.streaming.upload<Uint8Array>('files', uploadId) // -> my-inspector:files
 fileReadable.pipeTo(upload.writable, { signal: upload.signal })
 ```
 
@@ -411,10 +494,11 @@ Authors bring their own SPA (any framework or plain HTML). Client entry:
 ```ts
 import { connectDevframe } from 'devframe/client'
 
-const rpc = await connectDevframe()
-// await rpc.ensureTrusted() // WS mode only — blocks until server accepts
+const client = await connectDevframe()
+// await client.ensureTrusted() // WS mode only — blocks until server accepts
+const my = client.scope('my-inspector') // preferred — namespaced calls
 
-const data = await rpc.call('my-inspector:get-stats', { limit: 10 })
+const data = await my.rpc.call('get-stats', { limit: 10 })
 ```
 
 `connectDevframe` auto-detects the backend via `/.devframe/.connection.json`:
@@ -422,7 +506,7 @@ const data = await rpc.call('my-inspector:get-stats', { limit: 10 })
 - **websocket** (dev mode) — full read/write, requires auth handshake. Listen for token updates on the `devframe-auth` BroadcastChannel.
 - **static** (build / spa output) — read-only, resolves calls from the baked RPC dump.
 
-Use `rpc.sharedState.get(key)` for observable state, `rpc.client.register(defineRpcFunction(...))` to receive server broadcasts, and `rpc.callOptional(...)` when a missing handler should resolve to `undefined` instead of throwing.
+Use `my.rpc.sharedState(key)` for observable state, `my.rpc.register(defineRpcFunction(...))` to receive server broadcasts, `my.rpc.callOptional(...)` when a missing handler should resolve to `undefined` instead of throwing, and `my.settings.{project,global}` for persisted per-workspace / per-user settings synced from the server.
 
 ## Build dumps
 
@@ -468,8 +552,8 @@ Devframe re-exports a curated set of helpers under `devframe/utils/*`. They are
 | `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 |
+| `randomToken` / `randomDigits` / `timingSafeEqual` from `devframe/utils/crypto-token` | (native WebCrypto) | CSPRNG bearer tokens, one-time codes, constant-time compare |
 | `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`) |
@@ -478,6 +562,20 @@ Devframe re-exports a curated set of helpers under `devframe/utils/*`. They are
 
 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.
 
+## Security (secure by default)
+
+RPC handlers run with the full privileges of the host process, so the boundary that matters is who may connect. Keep that boundary tight:
+
+- **`auth` defaults to `true`** — dev-mode connections must authenticate before calls are accepted. Devframe ships the node primitives (`exchangeTempAuthCode`, `verifyAuthToken` in `devframe/node/auth`); the host adapter (e.g. Vite DevTools) provides the interactive `devframe:anonymous:auth` + `devframe:auth:exchange` handlers and auth UI.
+- **`auth: false` trusts every reachable connection.** Use it only for single-user `localhost` tools. Never combine it with a non-loopback bind host, a tunnel, or a shared/CI environment. The default bind host is already `localhost`.
+- **Authentication** exchanges a 6-digit one-time code (shown in the developer's terminal) for a node-issued bearer token via `requestTrustWithCode(code)`. The code is single-use, expires in 5 min, compared in constant time, and rotates after repeated failures — show it only in the terminal, never over the network.
+- **Magic-link (optional):** print `buildOtpAuthUrl(origin)` — `<origin>/?devframe_otp=<code>`. `connectDevframe` reads the code, exchanges it, and strips it from the URL. Integrations can opt out (`otpParam: false`) and drive it via the exposed `authenticateWithUrlOtp(rpc)` / `consumeOtpFromUrl()` client utilities. Only the single-use code rides the URL, never the bearer; treat the printed link like the code itself.
+- **Tokens are secrets.** The bearer token rides the WS URL (`?devframe_auth_token=…`) — serve over `wss://`/`https://` beyond loopback. Never log the token or code, never bake them into build output. Revoke via `revokeAuthToken(...)`; clients drop to untrusted on `devframe:auth:revoked`.
+- **Authorize handlers.** Any trusted client can call any registered function — validate inputs, and mark state-changing functions `type: 'destructive'` so MCP/agent clients prompt first.
+- **Origin-lock remote docks** (`originLock`) so a dock token is honored only from its expected origin.
+
+See [Security](https://devfra.me/security) for the full reference.
+
 ## Testing
 
 - Unit-test host classes with fake contexts.
@@ -489,6 +587,7 @@ For "open file in editor" + "reveal in finder", prefer the prebuilt `openHelpers
 Devframe-level pages (one-tool, portable surface):
 
 - [Devframe Definition](https://devfra.me/devframe-definition) — fields, runtime flags, multi-adapter wiring
+- [Scoped Context](https://devfra.me/scoped-context) — `ctx.scope(id)`, auto-namespacing, the `settings` store
 - [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
@@ -497,6 +596,7 @@ Devframe-level pages (one-tool, portable surface):
 - [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
+- [Security](https://devfra.me/security) — trust model, authentication, secure-by-default practices
 - [Agent-Native](https://devfra.me/agent-native) — agent field, tools/resources, MCP + Claude Desktop
 
 Host-specific extras (when mounting into Vite DevTools — other hosts have their own equivalents):

package/skills/devframe/templates/counter-devframe.ts

@@ -2,21 +2,31 @@
 // `id` / `name` / `icon` when this definition is mounted into Vite
 // DevTools via `createPluginFromDevframe(devframe)`.
 import { defineDevframe, defineRpcFunction } from 'devframe'
+// Recommended: source version/packageName/homepage/description from your
+// package.json so the published metadata stays in sync. The import-attribute
+// form resolves under both bundlers and Node's native TypeScript execution.
+import pkg from '../package.json' with { type: 'json' }
 
 let counter = 0
 
 export default defineDevframe({
   id: 'counter',
   name: 'Counter',
+  version: pkg.version,
+  packageName: pkg.name,
+  homepage: pkg.homepage,
+  description: pkg.description,
   icon: 'ph:counter-duotone',
   setup(ctx) {
-    ctx.rpc.register(defineRpcFunction({
-      name: 'counter:get',
+    // Scoped context — auto-namespaces ids with `counter:`.
+    const my = ctx.scope('counter')
+    my.rpc.register(defineRpcFunction({
+      name: 'get', // -> counter:get
       type: 'static',
       handler: () => ({ count: counter }),
     }))
-    ctx.rpc.register(defineRpcFunction({
-      name: 'counter:bump',
+    my.rpc.register(defineRpcFunction({
+      name: 'bump', // -> counter:bump
       type: 'action',
       handler: () => ({ count: ++counter }),
     }))