npm · cascivo.com · Docs · Storybook · GitHub

A runtime that turns a plain JSON config into live cascivo UI. CascivoView takes a ViewConfig object and renders the real components — so AI agents (and no-code tooling) can emit data instead of writing TSX.

Usage

A ViewConfig is named regions of component nodes; each node names a component (component), plus optional props, children, data bindings, and event wiring:

import { CascivoView, type ViewConfig } from '@cascivo/render'

const view: ViewConfig = {
  view: {
    regions: {
      main: [
        {
          component: 'Card',
          children: [
            {
              component: 'Badge',
              props: { variant: 'secondary' },
              bind: { children: '$data.count' },
            },
            {
              component: 'Button',
              props: { variant: 'primary' },
              children: 'Invite',
              events: { onClick: '$actions.invite' },
            },
          ],
        },
      ],
    },
  },
}

export function App() {
  return (
    <CascivoView
      config={view}
      data={{ count: 42 }}
      actions={{ invite: () => console.log('invite') }}
    />
  )
}

The JSON stays fully serializable: live values come from the host via bind ("$data.users.active" resolves a dot-path into the data prop) and handlers via events ("$actions.invite" looks up the actions prop) — never from the config itself. Strings can be i18n refs ({ "$t": "catalog.key" }), resolved through @cascivo/i18n. config also accepts a Signal<ViewConfig>, so a view can be swapped live.

Nodes resolve against a built-in component map of 74 cascivo components (Button, Card, Badge, Input, Select, Modal, Tabs, DataTable, Form, …) — see component-map.ts for the full list.

Your own components, and charts

Pass components to render names beyond the built-in set: charts, or your app's own components. They are looked up before the built-ins, the validator accepts them, and their props are passed through unchecked:

import { Kpi, LineChart } from '@cascivo/charts'

;<CascivoView config={view} data={data} components={{ Kpi, LineChart }} />

@cascivo/render does not depend on @cascivo/charts, so only an app that renders charts installs it. Validate such a view with the same names: validateView(view, { components: ['Kpi', 'LineChart'] }), and read it as Markdown with viewToMarkdown(view, { components: { Kpi, LineChart } }).

Validation

Every render validates first. Invalid configs throw by default with exact paths; pass onInvalid="render" to show errors inline instead (playground mode). validateView is exported for validating before rendering:

import { validateView } from '@cascivo/render'

const { valid, errors } = validateView(view) // errors: { path, message }[]

Unknown components (with a did-you-mean hint), malformed nodes, and prop values that don't match the generated per-component prop schemas are reported with exact paths, so generated views fail loudly rather than rendering garbage.

On a server, import it from @cascivo/render/validate. That entry has no React and no components, only the validator and the prop schemas it checks against, so it runs in a Cloudflare Worker, an edge function or a Node script:

import { validateView } from '@cascivo/render/validate'

// In an AI tool: hand the errors back to the model, which fixes them and calls again.
const { valid, errors } = validateView(modelOutput)

cascivo create --framework cloudflare --example agent builds an assistant around exactly this: the Worker validates each view the model produces, and the page renders it with <CascivoView>.

Pair it with the MCP server's bound-vocabulary grammar (get_view_grammar) and scaffold_view for the full anti-hallucination loop: the model can only emit components and props that exist, and validateView is the enforcement backstop. cascivo generate <config.json> converts a validated ViewConfig into owned TSX when you want to graduate from JSON to source.

Install

pnpm add @cascivo/render

cascivo.com · Docs · Storybook · GitHub · AI agents: read llms.txt (install steps + component index, plain text) or use @cascivo/mcp and registry.json · MIT