generative-mui — Material UI renderer for A2UI (v0.9.1)

[yessGlory17]

Hi A2UI community! 👋

I built generative-mui, a community-maintained A2UI renderer that maps A2UI surfaces onto Material UI (MUI) — as far as I can tell, the first MUI renderer in the ecosystem. The agent emits A2UI (a flat, id-referenced adjacency list + a JSON-Pointer-bound data model) and the library renders it as real MUI components inside your app's existing <ThemeProvider>. The surface has no theme of its own, so it inherits your palette/typography and re-skins top-to-bottom when you switch themes.

Links

• GitHub: https://github.com/yessGlory17/generative-mui
• npm: https://www.npmjs.com/package/@yessglory/generative-mui-react (core: https://www.npmjs.com/package/@yessglory/generative-mui-core)
• PR to the community renderers list: docs: add generative-mui (Material UI renderer) to community renderers #2082

Spec support

• A2UI v0.9.1 (v0.9 family). v0.8 not supported.

What it does

• All 18 Basic Catalog components mapped 1:1 to MUI (Text→Typography, Row/Column→Stack, Button with checks→disabled, Modal→Dialog, …).
• Opt-in Extended Catalog: LineChart/BarChart/PieChart/Gauge/SparkLine via @mui/x-charts, plus Table, Alert, Chip, Accordion, Stepper, Switch, Rating, Autocomplete, and more. The schemas live in the React-free core, so only the renderers (and the @mui/x-charts dep) are opt-in.
• Two-way binding & validation: inputs bound to {"path":"/field"} read/write the data model; Button.checks (required, regex) disable the button and surface the first error as helper text.
• Streaming resilience: components arrive piece by piece with Skeleton placeholders, append-only string-delta detection so a growing stream never clobbers local edits, cycle/MAX_RENDER_DEPTH guards, and a per-node error boundary.
• Safe by construction: a type not in the registry never runs arbitrary code (safe fallback); sx/style/className from the agent never reach MUI; local regex has ReDoS length caps.

Architecture

Two packages with a lint-enforced one-way dependency (core ← react):

• @yessglory/generative-mui-core — framework-neutral A2UI v0.9.1: Zod schemas, JSONL parser, JSON-Pointer, a deterministic subscribable SurfaceStore, value resolution, and provider-agnostic agent tool schemas. Imports no React/MUI, so it runs on server/edge/RSC.
• @yessglory/generative-mui-react — the MUI adapter, exposed as a single <A2uiSurface> component.

Install

pnpm add @yessglory/generative-mui-react   # core comes with it

import { A2uiSurface, SurfaceStore, extendedRegistry } from '@yessglory/generative-mui-react'

const store = new SurfaceStore()
store.apply(a2uiJsonlFromYourAgent)   // JSONL / message array / single message

function Chat() {
  return (
    <A2uiSurface
      source={store}                    // live store → streaming + two-way binding
      registry={extendedRegistry}       // enable charts too (optional; @mui/x-charts)
      onAction={(a) => sendToAgent(a)}  // action.event goes back to the agent
    />
  )
}

The repo ships two runnable examples (Vite SPA and Next.js App Router) that work out of the box in demo mode with no API key. Feedback and issues very welcome — thanks for building A2UI! 🙏

[yessGlory17]

cc @ditman @yjbanov — sharing this here as suggested in the submission guide. The companion PR that adds it to the community renderers list is #2082 (CLA green, review feedback applied). Happy to adjust anything — feedback very welcome, and thanks for maintaining A2UI! 🙏

[ditman]

Hey @yessGlory17! Thanks for building this and showing it, I think it's great! I've noticed that you have a dependency on "zod": "^3.24.1", but now I'm experimenting with creating a more flexible dependency range (similar to your peerDep on react/react-dom).

QQ I didn't have time to fully review your code; how reusable is your core package? could you build mui for other frameworks (like Lit) or is it a react-only thing?

[yessGlory17]

Thanks @ditman, really glad you like it! 🙏

On Zod — it's a hard dependency today (^3.24.1) because the whole catalog is Zod schemas and validation runs on it. But you're right to flag it: since the library exposes those schemas in its public API (anyComponentSchema, registerComponent, …), a single shared Zod instance actually matters — a duplicated/mismatched Zod in the host can break instanceof/parsing. So moving Zod to a peerDependency (or a wide range) is the right call and I'm happy to do it. Two wrinkles I'd want to get right:

• I also use zod-to-json-schema for the agent tool schema. Zod v4 ships native JSON Schema (z.toJSONSchema), so a v4 bump could drop that extra dep entirely.
• Supporting v3 and v4 in one range needs a little care (a few APIs moved). Happy to match whatever range convention you land on — if you're standardizing this across renderers, I'll align with it.

On core reusability — this is the fun part: it's React-free by construction (enforced by eslint-plugin-boundaries; core imports zero React/MUI). core does everything except the widget mapping:

• Basic + Extended catalog Zod schemas
• JSONL parser + the 4-message protocol reducer (reduce, pure)
• JSON Pointer (get/set/remove)
• SurfaceStore — a plain observable (getState() + subscribe()), not React-specific; it just happens to fit useSyncExternalStore
• value resolution (literal / {path} / FunctionCall, incl. required/regex)
• the agent tool schema + describeCatalog() prompt helpers

So yes — you could absolutely build a Lit (or Vue/Svelte/Angular) renderer on top of core: subscribe to the store, walk the resolved graph, and map catalog component types to your framework's widgets. The only React/MUI-specific package is -react; the -mui naming is really just about the reference adapter. If a shared framework-neutral JS core across renderers is directionally interesting to you, I'd be very happy to collaborate on it. 🙏

[ditman]

So moving Zod to a peerDependency (or a wide range) is the right call and I'm happy to do it.

I'm actually working on this right now on the a2ui-project/a2ui renderers themselves; I'm trying to figure out how to add unit tests to ensure our stuff works with both Zod versions.

this is the fun part: it's React-free by construction (enforced by eslint-plugin-boundaries; core imports zero React/MUI). core does everything except the widget mapping

This is very cool, can you explain the relationship between @a2ui/web_core and your core package a little bit more? Are you using any of the message parsing logic from web_core in your own? I guess your core is only for the basic catalog definitions?

[yessGlory17]

Great question — let me answer it directly.

Short answer: no, I don't depend on @a2ui/web_core. generative-mui-core is a fully independent, from-scratch TypeScript implementation — I'm not using web_core's message parsing / model-processor / generic-binder logic. So it's not "just the basic catalog definitions"; it re-implements most of web_core's responsibilities in parallel:

web_core	generative-mui-core equivalent
v0_9/schema/* (TS interfaces + guards)	Zod schemas (Basic + Extended catalog)
processing/message-processor	4-message protocol reducer (reduce, pure)
data/model-processor + JSON Pointer binding	JSON Pointer get/set/remove + value resolution
state/surface management	SurfaceStore — a plain observable (getState()/subscribe())
styles/*	(deliberately absent — styling is left to the host theme)
—	agent tool schema + describeCatalog() (not in web_core)

Why I went parallel: the core design choice is "Zod as the single source of truth." web_core takes the TS-interfaces + runtime-guards route; in mine, each component's Zod schema is the one source, and two things derive from it: (1) runtime validation of untrusted agent output, and (2) the agent tool JSON Schema handed to the LLM (zod-to-json-schema today, native z.toJSONSchema under Zod v4). That second part — the producer side — is something web_core doesn't cover today, and it's the piece I think adds the most.

On convergence: since web_core is the canonical framework-agnostic core, the "shared core across renderers" idea you raised makes a lot of sense to me. Two directions, and I'm open to both:

• Align my reducer/binding with web_core's message-processor + generic-binder semantics (backed by conformance tests), or
• Bring the agent-tooling layer (Zod → JSON Schema tool definitions + describeCatalog) upstream into web_core, so every renderer can benefit on the generative/agent side.

On Zod v3+v4 testing — I'm in exactly the same spot right now (dropping zod-to-json-schema for z.toJSONSchema on v4). I'd happily follow whatever dual-version test approach you land on in the renderers, and converge on a shared convention. I'd love to see how you're wiring it up.

[ditman]

Bring the agent-tooling layer to web_core

Even though I like a single source of truth, I don't think we can drop the JSON Schema definitions, because those are used by other frameworks (like python or dart/flutter), so making this zod-first makes it harder to consume by other frameworks without post-processing (maybe z.toJSONSchema is an easy way to produce the JSON from Zod and this would be a moot problem). Have you experimented generating the Zod code from the JSON Schemas? (In my opinion) that should be more straightforward maybe? I've never tried this though!

In any case, I think we should create an isue for A2UI to remove the duplicity of zod and json either way; this is feedback that we've received previously!

[yessGlory17]

@ditman Hi, what you said made a lot of sense to me, so I decided to align my project with web_core. I'm not done yet, but here is what I've moved over to web_core so far. It's currently 2:52 AM in Turkey. I'll finish this up in the morning and get back to you.
yessGlory17/generative-mui#1

[ditman]

Thanks! I think this'll make it much easier for your users to adopt it, and for you to evolve/maintain as the protocol evolves!