React package README and skill: Quick Start crashes, nested spec example, JSONUIProvider props #473

Summary

#443 and #445 fix the bare <Renderer> examples in the root README.md. The same problems, plus two more, are in packages/react/README.md and skills/react/SKILL.md, which neither touches. The skill matters most, because agents follow it as written.

Checked against main at f5c1240 and the published 0.22.0 packages. The packages/react/README.md that ships in the npm tarball is identical to main.

Where

packages/react/README.md

• Lines 97–103, Quick Start "3. Render Specs": wraps Renderer in StateProvider and ActionProvider, but not VisibilityProvider, so it throws useVisibility must be used within a VisibilityProvider.
• Line 534: renders a bare <Renderer> and throws the same error.
• Lines 353–357, $computed: passes spec and catalog to JSONUIProvider, which takes neither, and leaves out the required registry. It renders at runtime, but fails to typecheck with TS2322 (… is not assignable to type 'IntrinsicAttributes & JSONUIProviderProps').

skills/react/SKILL.md

• Line 23, Quick Start: bare <Renderer>, which throws at runtime.
• Lines 81–93, "Spec Structure (Element Tree)": shows a nested spec ("root": { "type": "Card", "children": [{ … }] }). The renderer and catalog.validate expect the flat { root: "<key>", elements: { … } } map that the package README and the rest of the skill use. The nested shape throws undefined is not an object (evaluating 'Object.keys(spec.elements)'), and catalog.validate(spec).success is false.
• Line 173, $computed: JSONUIProvider without registry, the same TS2322.

Reproduction

import { renderToString } from "react-dom/server";
import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
import { ActionProvider, defineRegistry, JSONUIProvider, Renderer, StateProvider } from "@json-render/react";
import { z } from "zod";

const catalog = defineCatalog(schema, {
  components: {
    Card: { props: z.object({ title: z.string() }), slots: ["default"], description: "card" },
    Button: { props: z.object({ label: z.string() }), description: "button" },
  },
  actions: {},
});
const { registry } = defineRegistry(catalog, {
  components: {
    Card: ({ props, children }) => <div>{props.title}{children}</div>,
    Button: ({ props }) => <button>{props.label}</button>,
  },
});

const flat = { root: "card", elements: {
  card: { type: "Card", props: { title: "Hello" }, children: ["btn"] },
  btn: { type: "Button", props: { label: "Click me" }, children: [] },
} };
const nested = { root: { type: "Card", props: { title: "Hello" }, children: [{ type: "Button", props: { label: "Click me" } }] } };

// packages/react/README.md Quick Start
renderToString(<StateProvider initialState={{}}><ActionProvider handlers={{}}><Renderer spec={flat} registry={registry} /></ActionProvider></StateProvider>);
// -> Error: useVisibility must be used within a VisibilityProvider

// skills/react/SKILL.md spec shape
catalog.validate(nested).success; // false
renderToString(<JSONUIProvider registry={registry}><Renderer spec={nested} registry={registry} /></JSONUIProvider>);
// -> TypeError: undefined is not an object (evaluating 'Object.keys(spec.elements)')

// Working version
renderToString(<JSONUIProvider registry={registry}><Renderer spec={flat} registry={registry} /></JSONUIProvider>);
// -> <div>Hello<button>Click me</button></div>

Suggested fix

• Wrap Renderer in <JSONUIProvider registry={registry}> in both Quick Starts and at README line 534, as docs: wrap Renderer in JSONUIProvider in README examples #445 does for the root README.
• Change both $computed snippets to <JSONUIProvider registry={registry} functions={…}>.
• Replace the skill's "Spec Structure (Element Tree)" example with the flat element map from the package README's "Spec Format" section.

Environment

• @json-render/core 0.22.0, @json-render/react 0.22.0
• react / react-dom 19.3.1, zod 4.6.7
• Bun 1.4.4, TypeScript 7.0.2

Related: #443, #445