feat(data-inspector): example source, docs page, in-app docs links

- built-in example source: a small live playground graph (Maps, Sets,
  class instances, circulars, BigInt, a query-time getter) with suggested
  queries; on by default, disabled via exampleSource: false, suppressed
  automatically by the agent and by the CLI when data files are given
- docs/plugins/data-inspector.md: using the plugin, providing data
  sources (registry + context service + contract), CLI, agent attach,
  static export, RPC surface; registered in the plugins sidebar/overview
- the SPA header links to the docs page, and an empty-source state
  points at the providing-data-sources section

Author: antfubot

docs/.vitepress/config.ts

@@ -61,6 +61,7 @@ function helpersItems(prefix: string) {
 function pluginsItems(prefix: string) {
   return [
     { text: 'Overview', link: `${prefix}/plugins/` },
+    { text: 'Data Inspector', link: `${prefix}/plugins/data-inspector` },
     { text: 'Devframe Inspector', link: `${prefix}/plugins/inspect` },
     { text: 'Accessibility Inspector', link: `${prefix}/plugins/a11y` },
     { text: 'Git', link: `${prefix}/plugins/git` },

docs/plugins/data-inspector.md

@@ -0,0 +1,138 @@
+---
+outline: deep
+---
+
+# Data Inspector
+
+An interactive query workbench for live server-side objects, built as a **Vue** SPA. Plugins and hosts register **data sources**; you compose [jora](https://discoveryjs.github.io/jora/) queries against them — executed in the process that owns the objects — and explore normalized results in a struct view with type badges, a data-shape panel, filters, and saved queries.
+
+Package: `@devframes/plugin-data-inspector` · framework: **Vue + Vite**
+
+## What it does
+
+- **Query workbench** — a CodeMirror jora editor with syntax highlighting and server-computed autocomplete; queries auto-run as you type, with a client-side syntax gate so malformed input never hits the wire. Source, query, and filters persist in the URL, so any workbench state is shareable.
+- **Result viewer** — results normalize to strict JSON (circulars become `$ref` markers; Maps, Sets, class instances, functions, and Dates get type badges) with per-query stats: jora / normalize / rpc timings, payload size, node count. The value-actions popup copies paths and turns any key into a query.
+- **Data shape panel** — a one-level type skeleton of the active source, independent of the query; click a property to query it.
+- **Filters** — exclude functions, `_`-prefixed, or `$`-prefixed properties from results and skeleton alike.
+- **Saved queries** — recipes (`query` + optional title/description + the filters they were authored with), id-keyed, in two scopes: **workspace** (committable, shared with the team) and **project** (per-checkout).
+
+A built-in example source demonstrates all of it on first run; disable it with `createDataInspectorDevframe({ exampleSource: false })` once your own sources are registered.
+
+## Providing data sources
+
+The registry is **process-global**: register from anywhere in the process — plugin setup, host hooks, application code — before or after the inspector mounts.
+
+```ts
+import { registerDataSource } from '@devframes/plugin-data-inspector/registry'
+
+registerDataSource({
+  id: 'my-plugin:store', // namespace with your plugin id
+  title: 'My plugin store',
+  description: 'The live state store',
+  icon: 'i-ph:database-duotone',
+  data: () => store,
+  queries: [
+    { title: 'Active sessions', query: 'sessions.mapEntries().value.[active]' },
+    { title: 'Config (data only)', query: 'config', excludeFunctions: true },
+  ],
+})
+```
+
+The contract:
+
+```ts
+interface DataSourceEntry {
+  id: string
+  title: string
+  description?: string
+  icon?: string
+  /** A plain value, or a factory returning one (sync or async). */
+  data: unknown | (() => unknown | Promise<unknown>)
+  /** The resolved value never changes: resolve once and memoize. */
+  static?: boolean
+  /** Suggested queries, shown read-only next to saved ones. */
+  queries?: Query[]
+}
+```
+
+Live objects passed to `data` stay live — every query reads their current state. `registerDataSource` returns an unregister function, and connected workbenches refresh their source list on every change.
+
+Integrations that prefer zero package dependency consume the same registry through the typed [context service](../guide/devframe-definition#cross-plugin-services):
+
+```ts
+ctx.services.whenAvailable('devframes:plugin:data-inspector:sources', (sources) => {
+  sources.register({ id: 'my-plugin:store', title: 'My store', data: () => store })
+})
+```
+
+> [!WARNING]
+> Queries are eval-grade access to registered objects: jora can invoke any function reachable as an own property and fires own getters. Register live objects with that in mind, and keep inspector endpoints on loopback.
+
+## Mount into a Vite host
+
+```ts
+import { registerDataSource } from '@devframes/plugin-data-inspector/registry'
+// vite.config.ts
+import { dataInspectorVitePlugin } from '@devframes/plugin-data-inspector/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    dataInspectorVitePlugin(),
+    {
+      name: 'my-app:data-sources',
+      configureServer(server) {
+        registerDataSource({
+          id: 'vite:server',
+          title: 'Vite Dev Server',
+          data: () => server,
+          queries: [{ title: 'Plugin names', query: 'config.plugins.name' }],
+        })
+      },
+    },
+  ],
+})
+```
+
+Hub hosts mount the default export like any devframe definition.
+
+## Standalone CLI
+
+```sh
+devframe-data-inspector                      # the example source
+devframe-data-inspector stats.json log.jsonl # one static source per data file
+devframe-data-inspector build stats.json     # self-contained static export
+devframe-data-inspector attach               # attach to a process running the agent
+```
+
+`.json` files parse whole; `.jsonl` / `.ndjson` parse as an array of records. `build` writes a static site embedding the dataset — the same query engine runs client-side there, so saved recipes keep working.
+
+## Attach to another Node process
+
+The target process opts in by starting the agent:
+
+```ts
+import { exposeDataInspector } from '@devframes/plugin-data-inspector/agent'
+
+await exposeDataInspector()
+```
+
+or with zero code changes:
+
+```sh
+DEVFRAME_DATA_INSPECTOR=1 node --import @devframes/plugin-data-inspector/agent server.js
+```
+
+The agent binds `127.0.0.1`, requires devframe's trust handshake with a per-run pre-shared token, and advertises its endpoint in `node_modules/.data-inspector/agent.json` — `devframe-data-inspector attach` consumes it automatically (or pass `ws://…` and `--token` explicitly). Queries execute inside the target process, where the live objects are. Treat the endpoint like a debugger port.
+
+## RPC surface
+
+All functions are namespaced `devframes:plugin:data-inspector:*`:
+
+| Function | Type | Returns |
+|----------|------|---------|
+| `sources` | `query` | Every registered source (meta and suggested queries). |
+| `query` | `query` | Runs a jora query against a source; normalized result with stats. |
+| `skeleton` | `query` | The type skeleton of a source, honoring the filter options. |
+| `suggest` | `query` | Autocomplete candidates from jora's stat mode at a cursor position. |
+| `saved:list` / `saved:save` / `saved:delete` | `query` / `action` | Saved-query recipes in the `workspace` and `project` scopes. |

docs/plugins/index.md

@@ -10,6 +10,7 @@ Each plugin is built with a **different UI framework**. That is deliberate: devf
 
 | Plugin | UI framework | What it does |
 |--------|--------------|--------------|
+| [Data Inspector](./data-inspector) | Vue | Query live server-side objects with jora — sources contributed by plugins, hosts, data files, or attached processes. |
 | [Devframe Inspector](./inspect) | Vue | Browse the RPC registry, invoke read-only queries, watch shared state update live, and explore the agent surface. |
 | [Accessibility Inspector](./a11y) | Solid | Run axe-core against a host app, list WCAG violations, and highlight the offending element in the page on hover. |
 | [Git](./git) | React (Next.js) | A repository dashboard — status, a commit graph, branches, and diffs, with optional staging and committing. |
@@ -18,7 +19,7 @@ Each plugin is built with a **different UI framework**. That is deliberate: devf
 
 ## One client, any framework
 
-The five plugins span Vue, Solid, React, Svelte, and framework-free TypeScript, yet they share the same node-side surface: register RPC functions, publish shared state, and connect from the browser with `connectDevframe`. Whatever renders the UI — a reactive framework or a handful of DOM calls — talks to the backend through the same protocol.
+The collection spans Vue, Solid, React, Svelte, and framework-free TypeScript, yet every plugin shares the same node-side surface: register RPC functions, publish shared state, and connect from the browser with `connectDevframe`. Whatever renders the UI — a reactive framework or a handful of DOM calls — talks to the backend through the same protocol.
 
 This is the framework-agnostic promise in practice. The browser bundle is the author's to choose; devframe handles the transport, the data model, the adapters, and the agent surface underneath.
 

plugins/data-inspector/src/agent/index.ts

@@ -94,7 +94,9 @@ export async function exposeDataInspector(options: ExposeDataInspectorOptions =
   }
 
   const context: DevframeNodeContext = await createHostContext({ cwd, mode: 'dev', host })
-  setupDataInspector(context)
+  // Attach exists to inspect the target's own objects; the example source
+  // would only be noise next to them.
+  setupDataInspector(context, { exampleSource: false })
 
   const useAuth = options.auth ?? true
   const token = useAuth ? (options.token ?? randomToken()) : undefined

plugins/data-inspector/src/cli.ts

@@ -54,7 +54,9 @@ export function createDataInspectorCli() {
     .action(async (files: string[], flags: { port?: number, host: string, open?: boolean }) => {
       for (const file of files)
         registerDataSource(createFileDataSource(file))
-      const def = createDataInspectorDevframe()
+      // With files given, they are the point; the example source only backs
+      // the empty first-run.
+      const def = createDataInspectorDevframe({ exampleSource: files.length === 0 })
       await createDevServer(def, {
         host: flags.host,
         port: flags.port ? Number(flags.port) : undefined,

plugins/data-inspector/src/index.ts

@@ -36,6 +36,12 @@ export interface DataInspectorDevframeOptions {
    * agent (`@devframes/plugin-data-inspector/agent`) defaults to `true`.
    */
   auth?: boolean
+  /**
+   * Register the built-in example source — a small live playground graph
+   * with suggested queries (default `true`). Disable once your own sources
+   * cover the first-run experience.
+   */
+  exampleSource?: boolean
 }
 
 /**
@@ -71,7 +77,7 @@ export function createDataInspectorDevframe(options: DataInspectorDevframeOption
     spa: { loader: 'none' },
     dock: { category: '~builtin' },
     setup(ctx) {
-      setupDataInspector(ctx)
+      setupDataInspector(ctx, { exampleSource: options.exampleSource })
     },
   })
 }

plugins/data-inspector/src/node/example-source.ts

@@ -0,0 +1,88 @@
+import type { DataSourceEntry } from '../registry/index'
+import process from 'node:process'
+
+/** Id of the built-in example source (namespaced like every source id). */
+export const EXAMPLE_SOURCE_ID = 'devframes:plugin:data-inspector:example'
+
+class RequestLog {
+  readonly startedAt = new Date()
+  private secret = 'own-fields-are-visible'
+  entries = new Map<string, { path: string, hits: number }>([
+    ['home', { path: '/', hits: 41 }],
+    ['docs', { path: '/docs', hits: 7 }],
+    ['api', { path: '/api/data', hits: 23 }],
+  ])
+}
+
+function createExampleData(): Record<string, unknown> {
+  const log = new RequestLog()
+  const node: Record<string, unknown> = { name: 'root' }
+  node.self = node // circular structures render as $ref markers
+
+  const data: Record<string, unknown> = {
+    server: {
+      name: 'example',
+      port: 5173,
+      tags: new Set(['dev', 'local', 'example']),
+      middlewares: [
+        { name: 'compression', handler: () => {} },
+        { name: 'static', handler: () => {} },
+      ],
+    },
+    requests: log,
+    build: {
+      hash: 'c3f7c4e',
+      size: 1024n * 512n,
+      modules: Array.from({ length: 300 }, (_, i) => ({
+        id: `src/module-${i}.ts`,
+        imports: i % 7,
+        sizeKb: Math.round(Math.sin(i) * 40 + 50),
+      })),
+    },
+    tree: node,
+    process: { pid: process.pid, node: process.version, platform: process.platform },
+  }
+  // An own getter: reads at query time, so re-running shows the data is live.
+  Object.defineProperty(data, 'queriedAt', {
+    enumerable: true,
+    get: () => new Date().toISOString(),
+  })
+  return data
+}
+
+/**
+ * The built-in example source — a small live graph exercising everything the
+ * viewer can show (Maps, Sets, class instances, circulars, BigInt, functions,
+ * a query-time getter), with suggested queries as starting points. Sources
+ * registered by your plugins and hosts appear next to it; disable it via
+ * `createDataInspectorDevframe({ exampleSource: false })`.
+ */
+export function createExampleDataSource(): DataSourceEntry {
+  let data: Record<string, unknown> | undefined
+  return {
+    id: EXAMPLE_SOURCE_ID,
+    title: 'Example data',
+    description: 'A built-in playground graph. Register your own sources to inspect real objects.',
+    icon: 'i-ph:flask-duotone',
+    data: () => data ??= createExampleData(),
+    queries: [
+      {
+        title: 'Busiest endpoints',
+        description: 'Live Map entries, sorted',
+        query: 'requests.entries.mapEntries().value.sort(hits desc)',
+      },
+      {
+        title: 'Large modules as a table',
+        description: 'Filter and project an array',
+        query: 'build.modules.[sizeKb > 80].({ id, sizeKb })',
+      },
+      {
+        title: 'Server config (data only)',
+        description: 'Filters strip the middleware functions',
+        query: 'server',
+        excludeFunctions: true,
+      },
+      { title: 'Everything', query: '' },
+    ],
+  }
+}

plugins/data-inspector/src/node/index.ts

@@ -1,10 +1,16 @@
 import type { DevframeNodeContext } from 'devframe/types'
-import { createDataSourcesService, DATA_SOURCES_SERVICE_ID, onDataSourcesChanged } from '../registry/index'
+import { createDataSourcesService, DATA_SOURCES_SERVICE_ID, getDataSource, onDataSourcesChanged, registerDataSource } from '../registry/index'
 import { serverFunctions } from '../rpc/index'
+import { createExampleDataSource, EXAMPLE_SOURCE_ID } from './example-source'
 
 /** Broadcast whenever the source registry changes (register/unregister). */
 export const SOURCES_CHANGED_EVENT = 'devframes:plugin:data-inspector:sources:changed'
 
+export interface SetupDataInspectorOptions {
+  /** Register the built-in example source (default `true`). */
+  exampleSource?: boolean
+}
+
 /**
  * Register the data-inspector's RPC functions on a devframe node context,
  * provide the source registry as a typed context service, and broadcast
@@ -13,7 +19,7 @@ export const SOURCES_CHANGED_EVENT = 'devframes:plugin:data-inspector:sources:ch
  * Called from the definition's `setup(ctx)` and reusable by host adapters
  * (the CLI and the in-process agent wire their own contexts through this).
  */
-export function setupDataInspector(ctx: DevframeNodeContext): void {
+export function setupDataInspector(ctx: DevframeNodeContext, options: SetupDataInspectorOptions = {}): void {
   for (const fn of serverFunctions)
     ctx.rpc.register(fn)
 
@@ -22,9 +28,13 @@ export function setupDataInspector(ctx: DevframeNodeContext): void {
   if (!ctx.services.has(DATA_SOURCES_SERVICE_ID))
     ctx.services.provide(DATA_SOURCES_SERVICE_ID, createDataSourcesService())
 
+  if ((options.exampleSource ?? true) && !getDataSource(EXAMPLE_SOURCE_ID))
+    registerDataSource(createExampleDataSource())
+
   onDataSourcesChanged(() => {
     ctx.rpc.broadcast(SOURCES_CHANGED_EVENT as never)
   })
 }
 
+export { createExampleDataSource, EXAMPLE_SOURCE_ID }
 export { serverFunctions }

plugins/data-inspector/src/spa/App.vue

@@ -100,6 +100,15 @@ function queryAppend(path: string): void {
                 :color="connection.connected ? 100 : 200"
               />
               <div class="flex-auto" />
+              <a
+                href="https://devfra.me/plugins/data-inspector"
+                target="_blank"
+                title="Data Inspector docs — using the plugin and providing data sources"
+                class="flex items-center gap-1 text-xs color-muted hover:color-active"
+              >
+                <span class="i-ph:book-open-duotone text-base" />
+                <span>Docs</span>
+              </a>
               <ActionDarkToggle
                 :color-scheme="colorScheme"
                 @update:color-scheme="colorScheme = $event"
@@ -126,6 +135,17 @@ function queryAppend(path: string): void {
                 </Button>
               </div>
 
+              <div v-if="connection.connected && !wb.sources.value.length" class="text-xs color-muted">
+                No data sources registered yet. Call
+                <code class="font-mono bg-secondary border border-base rounded px-1">registerDataSource()</code>
+                from your plugin or host —
+                <a
+                  href="https://devfra.me/plugins/data-inspector#providing-data-sources"
+                  target="_blank"
+                  class="color-active hover:underline"
+                >see the docs</a>.
+              </div>
+
               <template v-if="showDataSourceDetails">
                 <DataShapePanel
                   :source="wb.activeSource.value"

plugins/data-inspector/test/registry.test.ts

@@ -94,3 +94,17 @@ describe('data source registry (process-global)', () => {
     expect(listDataSources()).toEqual([])
   })
 })
+
+describe('example source', () => {
+  it('registers a live, queryable playground with suggested queries', async () => {
+    const { createExampleDataSource } = await import('../src/node/example-source')
+    const entry = createExampleDataSource()
+    registerDataSource(entry)
+    const data = await resolveSourceData(getDataSource(entry.id)!)
+    const { runQuery } = await import('../src/engine/query-engine')
+    for (const recipe of entry.queries ?? []) {
+      const out = runQuery(data, recipe.query.trim() || '$', recipe)
+      expect(out.ok, `suggested query "${recipe.title}" must run`).toBe(true)
+    }
+  })
+})