feat(prototype): data-inspector rework — Vue/@antfu/design workbench, source contract, saved queries

Renames the spike to data-inspector and reworks it along the agreed
direction:

- data sources follow { id, title, description?, getData(), static? }
  with dynamic register/unregister + change listeners; static sources
  memoize getData()
- saved queries (title/description, id-keyed) persisted per scope:
  user -> node_modules/.data-inspector, project -> .devframe/data-inspector
  (committable, shared with the team)
- SPA rebuilt as Vue 3 + @antfu/design on the canonical uno preset:
  split-pane workbench, debounced auto-run, client-side jora syntax gate,
  non-destructive errors (last good result stays), stats bar with query
  time + payload size, remote suggestions, synced dark mode

Full e2e verified in-browser; spike still 13/13. Findings captured in
the prototype README.

Author: antfubot

examples/prototype-data-inspector/.devframe/data-inspector/queries.json

@@ -0,0 +1,12 @@
+{
+  "queries": {
+    "plugin-names": {
+      "id": "plugin-names",
+      "title": "Plugin names",
+      "description": "All Vite plugin names in order",
+      "query": "config.plugins.name",
+      "sourceId": "vite:server",
+      "updatedAt": 1784177708176
+    }
+  }
+}

examples/prototype-data-inspector/README.md

@@ -0,0 +1,98 @@
+# prototype-data-inspector
+
+> **PROTOTYPE — throwaway code.** This is not an example and not a plugin.
+> It exists to answer one question and is kept on its spike branch as a
+> primary source. Do not merge, extend, or depend on it.
+
+## The question
+
+Can a **data-inspector plugin** work on devframe? Architecture under test:
+other plugins/hosts register live server objects into a registry; the UI
+composes jora queries that execute **server-side against the live object**;
+normalized results return over devframe RPC and render in a **themed
+discovery `struct` view** inside a **Vue + `@antfu/design`** workbench, with
+saved queries persisted per user or per project.
+
+## Verdict: YES — validated end to end
+
+Stage 1 (`pnpm --filter prototype-data-inspector spike`): **13/13 checks**
+against a real programmatic `ViteDevServer` (jora over live objects, Map/Set
+bridge methods, normalizer, stat-mode suggestions, function-invocation hazard).
+
+Stage 2 (`pnpm --filter prototype-data-inspector dev`): the full workbench
+against the Vite server serving the page itself — left editor / right viewer
+split panes, debounced auto-run, client-side syntax gate, non-destructive
+errors, per-query stats (jora / normalize / rpc timings, payload size, node
+count), remote autocomplete, saved queries in both scopes, synced dark mode.
+
+## The pieces (what the real plugin reuses)
+
+- **`src/registry.ts`** — data sources as
+  `{ id, title, description?, getData(): any, static?: boolean }`, registered
+  dynamically against the shared `DevframeNodeContext`
+  (`WeakMap` idiom from `plugins/git`). `static: true` memoizes `getData()`;
+  `registerDataSource` returns an unregister fn and fires change listeners.
+- **`src/normalize.ts`** — the core asset: live graph -> strict JSON
+  (circular -> `$ref`, Map/Set/class/function/BigInt/Error tagging,
+  depth/entry/prop/string caps) with stats.
+- **`src/query-engine.ts`** — jora with duck-typed `fromMap()` /
+  `mapEntries()` / `fromSet()` / `ownKeys()` / `typeOf()` bridges, plus
+  flattened stat-mode suggestions.
+- **`src/saved-queries.ts`** — id-keyed saved queries via devframe
+  `createStorage` (debounced atomic JSON):
+  `user` -> `node_modules/.data-inspector/queries.json` (per checkout),
+  `project` -> `.devframe/data-inspector/queries.json` (committable, shared).
+  Saving an id into one scope removes its twin from the other.
+- **`src/rpc-functions.ts`** — `data-inspector:{sources,query,suggest}` +
+  `data-inspector:saved:{list,save,delete}`, all `jsonSerializable`.
+- **`src/spa/`** — Vue 3 + `@antfu/design` workbench: canonical uno preset
+  block (mirrors `plugins/inspect`), design components used directly
+  (`LayoutToolbar`, `LayoutSplitPane`, `FormSelect`, `FormTextInput`,
+  `ActionButton`/`ActionIconButton`/`ActionDarkToggle`,
+  `DisplayBadge`/`DisplayBytes`/`DisplayDuration`), discovery `ViewModel`
+  bound to a container ref with the default page redefined as a struct view.
+
+## Findings (things the real plugin must know)
+
+1. **Vite 8 compat surfaces**: `server.moduleGraph.idToModuleMap` is
+   Map-*shaped* but not a `Map` (duck-type it), and compat `ModuleNode`s are
+   getter facades whose own keys are `_moduleGraph`/`_clientModule`/`_ssrModule`
+   only — query `environments.<name>.moduleGraph` for real own fields.
+2. **discovery under Vite** needs `define: { global: 'globalThis' }` and its
+   CSS injected into the shadow root via `?inline` import. Render results
+   through the model (`page.define('default', ...)` + `setData`) — rendering
+   into `dom.pageContent` manually races discovery's own page cycle.
+3. **Theming**: `host.colorScheme.set()` + `--discovery-*` custom props
+   (bridged to design tokens through CSS vars that flip with `.dark`).
+4. **jora syntax check runs client-side** (`jora.syntax.parse`, ~20 KB gzip):
+   parse errors carry `details.loc.range`, so end-of-input errors show as a
+   soft "keep typing" state and malformed queries never hit the wire.
+5. **Suggestions** arrive nested per stat entry (flatten server-side);
+   prefix-filtering is the client's job.
+6. **`DisplayBadge` with an explicit CSS color** sets fg and bg to the same
+   value — pass a hue number (theme-aware tint) or use `variant="solid"`.
+7. **`LayoutSplitPane`** needs `splitpanes` (+ `Pane`) as a direct dep — it's
+   an `@antfu/design` peer, not a bundled dep.
+8. **HAZARD (by design of live-query mode)**: a jora query can invoke any
+   function reachable as an own property of the live object and fires own
+   getters; no CPU/timeout limits. Present it as eval-grade access to the dev
+   server (localhost-only), and pin `jora >= 1.0.0-beta.16`.
+9. **Versions pinned deliberately**: `jora@1.0.0-beta.16`,
+   `@discoveryjs/discovery@1.0.0-beta.99` — both beta with breaking renames
+   between betas.
+
+## Deviations from repo conventions (prototype-only)
+
+- `jora` + `@discoveryjs/discovery` pinned in the *default* catalog (pnpm
+  auto-promoted them); a real plugin would place them in a named catalog
+- plain textarea editor; production should embed discovery's `QueryEditor`
+  (CodeMirror 5 + jora mode) with the async-suggestion re-trigger pattern
+- `.vue` internals aren't typechecked (`tsc --noEmit` + shims, same as the
+  existing plugins)
+
+## Run it
+
+```sh
+pnpm --filter prototype-data-inspector spike   # stage 1: node-only proof, prints 13 checks
+pnpm --filter prototype-data-inspector dev     # stage 2: http://localhost:5173/
+```

examples/prototype-data-inspector/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Data Inspector — PROTOTYPE</title>
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="/src/spa/main.ts"></script>
+</body>
+</html>

examples/prototype-data-inspector/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "prototype-data-inspector",
+  "type": "module",
+  "version": "0.0.0",
+  "private": true,
+  "description": "PROTOTYPE (throwaway) — validates the data-inspector plugin architecture: server-side jora over live registered objects + RPC + saved queries + a Vue/@antfu/design workbench with a themed discovery struct view. Not a real example; see README.",
+  "scripts": {
+    "dev": "vite --host",
+    "spike": "tsx src/spike.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@antfu/design": "catalog:frontend",
+    "@discoveryjs/discovery": "catalog:",
+    "devframe": "workspace:*",
+    "floating-vue": "catalog:frontend",
+    "jora": "catalog:",
+    "reka-ui": "catalog:frontend",
+    "splitpanes": "catalog:",
+    "vue": "catalog:frontend"
+  },
+  "devDependencies": {
+    "@iconify-json/ph": "catalog:frontend",
+    "@vitejs/plugin-vue": "catalog:build",
+    "get-port-please": "catalog:deps",
+    "tsx": "catalog:build",
+    "unocss": "catalog:frontend",
+    "vite": "catalog:build"
+  }
+}

…s/prototype-data-viewer/src/demo-data.ts …rototype-data-inspector/src/demo-data.tsexamples/prototype-data-viewer/src/demo-data.ts renamed to examples/prototype-data-inspector/src/demo-data.ts examples/prototype-data-viewer/src/demo-data.ts renamed to examples/prototype-data-inspector/src/demo-data.ts

@@ -11,9 +11,16 @@ declare module 'jora' {
     assertions?: Record<string, string | ((current: unknown) => boolean)>
   }
   export type JoraQueryFn = (data: unknown, context?: unknown) => unknown
+  export interface JoraSyntax {
+    parse: (source: string, tolerantMode?: boolean) => unknown
+    tokenize: (source: string) => unknown
+    stringify: (ast: unknown) => string
+    walk: (ast: unknown, visitor: unknown) => void
+  }
   export interface Jora {
     (query: string, options?: JoraQueryOptions): JoraQueryFn
     setup: (options?: JoraSetupOptions) => (query: string, options?: JoraQueryOptions) => JoraQueryFn
+    syntax: JoraSyntax
     version: string
   }
   const jora: Jora

…mples/prototype-data-viewer/src/env.d.ts …es/prototype-data-inspector/src/env.d.tsexamples/prototype-data-viewer/src/env.d.ts renamed to examples/prototype-data-inspector/src/env.d.ts examples/prototype-data-viewer/src/env.d.ts renamed to examples/prototype-data-inspector/src/env.d.ts

@@ -5,8 +5,8 @@
  * suggestions. Custom methods bridge jora's blind spots on live graphs
  * (Map/Set are opaque to it; the prototype chain is not walked).
  */
-import type { NormalizeOptions, NormalizeStats } from './normalize'
-import type { SuggestItem, SuggestOutcome } from './rpc-contract'
+import type { NormalizeOptions } from './normalize'
+import type { QueryOutcome, SuggestItem, SuggestOutcome } from './rpc-contract'
 import jora from 'jora'
 import { normalize } from './normalize'
 
@@ -50,24 +50,17 @@ const createQuery = jora.setup({
   },
 })
 
-export interface QuerySuccess {
-  ok: true
-  result: unknown
-  stats: { queryMs: number, normalize: NormalizeStats }
-}
-export interface QueryFailure {
-  ok: false
-  error: { message: string, name: string }
-}
-export type QueryOutcome = QuerySuccess | QueryFailure
+export type { QueryOutcome } from './rpc-contract'
 
 export function runQuery(target: unknown, query: string, options?: NormalizeOptions): QueryOutcome {
   try {
     const started = performance.now()
     const raw = createQuery(query)(target)
     const queryMs = Math.round((performance.now() - started) * 100) / 100
     const { data, stats } = normalize(raw, options)
-    return { ok: true, result: data, stats: { queryMs, normalize: stats } }
+    // The normalizer guarantees plain JSON, so this measures the actual wire payload.
+    const payloadBytes = new TextEncoder().encode(JSON.stringify(data) ?? '').length
+    return { ok: true, result: data, stats: { queryMs, normalize: stats, payloadBytes } }
   }
   catch (error) {
     const e = error instanceof Error ? error : new Error(String(error))

…s/prototype-data-viewer/src/normalize.ts …rototype-data-inspector/src/normalize.tsexamples/prototype-data-viewer/src/normalize.ts renamed to examples/prototype-data-inspector/src/normalize.ts examples/prototype-data-viewer/src/normalize.ts renamed to examples/prototype-data-inspector/src/normalize.ts

@@ -0,0 +1,90 @@
+/**
+ * PROTOTYPE — throwaway code.
+ *
+ * The data-source registry under validation: a `WeakMap` keyed by the shared
+ * `DevframeNodeContext` (the `plugins/git/src/rpc/context.ts` idiom). Every
+ * plugin's `setup()` and the host's `configureServer` receive the SAME context
+ * object, so anyone can register sources dynamically — at setup time or later —
+ * and the data-inspector finds them with no dependency edge beyond this module.
+ */
+import type { DataSourceMeta } from './rpc-contract'
+
+export interface DataSourceEntry {
+  id: string
+  title: string
+  description?: string
+  /** Produce the object to query. Called per query unless `static`. */
+  getData: () => unknown
+  /** Data never changes; `getData()` is called once and memoized (default false). */
+  static?: boolean
+}
+
+interface Registry {
+  entries: Map<string, DataSourceEntry>
+  /** Memoized `getData()` results for `static: true` sources. */
+  staticCache: Map<string, unknown>
+  listeners: Set<() => void>
+}
+
+const registries = new WeakMap<object, Registry>()
+
+function registryFor(ctx: object): Registry {
+  let registry = registries.get(ctx)
+  if (!registry) {
+    registry = { entries: new Map(), staticCache: new Map(), listeners: new Set() }
+    registries.set(ctx, registry)
+  }
+  return registry
+}
+
+function notify(registry: Registry): void {
+  for (const listener of registry.listeners)
+    listener()
+}
+
+/** Register (or replace) a source. Returns an unregister function. */
+export function registerDataSource(ctx: object, entry: DataSourceEntry): () => void {
+  const registry = registryFor(ctx)
+  registry.entries.set(entry.id, entry)
+  registry.staticCache.delete(entry.id)
+  notify(registry)
+  return () => unregisterDataSource(ctx, entry.id)
+}
+
+export function unregisterDataSource(ctx: object, id: string): void {
+  const registry = registryFor(ctx)
+  if (registry.entries.delete(id)) {
+    registry.staticCache.delete(id)
+    notify(registry)
+  }
+}
+
+export function listDataSources(ctx: object): DataSourceMeta[] {
+  return Array.from(registryFor(ctx).entries.values()).map(entry => ({
+    id: entry.id,
+    title: entry.title,
+    description: entry.description,
+    static: entry.static ?? false,
+  }))
+}
+
+export function getDataSource(ctx: object, id: string): DataSourceEntry | undefined {
+  return registryFor(ctx).entries.get(id)
+}
+
+/** Resolve a source's data, honoring `static` memoization. */
+export function resolveSourceData(ctx: object, entry: DataSourceEntry): unknown {
+  if (!entry.static)
+    return entry.getData()
+  const registry = registryFor(ctx)
+  if (!registry.staticCache.has(entry.id))
+    registry.staticCache.set(entry.id, entry.getData())
+  return registry.staticCache.get(entry.id)
+}
+
+/** Subscribe to registry changes (register/unregister). Returns unsubscribe. */
+export function onDataSourcesChanged(ctx: object, listener: () => void): () => void {
+  const registry = registryFor(ctx)
+  registry.listeners.add(listener)
+  return () => registry.listeners.delete(listener)
+}

…rototype-data-viewer/src/query-engine.ts …otype-data-inspector/src/query-engine.tsexamples/prototype-data-viewer/src/query-engine.ts renamed to examples/prototype-data-inspector/src/query-engine.ts examples/prototype-data-viewer/src/query-engine.ts renamed to examples/prototype-data-inspector/src/query-engine.ts

@@ -0,0 +1,76 @@
+/**
+ * PROTOTYPE — throwaway code.
+ *
+ * Wire types shared by the server RPC functions and the SPA. Types only —
+ * safe to import from browser code without dragging jora into the bundle.
+ */
+
+/** What the client sees of a registered data source. */
+export interface DataSourceMeta {
+  id: string
+  title: string
+  description?: string
+  /** Data never changes; the server memoizes `getData()`. */
+  static: boolean
+}
+
+/** One completion candidate: replace [from, to) with `value`. */
+export interface SuggestItem {
+  type: string
+  from: number
+  to: number
+  /** The fragment currently typed in that range. */
+  current: string
+  /** The completion to insert. */
+  value: string
+}
+
+export interface SuggestOutcome {
+  ok: boolean
+  suggestions: SuggestItem[]
+  statMs: number
+  error?: string
+}
+
+export interface NormalizeStatsWire {
+  nodes: number
+  refs: number
+  truncatedDepth: number
+  truncatedEntries: number
+  truncatedProps: number
+  ms: number
+}
+
+export interface QueryStats {
+  queryMs: number
+  normalize: NormalizeStatsWire
+  payloadBytes: number
+}
+
+export type QueryOutcome
+  = | { ok: true, result: unknown, stats: QueryStats }
+    | { ok: false, error: { name: string, message: string } }
+
+/** Where a saved query persists. */
+export type SavedQueryScope = 'user' | 'project'
+
+export interface SavedQuery {
+  /** Storage key. Derived from the title when not supplied. */
+  id: string
+  title: string
+  description?: string
+  query: string
+  /** Source the query was authored against. */
+  sourceId: string
+  scope: SavedQueryScope
+  updatedAt: number
+}
+
+export interface SaveQueryInput {
+  id?: string
+  title: string
+  description?: string
+  query: string
+  sourceId: string
+  scope: SavedQueryScope
+}