@json-render/core 0.6.1 → 0.8.0

package/README.md

@@ -157,6 +157,14 @@ const spec = compileSpecStream<MySpec>(jsonlString);
 | `defineSchema(builder, options?)` | Create a schema with spec/catalog structure |
 | `SchemaBuilder` | Builder with `s.object()`, `s.array()`, `s.map()`, etc. |
 
+Schema options:
+
+| Option | Purpose |
+|--------|---------|
+| `promptTemplate` | Custom AI prompt generator |
+| `defaultRules` | Default rules injected before custom rules in prompts |
+| `builtInActions` | Actions always available at runtime, auto-injected into prompts (e.g. `setState`) |
+
 ### Catalog
 
 | Export | Purpose |
@@ -196,12 +204,30 @@ const spec = compileSpecStream<MySpec>(jsonlString);
 | `autoFixSpec(spec)` | Auto-fix common spec issues (returns corrected copy) |
 | `formatSpecIssues(issues)` | Format validation issues as readable strings |
 
+### Actions
+
+| Export | Purpose |
+|--------|---------|
+| `ActionBinding` | Action binding with `action`, `params`, `confirm`, `preventDefault`, etc. |
+| `BuiltInAction` | Built-in action definition with `name` and `description` |
+
+### Chat Mode (Mixed Streams)
+
+| Export | Purpose |
+|--------|---------|
+| `createJsonRenderTransform()` | TransformStream that separates text from JSONL patches in a mixed stream |
+| `pipeJsonRender()` | Server-side helper to pipe a mixed stream through the transform |
+| `SPEC_DATA_PART` / `SPEC_DATA_PART_TYPE` | Constants for filtering spec data parts |
+
+The transform splits text blocks around spec data by emitting `text-end`/`text-start` pairs, ensuring the AI SDK creates separate text parts and preserving correct interleaving of prose and UI in `message.parts`.
+
 ### Types
 
 | Export | Purpose |
 |--------|---------|
 | `Spec` | Base spec type |
 | `Catalog` | Catalog type |
+| `BuiltInAction` | Built-in action type (`name` + `description`) |
 | `VisibilityCondition` | Visibility condition type (used by `$cond`) |
 | `VisibilityContext` | Context for evaluating visibility and prop expressions |
 | `SpecStreamLine` | Single patch operation |

package/dist/index.d.mts

@@ -47,6 +47,8 @@ interface ActionBinding {
     onSuccess?: ActionOnSuccess;
     /** Handler after failed execution */
     onError?: ActionOnError;
+    /** Whether to prevent default browser behavior (e.g. navigation on links) */
+    preventDefault?: boolean;
 }
 /**
  * @deprecated Use ActionBinding instead
@@ -113,6 +115,7 @@ declare const ActionBindingSchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         action: z.ZodString;
     }, z.core.$strip>]>>;
+    preventDefault: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 /**
  * @deprecated Use ActionBindingSchema instead
@@ -144,6 +147,7 @@ declare const ActionSchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         action: z.ZodString;
     }, z.core.$strip>]>>;
+    preventDefault: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 /**
  * Action handler function signature
@@ -1129,6 +1133,8 @@ interface Schema<TDef extends SchemaDefinition = SchemaDefinition> {
     readonly promptTemplate?: PromptTemplate;
     /** Default rules baked into the schema (injected before customRules) */
     readonly defaultRules?: string[];
+    /** Built-in actions always available at runtime (injected into prompts automatically) */
+    readonly builtInActions?: BuiltInAction[];
     /** Create a catalog from this schema */
     createCatalog<TCatalog extends InferCatalogInput<TDef["catalog"]>>(catalog: TCatalog): Catalog<TDef, TCatalog>;
 }
@@ -1191,6 +1197,17 @@ interface PromptContext<TCatalog = unknown> {
  * Prompt template function type
  */
 type PromptTemplate<TCatalog = unknown> = (context: PromptContext<TCatalog>) => string;
+/**
+ * A built-in action that is always available regardless of catalog configuration.
+ * These are handled by the runtime (e.g. ActionProvider) and injected into prompts
+ * automatically so the LLM knows about them.
+ */
+interface BuiltInAction {
+    /** Action name (e.g. "setState") */
+    name: string;
+    /** Human-readable description for the LLM */
+    description: string;
+}
 /**
  * Schema options
  */
@@ -1199,6 +1216,13 @@ interface SchemaOptions<TCatalog = unknown> {
     promptTemplate?: PromptTemplate<TCatalog>;
     /** Default rules baked into the schema (injected before customRules in prompts) */
     defaultRules?: string[];
+    /**
+     * Built-in actions that are always available regardless of catalog configuration.
+     * These are injected into prompts automatically so the LLM knows about them,
+     * but they don't require handlers in defineRegistry because the runtime
+     * (e.g. ActionProvider) handles them directly.
+     */
+    builtInActions?: BuiltInAction[];
 }
 /**
  * Spec validation result
@@ -1312,4 +1336,4 @@ interface UserPromptOptions {
  */
 declare function buildUserPrompt(options: UserPromptOptions): string;
 
-export { type Action, type ActionBinding, ActionBindingSchema, type ActionConfirm, ActionConfirmSchema, type ActionDefinition, type ActionExecutionContext, type ActionHandler, type ActionOnError, ActionOnErrorSchema, type ActionOnSuccess, ActionOnSuccessSchema, ActionSchema, type AndCondition, type Catalog, type ComponentSchema, type DynamicBoolean, DynamicBooleanSchema, type DynamicNumber, DynamicNumberSchema, type DynamicString, DynamicStringSchema, type DynamicValue, DynamicValueSchema, type FlatElement, type IndexCondition, type InferActionParams, type InferCatalogActions, type InferCatalogComponents, type InferCatalogInput, type InferComponentProps, type InferSpec, type ItemCondition, type JsonPatch, type MixedStreamCallbacks, type MixedStreamParser, type OrCondition, type PatchOp, type PromptContext, type PromptOptions, type PromptTemplate, type PropExpression, type PropResolutionContext, type ResolvedAction, SPEC_DATA_PART, SPEC_DATA_PART_TYPE, type Schema, type SchemaBuilder, type SchemaDefinition, type SchemaOptions, type SchemaType, type SingleCondition, type Spec, type SpecDataPart, type SpecIssue, type SpecIssueSeverity, type SpecStreamCompiler, type SpecStreamLine, type SpecValidationIssues, type SpecValidationResult, type StateCondition, type StateModel, type StreamChunk, 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, applySpecPatch, applySpecStreamPatch, autoFixSpec, buildUserPrompt, builtInValidationFunctions, check, compileSpecStream, createJsonRenderTransform, createMixedStreamParser, createSpecStreamCompiler, defineCatalog, defineSchema, evaluateVisibility, executeAction, findFormValue, formatSpecIssues, getByPath, interpolateString, nestedToFlat, parseSpecStreamLine, pipeJsonRender, removeByPath, resolveAction, resolveActionParam, resolveBindings, resolveDynamicValue, resolveElementProps, resolvePropValue, runValidation, runValidationCheck, setByPath, validateSpec, visibility };
+export { type Action, type ActionBinding, ActionBindingSchema, type ActionConfirm, ActionConfirmSchema, type ActionDefinition, type ActionExecutionContext, type ActionHandler, type ActionOnError, ActionOnErrorSchema, type ActionOnSuccess, ActionOnSuccessSchema, ActionSchema, type AndCondition, type BuiltInAction, type Catalog, type ComponentSchema, type DynamicBoolean, DynamicBooleanSchema, type DynamicNumber, DynamicNumberSchema, type DynamicString, DynamicStringSchema, type DynamicValue, DynamicValueSchema, type FlatElement, type IndexCondition, type InferActionParams, type InferCatalogActions, type InferCatalogComponents, type InferCatalogInput, type InferComponentProps, type InferSpec, type ItemCondition, type JsonPatch, type MixedStreamCallbacks, type MixedStreamParser, type OrCondition, type PatchOp, type PromptContext, type PromptOptions, type PromptTemplate, type PropExpression, type PropResolutionContext, type ResolvedAction, SPEC_DATA_PART, SPEC_DATA_PART_TYPE, type Schema, type SchemaBuilder, type SchemaDefinition, type SchemaOptions, type SchemaType, type SingleCondition, type Spec, type SpecDataPart, type SpecIssue, type SpecIssueSeverity, type SpecStreamCompiler, type SpecStreamLine, type SpecValidationIssues, type SpecValidationResult, type StateCondition, type StateModel, type StreamChunk, 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, applySpecPatch, applySpecStreamPatch, autoFixSpec, buildUserPrompt, builtInValidationFunctions, check, compileSpecStream, createJsonRenderTransform, createMixedStreamParser, createSpecStreamCompiler, defineCatalog, defineSchema, evaluateVisibility, executeAction, findFormValue, formatSpecIssues, getByPath, interpolateString, nestedToFlat, parseSpecStreamLine, pipeJsonRender, removeByPath, resolveAction, resolveActionParam, resolveBindings, resolveDynamicValue, resolveElementProps, resolvePropValue, runValidation, runValidationCheck, setByPath, validateSpec, visibility };

package/dist/index.d.ts

@@ -47,6 +47,8 @@ interface ActionBinding {
     onSuccess?: ActionOnSuccess;
     /** Handler after failed execution */
     onError?: ActionOnError;
+    /** Whether to prevent default browser behavior (e.g. navigation on links) */
+    preventDefault?: boolean;
 }
 /**
  * @deprecated Use ActionBinding instead
@@ -113,6 +115,7 @@ declare const ActionBindingSchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         action: z.ZodString;
     }, z.core.$strip>]>>;
+    preventDefault: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 /**
  * @deprecated Use ActionBindingSchema instead
@@ -144,6 +147,7 @@ declare const ActionSchema: z.ZodObject<{
     }, z.core.$strip>, z.ZodObject<{
         action: z.ZodString;
     }, z.core.$strip>]>>;
+    preventDefault: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 /**
  * Action handler function signature
@@ -1129,6 +1133,8 @@ interface Schema<TDef extends SchemaDefinition = SchemaDefinition> {
     readonly promptTemplate?: PromptTemplate;
     /** Default rules baked into the schema (injected before customRules) */
     readonly defaultRules?: string[];
+    /** Built-in actions always available at runtime (injected into prompts automatically) */
+    readonly builtInActions?: BuiltInAction[];
     /** Create a catalog from this schema */
     createCatalog<TCatalog extends InferCatalogInput<TDef["catalog"]>>(catalog: TCatalog): Catalog<TDef, TCatalog>;
 }
@@ -1191,6 +1197,17 @@ interface PromptContext<TCatalog = unknown> {
  * Prompt template function type
  */
 type PromptTemplate<TCatalog = unknown> = (context: PromptContext<TCatalog>) => string;
+/**
+ * A built-in action that is always available regardless of catalog configuration.
+ * These are handled by the runtime (e.g. ActionProvider) and injected into prompts
+ * automatically so the LLM knows about them.
+ */
+interface BuiltInAction {
+    /** Action name (e.g. "setState") */
+    name: string;
+    /** Human-readable description for the LLM */
+    description: string;
+}
 /**
  * Schema options
  */
@@ -1199,6 +1216,13 @@ interface SchemaOptions<TCatalog = unknown> {
     promptTemplate?: PromptTemplate<TCatalog>;
     /** Default rules baked into the schema (injected before customRules in prompts) */
     defaultRules?: string[];
+    /**
+     * Built-in actions that are always available regardless of catalog configuration.
+     * These are injected into prompts automatically so the LLM knows about them,
+     * but they don't require handlers in defineRegistry because the runtime
+     * (e.g. ActionProvider) handles them directly.
+     */
+    builtInActions?: BuiltInAction[];
 }
 /**
  * Spec validation result
@@ -1312,4 +1336,4 @@ interface UserPromptOptions {
  */
 declare function buildUserPrompt(options: UserPromptOptions): string;
 
-export { type Action, type ActionBinding, ActionBindingSchema, type ActionConfirm, ActionConfirmSchema, type ActionDefinition, type ActionExecutionContext, type ActionHandler, type ActionOnError, ActionOnErrorSchema, type ActionOnSuccess, ActionOnSuccessSchema, ActionSchema, type AndCondition, type Catalog, type ComponentSchema, type DynamicBoolean, DynamicBooleanSchema, type DynamicNumber, DynamicNumberSchema, type DynamicString, DynamicStringSchema, type DynamicValue, DynamicValueSchema, type FlatElement, type IndexCondition, type InferActionParams, type InferCatalogActions, type InferCatalogComponents, type InferCatalogInput, type InferComponentProps, type InferSpec, type ItemCondition, type JsonPatch, type MixedStreamCallbacks, type MixedStreamParser, type OrCondition, type PatchOp, type PromptContext, type PromptOptions, type PromptTemplate, type PropExpression, type PropResolutionContext, type ResolvedAction, SPEC_DATA_PART, SPEC_DATA_PART_TYPE, type Schema, type SchemaBuilder, type SchemaDefinition, type SchemaOptions, type SchemaType, type SingleCondition, type Spec, type SpecDataPart, type SpecIssue, type SpecIssueSeverity, type SpecStreamCompiler, type SpecStreamLine, type SpecValidationIssues, type SpecValidationResult, type StateCondition, type StateModel, type StreamChunk, 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, applySpecPatch, applySpecStreamPatch, autoFixSpec, buildUserPrompt, builtInValidationFunctions, check, compileSpecStream, createJsonRenderTransform, createMixedStreamParser, createSpecStreamCompiler, defineCatalog, defineSchema, evaluateVisibility, executeAction, findFormValue, formatSpecIssues, getByPath, interpolateString, nestedToFlat, parseSpecStreamLine, pipeJsonRender, removeByPath, resolveAction, resolveActionParam, resolveBindings, resolveDynamicValue, resolveElementProps, resolvePropValue, runValidation, runValidationCheck, setByPath, validateSpec, visibility };
+export { type Action, type ActionBinding, ActionBindingSchema, type ActionConfirm, ActionConfirmSchema, type ActionDefinition, type ActionExecutionContext, type ActionHandler, type ActionOnError, ActionOnErrorSchema, type ActionOnSuccess, ActionOnSuccessSchema, ActionSchema, type AndCondition, type BuiltInAction, type Catalog, type ComponentSchema, type DynamicBoolean, DynamicBooleanSchema, type DynamicNumber, DynamicNumberSchema, type DynamicString, DynamicStringSchema, type DynamicValue, DynamicValueSchema, type FlatElement, type IndexCondition, type InferActionParams, type InferCatalogActions, type InferCatalogComponents, type InferCatalogInput, type InferComponentProps, type InferSpec, type ItemCondition, type JsonPatch, type MixedStreamCallbacks, type MixedStreamParser, type OrCondition, type PatchOp, type PromptContext, type PromptOptions, type PromptTemplate, type PropExpression, type PropResolutionContext, type ResolvedAction, SPEC_DATA_PART, SPEC_DATA_PART_TYPE, type Schema, type SchemaBuilder, type SchemaDefinition, type SchemaOptions, type SchemaType, type SingleCondition, type Spec, type SpecDataPart, type SpecIssue, type SpecIssueSeverity, type SpecStreamCompiler, type SpecStreamLine, type SpecValidationIssues, type SpecValidationResult, type StateCondition, type StateModel, type StreamChunk, 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, applySpecPatch, applySpecStreamPatch, autoFixSpec, buildUserPrompt, builtInValidationFunctions, check, compileSpecStream, createJsonRenderTransform, createMixedStreamParser, createSpecStreamCompiler, defineCatalog, defineSchema, evaluateVisibility, executeAction, findFormValue, formatSpecIssues, getByPath, interpolateString, nestedToFlat, parseSpecStreamLine, pipeJsonRender, removeByPath, resolveAction, resolveActionParam, resolveBindings, resolveDynamicValue, resolveElementProps, resolvePropValue, runValidation, runValidationCheck, setByPath, validateSpec, visibility };

package/dist/index.js

@@ -477,7 +477,28 @@ function createJsonRenderTransform() {
   let currentTextId = "";
   let buffering = false;
   let inSpecFence = false;
+  let inTextBlock = false;
+  let textIdCounter = 0;
+  function closeTextBlock(controller) {
+    if (inTextBlock) {
+      controller.enqueue({ type: "text-end", id: currentTextId });
+      inTextBlock = false;
+    }
+  }
+  function ensureTextBlock(controller) {
+    if (!inTextBlock) {
+      textIdCounter++;
+      currentTextId = String(textIdCounter);
+      controller.enqueue({ type: "text-start", id: currentTextId });
+      inTextBlock = true;
+    }
+  }
+  function emitTextDelta(delta, controller) {
+    ensureTextBlock(controller);
+    controller.enqueue({ type: "text-delta", id: currentTextId, delta });
+  }
   function emitPatch(patch, controller) {
+    closeTextBlock(controller);
     controller.enqueue({
       type: SPEC_DATA_PART_TYPE,
       data: { type: "patch", patch }
@@ -500,18 +521,10 @@ function createJsonRenderTransform() {
       if (patch) {
         emitPatch(patch, controller);
       } else {
-        controller.enqueue({
-          type: "text-delta",
-          id: currentTextId,
-          delta: lineBuffer
-        });
+        emitTextDelta(lineBuffer, controller);
       }
     } else {
-      controller.enqueue({
-        type: "text-delta",
-        id: currentTextId,
-        delta: lineBuffer
-      });
+      emitTextDelta(lineBuffer, controller);
     }
     lineBuffer = "";
     buffering = false;
@@ -534,35 +547,32 @@ function createJsonRenderTransform() {
       return;
     }
     if (!trimmed) {
-      controller.enqueue({
-        type: "text-delta",
-        id: currentTextId,
-        delta: "\n"
-      });
+      emitTextDelta("\n", controller);
       return;
     }
     const patch = parseSpecStreamLine(trimmed);
     if (patch) {
       emitPatch(patch, controller);
     } else {
-      controller.enqueue({
-        type: "text-delta",
-        id: currentTextId,
-        delta: line + "\n"
-      });
+      emitTextDelta(line + "\n", controller);
     }
   }
   return new TransformStream({
     transform(chunk, controller) {
       switch (chunk.type) {
         case "text-start": {
-          currentTextId = chunk.id;
+          const id = chunk.id;
+          const idNum = parseInt(id, 10);
+          if (!isNaN(idNum) && idNum >= textIdCounter) {
+            textIdCounter = idNum;
+          }
+          currentTextId = id;
+          inTextBlock = true;
           controller.enqueue(chunk);
           break;
         }
         case "text-delta": {
           const delta = chunk;
-          currentTextId = delta.id;
           const text = delta.delta;
           for (let i = 0; i < text.length; i++) {
             const ch = text.charAt(i);
@@ -573,11 +583,7 @@ function createJsonRenderTransform() {
                 buffering = false;
               } else {
                 if (!inSpecFence) {
-                  controller.enqueue({
-                    type: "text-delta",
-                    id: currentTextId,
-                    delta: "\n"
-                  });
+                  emitTextDelta("\n", controller);
                 }
               }
             } else if (lineBuffer.length === 0 && !buffering) {
@@ -585,27 +591,22 @@ function createJsonRenderTransform() {
                 buffering = true;
                 lineBuffer += ch;
               } else {
-                controller.enqueue({
-                  type: "text-delta",
-                  id: currentTextId,
-                  delta: ch
-                });
+                emitTextDelta(ch, controller);
               }
             } else if (buffering) {
               lineBuffer += ch;
             } else {
-              controller.enqueue({
-                type: "text-delta",
-                id: currentTextId,
-                delta: ch
-              });
+              emitTextDelta(ch, controller);
             }
           }
           break;
         }
         case "text-end": {
           flushBuffer(controller);
-          controller.enqueue(chunk);
+          if (inTextBlock) {
+            controller.enqueue({ type: "text-end", id: currentTextId });
+            inTextBlock = false;
+          }
           break;
         }
         default: {
@@ -616,6 +617,7 @@ function createJsonRenderTransform() {
     },
     flush(controller) {
       flushBuffer(controller);
+      closeTextBlock(controller);
     }
   });
 }
@@ -912,7 +914,8 @@ var ActionBindingSchema = import_zod3.z.object({
   params: import_zod3.z.record(import_zod3.z.string(), DynamicValueSchema).optional(),
   confirm: ActionConfirmSchema.optional(),
   onSuccess: ActionOnSuccessSchema.optional(),
-  onError: ActionOnErrorSchema.optional()
+  onError: ActionOnErrorSchema.optional(),
+  preventDefault: import_zod3.z.boolean().optional()
 });
 var ActionSchema = ActionBindingSchema;
 function resolveAction(binding, stateModel) {
@@ -1371,6 +1374,7 @@ function defineSchema(builder, options) {
     definition,
     promptTemplate: options?.promptTemplate,
     defaultRules: options?.defaultRules,
+    builtInActions: options?.builtInActions,
     createCatalog(catalog) {
       return createCatalogFromSchema(this, catalog);
     }
@@ -1696,11 +1700,19 @@ Note: state patches appear right after the elements that use them, so the UI fil
     lines.push("");
   }
   const actions = catalog.data.actions;
-  if (actions && catalog.actionNames.length > 0) {
+  const builtInActions = catalog.schema.builtInActions ?? [];
+  const hasCustomActions = actions && catalog.actionNames.length > 0;
+  const hasBuiltInActions = builtInActions.length > 0;
+  if (hasCustomActions || hasBuiltInActions) {
     lines.push("AVAILABLE ACTIONS:");
     lines.push("");
-    for (const [name, def] of Object.entries(actions)) {
-      lines.push(`- ${name}${def.description ? `: ${def.description}` : ""}`);
+    for (const action2 of builtInActions) {
+      lines.push(`- ${action2.name}: ${action2.description} [built-in]`);
+    }
+    if (hasCustomActions) {
+      for (const [name, def] of Object.entries(actions)) {
+        lines.push(`- ${name}${def.description ? `: ${def.description}` : ""}`);
+      }
     }
     lines.push("");
   }