feat(prototype): query recipes, suggested queries, save dialog, type badges, URL state

- FilterOptions { excludeFunctions, excludeUnderscoreProps, excludeDollarProps }
  replace the old settings names; saved queries become source-agnostic
  recipes { query, title?, description?, ...FilterOptions } with title
  optional (untitled ids derive from a stable query hash)
- data sources can provide suggested queries ({ queries?: Query[] }),
  listed read-only next to saved ones; loading any recipe applies its
  filter options
- save query now opens an OverlayModal dialog (query preview, active
  filters, title/description, scope)
- discovery struct annotations badge exotic values: Function, Map(n),
  Set(n), Date, class names, circular refs
- source, query, and filters persist in the URL (shareable/restorable)

Author: antfubot

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

@@ -5,7 +5,6 @@
       "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

@@ -25,17 +25,22 @@ against the Vite server serving the page itself — resizable split panes
 debounced auto-run with a manual re-run button, an empty query running `$`
 (the entire source object), client-side syntax gate, non-destructive errors,
 per-query stats (jora / normalize / rpc timings, payload size, node count),
-query settings (ignore functions / `_`-prefixed / `$`-prefixed, persisted,
-applied to results and skeleton alike), an "available data" panel showing the
-source's type skeleton independent of the query, remote autocomplete, saved
-queries in both scopes, and synced dark mode.
+filter options (exclude functions / `_` props / `$` props) applied to results
+and skeleton alike, an "available data" panel showing the source's type
+skeleton independent of the query, type badges on exotic values (`Function`,
+`Map(n)`, `Set(n)`, `Date`, class names, `circular`) via discovery's value
+annotations, remote autocomplete, source-provided suggested queries plus
+saved queries in both scopes (save dialog, recipes carry their filter
+options), the whole workbench state (source, query, filters) persisted in
+the URL, and 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`
+  `{ id, title, description?, getData(): any, static?: boolean, queries?: Query[] }`,
+  registered dynamically against the shared `DevframeNodeContext`
   (`WeakMap` idiom from `plugins/git`). `static: true` memoizes `getData()`;
+  `queries` are source-suggested recipes shown read-only in the UI;
   `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,
@@ -47,7 +52,9 @@ queries in both scopes, and synced dark mode.
 - **`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
+- **`src/saved-queries.ts`** — saved queries are source-agnostic recipes
+  `{ query, title?, description?, ...FilterOptions }`, id-keyed (slug of the
+  title, or a stable hash of the query when untitled) via devframe
   `createStorage` (debounced atomic JSON):
   `user` -> `node_modules/.data-inspector/queries.json` (per checkout),
   `project` -> `.devframe/data-inspector/queries.json` (committable, shared).

examples/prototype-data-inspector/src/normalize.ts

@@ -27,18 +27,18 @@ export interface NormalizeOptions {
   /** Max string length before truncation. */
   maxString?: number
   /** Drop function values (object props and array items). */
-  ignoreFunctions?: boolean
+  excludeFunctions?: boolean
   /** Drop object properties whose key starts with `_`. */
-  ignoreUnderscorePrefixed?: boolean
+  excludeUnderscoreProps?: boolean
   /** Drop object properties whose key starts with `$`. */
-  ignoreDollarPrefixed?: boolean
+  excludeDollarProps?: boolean
 }
 
-/** True when a property key is excluded by the ignore settings. */
-export function isIgnoredKey(key: string, opts: Pick<NormalizeOptions, 'ignoreUnderscorePrefixed' | 'ignoreDollarPrefixed'>): boolean {
-  if (opts.ignoreUnderscorePrefixed && key.startsWith('_'))
+/** True when a property key is excluded by the filter options. */
+export function isExcludedKey(key: string, opts: Pick<NormalizeOptions, 'excludeUnderscoreProps' | 'excludeDollarProps'>): boolean {
+  if (opts.excludeUnderscoreProps && key.startsWith('_'))
     return true
-  if (opts.ignoreDollarPrefixed && key.startsWith('$'))
+  if (opts.excludeDollarProps && key.startsWith('$'))
     return true
   return false
 }
@@ -76,9 +76,9 @@ export function normalize(value: unknown, options: NormalizeOptions = {}): { dat
       maxEntries: options.maxEntries ?? 200,
       maxProps: options.maxProps ?? 150,
       maxString: options.maxString ?? 4000,
-      ignoreFunctions: options.ignoreFunctions ?? false,
-      ignoreUnderscorePrefixed: options.ignoreUnderscorePrefixed ?? false,
-      ignoreDollarPrefixed: options.ignoreDollarPrefixed ?? false,
+      excludeFunctions: options.excludeFunctions ?? false,
+      excludeUnderscoreProps: options.excludeUnderscoreProps ?? false,
+      excludeDollarProps: options.excludeDollarProps ?? false,
     },
   }
   const data = walk(value, walker, 0, '#')
@@ -146,7 +146,7 @@ function walk(value: unknown, w: Walker, depth: number, path: string): unknown {
   w.seen.set(obj, path)
 
   if (Array.isArray(obj)) {
-    const source = w.opts.ignoreFunctions ? obj.filter(item => typeof item !== 'function') : obj
+    const source = w.opts.excludeFunctions ? obj.filter(item => typeof item !== 'function') : obj
     const cap = Math.min(source.length, w.opts.maxEntries)
     const out: unknown[] = Array.from({ length: cap })
     for (let i = 0; i < cap; i++)
@@ -201,7 +201,7 @@ function walk(value: unknown, w: Walker, depth: number, path: string): unknown {
   if (className && className !== 'Object')
     out.$class = className
 
-  const keys = Object.keys(obj).filter(key => !isIgnoredKey(key, w.opts))
+  const keys = Object.keys(obj).filter(key => !isExcludedKey(key, w.opts))
   const cap = Math.min(keys.length, w.opts.maxProps)
   for (let i = 0; i < cap; i++) {
     const key = keys[i]
@@ -213,7 +213,7 @@ function walk(value: unknown, w: Walker, depth: number, path: string): unknown {
       out[key] = { $type: 'getter-error', message: error instanceof Error ? error.message : String(error) }
       continue
     }
-    if (w.opts.ignoreFunctions && typeof v === 'function')
+    if (w.opts.excludeFunctions && typeof v === 'function')
       continue
     out[key] = walk(v, w, depth + 1, `${path}.${key}`)
   }

examples/prototype-data-inspector/src/registry.ts

@@ -7,7 +7,7 @@
  * 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'
+import type { DataSourceMeta, Query } from './rpc-contract'
 
 export interface DataSourceEntry {
   id: string
@@ -17,6 +17,8 @@ export interface DataSourceEntry {
   getData: () => unknown
   /** Data never changes; `getData()` is called once and memoized (default false). */
   static?: boolean
+  /** Suggested queries, surfaced in the UI alongside saved ones (read-only). */
+  queries?: Query[]
 }
 
 interface Registry {
@@ -65,6 +67,7 @@ export function listDataSources(ctx: object): DataSourceMeta[] {
     title: entry.title,
     description: entry.description,
     static: entry.static ?? false,
+    queries: entry.queries,
   }))
 }
 

examples/prototype-data-inspector/src/rpc-contract.ts

@@ -5,13 +5,29 @@
  * safe to import from browser code without dragging jora into the bundle.
  */
 
+/** Client-controlled filtering, applied by the normalizer and the skeleton. */
+export interface FilterOptions {
+  excludeFunctions?: boolean
+  excludeUnderscoreProps?: boolean
+  excludeDollarProps?: boolean
+}
+
+/** A query recipe: the text plus the filter options it was authored with. */
+export interface Query extends FilterOptions {
+  query: string
+  title?: string
+  description?: string
+}
+
 /** 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
+  /** Suggested queries provided by the source (shown read-only). */
+  queries?: Query[]
 }
 
 /** One completion candidate: replace [from, to) with `value`. */
@@ -51,37 +67,21 @@ export type QueryOutcome
   = | { ok: true, result: unknown, stats: QueryStats }
     | { ok: false, error: { name: string, message: string } }
 
-/** Client-controlled query settings, forwarded to the normalizer/skeleton. */
-export interface QuerySettings {
-  ignoreFunctions?: boolean
-  ignoreUnderscorePrefixed?: boolean
-  ignoreDollarPrefixed?: boolean
-}
-
 export type SkeletonOutcome
   = | { ok: true, skeleton: unknown, nodes: number, ms: number }
     | { 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. */
+export interface SavedQuery extends Query {
+  /** Storage key. Derived from the title (or query) 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 {
+export interface SaveQueryInput extends Query {
   id?: string
-  title: string
-  description?: string
-  query: string
-  sourceId: string
   scope: SavedQueryScope
 }

examples/prototype-data-inspector/src/rpc-functions.ts

@@ -7,7 +7,7 @@
  * strict and proves wire-safety on every call.
  */
 import type { DevframeNodeContext } from 'devframe/types'
-import type { QuerySettings, SavedQueryScope, SaveQueryInput, SkeletonOutcome } from './rpc-contract'
+import type { FilterOptions, SavedQueryScope, SaveQueryInput, SkeletonOutcome } from './rpc-contract'
 import { createDefineWrapperWithContext } from 'devframe/rpc'
 import { runQuery, suggest } from './query-engine'
 import { getDataSource, listDataSources, resolveSourceData } from './registry'
@@ -32,7 +32,7 @@ export const queryFn = defineRpc({
   type: 'query',
   jsonSerializable: true,
   setup: ctx => ({
-    handler: async (sourceId: string, joraQuery: string, options?: { maxDepth?: number, maxEntries?: number } & QuerySettings) => {
+    handler: async (sourceId: string, joraQuery: string, options?: { maxDepth?: number, maxEntries?: number } & FilterOptions) => {
       const source = getDataSource(ctx, sourceId)
       if (!source)
         return { ok: false as const, error: { name: 'UnknownSource', message: `No data source "${sourceId}"` } }
@@ -46,7 +46,7 @@ export const skeletonFn = defineRpc({
   type: 'query',
   jsonSerializable: true,
   setup: ctx => ({
-    handler: async (sourceId: string, options?: QuerySettings): Promise<SkeletonOutcome> => {
+    handler: async (sourceId: string, options?: FilterOptions): Promise<SkeletonOutcome> => {
       const source = getDataSource(ctx, sourceId)
       if (!source)
         return { ok: false, error: { name: 'UnknownSource', message: `No data source "${sourceId}"` } }

examples/prototype-data-inspector/src/saved-queries.ts

@@ -7,7 +7,9 @@
  *   - `project` -> `<workspaceRoot>/.devframe/data-inspector/queries.json`
  *                  (committable, shared with the team)
  *
- * Backed by devframe's `createStorage` (debounced atomic JSON writes).
+ * A saved query is a source-agnostic recipe: the query text, optional
+ * title/description, and the FilterOptions it was authored with. Backed by
+ * devframe's `createStorage` (debounced atomic JSON writes).
  */
 import type { DevframeNodeContext } from 'devframe/types'
 import type { SavedQuery, SavedQueryScope, SaveQueryInput } from './rpc-contract'
@@ -45,12 +47,28 @@ function storesFor(ctx: DevframeNodeContext): Record<SavedQueryScope, Store> {
   return byScope
 }
 
-function slugify(title: string): string {
-  return title
+function slugify(text: string): string {
+  return text
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '')
-    || `query-${Date.now()}`
+    .slice(0, 60)
+}
+
+/** djb2 — stable short id for untitled queries (same query, same id). */
+function hashOf(text: string): string {
+  let hash = 5381
+  for (let i = 0; i < text.length; i++)
+    hash = ((hash << 5) + hash + text.charCodeAt(i)) >>> 0
+  return hash.toString(36)
+}
+
+function deriveId(input: SaveQueryInput): string {
+  if (input.id)
+    return input.id
+  if (input.title?.trim())
+    return slugify(input.title)
+  return `q-${hashOf(input.query)}`
 }
 
 export function listSavedQueries(ctx: DevframeNodeContext): SavedQuery[] {
@@ -65,13 +83,15 @@ export function listSavedQueries(ctx: DevframeNodeContext): SavedQuery[] {
 
 export function saveQuery(ctx: DevframeNodeContext, input: SaveQueryInput): SavedQuery {
   const byScope = storesFor(ctx)
-  const id = input.id ?? slugify(input.title)
+  const id = deriveId(input)
   const record: Omit<SavedQuery, 'scope'> = {
     id,
-    title: input.title,
-    description: input.description || undefined,
     query: input.query,
-    sourceId: input.sourceId,
+    title: input.title?.trim() || undefined,
+    description: input.description?.trim() || undefined,
+    excludeFunctions: input.excludeFunctions || undefined,
+    excludeUnderscoreProps: input.excludeUnderscoreProps || undefined,
+    excludeDollarProps: input.excludeDollarProps || undefined,
     updatedAt: Date.now(),
   }
   byScope[input.scope].mutate((draft) => {

examples/prototype-data-inspector/src/skeleton.ts

@@ -14,11 +14,11 @@
  *   - depth/prop caps      -> '...'
  */
 import type { NormalizeOptions } from './normalize'
-import { isIgnoredKey } from './normalize'
+import { isExcludedKey } from './normalize'
 
 export type SkeletonOptions = Pick<
   NormalizeOptions,
-  'maxDepth' | 'maxProps' | 'ignoreFunctions' | 'ignoreUnderscorePrefixed' | 'ignoreDollarPrefixed'
+  'maxDepth' | 'maxProps' | 'excludeFunctions' | 'excludeUnderscoreProps' | 'excludeDollarProps'
 >
 
 interface SkeletonWalker {
@@ -35,9 +35,9 @@ export function skeletonOf(value: unknown, options: SkeletonOptions = {}): { ske
     opts: {
       maxDepth: options.maxDepth ?? 5,
       maxProps: options.maxProps ?? 80,
-      ignoreFunctions: options.ignoreFunctions ?? false,
-      ignoreUnderscorePrefixed: options.ignoreUnderscorePrefixed ?? false,
-      ignoreDollarPrefixed: options.ignoreDollarPrefixed ?? false,
+      excludeFunctions: options.excludeFunctions ?? false,
+      excludeUnderscoreProps: options.excludeUnderscoreProps ?? false,
+      excludeDollarProps: options.excludeDollarProps ?? false,
     },
   }
   const skeleton = walk(value, walker, 0)
@@ -94,7 +94,7 @@ function walk(value: unknown, w: SkeletonWalker, depth: number): unknown {
 
 function walkObject(obj: object, w: SkeletonWalker, depth: number): unknown {
   if (Array.isArray(obj)) {
-    const items = w.opts.ignoreFunctions ? obj.filter(item => typeof item !== 'function') : obj
+    const items = w.opts.excludeFunctions ? obj.filter(item => typeof item !== 'function') : obj
     if (items.length === 0)
       return []
     const first = walk(items[0], w, depth + 1)
@@ -130,7 +130,7 @@ function walkObject(obj: object, w: SkeletonWalker, depth: number): unknown {
   if (className && className !== 'Object')
     out.$class = className
 
-  const keys = Object.keys(obj).filter(key => !isIgnoredKey(key, w.opts))
+  const keys = Object.keys(obj).filter(key => !isExcludedKey(key, w.opts))
   const cap = Math.min(keys.length, w.opts.maxProps)
   for (let i = 0; i < cap; i++) {
     const key = keys[i]
@@ -142,7 +142,7 @@ function walkObject(obj: object, w: SkeletonWalker, depth: number): unknown {
       out[key] = 'getter-error'
       continue
     }
-    if (w.opts.ignoreFunctions && typeof v === 'function')
+    if (w.opts.excludeFunctions && typeof v === 'function')
       continue
     out[key] = walk(v, w, depth + 1)
   }