@docyrus/generative-ui

React UI package for Docyrus-backed generative interfaces built on top of @json-render plus a work-file-driven code-react-ts mode.

This package is the frontend/runtime layer. It gives you:

• the GenerativeUI React component
• React registry helpers for adapter-based preview rendering
• the shared mode catalogs and compile helpers re-exported from @docyrus/generative-ui-core
• typed mode/adaptor contracts for dashboard, widget, data-grid, form, email, PDF, image, and code-react-ts generation

If you need backend-safe catalogs, prompt metadata, or compile helpers without a React runtime, use @docyrus/generative-ui-core directly.

Package Split

The generative UI system is intentionally split into two packages:

• @docyrus/generative-ui Frontend/runtime package. Use this in React applications.
• @docyrus/generative-ui-core Shared non-React package. Use this in backend services, API layers, validators, and generators.

In practice:

• browser app -> @docyrus/generative-ui
• backend API -> @docyrus/generative-ui-core

Installation

pnpm add @docyrus/generative-ui @docyrus/signin react react-dom

Peer dependencies:

• react
• react-dom
• @docyrus/signin

What GenerativeUI Does

GenerativeUI is a two-pane experience:

• left side: chat / prompt history
• right side: rendered preview, raw JSON, or a code workspace depending on mode

It talks to a Docyrus backend that streams AI SDK UIMessage responses and integrates with client-created threads, persisted works, and per-generation work versions.

Mode behavior:

• json-render modes stream renderable spec data and preview it immediately
• code-react-ts uses the generation stream for chat, then hydrates its editor/preview from the generated work version's files

Default backend route shape:

/v1/ai/generate-ui/:mode

Additional default endpoints:

/v1/inbox/threads
/v1/ai/works

You can override these with the endpoints prop. endpointBasePath is still supported as a backward-compatible alias for the generate endpoint.

Supported Modes

• dashboard
• widget
• data-grid
• form
• code-react-ts
• email
• pdf
• image

Adapter requirements:

• dashboard -> requires adapters.dashboard
• widget -> requires adapters.widget
• data-grid -> requires adapters.widget
• form -> requires adapters.form
• email, pdf, image, code-react-ts -> no React adapter required

Quick Start

import {
  GenerativeUI,
  type FormAdapterProps,
  type SmartCanvasValue,
  type SmartCanvasWidget,
} from "@docyrus/generative-ui";

function DashboardAdapter({ value }: { value: SmartCanvasValue }) {
  return <pre>{JSON.stringify(value, null, 2)}</pre>;
}

function WidgetAdapter({ widget }: { widget: SmartCanvasWidget }) {
  return <pre>{JSON.stringify(widget, null, 2)}</pre>;
}

function FormAdapter({ definition }: FormAdapterProps) {
  return <pre>{JSON.stringify(definition, null, 2)}</pre>;
}

export function Example() {
  return (
    <GenerativeUI
      modes={["dashboard", "widget", "data-grid", "form", "email", "pdf", "image", "code-react-ts"]}
      adapters={{
        dashboard: DashboardAdapter,
        widget: WidgetAdapter,
        form: FormAdapter,
      }}
      endpoints={{
        generate: "/v1/ai/generate-ui",
        threads: "/v1/inbox/threads",
        works: "/v1/ai/works",
      }}
      initialSessions={{
        dashboard: {
          threadId: "thread-id",
          workId: "work-id",
          workVersionId: "work-version-id",
          messages: [],
        },
      }}
      codeReact={{
        imports: {
          react: "https://esm.sh/react@19",
          "react-dom/client": "https://esm.sh/react-dom@19/client",
          "react/jsx-runtime": "https://esm.sh/react@19/jsx-runtime",
        },
      }}
      defaultMode="dashboard"
      className="h-[900px]"
    />
  );
}

GenerativeUI Props

interface GenerativeUIProps {
  modes?: GenerativeUIMode[];
  defaultMode?: GenerativeUIMode;
  chatSurfaceMode?: "fixed" | "floating";
  endpointBasePath?: string;
  endpoints?: {
    generate?: string;
    threads?: string;
    works?: string;
  };
  floatingPlaceholder?: string;
  initialSessions?: Partial<Record<GenerativeUIMode, GenerativeUIResumeSession>>;
  codeReact?: {
    wasmUrl?: string;
    imports?: Record<string, string>;
  };
  adapters?: {
    dashboard?: DashboardAdapter;
    widget?: WidgetAdapter;
    form?: FormAdapter;
  };
  className?: string;
  onModeChange?: (mode: GenerativeUIMode) => void;
  onSessionChange?: (mode: GenerativeUIMode, session: GenerativeUISessionState) => void;
  onCreditsDepleted?: (usage: {
    remainingCredits: number;
    usedCredits: number;
    totalCredits: number;
  }) => void;
}

Notes:

• if modes is omitted, the component enables all supported modes it can satisfy from the provided adapters
• data-grid reuses the widget adapter because its compiled output is still a SmartCanvasWidget
• chatSurfaceMode="floating" is useful when embedding the generator as an assistant-style overlay
• the component manages per-mode threadId, workId, and workVersionId internally
• initialSessions lets a host restore a known thread/work/message state without building a works library into the package
• codeReact config controls the browser compiler/runtime for the code-react-ts workspace

Adapter Model

The model does not directly generate the final adapter payloads for the json-render React modes.

Instead, the flow is:

1. the backend streams a child-based json-render spec
2. the frontend parses that spec
3. the frontend compiles it into the final adapter shape
4. the preview is rendered through your adapter component

This is why the package exports both:

• catalogs / schemas / compile helpers
• registry helpers for preview rendering

code-react-ts is different:

1. the backend creates or updates a work and work version
2. the frontend captures X-Work-Id and X-Work-Version-Id
3. the frontend loads the generated files from the work file endpoints
4. Monaco + esbuild-wasm provide the in-browser editor and preview

Common Exports

Component:

• GenerativeUI

Registry helpers:

• createDashboardRegistry
• createWidgetRegistry
• createFormRegistry

Compile helpers and adapter-spec helpers:

• compileDashboardSpec
• compileWidgetSpec
• compileDataGridSpec
• compileFormSpec
• createDashboardAdapterSpec
• createWidgetAdapterSpec
• createDataGridAdapterSpec
• createFormAdapterSpec

Catalogs and schemas:

• dashboardCatalog
• widgetCatalog
• dataGridCatalog
• formCatalog
• dashboardSchema
• widgetSchema
• dataGridSchema
• formSchema

Types:

• GenerativeUIMode
• GenerativeUIResumeSession
• GenerativeUISessionState
• SmartCanvasWidget
• SmartCanvasValue
• GeneratedFormDefinition
• GeneratedFormField
• DashboardAdapterProps
• WidgetAdapterProps
• FormAdapterProps

Backend Expectations

For best results, pair this package with a backend that uses @docyrus/generative-ui-core.

The backend should:

• accept POST /api/v1/ai/generate-ui/:mode
• stream AI SDK UIMessage responses
• create or reuse a work and create a new work version for each generation
• return X-Work-Id and X-Work-Version-Id response headers
• persist thread history when threadId is provided
• emit json-render patches for json-render modes
• write generated files to work storage for code-react-ts
• validate React-based json-render modes with the compile helpers from core

Minimal backend usage looks like:

import {
  getCatalogForMode,
  getGenerationModeEntry,
  ROOT_ELEMENT_TYPES,
} from "@docyrus/generative-ui-core";

When To Use @docyrus/generative-ui-core Instead

Use core directly when you need:

• mode metadata such as SUPPORTED_MODES
• backend prompt generation via getCatalogForMode()
• compile-time validation on the server
• React-free access to catalogs and schemas
• CommonJS support in Node backends

Development Notes

• this package is published as a dist-based package
• it depends on @docyrus/generative-ui-core for all non-React mode logic
• image preview rendering uses a browser-side helper module and may rely on bundler-specific behavior when @json-render/image is involved

Related Packages

• @docyrus/generative-ui-core
• @json-render/core
• @json-render/react
• @json-render/react-email
• @json-render/react-pdf
• @json-render/image