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. 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: 107 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 a $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/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. 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. Implement it to plug in an evaluator for another language. |
ExpressionError | Every refusal and fault, with a reason. |
Types: EvaluatorOptions, EvaluatorContexts, BudgetOptions,
ExpressionFacts, ExpressionErrorReason, and StandardToolV0 with
StandardSchemaV1 / StandardJSONSchemaV1, copied verbatim from
standard-tool and the Standard Schema spec. A standard-tool tool fits as is.
@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. |
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.