API reference
Five packages, published as compiled ESM with type declarations.
| Package | What it is |
|---|---|
@uicast/core | The engine: entry types, reactive scopes, the prompt builders, the expr tool. No React. |
@uicast/expr | The expression evaluator: closed grammar, runtime membrane, budget. No uicast imports. |
@uicast/react | The React binding: the renderer and the implementation factory. |
@uicast/shadcn-catalog | A reference catalog: 106 def/impl pairs over shadcn/ui. |
@uicast/streamdown | Renders uicast fences inside a Markdown chat reply. |
@uicast/core
See Core concepts.
@uicast/core — index module
| Export | What it does |
|---|---|
createComponentDefinition(def) | Builds a component definition. |
createProxyScope(initial?) | One reactive scope: a shallow proxy over its fields. A write emits the field. |
buildElementsByKey(entries) | Folds entries into a key → entry map, applying partial replacement. |
streamJsonLines<T>(source) | Async generator over a byte or string stream. Yields each line that parses as JSON; skips prose and partial lines. |
isComponentEntry(value) | Runtime guard: is this parsed JSON an entry? |
EntryError | The classified error every fault arrives as. See Error recovery. |
Types: ComponentEntry, ComponentListEntry, ComponentDefinition,
CombinedSpec, ValueSource, ValueSourceAssignment,
CallbackValueSourceAssignment, ReactiveProxy, UrlPolicy,
EntryErrorReason, EntryFault, and ExpressionEvaluator (re-exported from
@uicast/expr).
@uicast/core/internal is plumbing for the React binding, with no semver
guarantee. Don’t build on it.
@uicast/core/prompt — prompt module
The prompt-partial builders. Each takes one options object.
| Export | Emits |
|---|---|
getCommonInstructionsPartialPrompt({ maxListItems?, note? }) | The output contract (entries, keys, partial replacement) and the names an expression can see: scopes, evt, currentValue. The language itself is getExpressionsPartialPrompt(); use both. |
getScopePartialPrompt({ kind, approxEntries?, note? }) | How much to build on this surface. |
getComponentsPartialPrompt({ definitions, urlPolicy?, note? }) | The component menu, from your definitions. Callback payloads with an id hoist into ## Common Events. With a URL prop listed, ## URL Props says what urlPolicy loads; pass the renderer’s. |
getExpressionsPartialPrompt({ maxLength?, note? }) | The # JavaScript Expressions block: the rules, the globals, a few idioms and the length limit. The globals come from @uicast/expr’s own list. |
getFunctionsPartialPrompt({ functions, note? }) | Call signatures, from your host functions. |
getEditRequestPrompt({ request, missingKeys? }) | A user-turn message for an edit. |
getErrorRecoveryPrompt({ failures }) | A user-turn message naming the elements that failed. |
Types: one options type per builder (ComponentsPromptOptions,
ScopePromptOptions, …) and RenderFailure. note? is host text, rendered
verbatim as the section’s trailing ## Note.
@uicast/core/tool — tool module
| Export | What it does |
|---|---|
exprTool({ read?, functions?, note? }) | The expr tool, a StandardToolV0 with Standard Schema input and output schemas: the model writes the state of the UI it wrote and calls host functions: the UI’s, or functions in their place, described in the tool’s text. With read: true, a call can also read a value back, and that value reaches the model; off by default. Its calls run in the browser through useExprTool(). See The expr tool. |
Types: ExprToolOptions, ExprToolInput, ExprToolOutput.
@uicast/expr
The expression language.
| Export | What it does |
|---|---|
Evaluator | The interpreter: eval, compile, validate. functions binds host functions at construction, so a call is checked before it runs; budget sets the limits. withFunctions(functions) returns a copy with other functions, same class and options. A subclass that sets toFunction runs expressions with new Function (Custom evaluator). |
ExpressionEvaluator | The interface Evaluator implements and uicast types against: eval, compile, validate, memberReads, functions, withFunctions. Implement it to plug in an evaluator for another language. |
ExpressionError | Every refusal and fault, with a reason. |
Types: EvaluatorOptions, EvaluatorContexts, BudgetOptions,
ExpressionFacts, ExpressionErrorReason. functions takes
standard-tool’s StandardToolV0: import the type from standard-tool, and
the schema types from @standard-schema/spec.
@uicast/expr/internal is shared with core, with no semver guarantee.
Don’t build on it.
@uicast/react
Re-exports nothing from core — import from both.
| Export | What it does |
|---|---|
<RendererProvider> | Holds the implementations, the evaluator (with host functions bound), fallback UI and the shared root scope. See Renderer. |
<EntriesRenderer entries> | Mounts a document. Memoized on the array reference. |
<DocumentSkeleton entries> | The document’s shape from the entries alone, drawn with the provider’s implementations and fallbackComponents.defaultSkeleton. Evaluates nothing, so it renders in a server pass. See Server rendering. |
useExprTool({ read?, functions? }) | Runs the expr tool’s calls against the provider’s state and returns the answer for the model. Without read: true, a call that reads is refused before any step runs. With functions, the calls run on evaluator.withFunctions(functions), and one naming another of the UI’s functions is refused before any step runs. See The expr tool. |
createComponentImplementation({ def, render, skeleton? }) | The React half of a component pair: { def, skeleton }, to register. See impl. |
Types: ComponentImplementation, FallbackComponents, SkeletonComponentProps,
ConfirmComponentProps, ErrorComponentProps, InitFn.
@uicast/shadcn-catalog
A reference catalog, usable as is. See Reference catalog.
| Entry point | What it holds |
|---|---|
@uicast/shadcn-catalog/all/defs | Every definition by name (CardDef, ButtonDef, …), and all of them as one array, defs, for getComponentsPartialPrompt. |
@uicast/shadcn-catalog/all/impls | Every implementation by name (CardImpl, …), and all of them as one array, impls, for <RendererProvider>. |
@uicast/shadcn-catalog/<group>/defs, /<group>/impls | The same, one group each: layout, content, data, charts, forms, navigation, overlays. See Reference catalog. |
@uicast/shadcn-catalog/essential/defs, /essential/impls | 29 common components from every group. |
@uicast/shadcn-catalog/events | mouseEventSchema, keyboardEventSchema: shared payloads the catalog’s callbacks reuse. See Shared events. |
@uicast/shadcn-catalog | ConfirmModal and RenderError, for fallbackComponents. |
@uicast/shadcn-catalog/ui/* | The 37 underlying components, shadcn/ui’s and Kibo UI’s kanban (/ui/button, /ui/skeleton, …). |
@uicast/shadcn-catalog/catalog.css | Every utility the components use, and defaults for --success, --warning and --info. Colors come from your theme’s variables. |
@uicast/shadcn-catalog/theme.css | Optional baseline: preflight plus the shadcn palette. |
@uicast/streamdown
See Streamdown plugin.
@uicast/streamdown — index module
| Export | What it does |
|---|---|
createFenceRenderer(options?) | The Streamdown renderer for uicast fences. Call once and reuse. |
Types: FenceRendererOptions, SourceToggleProps.
@uicast/streamdown/prompt — prompt module
| Export | Emits |
|---|---|
getFencePartialPrompt({ note? }) | The fence syntax and shared-state rules. |
Types: FencePromptOptions.
Last updated on