Merge branch 'main' into whole-beds-bet

Author: antfubot

AGENTS.md

@@ -36,6 +36,8 @@ The `pnpm test` script intentionally runs `build` first so `tsnapi` snapshots co
 
 Ahead-of-time build artifacts that live under `src/` - the shadow-root stylesheets in `packages/hub-ui/src/client/.generated/` and `packages/json-render-ui/src/.generated/` - are **generated, not committed** (`.generated` is gitignored). Each owning package builds its own with `pnpm run build:css`, and three things guarantee the file is on disk before anything imports it: the root `postinstall` runs `turbo run build:css`, the Turbo `typecheck` task depends on both `build:css` tasks, and each package's `build` script chains `build:css` first. A new generated-under-`src` artifact follows the same shape - its own build script, declared `outputs` in `turbo.json`, and a `typecheck` dependency - rather than being checked in, since a minified single-line blob conflicts on every concurrent edit.
 
+**`starter/`** is the top-level, self-contained template for creating a new devframe integration (Vanilla TS, Vite client, playgrounds, tests). It uses real versions in its `package.json` (no catalogs, no `workspace:*`) so it's copy-paste ready for users. Pnpm links its `devframe`/`@devframes/*` dependencies to the local workspace copies during development. When `bumpp -r` bumps the repo versions, `bumpp.config.ts` runs `scripts/sync-starter-version.ts` to update the starter's dependencies to match.
+
 `pnpm knip` finds unused files, dependencies, and exports across every workspace (config in `knip.jsonc`). It runs against source directly - no prior build needed. Most workspaces need no configuration; `knip.jsonc` only carries per-workspace overrides for cases knip's defaults can't infer on their own: a package's non-`index.ts` `exports` subpaths (knip's package.json→`dist`→`src` source mapping needs a workspace `tsconfig.json` `outDir`, which conflicts with this repo's cross-workspace `src/*.ts` imports, so multi-entry packages list their `exports`-mapped entry files explicitly instead - keep that list in sync with each `tsdown.config.ts`), config files knip's plugins don't discover in a nested location (a Next.js app rooted below the workspace root, `storybook-solidjs-vite` not matching the Storybook plugin trigger), and dependencies referenced dynamically outside its static import graph (icon collections consumed by UnoCSS at build time, plugin packages loaded via a runtime `import()` string). Prefer fixing the underlying gap or a scoped `ignoreDependencies`/`entry` override over a blanket `ignore`.
 
 ## Conventions

bump.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'bumpp'
+import { syncStarterVersion } from './scripts/sync-starter-version.ts'
+
+export default defineConfig({
+  // `starter/` pins real `devframe`/`@devframes/*` versions (it's a
+  // copy-paste-ready template, not a workspace member consuming
+  // `catalog:`/`workspace:*`), so `bumpp -r` can't reach it on its own -
+  // sync it here, before the version-bump commit is made.
+  execute: operation => syncStarterVersion(operation.state.newVersion),
+})

docs/content/6.errors/DF0073.md

@@ -0,0 +1,20 @@
+---
+title: 'DF0073: JSON-Render Spec Does Not Match Its Schema'
+description: 'JSON-render view "{id}" does not match its configured schema: {issues}'
+---
+
+## Message
+
+> JSON-render view "`{id}`" does not match its configured schema: `{issues}`
+
+## Cause
+
+The spec failed the optional Standard Schema supplied when the JSON-render view was created. The same schema guards the initial spec and every update.
+
+## Fix
+
+Match the authored spec to the configured schema before creating or updating the view.
+
+## Source
+
+- [`packages/json-render/src/node/create-view.ts`](https://github.com/devframes/devframe/blob/main/packages/json-render/src/node/create-view.ts) — `validateSpec()` throws this before shared state changes.

docs/content/6.errors/DF0074.md

@@ -0,0 +1,20 @@
+---
+title: 'DF0074: JSON-Render Schema Is Asynchronous'
+description: 'JSON-render view "{id}" uses an asynchronous Standard Schema.'
+---
+
+## Message
+
+> JSON-render view "`{id}`" uses an asynchronous Standard Schema.
+
+## Cause
+
+JSON-render view creation and updates are synchronous, while the configured Standard Schema returned a promise.
+
+## Fix
+
+Use a synchronous Standard Schema for JSON-render specs.
+
+## Source
+
+- [`packages/json-render/src/node/create-view.ts`](https://github.com/devframes/devframe/blob/main/packages/json-render/src/node/create-view.ts) — `validateSpec()` rejects promise-returning validators.

docs/content/6.errors/index.md

@@ -41,3 +41,5 @@ Emitted by `devframe` — framework-neutral host / shared-state / auth surface.
 | [DF0031](/errors/DF0031) | error | Write to Closed Stream |
 | [DF0032](/errors/DF0032) | error | Streaming Channel Already Registered |
 | [DF0033](/errors/DF0033) | warn | Dev RPC Bridge Failed to Start |
+| [DF0073](/errors/DF0073) | error | JSON-Render Spec Does Not Match Its Schema |
+| [DF0074](/errors/DF0074) | error | JSON-Render Schema Is Asynchronous |

packages/json-render/package.json

@@ -46,6 +46,7 @@
   },
   "dependencies": {
     "@json-render/core": "catalog:deps",
+    "@standard-schema/spec": "catalog:deps",
     "zod": "catalog:deps"
   },
   "devDependencies": {

packages/json-render/src/index.ts

@@ -35,7 +35,7 @@ export {
 } from './prop-schemas'
 
 // ── Devframes-facing type names ──────────────────────────────────────────
-export type { DevframeJsonRenderSpec, JsonRenderView } from './types'
+export type { CatalogUIElement, DevframeJsonRenderSpec, JsonRenderView } from './types'
 // ── View index (frontend view discovery) ─────────────────────────────────
 export { JSON_RENDER_INDEX_KEY } from './view-index'
 

packages/json-render/src/node/create-view.ts

@@ -1,3 +1,4 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type { DevframeNodeContext, DevframeScopedNodeContext } from 'devframe'
 import type { SharedState, SharedStatePatch } from 'devframe/utils/shared-state'
 import type { DevframeJsonRenderSpec, JsonRenderStatePatch, JsonRenderView } from '../types'
@@ -8,15 +9,17 @@ import { JSON_RENDER_INDEX_KEY } from '../view-index'
 import { diagnostics } from './diagnostics'
 
 /** Options for {@link createJsonRenderView}. */
-export interface CreateJsonRenderViewOptions {
+export interface CreateJsonRenderViewOptions<SpecType extends DevframeJsonRenderSpec = DevframeJsonRenderSpec> {
   /**
    * Stable, author-supplied id, unique within the view's scope. Forms the
    * shared-state key `devframe:json-render:<scope>:<id>` and never changes
    * across updates, so a client keeps its subscription across reconnects.
    */
   id: string
   /** The initial spec. */
-  spec: DevframeJsonRenderSpec
+  spec: SpecType
+  /** A replacement Standard Schema validator, or `false` to disable validation. */
+  schema?: StandardSchemaV1 | false
   /**
    * Override the scope segment of the view's stable id. Defaults to the
    * context's namespace when created from a scoped context, otherwise
@@ -98,9 +101,43 @@ function validateElementProps(id: string, spec: DevframeJsonRenderSpec): void {
   }
 }
 
+function formatStandardSchemaIssues(issues: readonly StandardSchemaV1.Issue[]): string {
+  return issues
+    .map((issue) => {
+      const path = issue.path
+        ?.map(segment => typeof segment === 'object' ? String(segment.key) : String(segment))
+        .join('.')
+      return `${path || '(root)'}: ${issue.message}`
+    })
+    .join('; ')
+}
+
+function isPromise<Result>(value: Result | Promise<Result>): value is Promise<Result> {
+  return typeof (value as Promise<Result>).then === 'function'
+}
+
+function validateSpec(
+  id: string,
+  spec: DevframeJsonRenderSpec,
+  schema: StandardSchemaV1 | false | undefined,
+): void {
+  if (schema === false)
+    return
+  if (!schema) {
+    validateElementProps(id, spec)
+    return
+  }
+
+  const result = schema['~standard'].validate(spec)
+  if (isPromise(result))
+    throw diagnostics.DF0074({ id })
+  if (result.issues)
+    throw diagnostics.DF0073({ id, issues: formatStandardSchemaIssues(result.issues) })
+}
+
 // Ensure the spec always carries a `state` object so JSON-Pointer patches
 // into `/state/...` have a container to target.
-function normalizeSpec(spec: DevframeJsonRenderSpec): DevframeJsonRenderSpec {
+function normalizeSpec<SpecType extends DevframeJsonRenderSpec>(spec: SpecType): SpecType {
   return spec.state ? spec : { ...spec, state: {} }
 }
 
@@ -119,10 +156,10 @@ function normalizeSpec(spec: DevframeJsonRenderSpec): DevframeJsonRenderSpec {
  * view.dispose()
  * ```
  */
-export function createJsonRenderView(
+export function createJsonRenderView<SpecType extends DevframeJsonRenderSpec = DevframeJsonRenderSpec>(
   ctx: AnyContext,
-  options: CreateJsonRenderViewOptions,
-): JsonRenderView {
+  options: CreateJsonRenderViewOptions<SpecType>,
+): JsonRenderView<SpecType> {
   const scoped = isScoped(ctx)
   const baseCtx = scoped ? ctx.base : ctx
   const scope = options.scope ?? (scoped ? ctx.namespace : 'global')
@@ -135,10 +172,10 @@ export function createJsonRenderView(
     throw diagnostics.DF0039({ id, scope })
 
   const initial = normalizeSpec(options.spec)
-  validateElementProps(id, initial)
+  validateSpec(id, initial, options.schema)
   assertJsonSerializable(id, initial)
 
-  const state: SharedState<DevframeJsonRenderSpec> = createSharedState({
+  const state: SharedState<SpecType> = createSharedState({
     initialValue: initial,
     enablePatches: true,
   })
@@ -165,11 +202,11 @@ export function createJsonRenderView(
     id,
     title,
     ref: { stateKey },
-    value: () => state.value() as DevframeJsonRenderSpec,
+    value: () => state.value() as SpecType,
     update(spec) {
       assertLive()
       const next = normalizeSpec(spec)
-      validateElementProps(id, next)
+      validateSpec(id, next, options.schema)
       assertJsonSerializable(id, next)
       state.mutate(() => next)
     },

packages/json-render/src/node/diagnostics.ts

@@ -1,9 +1,8 @@
 import { defineDiagnostics } from 'devframe/utils/nostics'
 
-// `@devframes/json-render` protocol/runtime diagnostics. These share the
-// `DF` prefix and live in the devframe core range (next free after the
-// current highest `DF00xx`, DF0037). Browser-only render failures keep
-// `console.*` in the UI package.
+// `@devframes/json-render` protocol/runtime diagnostics share the `DF`
+// prefix and use the next globally available core codes. Browser-only render
+// failures keep `console.*` in the UI package.
 export const diagnostics = defineDiagnostics({
   docsBase: 'https://devfra.me/errors',
   codes: {
@@ -27,5 +26,15 @@ export const diagnostics = defineDiagnostics({
         `JSON-render view "${p.id}" spec is not JSON-serializable: ${p.reason}`,
       fix: 'Specs and state travel as strict JSON — remove functions, symbols, class instances, Map/Set, or circular references.',
     },
+    DF0073: {
+      why: (p: { id: string, issues: string }) =>
+        `JSON-render view "${p.id}" does not match its configured schema: ${p.issues}`,
+      fix: 'Match the authored spec to the Standard Schema passed to `createJsonRenderView`.',
+    },
+    DF0074: {
+      why: (p: { id: string }) =>
+        `JSON-render view "${p.id}" uses an asynchronous Standard Schema.`,
+      fix: 'Use a synchronous Standard Schema so initial creation and updates remain synchronous.',
+    },
   },
 })

packages/json-render/src/types.ts

@@ -1,12 +1,28 @@
-import type { Spec } from '@json-render/core'
+import type {
+  Catalog,
+  InferCatalogComponents,
+  InferComponentProps,
+  Spec,
+  UIElement,
+} from '@json-render/core'
 import type { JsonRenderViewStateRef } from './view-ref'
 
 /**
  * A Devframes JSON-render spec **is** an `@json-render/core` `Spec`: a flat
  * `root` key, an `elements` map, and optional initial `state`. This alias is
  * the Devframes-facing name; it does not add or remove fields.
  */
-export type DevframeJsonRenderSpec = Spec
+export type DevframeJsonRenderSpec<Element extends UIElement = UIElement> = Omit<Spec, 'elements'> & {
+  elements: Record<string, Element>
+}
+
+/** Derive a discriminated element union from every component in a catalog. */
+export type CatalogUIElement<CatalogType extends Catalog> = {
+  [ComponentName in keyof InferCatalogComponents<CatalogType> & string]: UIElement<
+    ComponentName,
+    InferComponentProps<CatalogType, ComponentName>
+  >
+}[keyof InferCatalogComponents<CatalogType> & string]
 
 /**
  * A single JSON-Pointer patch to a view's `state` model. `path` is an
@@ -27,23 +43,23 @@ export interface JsonRenderStatePatch {
  * serializable {@link JsonRenderViewStateRef} that a hub dock (or any client
  * transport) uses to locate it.
  */
-export interface JsonRenderView {
+export interface JsonRenderView<SpecType extends DevframeJsonRenderSpec = DevframeJsonRenderSpec> {
   /** Author-supplied stable id, unique within the view's scope. */
   readonly id: string
   /** Human-facing label published in the view index (defaults to `id`). */
   readonly title: string
   /** The serializable reference clients subscribe through. */
   readonly ref: JsonRenderViewStateRef
   /** Replace the entire spec (a structural change replaces the whole spec). */
-  update: (spec: DevframeJsonRenderSpec) => void
+  update: (spec: SpecType) => void
   /**
    * Apply JSON-Pointer patches to the view's `state`. Travels as a
    * shared-state patch (not a whole-spec snapshot), so only the changed
    * paths cross the wire.
    */
   patchState: (patches: JsonRenderStatePatch[]) => void
   /** Read the current spec (immutable). */
-  value: () => DevframeJsonRenderSpec
+  value: () => SpecType
   /** Unregister the shared state and its listeners. */
   dispose: () => void
 }