@json-render/core 0.4.4 → 0.5.0

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/dist/index.d.ts CHANGED
@@ -1,7 +1,225 @@
1
1
  import { z } from 'zod';
2
2
 
3
3
  /**
4
- * Dynamic value - can be a literal or a path reference to data model
4
+ * Confirmation dialog configuration
5
+ */
6
+ interface ActionConfirm {
7
+ title: string;
8
+ message: string;
9
+ confirmLabel?: string;
10
+ cancelLabel?: string;
11
+ variant?: "default" | "danger";
12
+ }
13
+ /**
14
+ * Action success handler
15
+ */
16
+ type ActionOnSuccess = {
17
+ navigate: string;
18
+ } | {
19
+ set: Record<string, unknown>;
20
+ } | {
21
+ action: string;
22
+ };
23
+ /**
24
+ * Action error handler
25
+ */
26
+ type ActionOnError = {
27
+ set: Record<string, unknown>;
28
+ } | {
29
+ action: string;
30
+ };
31
+ /**
32
+ * Action binding — maps an event to an action invocation.
33
+ *
34
+ * Used inside the `on` field of a UIElement:
35
+ * ```json
36
+ * { "on": { "press": { "action": "setState", "params": { "path": "/x", "value": 1 } } } }
37
+ * ```
38
+ */
39
+ interface ActionBinding {
40
+ /** Action name (must be in catalog) */
41
+ action: string;
42
+ /** Parameters to pass to the action handler */
43
+ params?: Record<string, DynamicValue>;
44
+ /** Confirmation dialog before execution */
45
+ confirm?: ActionConfirm;
46
+ /** Handler after successful execution */
47
+ onSuccess?: ActionOnSuccess;
48
+ /** Handler after failed execution */
49
+ onError?: ActionOnError;
50
+ }
51
+ /**
52
+ * @deprecated Use ActionBinding instead
53
+ */
54
+ type Action = ActionBinding;
55
+ /**
56
+ * Schema for action confirmation
57
+ */
58
+ declare const ActionConfirmSchema: z.ZodObject<{
59
+ title: z.ZodString;
60
+ message: z.ZodString;
61
+ confirmLabel: z.ZodOptional<z.ZodString>;
62
+ cancelLabel: z.ZodOptional<z.ZodString>;
63
+ variant: z.ZodOptional<z.ZodEnum<{
64
+ default: "default";
65
+ danger: "danger";
66
+ }>>;
67
+ }, z.core.$strip>;
68
+ /**
69
+ * Schema for success handlers
70
+ */
71
+ declare const ActionOnSuccessSchema: z.ZodUnion<readonly [z.ZodObject<{
72
+ navigate: z.ZodString;
73
+ }, z.core.$strip>, z.ZodObject<{
74
+ set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
75
+ }, z.core.$strip>, z.ZodObject<{
76
+ action: z.ZodString;
77
+ }, z.core.$strip>]>;
78
+ /**
79
+ * Schema for error handlers
80
+ */
81
+ declare const ActionOnErrorSchema: z.ZodUnion<readonly [z.ZodObject<{
82
+ set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
83
+ }, z.core.$strip>, z.ZodObject<{
84
+ action: z.ZodString;
85
+ }, z.core.$strip>]>;
86
+ /**
87
+ * Full action binding schema
88
+ */
89
+ declare const ActionBindingSchema: z.ZodObject<{
90
+ action: z.ZodString;
91
+ params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodObject<{
92
+ path: z.ZodString;
93
+ }, z.core.$strip>]>>>;
94
+ confirm: z.ZodOptional<z.ZodObject<{
95
+ title: z.ZodString;
96
+ message: z.ZodString;
97
+ confirmLabel: z.ZodOptional<z.ZodString>;
98
+ cancelLabel: z.ZodOptional<z.ZodString>;
99
+ variant: z.ZodOptional<z.ZodEnum<{
100
+ default: "default";
101
+ danger: "danger";
102
+ }>>;
103
+ }, z.core.$strip>>;
104
+ onSuccess: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
105
+ navigate: z.ZodString;
106
+ }, z.core.$strip>, z.ZodObject<{
107
+ set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
108
+ }, z.core.$strip>, z.ZodObject<{
109
+ action: z.ZodString;
110
+ }, z.core.$strip>]>>;
111
+ onError: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
112
+ set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
113
+ }, z.core.$strip>, z.ZodObject<{
114
+ action: z.ZodString;
115
+ }, z.core.$strip>]>>;
116
+ }, z.core.$strip>;
117
+ /**
118
+ * @deprecated Use ActionBindingSchema instead
119
+ */
120
+ declare const ActionSchema: z.ZodObject<{
121
+ action: z.ZodString;
122
+ params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodObject<{
123
+ path: z.ZodString;
124
+ }, z.core.$strip>]>>>;
125
+ confirm: z.ZodOptional<z.ZodObject<{
126
+ title: z.ZodString;
127
+ message: z.ZodString;
128
+ confirmLabel: z.ZodOptional<z.ZodString>;
129
+ cancelLabel: z.ZodOptional<z.ZodString>;
130
+ variant: z.ZodOptional<z.ZodEnum<{
131
+ default: "default";
132
+ danger: "danger";
133
+ }>>;
134
+ }, z.core.$strip>>;
135
+ onSuccess: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
136
+ navigate: z.ZodString;
137
+ }, z.core.$strip>, z.ZodObject<{
138
+ set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
139
+ }, z.core.$strip>, z.ZodObject<{
140
+ action: z.ZodString;
141
+ }, z.core.$strip>]>>;
142
+ onError: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
143
+ set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
144
+ }, z.core.$strip>, z.ZodObject<{
145
+ action: z.ZodString;
146
+ }, z.core.$strip>]>>;
147
+ }, z.core.$strip>;
148
+ /**
149
+ * Action handler function signature
150
+ */
151
+ type ActionHandler<TParams = Record<string, unknown>, TResult = unknown> = (params: TParams) => Promise<TResult> | TResult;
152
+ /**
153
+ * Action definition in catalog
154
+ */
155
+ interface ActionDefinition<TParams = Record<string, unknown>> {
156
+ /** Zod schema for params validation */
157
+ params?: z.ZodType<TParams>;
158
+ /** Description for AI */
159
+ description?: string;
160
+ }
161
+ /**
162
+ * Resolved action with all dynamic values resolved
163
+ */
164
+ interface ResolvedAction {
165
+ action: string;
166
+ params: Record<string, unknown>;
167
+ confirm?: ActionConfirm;
168
+ onSuccess?: ActionOnSuccess;
169
+ onError?: ActionOnError;
170
+ }
171
+ /**
172
+ * Resolve all dynamic values in an action binding
173
+ */
174
+ declare function resolveAction(binding: ActionBinding, stateModel: StateModel): ResolvedAction;
175
+ /**
176
+ * Interpolate ${path} expressions in a string
177
+ */
178
+ declare function interpolateString(template: string, stateModel: StateModel): string;
179
+ /**
180
+ * Context for action execution
181
+ */
182
+ interface ActionExecutionContext {
183
+ /** The resolved action */
184
+ action: ResolvedAction;
185
+ /** The action handler from the host */
186
+ handler: ActionHandler;
187
+ /** Function to update state model */
188
+ setState: (path: string, value: unknown) => void;
189
+ /** Function to navigate */
190
+ navigate?: (path: string) => void;
191
+ /** Function to execute another action */
192
+ executeAction?: (name: string) => Promise<void>;
193
+ }
194
+ /**
195
+ * Execute an action with all callbacks
196
+ */
197
+ declare function executeAction(ctx: ActionExecutionContext): Promise<void>;
198
+ /**
199
+ * Helper to create action bindings
200
+ */
201
+ declare const actionBinding: {
202
+ /** Create a simple action binding */
203
+ simple: (actionName: string, params?: Record<string, DynamicValue>) => ActionBinding;
204
+ /** Create an action binding with confirmation */
205
+ withConfirm: (actionName: string, confirm: ActionConfirm, params?: Record<string, DynamicValue>) => ActionBinding;
206
+ /** Create an action binding with success handler */
207
+ withSuccess: (actionName: string, onSuccess: ActionOnSuccess, params?: Record<string, DynamicValue>) => ActionBinding;
208
+ };
209
+ /**
210
+ * @deprecated Use actionBinding instead
211
+ */
212
+ declare const action: {
213
+ /** Create a simple action binding */
214
+ simple: (actionName: string, params?: Record<string, DynamicValue>) => ActionBinding;
215
+ /** Create an action binding with confirmation */
216
+ withConfirm: (actionName: string, confirm: ActionConfirm, params?: Record<string, DynamicValue>) => ActionBinding;
217
+ /** Create an action binding with success handler */
218
+ withSuccess: (actionName: string, onSuccess: ActionOnSuccess, params?: Record<string, DynamicValue>) => ActionBinding;
219
+ };
220
+
221
+ /**
222
+ * Dynamic value - can be a literal or a path reference to state model
5
223
  */
6
224
  type DynamicValue<T = unknown> = T | {
7
225
  path: string;
@@ -45,6 +263,13 @@ interface UIElement<T extends string = string, P = Record<string, unknown>> {
45
263
  children?: string[];
46
264
  /** Visibility condition */
47
265
  visible?: VisibilityCondition;
266
+ /** Event bindings — maps event names to action bindings */
267
+ on?: Record<string, ActionBinding | ActionBinding[]>;
268
+ /** Repeat children once per item in a state array */
269
+ repeat?: {
270
+ path: string;
271
+ key?: string;
272
+ };
48
273
  }
49
274
  /**
50
275
  * Element with key and parentKey for use with flatToTree.
@@ -97,6 +322,9 @@ interface Spec {
97
322
  root: string;
98
323
  /** Flat map of elements by key */
99
324
  elements: Record<string, UIElement>;
325
+ /** Optional initial state to seed the state model.
326
+ * Components using statePath will read from / write to this state. */
327
+ state?: Record<string, unknown>;
100
328
  }
101
329
  /**
102
330
  * Auth state for visibility evaluation
@@ -106,9 +334,9 @@ interface AuthState {
106
334
  user?: Record<string, unknown>;
107
335
  }
108
336
  /**
109
- * Data model type
337
+ * State model type
110
338
  */
111
- type DataModel = Record<string, unknown>;
339
+ type StateModel = Record<string, unknown>;
112
340
  /**
113
341
  * Component schema definition using Zod
114
342
  */
@@ -133,9 +361,9 @@ interface JsonPatch {
133
361
  from?: string;
134
362
  }
135
363
  /**
136
- * Resolve a dynamic value against a data model
364
+ * Resolve a dynamic value against a state model
137
365
  */
138
- declare function resolveDynamicValue<T>(value: DynamicValue<T>, dataModel: DataModel): T | undefined;
366
+ declare function resolveDynamicValue<T>(value: DynamicValue<T>, stateModel: StateModel): T | undefined;
139
367
  /**
140
368
  * Get a value from an object by JSON Pointer path (RFC 6901)
141
369
  */
@@ -271,7 +499,7 @@ declare const VisibilityConditionSchema: z.ZodType<VisibilityCondition>;
271
499
  * Context for evaluating visibility
272
500
  */
273
501
  interface VisibilityContext {
274
- dataModel: DataModel;
502
+ stateModel: StateModel;
275
503
  authState?: AuthState;
276
504
  }
277
505
  /**
@@ -321,171 +549,29 @@ declare const visibility: {
321
549
  };
322
550
 
323
551
  /**
324
- * Confirmation dialog configuration
325
- */
326
- interface ActionConfirm {
327
- title: string;
328
- message: string;
329
- confirmLabel?: string;
330
- cancelLabel?: string;
331
- variant?: "default" | "danger";
332
- }
333
- /**
334
- * Action success handler
335
- */
336
- type ActionOnSuccess = {
337
- navigate: string;
338
- } | {
339
- set: Record<string, unknown>;
340
- } | {
341
- action: string;
342
- };
343
- /**
344
- * Action error handler
552
+ * A prop expression that resolves to a value based on state.
553
+ *
554
+ * - `{ $path: string }` reads a value from the state model
555
+ * - `{ $cond, $then, $else }` conditionally picks a value
556
+ * - Any other value is a literal (passthrough)
345
557
  */
346
- type ActionOnError = {
347
- set: Record<string, unknown>;
558
+ type PropExpression<T = unknown> = T | {
559
+ $path: string;
348
560
  } | {
349
- action: string;
561
+ $cond: VisibilityCondition;
562
+ $then: PropExpression<T>;
563
+ $else: PropExpression<T>;
350
564
  };
351
565
  /**
352
- * Rich action definition
353
- */
354
- interface Action {
355
- /** Action name (must be in catalog) */
356
- name: string;
357
- /** Parameters to pass to the action handler */
358
- params?: Record<string, DynamicValue>;
359
- /** Confirmation dialog before execution */
360
- confirm?: ActionConfirm;
361
- /** Handler after successful execution */
362
- onSuccess?: ActionOnSuccess;
363
- /** Handler after failed execution */
364
- onError?: ActionOnError;
365
- }
366
- /**
367
- * Schema for action confirmation
368
- */
369
- declare const ActionConfirmSchema: z.ZodObject<{
370
- title: z.ZodString;
371
- message: z.ZodString;
372
- confirmLabel: z.ZodOptional<z.ZodString>;
373
- cancelLabel: z.ZodOptional<z.ZodString>;
374
- variant: z.ZodOptional<z.ZodEnum<{
375
- default: "default";
376
- danger: "danger";
377
- }>>;
378
- }, z.core.$strip>;
379
- /**
380
- * Schema for success handlers
566
+ * Resolve a single prop value that may contain expressions.
567
+ * Recursively resolves $path and $cond/$then/$else expressions.
381
568
  */
382
- declare const ActionOnSuccessSchema: z.ZodUnion<readonly [z.ZodObject<{
383
- navigate: z.ZodString;
384
- }, z.core.$strip>, z.ZodObject<{
385
- set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
386
- }, z.core.$strip>, z.ZodObject<{
387
- action: z.ZodString;
388
- }, z.core.$strip>]>;
389
- /**
390
- * Schema for error handlers
391
- */
392
- declare const ActionOnErrorSchema: z.ZodUnion<readonly [z.ZodObject<{
393
- set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
394
- }, z.core.$strip>, z.ZodObject<{
395
- action: z.ZodString;
396
- }, z.core.$strip>]>;
569
+ declare function resolvePropValue(value: unknown, ctx: VisibilityContext): unknown;
397
570
  /**
398
- * Full action schema
571
+ * Resolve all prop values in an element's props object.
572
+ * Returns a new props object with all expressions resolved.
399
573
  */
400
- declare const ActionSchema: z.ZodObject<{
401
- name: z.ZodString;
402
- params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodObject<{
403
- path: z.ZodString;
404
- }, z.core.$strip>]>>>;
405
- confirm: z.ZodOptional<z.ZodObject<{
406
- title: z.ZodString;
407
- message: z.ZodString;
408
- confirmLabel: z.ZodOptional<z.ZodString>;
409
- cancelLabel: z.ZodOptional<z.ZodString>;
410
- variant: z.ZodOptional<z.ZodEnum<{
411
- default: "default";
412
- danger: "danger";
413
- }>>;
414
- }, z.core.$strip>>;
415
- onSuccess: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
416
- navigate: z.ZodString;
417
- }, z.core.$strip>, z.ZodObject<{
418
- set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
419
- }, z.core.$strip>, z.ZodObject<{
420
- action: z.ZodString;
421
- }, z.core.$strip>]>>;
422
- onError: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
423
- set: z.ZodRecord<z.ZodString, z.ZodUnknown>;
424
- }, z.core.$strip>, z.ZodObject<{
425
- action: z.ZodString;
426
- }, z.core.$strip>]>>;
427
- }, z.core.$strip>;
428
- /**
429
- * Action handler function signature
430
- */
431
- type ActionHandler<TParams = Record<string, unknown>, TResult = unknown> = (params: TParams) => Promise<TResult> | TResult;
432
- /**
433
- * Action definition in catalog
434
- */
435
- interface ActionDefinition<TParams = Record<string, unknown>> {
436
- /** Zod schema for params validation */
437
- params?: z.ZodType<TParams>;
438
- /** Description for AI */
439
- description?: string;
440
- }
441
- /**
442
- * Resolved action with all dynamic values resolved
443
- */
444
- interface ResolvedAction {
445
- name: string;
446
- params: Record<string, unknown>;
447
- confirm?: ActionConfirm;
448
- onSuccess?: ActionOnSuccess;
449
- onError?: ActionOnError;
450
- }
451
- /**
452
- * Resolve all dynamic values in an action
453
- */
454
- declare function resolveAction(action: Action, dataModel: DataModel): ResolvedAction;
455
- /**
456
- * Interpolate ${path} expressions in a string
457
- */
458
- declare function interpolateString(template: string, dataModel: DataModel): string;
459
- /**
460
- * Context for action execution
461
- */
462
- interface ActionExecutionContext {
463
- /** The resolved action */
464
- action: ResolvedAction;
465
- /** The action handler from the host */
466
- handler: ActionHandler;
467
- /** Function to update data model */
468
- setData: (path: string, value: unknown) => void;
469
- /** Function to navigate */
470
- navigate?: (path: string) => void;
471
- /** Function to execute another action */
472
- executeAction?: (name: string) => Promise<void>;
473
- }
474
- /**
475
- * Execute an action with all callbacks
476
- */
477
- declare function executeAction(ctx: ActionExecutionContext): Promise<void>;
478
- /**
479
- * Helper to create actions
480
- */
481
- declare const action: {
482
- /** Create a simple action */
483
- simple: (name: string, params?: Record<string, DynamicValue>) => Action;
484
- /** Create an action with confirmation */
485
- withConfirm: (name: string, confirm: ActionConfirm, params?: Record<string, DynamicValue>) => Action;
486
- /** Create an action with success handler */
487
- withSuccess: (name: string, onSuccess: ActionOnSuccess, params?: Record<string, DynamicValue>) => Action;
488
- };
574
+ declare function resolveElementProps(props: Record<string, unknown>, ctx: VisibilityContext): Record<string, unknown>;
489
575
 
490
576
  /**
491
577
  * Validation check definition
@@ -577,7 +663,7 @@ interface ValidationContext {
577
663
  /** Current value to validate */
578
664
  value: unknown;
579
665
  /** Full data model for resolving paths */
580
- dataModel: DataModel;
666
+ stateModel: StateModel;
581
667
  /** Custom validation functions from catalog */
582
668
  customFunctions?: Record<string, ValidationFunction>;
583
669
  }
@@ -608,6 +694,81 @@ declare const check: {
608
694
  matches: (otherPath: string, message?: string) => ValidationCheck;
609
695
  };
610
696
 
697
+ /**
698
+ * Severity level for validation issues.
699
+ */
700
+ type SpecIssueSeverity = "error" | "warning";
701
+ /**
702
+ * A single validation issue found in a spec.
703
+ */
704
+ interface SpecIssue {
705
+ /** Severity: errors should be fixed, warnings are informational */
706
+ severity: SpecIssueSeverity;
707
+ /** Human-readable description of the issue */
708
+ message: string;
709
+ /** The element key where the issue was found (if applicable) */
710
+ elementKey?: string;
711
+ /** Machine-readable issue code for programmatic handling */
712
+ code: "missing_root" | "root_not_found" | "missing_child" | "visible_in_props" | "orphaned_element" | "empty_spec" | "on_in_props" | "repeat_in_props";
713
+ }
714
+ /**
715
+ * Result of spec structural validation.
716
+ */
717
+ interface SpecValidationIssues {
718
+ /** Whether the spec passed validation (no errors; warnings are OK) */
719
+ valid: boolean;
720
+ /** List of issues found */
721
+ issues: SpecIssue[];
722
+ }
723
+ /**
724
+ * Options for validateSpec.
725
+ */
726
+ interface ValidateSpecOptions {
727
+ /**
728
+ * Whether to check for orphaned elements (elements not reachable from root).
729
+ * Defaults to false since orphans are harmless (just unused).
730
+ */
731
+ checkOrphans?: boolean;
732
+ }
733
+ /**
734
+ * Validate a spec for structural integrity.
735
+ *
736
+ * Checks for common AI-generation errors:
737
+ * - Missing or empty root
738
+ * - Root element not found in elements map
739
+ * - Children referencing non-existent elements
740
+ * - `visible` placed inside `props` instead of on the element
741
+ * - Orphaned elements (optional)
742
+ *
743
+ * @example
744
+ * ```ts
745
+ * const result = validateSpec(spec);
746
+ * if (!result.valid) {
747
+ * console.log("Spec errors:", result.issues);
748
+ * }
749
+ * ```
750
+ */
751
+ declare function validateSpec(spec: Spec, options?: ValidateSpecOptions): SpecValidationIssues;
752
+ /**
753
+ * Auto-fix common spec issues in-place and return a corrected copy.
754
+ *
755
+ * Currently fixes:
756
+ * - `visible` inside `props` → moved to element level
757
+ * - `on` inside `props` → moved to element level
758
+ * - `repeat` inside `props` → moved to element level
759
+ *
760
+ * Returns the fixed spec and a list of fixes applied.
761
+ */
762
+ declare function autoFixSpec(spec: Spec): {
763
+ spec: Spec;
764
+ fixes: string[];
765
+ };
766
+ /**
767
+ * Format validation issues into a human-readable string suitable for
768
+ * inclusion in a repair prompt sent back to the AI.
769
+ */
770
+ declare function formatSpecIssues(issues: SpecIssue[]): string;
771
+
611
772
  /**
612
773
  * Schema builder primitives
613
774
  */
@@ -664,6 +825,8 @@ interface Schema<TDef extends SchemaDefinition = SchemaDefinition> {
664
825
  readonly definition: TDef;
665
826
  /** Custom prompt template for this schema */
666
827
  readonly promptTemplate?: PromptTemplate;
828
+ /** Default rules baked into the schema (injected before customRules) */
829
+ readonly defaultRules?: string[];
667
830
  /** Create a catalog from this schema */
668
831
  createCatalog<TCatalog extends InferCatalogInput<TDef["catalog"]>>(catalog: TCatalog): Catalog$1<TDef, TCatalog>;
669
832
  }
@@ -724,6 +887,8 @@ type PromptTemplate<TCatalog = unknown> = (context: PromptContext<TCatalog>) =>
724
887
  interface SchemaOptions<TCatalog = unknown> {
725
888
  /** Custom prompt template for this schema */
726
889
  promptTemplate?: PromptTemplate<TCatalog>;
890
+ /** Default rules baked into the schema (injected before customRules in prompts) */
891
+ defaultRules?: string[];
727
892
  }
728
893
  /**
729
894
  * Spec validation result
@@ -802,6 +967,41 @@ declare function defineSchema<TDef extends SchemaDefinition>(builder: (s: Schema
802
967
  */
803
968
  declare function defineCatalog<TDef extends SchemaDefinition, TCatalog extends InferCatalogInput<TDef["catalog"]>>(schema: Schema<TDef>, catalog: TCatalog): Catalog$1<TDef, TCatalog>;
804
969
 
970
+ /**
971
+ * Options for building a user prompt.
972
+ */
973
+ interface UserPromptOptions {
974
+ /** The user's text prompt */
975
+ prompt: string;
976
+ /** Existing spec to refine (triggers patch-only mode) */
977
+ currentSpec?: Spec | null;
978
+ /** Runtime state context to include */
979
+ state?: Record<string, unknown> | null;
980
+ /** Maximum length for the user's text prompt (applied before wrapping) */
981
+ maxPromptLength?: number;
982
+ }
983
+ /**
984
+ * Build a user prompt for AI generation.
985
+ *
986
+ * Handles common patterns that every consuming app needs:
987
+ * - Truncating the user's prompt to a max length
988
+ * - Including the current spec for refinement (patch-only mode)
989
+ * - Including runtime state context
990
+ *
991
+ * @example
992
+ * ```ts
993
+ * // Fresh generation
994
+ * buildUserPrompt({ prompt: "create a todo app" })
995
+ *
996
+ * // Refinement with existing spec
997
+ * buildUserPrompt({ prompt: "add a dark mode toggle", currentSpec: spec })
998
+ *
999
+ * // With state context
1000
+ * buildUserPrompt({ prompt: "show my data", state: { todos: [] } })
1001
+ * ```
1002
+ */
1003
+ declare function buildUserPrompt(options: UserPromptOptions): string;
1004
+
805
1005
  /**
806
1006
  * Component definition with visibility and validation support
807
1007
  */
@@ -900,4 +1100,4 @@ interface SystemPromptOptions {
900
1100
  */
901
1101
  declare function generateSystemPrompt<TComponents extends Record<string, ComponentDefinition>, TActions extends Record<string, ActionDefinition>, TFunctions extends Record<string, ValidationFunction>>(catalog: Catalog<TComponents, TActions, TFunctions>, options?: SystemPromptOptions): string;
902
1102
 
903
- export { type Action, type ActionConfirm, ActionConfirmSchema, type ActionDefinition, type ActionExecutionContext, type ActionHandler, type ActionOnError, ActionOnErrorSchema, type ActionOnSuccess, ActionOnSuccessSchema, ActionSchema, type AuthState, type Catalog$1 as Catalog, type CatalogConfig, type ComponentDefinition, type ComponentSchema, type DataModel, type DynamicBoolean, DynamicBooleanSchema, type DynamicNumber, DynamicNumberSchema, type DynamicString, DynamicStringSchema, type DynamicValue, DynamicValueSchema, type FlatElement, type InferActionParams, type InferCatalogActions, type InferCatalogComponentProps, type InferCatalogComponents, type InferCatalogInput, type InferComponentProps, type InferSpec, type JsonPatch, type Catalog as LegacyCatalog, type LogicExpression, LogicExpressionSchema, type PatchOp, type PromptContext, type PromptOptions, type PromptTemplate, type ResolvedAction, type Schema, type SchemaBuilder, type SchemaDefinition, type SchemaOptions, type SchemaType, type Spec, type SpecStreamCompiler, type SpecStreamLine, type SpecValidationResult, type SystemPromptOptions, type UIElement, type ValidationCheck, type ValidationCheckResult, ValidationCheckSchema, type ValidationConfig, ValidationConfigSchema, type ValidationContext, type ValidationFunction, type ValidationFunctionDefinition, type ValidationMode, type ValidationResult, type VisibilityCondition, VisibilityConditionSchema, type VisibilityContext, action, addByPath, applySpecStreamPatch, builtInValidationFunctions, check, compileSpecStream, createCatalog, createSpecStreamCompiler, defineCatalog, defineSchema, evaluateLogicExpression, evaluateVisibility, executeAction, findFormValue, generateCatalogPrompt, generateSystemPrompt, getByPath, interpolateString, parseSpecStreamLine, removeByPath, resolveAction, resolveDynamicValue, runValidation, runValidationCheck, setByPath, visibility };
1103
+ export { type Action, type ActionBinding, ActionBindingSchema, type ActionConfirm, ActionConfirmSchema, type ActionDefinition, type ActionExecutionContext, type ActionHandler, type ActionOnError, ActionOnErrorSchema, type ActionOnSuccess, ActionOnSuccessSchema, ActionSchema, type AuthState, type Catalog$1 as Catalog, type CatalogConfig, type ComponentDefinition, type ComponentSchema, type DynamicBoolean, DynamicBooleanSchema, type DynamicNumber, DynamicNumberSchema, type DynamicString, DynamicStringSchema, type DynamicValue, DynamicValueSchema, type FlatElement, type InferActionParams, type InferCatalogActions, type InferCatalogComponentProps, type InferCatalogComponents, type InferCatalogInput, type InferComponentProps, type InferSpec, type JsonPatch, type Catalog as LegacyCatalog, type LogicExpression, LogicExpressionSchema, type PatchOp, type PromptContext, type PromptOptions, type PromptTemplate, type PropExpression, type ResolvedAction, type Schema, type SchemaBuilder, type SchemaDefinition, type SchemaOptions, type SchemaType, type Spec, type SpecIssue, type SpecIssueSeverity, type SpecStreamCompiler, type SpecStreamLine, type SpecValidationIssues, type SpecValidationResult, type StateModel, type SystemPromptOptions, type UIElement, type UserPromptOptions, type ValidateSpecOptions, type ValidationCheck, type ValidationCheckResult, ValidationCheckSchema, type ValidationConfig, ValidationConfigSchema, type ValidationContext, type ValidationFunction, type ValidationFunctionDefinition, type ValidationMode, type ValidationResult, type VisibilityCondition, VisibilityConditionSchema, type VisibilityContext, action, actionBinding, addByPath, applySpecStreamPatch, autoFixSpec, buildUserPrompt, builtInValidationFunctions, check, compileSpecStream, createCatalog, createSpecStreamCompiler, defineCatalog, defineSchema, evaluateLogicExpression, evaluateVisibility, executeAction, findFormValue, formatSpecIssues, generateCatalogPrompt, generateSystemPrompt, getByPath, interpolateString, parseSpecStreamLine, removeByPath, resolveAction, resolveDynamicValue, resolveElementProps, resolvePropValue, runValidation, runValidationCheck, setByPath, validateSpec, visibility };