@xmachines/json-render-core 0.20.0-xm.3 → 0.21.0-xm.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +51 -0
- package/dist/index.d.mts +132 -3
- package/dist/index.d.ts +132 -3
- package/dist/index.js +862 -0
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +860 -0
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -8,6 +8,57 @@ Core library for json-render. Define schemas, create catalogs, generate AI promp
|
|
|
8
8
|
npm install @xmachines/json-render-core zod
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
+
## Experimental decision-model composition
|
|
12
|
+
|
|
13
|
+
`experimental_composeSpec` builds a flat `Spec` by choosing among your app's atomic element candidates. `experimental_createEvaluator` connects a choice evaluation model through Vercel AI Gateway. Jev (`typesafe-ai/jev`) is the current example; the API names and explicit `model` option are model-neutral. Use your own catalog, props, state bindings, action bindings, and renderer; no playground components are required.
|
|
14
|
+
|
|
15
|
+
**Unreleased:** try a source build before the next package release. APIs prefixed with `experimental_` or `Experimental_` may change in any release. Pin exact versions and review release notes before upgrading.
|
|
16
|
+
|
|
17
|
+
```typescript
|
|
18
|
+
// Server only
|
|
19
|
+
import { experimental_composeSpec, experimental_createEvaluator } from "@xmachines/json-render-core";
|
|
20
|
+
import { catalog } from "./catalog";
|
|
21
|
+
import { candidates } from "./candidates";
|
|
22
|
+
|
|
23
|
+
const evaluate = experimental_createEvaluator({
|
|
24
|
+
model: "typesafe-ai/jev",
|
|
25
|
+
apiKey: process.env.AI_GATEWAY_API_KEY!,
|
|
26
|
+
});
|
|
27
|
+
|
|
28
|
+
for await (const event of experimental_composeSpec({
|
|
29
|
+
catalog,
|
|
30
|
+
candidates,
|
|
31
|
+
prompt: "Create account preferences with a name field and Save button",
|
|
32
|
+
initialState: { name: "" },
|
|
33
|
+
evaluate,
|
|
34
|
+
maxSteps: 12,
|
|
35
|
+
maxElements: 24,
|
|
36
|
+
signal: AbortSignal.timeout(30_000),
|
|
37
|
+
})) {
|
|
38
|
+
// Send snapshots to your client and render using your existing registry.
|
|
39
|
+
if (event.type === "step") console.log(event.spec);
|
|
40
|
+
else console.log(event.stopReason, event.spec);
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Candidates contain `id`, `description`, and an atomic `element` (`type`, `props`, optional `on` and `visible`). `root: false` excludes a candidate from root selection; `maxUses` defaults to one; candidates sharing a `resource` are mutually exclusive. The catalog's slots determine where children can be attached. Props and action parameters are checked against initial state; expressions remain live in the output. Actions are never executed by the composer.
|
|
45
|
+
|
|
46
|
+
Candidates are configured component instances. The model constructs their tree, grouping, and order; it does not choose arbitrary prop values from the full catalog schema. Apps can build candidates per request from their records and permitted operations, or bind props to data in `initialState`. To let the model choose a different chart type or field configuration, supply those alternatives as candidates. No complete page template is required. Explicitly name required sections in the prompt; structural validation does not detect omitted content.
|
|
47
|
+
|
|
48
|
+
New compositions default to `strategy: "batch"`. One evaluation selects the root and component membership together, grouping mutually exclusive variants into one question and selecting bounded counts for reusable recipes. The first snapshot contains the selected content in catalog order under the root's default slot (or first declared slot). A second evaluation arranges parent slots and sibling order when needed. The entire resulting tree is validated before it is emitted; inconsistent placements throw and leave the first snapshot usable as partial UI. Equal sibling positions retain catalog order. Root selection takes precedence over speculative membership/count answers for the same recipe or resource. No separate finish call is needed.
|
|
49
|
+
|
|
50
|
+
`maxElements` bounds batched creation (default 32, including the root). An element/depth limit or a missing layout evaluation due to `maxSteps` produces `stopReason: "limit"`. Set `strategy: "sequential"` for one-operation-at-a-time creation or an existing custom evaluator using the `next`/`parent` protocol. Follow-up edits always use that sequential protocol, regardless of strategy.
|
|
51
|
+
|
|
52
|
+
For follow-up edits, pass the selected version as `initialSpec`. The composer can add candidates, replace an element's recipe while preserving its ID and children, remove a non-root subtree, or move/reorder a subtree among valid slots. Unchanged elements and state are retained, and the input spec is never mutated. `elementDescriptions` optionally supplies text identifying existing elements to the evaluator; otherwise matching recipes supply descriptions, with component names as the fallback. Raw props and state remain private. `initialState`, if supplied, replaces the seed's state.
|
|
53
|
+
|
|
54
|
+
Seed specs must be valid trees within the same catalog, supported expression subset, and depth limit. Existing elements that exactly match a candidate count toward its usage/resource limits. Removing or replacing them releases those limits. Replacements and moves use a second evaluation to select a valid recipe or destination; both decisions count toward `maxSteps`. A budget or cancellation can stop before an edit is applied.
|
|
55
|
+
|
|
56
|
+
The async generator emits detached `step` snapshots and a `complete` event with `stopReason: "finish" | "limit" | "unavailable"`, decision traces, timing, and nullable input usage. A batched trace represents one evaluation (`choice: "select"` or `"layout"`) and includes its independent `answers`; time and tokens are counted once per evaluation. Completion can include a partial spec or no spec, and does not guarantee that the model selected the right content. Provider errors, invalid choices, invalid combined layouts, and cancellation throw. Defaults: 32 evaluations, depth eight, and a 10-second per-call Gateway timeout.
|
|
57
|
+
|
|
58
|
+
V1 supports standard flat Spec catalogs, literals, `$state`, `$bindState`, state-based visibility, and named slots. It excludes repeat/watch, computed/custom expressions, and subtrees within candidate recipes. Bindings must resolve to valid values in the seed state or explicit `initialState`; handlers must still validate later user input. Candidate descriptions, element descriptions, and explicit `context` are sent to the evaluator; state values and raw props/bindings are not sent automatically.
|
|
59
|
+
|
|
60
|
+
See the [Jev guide](https://json-render.dev/docs/jev) for complete catalog/candidate examples, source-build installation, rendering, custom evaluators, limitations, and feedback. The [playground implementation](../../apps/web/lib/jev) uses these same APIs.
|
|
61
|
+
|
|
11
62
|
## Key Concepts
|
|
12
63
|
|
|
13
64
|
- **Schema**: Defines the structure of specs and catalogs
|
package/dist/index.d.mts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { S as StateModel, V as VisibilityCondition, a as StateCondition, A as AndCondition, O as OrCondition, D as DynamicValue, b as Spec, J as JsonPatch } from './store-utils-CGwRAVOR.mjs';
|
|
2
|
-
export { $ as Action, _ as ActionBinding, a7 as ActionBindingSchema, a0 as ActionConfirm, a9 as ActionConfirmSchema, a4 as ActionDefinition, a6 as ActionExecutionContext, a3 as ActionHandler, a2 as ActionOnError, ab as ActionOnErrorSchema, a1 as ActionOnSuccess, aa as ActionOnSuccessSchema, a8 as ActionSchema, C as ComponentSchema, e as DynamicBoolean, r as DynamicBooleanSchema, d as DynamicNumber, q as DynamicNumberSchema, c as DynamicString, p as DynamicStringSchema, o as DynamicValueSchema, F as FlatElement, f as IndexCondition, I as ItemCondition, M as MixedStreamCallbacks, l as MixedStreamParser, P as PatchOp, R as RepeatStatePath, a5 as ResolvedAction, W as SPEC_DATA_PART, X as SPEC_DATA_PART_TYPE, g as SingleCondition, n as SpecDataPart, k as SpecStreamCompiler, j as SpecStreamLine, h as StateStore, Y as StoreAdapterConfig, m as StreamChunk,
|
|
1
|
+
import { S as StateModel, V as VisibilityCondition, a as StateCondition, A as AndCondition, O as OrCondition, D as DynamicValue, b as Spec, J as JsonPatch, U as UIElement } from './store-utils-CGwRAVOR.mjs';
|
|
2
|
+
export { $ as Action, _ as ActionBinding, a7 as ActionBindingSchema, a0 as ActionConfirm, a9 as ActionConfirmSchema, a4 as ActionDefinition, a6 as ActionExecutionContext, a3 as ActionHandler, a2 as ActionOnError, ab as ActionOnErrorSchema, a1 as ActionOnSuccess, aa as ActionOnSuccessSchema, a8 as ActionSchema, C as ComponentSchema, e as DynamicBoolean, r as DynamicBooleanSchema, d as DynamicNumber, q as DynamicNumberSchema, c as DynamicString, p as DynamicStringSchema, o as DynamicValueSchema, F as FlatElement, f as IndexCondition, I as ItemCondition, M as MixedStreamCallbacks, l as MixedStreamParser, P as PatchOp, R as RepeatStatePath, a5 as ResolvedAction, W as SPEC_DATA_PART, X as SPEC_DATA_PART_TYPE, g as SingleCondition, n as SpecDataPart, k as SpecStreamCompiler, j as SpecStreamLine, h as StateStore, Y as StoreAdapterConfig, m as StreamChunk, i as ValidationMode, ag as action, af as actionBinding, x as addByPath, G as applySpecPatch, E as applySpecStreamPatch, K as compileSpecStream, Q as createJsonRenderTransform, N as createMixedStreamParser, L as createSpecStreamCompiler, Z as createStateStore, ad as executeAction, z as findFormValue, t as getByPath, ae as interpolateString, H as nestedToFlat, B as parseSpecStreamLine, T as pipeJsonRender, y as removeByPath, ac as resolveAction, s as resolveDynamicValue, v as resolveRepeatItemStatePath, u as resolveRepeatStatePath, w as setByPath } from './store-utils-CGwRAVOR.mjs';
|
|
3
3
|
import { z } from 'zod';
|
|
4
4
|
|
|
5
5
|
/**
|
|
@@ -958,4 +958,133 @@ declare function deepMergeSpec(base: Record<string, unknown>, patch: Record<stri
|
|
|
958
958
|
*/
|
|
959
959
|
declare function diffToPatches(oldObj: Record<string, unknown>, newObj: Record<string, unknown>, basePath?: string): JsonPatch[];
|
|
960
960
|
|
|
961
|
-
|
|
961
|
+
/** Experimental: may change in any release. A catalog using the flat Spec format. */
|
|
962
|
+
interface Experimental_CompositionCatalog {
|
|
963
|
+
data: {
|
|
964
|
+
components: Record<string, {
|
|
965
|
+
props: z.ZodType;
|
|
966
|
+
slots?: readonly string[];
|
|
967
|
+
events?: readonly string[];
|
|
968
|
+
}>;
|
|
969
|
+
actions?: Record<string, {
|
|
970
|
+
params?: z.ZodType;
|
|
971
|
+
}>;
|
|
972
|
+
};
|
|
973
|
+
schema?: {
|
|
974
|
+
builtInActions?: readonly {
|
|
975
|
+
name: string;
|
|
976
|
+
}[];
|
|
977
|
+
};
|
|
978
|
+
validate(spec: unknown): {
|
|
979
|
+
success: boolean;
|
|
980
|
+
};
|
|
981
|
+
}
|
|
982
|
+
/** One app-owned element recipe. The evaluator cannot modify its props or bindings. */
|
|
983
|
+
interface Experimental_CompositionCandidate {
|
|
984
|
+
id: string;
|
|
985
|
+
description: string;
|
|
986
|
+
element: Pick<UIElement, "type" | "props" | "on" | "visible">;
|
|
987
|
+
/** Whether this candidate can be the root. Defaults to true. */
|
|
988
|
+
root?: boolean;
|
|
989
|
+
/** Defaults to one. Reusable layout elements can opt into a larger count. */
|
|
990
|
+
maxUses?: number;
|
|
991
|
+
/** Candidates sharing a resource are mutually exclusive. */
|
|
992
|
+
resource?: string;
|
|
993
|
+
}
|
|
994
|
+
interface Experimental_ChoiceQuestion {
|
|
995
|
+
type: "choice";
|
|
996
|
+
instructions: string;
|
|
997
|
+
criteria: Record<string, string>;
|
|
998
|
+
}
|
|
999
|
+
interface Experimental_CompositionEvaluation {
|
|
1000
|
+
answers: Record<string, {
|
|
1001
|
+
choice: string;
|
|
1002
|
+
confidence?: number;
|
|
1003
|
+
}>;
|
|
1004
|
+
usage?: {
|
|
1005
|
+
inputTokens?: number;
|
|
1006
|
+
};
|
|
1007
|
+
}
|
|
1008
|
+
/** Custom adapters must return one of each question's offered criteria keys. */
|
|
1009
|
+
type Experimental_CompositionEvaluator = (request: {
|
|
1010
|
+
state: Record<string, unknown>;
|
|
1011
|
+
questions: Record<string, Experimental_ChoiceQuestion>;
|
|
1012
|
+
signal: AbortSignal;
|
|
1013
|
+
}) => Promise<Experimental_CompositionEvaluation>;
|
|
1014
|
+
interface Experimental_CompositionStep {
|
|
1015
|
+
index: number;
|
|
1016
|
+
choice: string;
|
|
1017
|
+
description: string;
|
|
1018
|
+
parent: string | null;
|
|
1019
|
+
slot: string | null;
|
|
1020
|
+
confidence: number | null;
|
|
1021
|
+
parentConfidence: number | null;
|
|
1022
|
+
elapsedMs: number;
|
|
1023
|
+
inputTokens: number | null;
|
|
1024
|
+
/** Independent answers from a batched selection or layout evaluation. */
|
|
1025
|
+
answers?: Experimental_CompositionEvaluation["answers"];
|
|
1026
|
+
}
|
|
1027
|
+
type Experimental_CompositionEvent = {
|
|
1028
|
+
type: "step";
|
|
1029
|
+
spec: Spec;
|
|
1030
|
+
step: Experimental_CompositionStep;
|
|
1031
|
+
} | {
|
|
1032
|
+
type: "complete";
|
|
1033
|
+
spec: Spec | null;
|
|
1034
|
+
steps: Experimental_CompositionStep[];
|
|
1035
|
+
elapsedMs: number;
|
|
1036
|
+
inputTokens: number | null;
|
|
1037
|
+
stopReason: "finish" | "limit" | "unavailable";
|
|
1038
|
+
};
|
|
1039
|
+
interface Experimental_ComposeSpecOptions {
|
|
1040
|
+
catalog: Experimental_CompositionCatalog;
|
|
1041
|
+
candidates: readonly Experimental_CompositionCandidate[];
|
|
1042
|
+
prompt: string;
|
|
1043
|
+
evaluate: Experimental_CompositionEvaluator;
|
|
1044
|
+
/** New trees use batched selection/layout by default. Edits remain sequential. */
|
|
1045
|
+
strategy?: "batch" | "sequential";
|
|
1046
|
+
/** Element budget for batched creation, including the root. Default: 32. */
|
|
1047
|
+
maxElements?: number;
|
|
1048
|
+
/** Edit an existing tree. Cloned and validated before evaluation. */
|
|
1049
|
+
initialSpec?: Spec;
|
|
1050
|
+
/** Descriptions explicitly shared for existing elements, keyed by element ID. */
|
|
1051
|
+
elementDescriptions?: Record<string, string>;
|
|
1052
|
+
/** Included in the spec, never sent to the evaluator. Overrides initialSpec.state. */
|
|
1053
|
+
initialState?: Record<string, unknown>;
|
|
1054
|
+
/** Additional app context explicitly shared with the evaluator. */
|
|
1055
|
+
context?: Record<string, unknown>;
|
|
1056
|
+
signal?: AbortSignal;
|
|
1057
|
+
/** Evaluation budget, including sequential terminal decisions. Default: 32. */
|
|
1058
|
+
maxSteps?: number;
|
|
1059
|
+
/** Root has depth one. Default: 8. */
|
|
1060
|
+
maxDepth?: number;
|
|
1061
|
+
/** App-specific guidance appended to the construction instructions. */
|
|
1062
|
+
instructions?: {
|
|
1063
|
+
root?: string;
|
|
1064
|
+
next?: string;
|
|
1065
|
+
parent?: string;
|
|
1066
|
+
};
|
|
1067
|
+
}
|
|
1068
|
+
/**
|
|
1069
|
+
* Experimental catalog-constrained composition. Streams detached Spec snapshots.
|
|
1070
|
+
* Throws on invalid configuration, evaluator output, provider errors, or abort.
|
|
1071
|
+
* Actions are copied into the spec; they are never executed by the composer.
|
|
1072
|
+
*/
|
|
1073
|
+
declare function experimental_composeSpec(options: Experimental_ComposeSpecOptions): AsyncGenerator<Experimental_CompositionEvent>;
|
|
1074
|
+
|
|
1075
|
+
interface Experimental_EvaluatorOptions {
|
|
1076
|
+
/** Server-side Vercel AI Gateway key. Never expose this in browser code. */
|
|
1077
|
+
apiKey: string;
|
|
1078
|
+
/** Gateway evaluation model identifier, for example typesafe-ai/jev. */
|
|
1079
|
+
model: string;
|
|
1080
|
+
/** Per-evaluation timeout in milliseconds. Default: 10000. */
|
|
1081
|
+
timeoutMs?: number;
|
|
1082
|
+
fetch?: typeof globalThis.fetch;
|
|
1083
|
+
}
|
|
1084
|
+
/**
|
|
1085
|
+
* Experimental server-side choice evaluator using Vercel AI Gateway's v4 evaluation
|
|
1086
|
+
* transport. No AI SDK provider constructor or additional dependency is needed.
|
|
1087
|
+
*/
|
|
1088
|
+
declare function experimental_createEvaluator(options: Experimental_EvaluatorOptions): Experimental_CompositionEvaluator;
|
|
1089
|
+
|
|
1090
|
+
export { type ActionDispatchInfo, type ActionObserver, type ActionSettleInfo, AndCondition, type BuildEditUserPromptOptions, type BuiltInAction, type Catalog, type ComputedFunction, type DirectiveDefinition, type DirectiveRegistry, DynamicValue, type EditConfig, type EditMode, type Experimental_ChoiceQuestion, type Experimental_ComposeSpecOptions, type Experimental_CompositionCandidate, type Experimental_CompositionCatalog, type Experimental_CompositionEvaluation, type Experimental_CompositionEvaluator, type Experimental_CompositionEvent, type Experimental_CompositionStep, type Experimental_EvaluatorOptions, type InferActionParams, type InferCatalogActions, type InferCatalogComponents, type InferCatalogInput, type InferComponentProps, type InferSpec, JsonPatch, type JsonSchemaOptions, OrCondition, type PromptContext, type PromptOptions, type PromptTemplate, type PropExpression, type PropResolutionContext, type RenderErrorHandler, type Schema, type SchemaBuilder, type SchemaDefinition, type SchemaOptions, type SchemaType, Spec, type SpecIssue, type SpecIssueSeverity, type SpecValidationIssues, type SpecValidationResult, StateCondition, StateModel, UIElement, type UserPromptOptions, type ValidateSpecOptions, type ValidationCheck, type ValidationCheckResult, ValidationCheckSchema, type ValidationConfig, ValidationConfigSchema, type ValidationContext, type ValidationFunction, type ValidationFunctionDefinition, type ValidationResult, VisibilityCondition, VisibilityConditionSchema, VisibilityConditionStrictSchema, type VisibilityContext, autoFixSpec, buildEditInstructions, buildEditUserPrompt, buildUserPrompt, builtInValidationFunctions, check, conditionUsesItemScope, createDirectiveRegistry, deepMergeSpec, defineCatalog, defineDirective, defineSchema, diffToPatches, evaluateVisibility, experimental_composeSpec, experimental_createEvaluator, findDirective, formatSpecIssues, isDevtoolsActive, isNonEmptySpec, markDevtoolsActive, nextActionDispatchId, notifyActionDispatch, notifyActionSettle, registerActionObserver, resolveActionParam, resolveBindings, resolveElementProps, resolvePropValue, runValidation, runValidationCheck, splitRepeatVisibility, subscribeDevtoolsActive, validateSpec, visibility };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { S as StateModel, V as VisibilityCondition, a as StateCondition, A as AndCondition, O as OrCondition, D as DynamicValue, b as Spec, J as JsonPatch } from './store-utils-CGwRAVOR.js';
|
|
2
|
-
export { $ as Action, _ as ActionBinding, a7 as ActionBindingSchema, a0 as ActionConfirm, a9 as ActionConfirmSchema, a4 as ActionDefinition, a6 as ActionExecutionContext, a3 as ActionHandler, a2 as ActionOnError, ab as ActionOnErrorSchema, a1 as ActionOnSuccess, aa as ActionOnSuccessSchema, a8 as ActionSchema, C as ComponentSchema, e as DynamicBoolean, r as DynamicBooleanSchema, d as DynamicNumber, q as DynamicNumberSchema, c as DynamicString, p as DynamicStringSchema, o as DynamicValueSchema, F as FlatElement, f as IndexCondition, I as ItemCondition, M as MixedStreamCallbacks, l as MixedStreamParser, P as PatchOp, R as RepeatStatePath, a5 as ResolvedAction, W as SPEC_DATA_PART, X as SPEC_DATA_PART_TYPE, g as SingleCondition, n as SpecDataPart, k as SpecStreamCompiler, j as SpecStreamLine, h as StateStore, Y as StoreAdapterConfig, m as StreamChunk,
|
|
1
|
+
import { S as StateModel, V as VisibilityCondition, a as StateCondition, A as AndCondition, O as OrCondition, D as DynamicValue, b as Spec, J as JsonPatch, U as UIElement } from './store-utils-CGwRAVOR.js';
|
|
2
|
+
export { $ as Action, _ as ActionBinding, a7 as ActionBindingSchema, a0 as ActionConfirm, a9 as ActionConfirmSchema, a4 as ActionDefinition, a6 as ActionExecutionContext, a3 as ActionHandler, a2 as ActionOnError, ab as ActionOnErrorSchema, a1 as ActionOnSuccess, aa as ActionOnSuccessSchema, a8 as ActionSchema, C as ComponentSchema, e as DynamicBoolean, r as DynamicBooleanSchema, d as DynamicNumber, q as DynamicNumberSchema, c as DynamicString, p as DynamicStringSchema, o as DynamicValueSchema, F as FlatElement, f as IndexCondition, I as ItemCondition, M as MixedStreamCallbacks, l as MixedStreamParser, P as PatchOp, R as RepeatStatePath, a5 as ResolvedAction, W as SPEC_DATA_PART, X as SPEC_DATA_PART_TYPE, g as SingleCondition, n as SpecDataPart, k as SpecStreamCompiler, j as SpecStreamLine, h as StateStore, Y as StoreAdapterConfig, m as StreamChunk, i as ValidationMode, ag as action, af as actionBinding, x as addByPath, G as applySpecPatch, E as applySpecStreamPatch, K as compileSpecStream, Q as createJsonRenderTransform, N as createMixedStreamParser, L as createSpecStreamCompiler, Z as createStateStore, ad as executeAction, z as findFormValue, t as getByPath, ae as interpolateString, H as nestedToFlat, B as parseSpecStreamLine, T as pipeJsonRender, y as removeByPath, ac as resolveAction, s as resolveDynamicValue, v as resolveRepeatItemStatePath, u as resolveRepeatStatePath, w as setByPath } from './store-utils-CGwRAVOR.js';
|
|
3
3
|
import { z } from 'zod';
|
|
4
4
|
|
|
5
5
|
/**
|
|
@@ -958,4 +958,133 @@ declare function deepMergeSpec(base: Record<string, unknown>, patch: Record<stri
|
|
|
958
958
|
*/
|
|
959
959
|
declare function diffToPatches(oldObj: Record<string, unknown>, newObj: Record<string, unknown>, basePath?: string): JsonPatch[];
|
|
960
960
|
|
|
961
|
-
|
|
961
|
+
/** Experimental: may change in any release. A catalog using the flat Spec format. */
|
|
962
|
+
interface Experimental_CompositionCatalog {
|
|
963
|
+
data: {
|
|
964
|
+
components: Record<string, {
|
|
965
|
+
props: z.ZodType;
|
|
966
|
+
slots?: readonly string[];
|
|
967
|
+
events?: readonly string[];
|
|
968
|
+
}>;
|
|
969
|
+
actions?: Record<string, {
|
|
970
|
+
params?: z.ZodType;
|
|
971
|
+
}>;
|
|
972
|
+
};
|
|
973
|
+
schema?: {
|
|
974
|
+
builtInActions?: readonly {
|
|
975
|
+
name: string;
|
|
976
|
+
}[];
|
|
977
|
+
};
|
|
978
|
+
validate(spec: unknown): {
|
|
979
|
+
success: boolean;
|
|
980
|
+
};
|
|
981
|
+
}
|
|
982
|
+
/** One app-owned element recipe. The evaluator cannot modify its props or bindings. */
|
|
983
|
+
interface Experimental_CompositionCandidate {
|
|
984
|
+
id: string;
|
|
985
|
+
description: string;
|
|
986
|
+
element: Pick<UIElement, "type" | "props" | "on" | "visible">;
|
|
987
|
+
/** Whether this candidate can be the root. Defaults to true. */
|
|
988
|
+
root?: boolean;
|
|
989
|
+
/** Defaults to one. Reusable layout elements can opt into a larger count. */
|
|
990
|
+
maxUses?: number;
|
|
991
|
+
/** Candidates sharing a resource are mutually exclusive. */
|
|
992
|
+
resource?: string;
|
|
993
|
+
}
|
|
994
|
+
interface Experimental_ChoiceQuestion {
|
|
995
|
+
type: "choice";
|
|
996
|
+
instructions: string;
|
|
997
|
+
criteria: Record<string, string>;
|
|
998
|
+
}
|
|
999
|
+
interface Experimental_CompositionEvaluation {
|
|
1000
|
+
answers: Record<string, {
|
|
1001
|
+
choice: string;
|
|
1002
|
+
confidence?: number;
|
|
1003
|
+
}>;
|
|
1004
|
+
usage?: {
|
|
1005
|
+
inputTokens?: number;
|
|
1006
|
+
};
|
|
1007
|
+
}
|
|
1008
|
+
/** Custom adapters must return one of each question's offered criteria keys. */
|
|
1009
|
+
type Experimental_CompositionEvaluator = (request: {
|
|
1010
|
+
state: Record<string, unknown>;
|
|
1011
|
+
questions: Record<string, Experimental_ChoiceQuestion>;
|
|
1012
|
+
signal: AbortSignal;
|
|
1013
|
+
}) => Promise<Experimental_CompositionEvaluation>;
|
|
1014
|
+
interface Experimental_CompositionStep {
|
|
1015
|
+
index: number;
|
|
1016
|
+
choice: string;
|
|
1017
|
+
description: string;
|
|
1018
|
+
parent: string | null;
|
|
1019
|
+
slot: string | null;
|
|
1020
|
+
confidence: number | null;
|
|
1021
|
+
parentConfidence: number | null;
|
|
1022
|
+
elapsedMs: number;
|
|
1023
|
+
inputTokens: number | null;
|
|
1024
|
+
/** Independent answers from a batched selection or layout evaluation. */
|
|
1025
|
+
answers?: Experimental_CompositionEvaluation["answers"];
|
|
1026
|
+
}
|
|
1027
|
+
type Experimental_CompositionEvent = {
|
|
1028
|
+
type: "step";
|
|
1029
|
+
spec: Spec;
|
|
1030
|
+
step: Experimental_CompositionStep;
|
|
1031
|
+
} | {
|
|
1032
|
+
type: "complete";
|
|
1033
|
+
spec: Spec | null;
|
|
1034
|
+
steps: Experimental_CompositionStep[];
|
|
1035
|
+
elapsedMs: number;
|
|
1036
|
+
inputTokens: number | null;
|
|
1037
|
+
stopReason: "finish" | "limit" | "unavailable";
|
|
1038
|
+
};
|
|
1039
|
+
interface Experimental_ComposeSpecOptions {
|
|
1040
|
+
catalog: Experimental_CompositionCatalog;
|
|
1041
|
+
candidates: readonly Experimental_CompositionCandidate[];
|
|
1042
|
+
prompt: string;
|
|
1043
|
+
evaluate: Experimental_CompositionEvaluator;
|
|
1044
|
+
/** New trees use batched selection/layout by default. Edits remain sequential. */
|
|
1045
|
+
strategy?: "batch" | "sequential";
|
|
1046
|
+
/** Element budget for batched creation, including the root. Default: 32. */
|
|
1047
|
+
maxElements?: number;
|
|
1048
|
+
/** Edit an existing tree. Cloned and validated before evaluation. */
|
|
1049
|
+
initialSpec?: Spec;
|
|
1050
|
+
/** Descriptions explicitly shared for existing elements, keyed by element ID. */
|
|
1051
|
+
elementDescriptions?: Record<string, string>;
|
|
1052
|
+
/** Included in the spec, never sent to the evaluator. Overrides initialSpec.state. */
|
|
1053
|
+
initialState?: Record<string, unknown>;
|
|
1054
|
+
/** Additional app context explicitly shared with the evaluator. */
|
|
1055
|
+
context?: Record<string, unknown>;
|
|
1056
|
+
signal?: AbortSignal;
|
|
1057
|
+
/** Evaluation budget, including sequential terminal decisions. Default: 32. */
|
|
1058
|
+
maxSteps?: number;
|
|
1059
|
+
/** Root has depth one. Default: 8. */
|
|
1060
|
+
maxDepth?: number;
|
|
1061
|
+
/** App-specific guidance appended to the construction instructions. */
|
|
1062
|
+
instructions?: {
|
|
1063
|
+
root?: string;
|
|
1064
|
+
next?: string;
|
|
1065
|
+
parent?: string;
|
|
1066
|
+
};
|
|
1067
|
+
}
|
|
1068
|
+
/**
|
|
1069
|
+
* Experimental catalog-constrained composition. Streams detached Spec snapshots.
|
|
1070
|
+
* Throws on invalid configuration, evaluator output, provider errors, or abort.
|
|
1071
|
+
* Actions are copied into the spec; they are never executed by the composer.
|
|
1072
|
+
*/
|
|
1073
|
+
declare function experimental_composeSpec(options: Experimental_ComposeSpecOptions): AsyncGenerator<Experimental_CompositionEvent>;
|
|
1074
|
+
|
|
1075
|
+
interface Experimental_EvaluatorOptions {
|
|
1076
|
+
/** Server-side Vercel AI Gateway key. Never expose this in browser code. */
|
|
1077
|
+
apiKey: string;
|
|
1078
|
+
/** Gateway evaluation model identifier, for example typesafe-ai/jev. */
|
|
1079
|
+
model: string;
|
|
1080
|
+
/** Per-evaluation timeout in milliseconds. Default: 10000. */
|
|
1081
|
+
timeoutMs?: number;
|
|
1082
|
+
fetch?: typeof globalThis.fetch;
|
|
1083
|
+
}
|
|
1084
|
+
/**
|
|
1085
|
+
* Experimental server-side choice evaluator using Vercel AI Gateway's v4 evaluation
|
|
1086
|
+
* transport. No AI SDK provider constructor or additional dependency is needed.
|
|
1087
|
+
*/
|
|
1088
|
+
declare function experimental_createEvaluator(options: Experimental_EvaluatorOptions): Experimental_CompositionEvaluator;
|
|
1089
|
+
|
|
1090
|
+
export { type ActionDispatchInfo, type ActionObserver, type ActionSettleInfo, AndCondition, type BuildEditUserPromptOptions, type BuiltInAction, type Catalog, type ComputedFunction, type DirectiveDefinition, type DirectiveRegistry, DynamicValue, type EditConfig, type EditMode, type Experimental_ChoiceQuestion, type Experimental_ComposeSpecOptions, type Experimental_CompositionCandidate, type Experimental_CompositionCatalog, type Experimental_CompositionEvaluation, type Experimental_CompositionEvaluator, type Experimental_CompositionEvent, type Experimental_CompositionStep, type Experimental_EvaluatorOptions, type InferActionParams, type InferCatalogActions, type InferCatalogComponents, type InferCatalogInput, type InferComponentProps, type InferSpec, JsonPatch, type JsonSchemaOptions, OrCondition, type PromptContext, type PromptOptions, type PromptTemplate, type PropExpression, type PropResolutionContext, type RenderErrorHandler, type Schema, type SchemaBuilder, type SchemaDefinition, type SchemaOptions, type SchemaType, Spec, type SpecIssue, type SpecIssueSeverity, type SpecValidationIssues, type SpecValidationResult, StateCondition, StateModel, UIElement, type UserPromptOptions, type ValidateSpecOptions, type ValidationCheck, type ValidationCheckResult, ValidationCheckSchema, type ValidationConfig, ValidationConfigSchema, type ValidationContext, type ValidationFunction, type ValidationFunctionDefinition, type ValidationResult, VisibilityCondition, VisibilityConditionSchema, VisibilityConditionStrictSchema, type VisibilityContext, autoFixSpec, buildEditInstructions, buildEditUserPrompt, buildUserPrompt, builtInValidationFunctions, check, conditionUsesItemScope, createDirectiveRegistry, deepMergeSpec, defineCatalog, defineDirective, defineSchema, diffToPatches, evaluateVisibility, experimental_composeSpec, experimental_createEvaluator, findDirective, formatSpecIssues, isDevtoolsActive, isNonEmptySpec, markDevtoolsActive, nextActionDispatchId, notifyActionDispatch, notifyActionSettle, registerActionObserver, resolveActionParam, resolveBindings, resolveElementProps, resolvePropValue, runValidation, runValidationCheck, splitRepeatVisibility, subscribeDevtoolsActive, validateSpec, visibility };
|