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
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.
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.
const node = renderer.render(validatedDocument, {
onEvent: async (event) => {
if (event.name !== "open-project") return;
await openProjectIfPermitted(event.payload.projectId);
},
});Props
Component props
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.