Skip to content
Browse documentation
whisk/ui

Generative UI primitives

Compose approved primitives in bounded generated interfaces.

Overview

Generative UI primitives let an application define a small, renderer-neutral catalog of approved interface contracts, validate a generated document against it, and lower only that validated snapshot through its own Whisk/UI bindings. They do not choose a model, generate content, execute actions, authorize data, or supply a default catalog.

Use when

Your application needs to present model-produced interface structure from a small, explicit catalog that it owns and validates.

Use instead

Use ordinary Whisk/UI components for application-authored interface structure, or MessagePair and StreamingText when the generated output is conversational content rather than a structured interface.

Usage

tsx
import { defineCatalog } from "@smoothie-framework/whisk-core";
import { stackDefinition, textDefinition } from "@smoothie-framework/whisk-core/components";
import { createGenUI } from "@smoothie-framework/whisk-core/gen-ui";
import { createCatalogRenderer, Stack, Text } from "@smoothie-framework/whisk-react";

export const catalog = defineCatalog({
  id: "workspace.summary",
  version: "1",
  components: { Stack: stackDefinition, Text: textDefinition },
});

export const genUI = createGenUI({ catalog });

export const renderer = createCatalogRenderer({
  catalog,
  renderers: {
    Stack: ({ props, slots }) => <Stack {...props}>{slots.children}</Stack>,
    Text: ({ props, slots }) => <Text {...props}>{slots.children}</Text>,
  },
});

Examples

Validate generated JSON before rendering

A schema can guide generation, but it does not grant rendering permission. Parse every received document—including one restored from storage or received over the network—against the selected catalog, then render only the returned snapshot. Keep diagnostics in application logging or a safe recovery UI; do not show raw input by default.

tsx
import { Alert } from "@smoothie-framework/whisk-react";

function renderGeneratedSummary(candidate: unknown) {
  const parsed = genUI.parse(candidate);

  if (!parsed.ok) {
    reportInvalidDocument(parsed.diagnostics);
    return <Alert title="Summary unavailable">Try again.</Alert>;
  }

  return renderer.render(parsed.value);
}

Handle declared events in the host

A generated document can emit only the semantic events declared by its catalog component. The event handler is still ordinary application code: verify current permissions and data, perform the operation, and show its result outside the renderer. Do not treat a declared event as authorization.

tsx
const node = renderer.render(validatedDocument, {
  onEvent: async (event) => {
    if (event.name !== "open-project") return;

    await openProjectIfPermitted(event.payload.projectId);
  },
});
Keep the catalog narrow
Start with a small set of display components and closed prop values. Add a component, slot, or semantic event only when the application can render and govern it deliberately.

Props

Component props

PropTypeDefaultDescription
catalogCatalognoneRequired, application-owned map of components created with defineComponent or a first-party portable definition. Its identity includes the component, prop, slot, and event contracts.
limitsPartial<DocumentLimits>package defaultsOptional stricter document bounds for createGenUI. Values can restrict package ceilings but cannot raise them.
schema | instructionsJsonSchema | stringnoneImmutable generation artifacts returned by createGenUI. Give them to the application-owned generation integration; receiving schema-shaped output is not validation proof.
documentunknownnoneUntrusted generated JSON passed to genUI.parse or parseDocument. A successful parse returns the opaque ValidatedDocument required by the renderer.
renderersExact renderer mapnoneRequired createCatalogRenderer binding. It must implement every catalog component exactly once with stable, application-owned native component types.
onEvent(event: CatalogEvent) => void | Promise<void>required for documents with declared eventsPer-render semantic event handler. The application authorizes, executes, retries, and reports the operation; the document cannot call application code directly.

Accessibility

Validation is a structural boundary, not an accessibility guarantee. Define catalog components whose native renderers provide the correct semantics, accessible names, keyboard behavior, and focus management. Validate every generated document before rendering, keep the catalog narrow, and ensure generated text or labels are understandable in context. Semantic events are not actions: the host must authorize them and provide any pending, success, or error feedback. Do not expose sensitive props, hidden data, arbitrary URLs, raw HTML, or executable code through the catalog.

Content guidance

Allow generated copy only when it is appropriate for the audience and supported by application data. Give any generated action a specific, human-readable label; never let a document invent an authorization, destination, or outcome.