feat: introduce scoped context and settings store (#41)

Author: antfubot

alias.ts

@@ -25,6 +25,7 @@ export const alias = {
   'devframe/utils/nanoid': r('devframe/src/utils/nanoid.ts'),
   'devframe/utils/open': r('devframe/src/utils/open.ts'),
   'devframe/utils/promise': r('devframe/src/utils/promise.ts'),
+  'devframe/utils/scope': r('devframe/src/utils/scope.ts'),
   'devframe/utils/serve-static': r('devframe/src/utils/serve-static.ts'),
   'devframe/utils/shared-state': r('devframe/src/utils/shared-state.ts'),
   'devframe/utils/streaming-channel': r('devframe/src/utils/streaming-channel.ts'),

docs/.vitepress/config.ts

@@ -21,6 +21,7 @@ function guideItems(prefix: string): DefaultTheme.NavItemWithLink[] {
     { text: 'Introduction', link: `${prefix}/guide/` },
     { text: 'Built with Devframe', link: `${prefix}/guide/built-with` },
     { text: 'Devframe Definition', link: `${prefix}/guide/devframe-definition` },
+    { text: 'Scoped Context', link: `${prefix}/guide/scoped-context` },
     { text: 'RPC', link: `${prefix}/guide/rpc` },
     { text: 'Shared State', link: `${prefix}/guide/shared-state` },
     { text: 'Streaming', link: `${prefix}/guide/streaming` },

docs/errors/DF0034.md

@@ -0,0 +1,34 @@
+---
+outline: deep
+---
+
+# DF0034: Already-Namespaced Scoped Registration
+
+## Message
+
+> Scoped RPC registration for namespace "`{namespace}`" received an already-namespaced function name "`{name}`".
+
+## Cause
+
+A [scoped context](../guide/scoped-context) auto-namespaces the ids you pass it. `ctx.scope('my-plugin').rpc.register(...)` therefore expects a **bare** function name and stores it as `my-plugin:<name>`. Passing a name that already contains a `:` separator would produce a double-prefixed id, so registration throws instead.
+
+## Example
+
+```ts
+const my = ctx.scope('my-plugin')
+
+// ✗ Bad — already namespaced
+my.rpc.register(defineRpcFunction({ name: 'my-plugin:get-cwd', type: 'query', handler }))
+
+// ✓ Good — bare name, stored as `my-plugin:get-cwd`
+my.rpc.register(defineRpcFunction({ name: 'get-cwd', type: 'query', handler }))
+```
+
+## Fix
+
+- Pass a bare name (no `:` separator) to the scoped `register`.
+- To register a fully-qualified name on purpose, use the unscoped host: `ctx.base.rpc.register(...)` (server) or `client.scope(...).base.client.register(...)` (browser).
+
+## Source
+
+- [`packages/devframe/src/node/scope.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/scope.ts) — `register()` / `update()` throw this when the supplied definition name is already namespaced.

docs/guide/client.md

@@ -93,30 +93,32 @@ const ok = await rpc.requestTrustWithToken('another-token')
 
 ## Calling functions
 
+Derive a [scoped client](./scoped-context) so ids are namespaced for you:
+
 ```ts
-const rpc = await connectDevframe()
+const my = (await connectDevframe()).scope('my-devframe')
 
 // Standard call — awaits a response or throws.
-const modules = await rpc.call('my-devframe:get-modules', { limit: 10 })
+const modules = await my.rpc.call('get-modules', { limit: 10 })
 
 // Optional — returns undefined when no handler responds (useful while HMR is restarting).
-const maybe = await rpc.callOptional('my-devframe:get-modules', { limit: 10 })
+const maybe = await my.rpc.callOptional('get-modules', { limit: 10 })
 
 // Event — fire-and-forget, no response expected.
-rpc.callEvent('my-devframe:notify', { message: 'hello' })
+my.rpc.callEvent('notify', { message: 'hello' })
 ```
 
-TypeScript types flow through from the server's `defineRpcFunction` definitions, so argument and return shapes are known at the call site.
+The unscoped `rpc.call('my-devframe:get-modules', ...)` works too. Either way, TypeScript types flow through from the server's `defineRpcFunction` definitions, so argument and return shapes are known at the call site.
 
 ## Registering client functions
 
-The client can register functions that the server calls via `ctx.rpc.broadcast`:
+The client can register functions that the server calls via `rpc.broadcast`:
 
 ```ts
 import { defineRpcFunction } from 'devframe'
 
-rpc.client.register(defineRpcFunction({
-  name: 'my-devframe:on-file-changed',
+my.rpc.register(defineRpcFunction({
+  name: 'on-file-changed', // -> my-devframe:on-file-changed
   type: 'event',
   setup: () => ({
     handler: async ({ file }: { file: string }) => {
@@ -131,7 +133,7 @@ That's how the server pushes live updates into the UI — file-watcher events, s
 ## Shared state
 
 ```ts
-const state = await rpc.sharedState.get('my-devframe:state')
+const state = await my.rpc.sharedState('state') // -> my-devframe:state
 
 console.log(state.value())
 
@@ -146,6 +148,17 @@ state.on('updated', (next) => {
 
 Client-side mutations round-trip through the server before reappearing locally. See [Shared State](./shared-state) for the full API.
 
+## Settings
+
+A scoped client also exposes a top-level persisted `settings` store, synced from the server. Read and write per-user (`global`) or per-workspace (`project`) values:
+
+```ts
+await my.settings.project.set('theme', 'dark')
+const theme = await my.settings.project.get('theme')
+```
+
+See [Scoped Context](./scoped-context#settings) for the full API.
+
 ## Caching
 
 Set `cacheOptions: true` (or an options object) when constructing the client:

docs/guide/devframe-definition.md

@@ -21,9 +21,12 @@ export default defineDevframe({
   description: 'A one-line summary of what the tool does.',
   icon: 'ph:gauge-duotone',
   setup(ctx) {
+    // A scoped context auto-namespaces ids with your devframe `id`.
+    const my = ctx.scope('my-devframe')
+
     // Register your RPC functions, shared state, etc. here.
-    ctx.rpc.register(defineRpcFunction({
-      name: 'my-devframe:hello',
+    my.rpc.register(defineRpcFunction({
+      name: 'hello', // stored as `my-devframe:hello`
       type: 'static',
       jsonSerializable: true,
       handler: () => ({ message: 'hello' }),
@@ -32,7 +35,7 @@ export default defineDevframe({
 })
 ```
 
-Host adapters (such as the [`vite` adapter](/adapters/vite) for Vite DevTools) derive their mount entry from `id`, `name`, `icon`, and `basePath` automatically.
+`ctx.scope(id)` is the preferred way to consume the context — see [Scoped Context](./scoped-context). Host adapters (such as the [`vite` adapter](/adapters/vite) for Vite DevTools) derive their mount entry from `id`, `name`, `icon`, and `basePath` automatically.
 
 ## Definition fields
 
@@ -109,12 +112,17 @@ interface DevframeNodeContext {
   views: DevframeViewHost // static file hosting (`hostStatic`)
   diagnostics: DevframeDiagnosticsHost
   agent: DevframeAgentHost // experimental
+
+  scope: (id) => DevframeScopedNodeContext // namespaced view (preferred)
 }
 ```
 
+`ctx.scope(id)` returns a namespace-scoped view that auto-prefixes every RPC id, shared-state key, and streaming channel and adds a persisted top-level `settings` store. It's the recommended entry point from a single tool's setup code — see [Scoped Context](./scoped-context).
+
 Host adapters can augment `ctx` with additional surfaces. For example, the [`vite` adapter](/adapters/vite) exposes Vite DevTools' dock, command, message, and terminal hosts via an optional `setup` hook on `createPluginFromDevframe` — consult the host's docs for those extras.
 
 Each devframe-level host has a dedicated page:
+- [Scoped Context](./scoped-context) — `ctx.scope(id)`, `settings`
 - [RPC](./rpc) — `ctx.rpc`
 - [Shared State](./shared-state) — `ctx.rpc.sharedState`
 - [Diagnostics](./diagnostics) — `ctx.diagnostics`

docs/guide/rpc.md

@@ -25,20 +25,20 @@ import { defineRpcFunction } from 'devframe'
 import * as v from 'valibot'
 
 export const getModules = defineRpcFunction({
-  name: 'my-devframe:get-modules',
+  name: 'get-modules', // bare — the scope namespaces it to `my-devframe:get-modules`
   type: 'query',
   args: [v.object({ limit: v.number() })],
   returns: v.array(v.object({ id: v.string(), size: v.number() })),
   setup: ctx => ({
     handler: async ({ limit }) => {
-      // `ctx` is the DevframeNodeContext.
+      // `ctx` is the full DevframeNodeContext.
       return loadModules().slice(0, limit)
     },
   }),
 })
 ```
 
-Register it in `setup`:
+Register it in `setup` through a [scoped context](./scoped-context) — `ctx.scope(id)` auto-namespaces ids, so you register and call by bare name:
 
 ```ts
 import { defineDevframe } from 'devframe'
@@ -48,16 +48,19 @@ export default defineDevframe({
   id: 'my-devframe',
   name: 'My Devframe',
   setup(ctx) {
-    ctx.rpc.register(getModules)
+    const my = ctx.scope('my-devframe')
+    my.rpc.register(getModules)
   },
 })
 ```
 
+The unscoped `ctx.rpc.register(getModules)` works too — it's the underlying primitive the scoped surface wraps.
+
 Place each function in its own file under `src/rpc/functions/`, and barrel them in `src/rpc/index.ts` as `const serverFunctions = [...] as const`. The same array feeds the [type-safe client registry](#type-safe-client-registry) and keeps registration order explicit. When per-file functions need to share setup-time state (channels, shared state handles, loaders), expose it through a `WeakMap<DevframeNodeContext, T>` in a sibling `src/context.ts`.
 
 ### Naming convention
 
-Scope with your devframe id and use kebab-case for the action: `my-devframe:get-modules`, `my-devframe:read-file`, `my-devframe:trigger-rebuild`.
+Scope with your devframe id and use kebab-case for the action: `my-devframe:get-modules`, `my-devframe:read-file`, `my-devframe:trigger-rebuild`. A scoped context applies this prefix for you: `ctx.scope('my-devframe').rpc.register({ name: 'get-modules' })` stores `my-devframe:get-modules`. Define each function with a bare name and let the scope namespace it.
 
 ### Function types
 
@@ -76,7 +79,7 @@ Handlers accept any serializable arguments. With `args` valibot schemas, argumen
 
 ```ts
 defineRpcFunction({
-  name: 'my-devframe:get-file',
+  name: 'get-file',
   type: 'query',
   args: [v.object({ path: v.string(), includeSource: v.optional(v.boolean()) })],
   returns: v.object({ path: v.string(), source: v.optional(v.string()) }),
@@ -101,7 +104,7 @@ Two ways to wire a handler:
 ```ts
 // With setup:
 defineRpcFunction({
-  name: 'my-devframe:count',
+  name: 'count',
   type: 'query',
   setup: ctx => ({
     handler: async () => ctx.rpc.sharedState.keys().length,
@@ -110,24 +113,25 @@ defineRpcFunction({
 
 // Shorthand:
 defineRpcFunction({
-  name: 'my-devframe:echo',
+  name: 'echo',
   type: 'query',
   handler: (msg: string) => msg,
 })
 ```
 
 ## Broadcasting
 
-`ctx.rpc.broadcast` sends a message from the server to every connected client:
+`rpc.broadcast` sends a message from the server to every connected client. Through a scoped context the client method name is namespaced for you:
 
 ```ts
 defineDevframe({
   id: 'my-devframe',
   name: 'My Devframe',
   setup(ctx) {
+    const my = ctx.scope('my-devframe')
     watcher.on('change', (file) => {
-      void ctx.rpc.broadcast({
-        method: 'my-devframe:on-file-changed',
+      void my.rpc.broadcast({
+        method: 'on-file-changed', // -> my-devframe:on-file-changed
         args: [{ file }],
       })
     })
@@ -159,52 +163,58 @@ See the [Streaming guide](./streaming) for the full API.
 
 ## Local invocation
 
-`ctx.rpc.invokeLocal` calls a registered server function directly, skipping the transport — useful for cross-function composition on the server side:
+A scoped `rpc.call` invokes a registered server function directly, skipping the transport — useful for cross-function composition on the server side. Bare names resolve within the namespace:
 
 ```ts
-const modules = await ctx.rpc.invokeLocal('my-devframe:get-modules', { limit: 10 })
+const my = ctx.scope('my-devframe')
+const modules = await my.rpc.call('get-modules', { limit: 10 })
 ```
 
+This wraps `ctx.rpc.invokeLocal('my-devframe:get-modules', { limit: 10 })`. Pass a fully-qualified name (containing `:`) to call another tool's function.
+
 ## Client-side calls
 
-From the browser, [`connectDevframe`](./client) (or `getDevframeRpcClient`) returns a client for calling registered functions:
+From the browser, [`connectDevframe`](./client) (or `getDevframeRpcClient`) returns a client. Scope it the same way to call registered functions by bare name:
 
 ```ts
 import { connectDevframe } from 'devframe/client'
 
-const rpc = await connectDevframe()
+const client = await connectDevframe()
+const my = client.scope('my-devframe')
 
-const modules = await rpc.call('my-devframe:get-modules', { limit: 10 })
+const modules = await my.rpc.call('get-modules', { limit: 10 })
 ```
 
-Client-side registration (for server→client calls) goes through `rpc.client.register()` — the mirror API of `ctx.rpc.register()`.
+Client-side registration (for server→client calls) goes through `my.rpc.register()` — the mirror API of the server-side scoped `rpc.register()`.
 
 ## Type-safe client registry
 
 Devframe exposes two augmentable interfaces — `DevframeRpcServerFunctions` (client→server calls) and `DevframeRpcClientFunctions` (server→client calls) — so each registered RPC name shows up on the typed client. Augment them once per devframe via `declare module 'devframe'`.
 
-The recommended pattern collects every server-side definition into a const array and feeds it through `RpcDefinitionsToFunctions`:
+The recommended pattern collects every server-side definition into a const array and feeds it through `RpcDefinitionsToFunctionsWithNamespace` — it prefixes each bare definition name with your devframe id, matching the ids the scoped `register` stores at runtime:
 
 ```ts
-import type { RpcDefinitionsToFunctions } from 'devframe/rpc'
+import type { RpcDefinitionsToFunctionsWithNamespace } from 'devframe/rpc'
 import { getFile, getModules } from './rpc'
 
 const serverFunctions = [getModules, getFile] as const
 
 declare module 'devframe' {
   interface DevframeRpcServerFunctions
-    extends RpcDefinitionsToFunctions<typeof serverFunctions> {}
+    extends RpcDefinitionsToFunctionsWithNamespace<'my-devframe', typeof serverFunctions> {}
 }
 ```
 
+If you define functions with full namespaced names instead, use `RpcDefinitionsToFunctions<typeof serverFunctions>` (no namespace argument) and register them through the unscoped `ctx.rpc.register`.
+
 Now `connectDevframe()` returns a client where every registered name is autocompletable and argument-typed:
 
 ```ts
 import { connectDevframe } from 'devframe/client'
 
-const rpc = await connectDevframe()
-const modules = await rpc.call('my-devframe:get-modules', { limit: 10 })
-//                       ^? typed from the augmentation above
+const my = (await connectDevframe()).scope('my-devframe')
+const modules = await my.rpc.call('get-modules', { limit: 10 })
+//                          ^? typed from the augmentation above
 ```
 
 For one-off augmentations, declare a single key with `RpcFunctionDefinitionToFunction`:
@@ -227,7 +237,7 @@ For `static` functions, Devframe records the handler's output during `createBuil
 
 ```ts
 defineRpcFunction({
-  name: 'my-devframe:build-meta',
+  name: 'build-meta',
   type: 'static',
   args: [],
   returns: v.object({ version: v.string(), builtAt: v.number() }),
@@ -241,7 +251,7 @@ For `query` functions, provide an explicit `dump` to enumerate which argument se
 
 ```ts
 defineRpcFunction({
-  name: 'my-devframe:get-session',
+  name: 'get-session',
   type: 'query',
   setup: ctx => ({
     handler: async (id: string) => loadSession(id),
@@ -253,7 +263,7 @@ defineRpcFunction({
 })
 ```
 
-At runtime, static clients resolve `rpc.call('my-devframe:get-session', 'session-a')` from the baked dump; unmatched arguments resolve to `dump.fallback` (or throw without one).
+At runtime, static clients resolve `my.rpc.call('get-session', 'session-a')` from the baked dump; unmatched arguments resolve to `dump.fallback` (or throw without one).
 
 ## JSON-serializable declaration
 
@@ -272,7 +282,7 @@ The wire stays plain JSON when every participating function is JSON-flagged —
 
 ```ts
 defineRpcFunction({
-  name: 'my-devframe:graph',
+  name: 'graph',
   jsonSerializable: true,
   // ⚠ throws DF0020 because Map cannot round-trip through JSON
   handler: () => ({ nodes: new Map([['a', 1]]) }),
@@ -291,7 +301,7 @@ Add an `agent` field to surface the function to coding agents over MCP. Agent ex
 
 ```ts
 defineRpcFunction({
-  name: 'my-devframe:get-modules',
+  name: 'get-modules',
   type: 'query',
   jsonSerializable: true,
   args: [v.object({ limit: v.number() })],