@docyrus/generative-ui-core

Shared non-React catalogs, schemas, prompt metadata, and compile helpers for the Docyrus generative UI system.

This package exists so backend and validation layers can use the exact same mode definitions as the React frontend without pulling in JSX or browser runtime code.

It is the source of truth for:

• shared generative UI types
• dashboard / widget / data-grid / form mode schemas
• backend mode metadata and custom prompt rules
• compile helpers that validate and normalize React-mode specs
• official email, pdf, and image catalog entries used by the backend contract

Runtime Compatibility

@docyrus/generative-ui-core is published with both ESM and CommonJS entries.

That means it can be used from:

• ESM frontend/build tooling
• CommonJS Node backends
• mixed backend workspaces such as NestJS + webpack/Nx setups

Installation

pnpm add @docyrus/generative-ui-core

When To Use This Package

Use @docyrus/generative-ui-core when you need:

• a backend route that generates specs by mode
• a stable SUPPORTED_MODES list
• prompt generation through catalog.prompt(...)
• tree-spec validation via compile helpers
• mode metadata without React

If you need the actual React chat/preview component, use @docyrus/generative-ui instead.

Top-Level Exports

The package exports three groups:

• types
• mode-catalogs
• mode-entries

In code:

import {
  SUPPORTED_MODES,
  ROOT_ELEMENT_TYPES,
  getCatalogForMode,
  dashboardCatalog,
  widgetCatalog,
  dataGridCatalog,
  formCatalog,
  compileDashboardSpec,
  compileWidgetSpec,
  compileDataGridSpec,
  compileFormSpec,
} from "@docyrus/generative-ui-core";

Supported Modes

SUPPORTED_MODES currently includes:

• dashboard
• widget
• data-grid
• form
• email
• pdf
• image

ROOT_ELEMENT_TYPES gives you the expected root component per mode.

What The Package Owns

React-Based Mode Catalogs

These are the child-based authoring surfaces used by the AI model:

• dashboardCatalog
• widgetCatalog
• dataGridCatalog
• formCatalog

Their schemas are also exported:

• dashboardSchema
• widgetSchema
• dataGridSchema
• formSchema

Backend Mode Entries

mode-entries adds the backend-facing pieces on top of the raw catalogs:

• getCatalogForMode(mode)
• ROOT_ELEMENT_TYPES
• SUPPORTED_MODES
• emailCatalog
• pdfCatalog
• imageCatalog
• custom prompt rule arrays such as DATA_GRID_CUSTOM_RULES

This is the right layer for server code that needs:

• the catalog itself
• the prompt rules to pass into catalog.prompt({ customRules })

Compile Helpers

Use these to validate and normalize child-based specs:

• compileDashboardSpec(spec)
• compileWidgetSpec(spec)
• compileDataGridSpec(spec)
• compileFormSpec(spec)

For React preview adapters or downstream renderers, these adapter-spec helpers are also exported:

• createDashboardAdapterSpec(spec)
• createWidgetAdapterSpec(spec)
• createDataGridAdapterSpec(spec)
• createFormAdapterSpec(spec)

Typical Backend Pattern

import { compileSpecStream, type Spec } from "@json-render/core";
import {
  getCatalogForMode,
  ROOT_ELEMENT_TYPES,
  compileDashboardSpec,
  compileWidgetSpec,
  compileDataGridSpec,
  compileFormSpec,
  type GenerativeUIMode,
} from "@docyrus/generative-ui-core";

function validateGeneratedSpec(jsonl: string, mode: GenerativeUIMode) {
  const spec = compileSpecStream(jsonl) as unknown as Spec;
  const { catalog, customRules } = getCatalogForMode(mode);

  // Build your system prompt from the catalog
  const systemPrompt = catalog.prompt({
    mode: "chat",
    customRules: [...customRules],
  });

  // Validate tree-based React modes with the shared compilers
  switch (mode) {
    case "dashboard":
      compileDashboardSpec(spec);
      break;
    case "widget":
      compileWidgetSpec(spec);
      break;
    case "data-grid":
      compileDataGridSpec(spec);
      break;
    case "form":
      compileFormSpec(spec);
      break;
    default:
      break;
  }

  return { spec, systemPrompt };
}

Note the customRules: [...customRules] copy. The exported rules are readonly.

Data-Grid Mode

data-grid is a first-class mode, not just a widget subtype.

Important behavior:

• root element must be WidgetSurface
• it must contain exactly one DataGridWidget child
• compileDataGridSpec() verifies that the compiled widget kind is actually data-grid

This makes it safe to expose a dedicated data-grid backend mode while still reusing the widget adapter shape on the frontend.

Shared Types

The package exports the shared data model used across the system, including:

• GenerativeUIMode
• SmartCanvasMode
• SmartCanvasWidgetKind
• SmartCanvasWidget
• SmartCanvasValue
• GeneratedFormDefinition
• GeneratedFormField
• DashboardAdapterProps
• WidgetAdapterProps
• FormAdapterProps

These types are intentionally React-free and safe to use in backend code.

Relationship To @docyrus/generative-ui

@docyrus/generative-ui reuses this package and adds:

• the GenerativeUI React component
• React registry helpers
• frontend adapter types

The simplest mental model is:

• core = shared model + validation + catalogs
• generative-ui = React runtime + preview experience

Notes

• this package does not export JSX or React registries
• it is suitable for Node backends and build-time tooling
• it is the preferred dependency for backend routes such as /v1/ai/generate-ui/:mode