@json-render/core 0.5.2 → 0.6.0

package/dist/index.d.mts

@@ -33,7 +33,7 @@ type ActionOnError = {
  *
  * Used inside the `on` field of a UIElement:
  * ```json
- * { "on": { "press": { "action": "setState", "params": { "path": "/x", "value": 1 } } } }
+ * { "on": { "press": { "action": "setState", "params": { "statePath": "/x", "value": 1 } } } }
  * ```
  */
 interface ActionBinding {
@@ -89,7 +89,7 @@ declare const ActionOnErrorSchema: z.ZodUnion<readonly [z.ZodObject<{
 declare const ActionBindingSchema: z.ZodObject<{
     action: z.ZodString;
     params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodObject<{
-        path: z.ZodString;
+        $state: z.ZodString;
     }, z.core.$strip>]>>>;
     confirm: z.ZodOptional<z.ZodObject<{
         title: z.ZodString;
@@ -120,7 +120,7 @@ declare const ActionBindingSchema: z.ZodObject<{
 declare const ActionSchema: z.ZodObject<{
     action: z.ZodString;
     params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodObject<{
-        path: z.ZodString;
+        $state: z.ZodString;
     }, z.core.$strip>]>>>;
     confirm: z.ZodOptional<z.ZodObject<{
         title: z.ZodString;
@@ -219,10 +219,13 @@ declare const action: {
 };
 
 /**
- * Dynamic value - can be a literal or a path reference to state model
+ * Dynamic value - can be a literal or a `{ $state }` reference to the state model.
+ *
+ * Used in action params and validation args where values can either be
+ * hardcoded or resolved from state at runtime.
  */
 type DynamicValue<T = unknown> = T | {
-    path: string;
+    $state: string;
 };
 /**
  * Dynamic string value
@@ -240,16 +243,16 @@ type DynamicBoolean = DynamicValue<boolean>;
  * Zod schema for dynamic values
  */
 declare const DynamicValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodObject<{
-    path: z.ZodString;
+    $state: z.ZodString;
 }, z.core.$strip>]>;
 declare const DynamicStringSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
-    path: z.ZodString;
+    $state: z.ZodString;
 }, z.core.$strip>]>;
 declare const DynamicNumberSchema: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
-    path: z.ZodString;
+    $state: z.ZodString;
 }, z.core.$strip>]>;
 declare const DynamicBooleanSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
-    path: z.ZodString;
+    $state: z.ZodString;
 }, z.core.$strip>]>;
 /**
  * Base UI element structure for v2
@@ -267,7 +270,7 @@ interface UIElement<T extends string = string, P = Record<string, unknown>> {
     on?: Record<string, ActionBinding | ActionBinding[]>;
     /** Repeat children once per item in a state array */
     repeat?: {
-        path: string;
+        statePath: string;
         key?: string;
     };
 }
@@ -283,37 +286,84 @@ interface FlatElement<T extends string = string, P = Record<string, unknown>> ex
     parentKey?: string | null;
 }
 /**
- * Visibility condition types
+ * Shared comparison operators for visibility conditions.
+ *
+ * Use at most ONE comparison operator per condition. If multiple are
+ * provided, only the first matching one is evaluated (precedence:
+ * eq > neq > gt > gte > lt > lte). With no operator, truthiness is checked.
+ *
+ * `not` inverts the final result of whichever operator (or truthiness
+ * check) is used.
+ */
+type ComparisonOperators = {
+    eq?: unknown;
+    neq?: unknown;
+    gt?: number | {
+        $state: string;
+    };
+    gte?: number | {
+        $state: string;
+    };
+    lt?: number | {
+        $state: string;
+    };
+    lte?: number | {
+        $state: string;
+    };
+    not?: true;
+};
+/**
+ * A single state-based condition.
+ * Resolves `$state` to a value from the state model, then applies the operator.
+ * Without an operator, checks truthiness.
+ *
+ * When `not` is `true`, the result of the entire condition is inverted.
+ * For example `{ $state: "/count", gt: 5, not: true }` means "NOT greater than 5".
  */
-type VisibilityCondition = boolean | {
-    path: string;
-} | {
-    auth: "signedIn" | "signedOut";
-} | LogicExpression;
+type StateCondition = {
+    $state: string;
+} & ComparisonOperators;
 /**
- * Logic expression for complex conditions
+ * A condition that resolves `$item` to a field on the current repeat item.
+ * Only meaningful inside a `repeat` scope.
+ *
+ * Use `""` to reference the whole item, or `"field"` for a specific field.
  */
-type LogicExpression = {
-    and: LogicExpression[];
-} | {
-    or: LogicExpression[];
-} | {
-    not: LogicExpression;
-} | {
-    path: string;
-} | {
-    eq: [DynamicValue, DynamicValue];
-} | {
-    neq: [DynamicValue, DynamicValue];
-} | {
-    gt: [DynamicValue<number>, DynamicValue<number>];
-} | {
-    gte: [DynamicValue<number>, DynamicValue<number>];
-} | {
-    lt: [DynamicValue<number>, DynamicValue<number>];
-} | {
-    lte: [DynamicValue<number>, DynamicValue<number>];
+type ItemCondition = {
+    $item: string;
+} & ComparisonOperators;
+/**
+ * A condition that resolves `$index` to the current repeat array index.
+ * Only meaningful inside a `repeat` scope.
+ */
+type IndexCondition = {
+    $index: true;
+} & ComparisonOperators;
+/** A single visibility condition (state, item, or index). */
+type SingleCondition = StateCondition | ItemCondition | IndexCondition;
+/**
+ * AND wrapper — all child conditions must be true.
+ * This is the explicit form of the implicit array AND (`SingleCondition[]`).
+ * Unlike the implicit form, `$and` supports nested `$or` and `$and` conditions.
+ */
+type AndCondition = {
+    $and: VisibilityCondition[];
+};
+/**
+ * OR wrapper — at least one child condition must be true.
+ */
+type OrCondition = {
+    $or: VisibilityCondition[];
 };
+/**
+ * Visibility condition types.
+ * - `boolean` — always/never
+ * - `SingleCondition` — single condition (`$state`, `$item`, or `$index`)
+ * - `SingleCondition[]` — implicit AND (all must be true)
+ * - `AndCondition` — `{ $and: [...] }`, explicit AND (all must be true)
+ * - `OrCondition` — `{ $or: [...] }`, at least one must be true
+ */
+type VisibilityCondition = boolean | SingleCondition | SingleCondition[] | AndCondition | OrCondition;
 /**
  * Flat UI tree structure (optimized for LLM generation)
  */
@@ -326,13 +376,6 @@ interface Spec {
      *  Components using statePath will read from / write to this state. */
     state?: Record<string, unknown>;
 }
-/**
- * Auth state for visibility evaluation
- */
-interface AuthState {
-    isSignedIn: boolean;
-    user?: Record<string, unknown>;
-}
 /**
  * State model type
  */
@@ -386,22 +429,22 @@ declare function addByPath(obj: Record<string, unknown>, path: string, value: un
  */
 declare function removeByPath(obj: Record<string, unknown>, path: string): void;
 /**
- * Find a form value from params and/or data.
+ * Find a form value from params and/or state.
  * Useful in action handlers to locate form input values regardless of path format.
  *
  * Checks in order:
  * 1. Direct param key (if not a path reference)
  * 2. Param keys ending with the field name
- * 3. Data keys ending with the field name (dot notation)
- * 4. Data paths using getByPath (slash notation)
+ * 3. State keys ending with the field name (dot notation)
+ * 4. State path using getByPath (slash notation)
  *
  * @example
- * // Find "name" from params or data
- * const name = findFormValue("name", params, data);
+ * // Find "name" from params or state
+ * const name = findFormValue("name", params, state);
  *
- * // Will find from: params.name, params["form.name"], data["customerForm.name"], data.customerForm.name
+ * // Will find from: params.name, params["form.name"], state["form.name"], or getByPath(state, "name")
  */
-declare function findFormValue(fieldName: string, params?: Record<string, unknown>, data?: Record<string, unknown>): unknown;
+declare function findFormValue(fieldName: string, params?: Record<string, unknown>, state?: Record<string, unknown>): unknown;
 /**
  * A SpecStream line - a single patch operation in the stream.
  */
@@ -423,6 +466,54 @@ declare function parseSpecStreamLine(line: string): SpecStreamLine | null;
  * @throws {Error} If a "test" operation fails (value mismatch).
  */
 declare function applySpecStreamPatch<T extends Record<string, unknown>>(obj: T, patch: SpecStreamLine): T;
+/**
+ * Apply a single RFC 6902 JSON Patch operation to a Spec.
+ * Mutates the spec in place and returns it.
+ *
+ * This is a typed convenience wrapper around `applySpecStreamPatch` that
+ * accepts a `Spec` directly without requiring a cast to `Record<string, unknown>`.
+ *
+ * Note: This mutates the spec. For React state updates, spread the result
+ * to create a new reference: `setSpec({ ...applySpecPatch(spec, patch) })`.
+ *
+ * @example
+ * let spec: Spec = { root: "", elements: {} };
+ * applySpecPatch(spec, { op: "add", path: "/root", value: "main" });
+ */
+declare function applySpecPatch(spec: Spec, patch: SpecStreamLine): Spec;
+/**
+ * Convert a nested (tree-structured) spec into the flat `Spec` format used
+ * by json-render renderers.
+ *
+ * In the nested format each node has inline `children` as an array of child
+ * objects. This function walks the tree, assigns auto-generated keys
+ * (`el-0`, `el-1`, ...), and produces a flat `{ root, elements, state }` spec.
+ *
+ * The top-level `state` field (if present on the root node) is hoisted to
+ * `spec.state`.
+ *
+ * @example
+ * ```ts
+ * const nested = {
+ *   type: "Card",
+ *   props: { title: "Hello" },
+ *   children: [
+ *     { type: "Text", props: { content: "World" } },
+ *   ],
+ *   state: { count: 0 },
+ * };
+ * const spec = nestedToFlat(nested);
+ * // {
+ * //   root: "el-0",
+ * //   elements: {
+ * //     "el-0": { type: "Card", props: { title: "Hello" }, children: ["el-1"] },
+ * //     "el-1": { type: "Text", props: { content: "World" }, children: [] },
+ * //   },
+ * //   state: { count: 0 },
+ * // }
+ * ```
+ */
+declare function nestedToFlat(nested: Record<string, unknown>): Spec;
 /**
  * Compile a SpecStream string into a JSON object.
  * Each line should be a patch operation.
@@ -485,101 +576,316 @@ interface SpecStreamCompiler<T> {
  * }
  */
 declare function createSpecStreamCompiler<T = Record<string, unknown>>(initial?: Partial<T>): SpecStreamCompiler<T>;
-
 /**
- * Logic expression schema (recursive)
- * Using a more permissive schema that aligns with runtime behavior
+ * Callbacks for the mixed stream parser.
+ */
+interface MixedStreamCallbacks {
+    /** Called when a JSONL patch line is parsed */
+    onPatch: (patch: SpecStreamLine) => void;
+    /** Called when a text (non-JSONL) line is received */
+    onText: (text: string) => void;
+}
+/**
+ * A stateful parser for mixed streams that contain both text and JSONL patches.
+ * Used in chat + GenUI scenarios where an LLM responds with conversational text
+ * interleaved with json-render JSONL patch operations.
+ */
+interface MixedStreamParser {
+    /** Push a chunk of streamed data. Calls onPatch/onText for each complete line. */
+    push(chunk: string): void;
+    /** Flush any remaining buffered content. Call when the stream ends. */
+    flush(): void;
+}
+/**
+ * Create a parser for mixed text + JSONL streams.
+ *
+ * In chat + GenUI scenarios, an LLM streams a response that contains both
+ * conversational text and json-render JSONL patch lines. This parser buffers
+ * incoming chunks, splits them into lines, and classifies each line as either
+ * a JSONL patch (via `parseSpecStreamLine`) or plain text.
+ *
+ * @example
+ * const parser = createMixedStreamParser({
+ *   onText: (text) => appendToMessage(text),
+ *   onPatch: (patch) => applySpecPatch(spec, patch),
+ * });
+ *
+ * // As chunks arrive from the stream:
+ * for await (const chunk of stream) {
+ *   parser.push(chunk);
+ * }
+ * parser.flush();
  */
-declare const LogicExpressionSchema: z.ZodType<LogicExpression>;
+declare function createMixedStreamParser(callbacks: MixedStreamCallbacks): MixedStreamParser;
 /**
- * Visibility condition schema
+ * Minimal chunk shape compatible with the AI SDK's `UIMessageChunk`.
+ *
+ * Defined here so that `@json-render/core` has no dependency on the `ai`
+ * package. The discriminated union covers the three text-related chunk types
+ * the transform inspects; all other chunk types pass through via the fallback.
+ */
+type StreamChunk = {
+    type: "text-start";
+    id: string;
+    [k: string]: unknown;
+} | {
+    type: "text-delta";
+    id: string;
+    delta: string;
+    [k: string]: unknown;
+} | {
+    type: "text-end";
+    id: string;
+    [k: string]: unknown;
+} | {
+    type: string;
+    [k: string]: unknown;
+};
+/**
+ * Creates a `TransformStream` that intercepts AI SDK UI message stream chunks
+ * and classifies text content as either prose or json-render JSONL patches.
+ *
+ * Two classification modes:
+ *
+ * 1. **Fence mode** (preferred): Lines between ` ```spec ` and ` ``` ` are
+ *    parsed as JSONL patches. Fence delimiters are swallowed (not emitted).
+ * 2. **Heuristic mode** (backward compat): Outside of fences, lines starting
+ *    with `{` are buffered and tested with `parseSpecStreamLine`. Valid patches
+ *    are emitted as {@link SPEC_DATA_PART_TYPE} parts; everything else is
+ *    flushed as text.
+ *
+ * Non-text chunks (tool events, step markers, etc.) are passed through unchanged.
+ *
+ * @example
+ * ```ts
+ * import { createJsonRenderTransform } from "@json-render/core";
+ * import { createUIMessageStream, createUIMessageStreamResponse } from "ai";
+ *
+ * const stream = createUIMessageStream({
+ *   execute: async ({ writer }) => {
+ *     writer.merge(
+ *       result.toUIMessageStream().pipeThrough(createJsonRenderTransform()),
+ *     );
+ *   },
+ * });
+ * return createUIMessageStreamResponse({ stream });
+ * ```
+ */
+declare function createJsonRenderTransform(): TransformStream<StreamChunk, StreamChunk>;
+/**
+ * The key registered in `AppDataParts` for json-render specs.
+ * The AI SDK automatically prefixes this with `"data-"` on the wire,
+ * so the actual stream chunk type is `"data-spec"` (see {@link SPEC_DATA_PART_TYPE}).
+ *
+ * @example
+ * ```ts
+ * import { SPEC_DATA_PART, type SpecDataPart } from "@json-render/core";
+ * type AppDataParts = { [SPEC_DATA_PART]: SpecDataPart };
+ * ```
+ */
+declare const SPEC_DATA_PART: "spec";
+/**
+ * The wire-format type string as it appears in stream chunks and message parts.
+ * This is `"data-"` + {@link SPEC_DATA_PART} — i.e. `"data-spec"`.
+ *
+ * Use this constant when filtering message parts or enqueuing stream chunks.
+ */
+declare const SPEC_DATA_PART_TYPE: "data-spec";
+/**
+ * Discriminated union for the payload of a {@link SPEC_DATA_PART_TYPE} SSE part.
+ *
+ * - `"patch"`: A single RFC 6902 JSON Patch operation (streaming, progressive UI).
+ * - `"flat"`: A complete flat spec with `root`, `elements`, and optional `state`.
+ * - `"nested"`: A complete nested spec (tree structure — schema depends on catalog).
+ */
+type SpecDataPart = {
+    type: "patch";
+    patch: JsonPatch;
+} | {
+    type: "flat";
+    spec: Spec;
+} | {
+    type: "nested";
+    spec: Record<string, unknown>;
+};
+/**
+ * Convenience wrapper that pipes an AI SDK UI message stream through the
+ * json-render transform, classifying text as prose or JSONL patches.
+ *
+ * Eliminates the need for manual `pipeThrough(createJsonRenderTransform())`
+ * and the associated type cast.
+ *
+ * @example
+ * ```ts
+ * import { pipeJsonRender } from "@json-render/core";
+ *
+ * const stream = createUIMessageStream({
+ *   execute: async ({ writer }) => {
+ *     writer.merge(pipeJsonRender(result.toUIMessageStream()));
+ *   },
+ * });
+ * return createUIMessageStreamResponse({ stream });
+ * ```
+ */
+declare function pipeJsonRender<T = StreamChunk>(stream: ReadableStream<T>): ReadableStream<T>;
+
+/**
+ * Visibility condition schema.
+ *
+ * Lazy because `OrCondition` can recursively contain `VisibilityCondition`.
  */
 declare const VisibilityConditionSchema: z.ZodType<VisibilityCondition>;
 /**
- * Context for evaluating visibility
+ * Context for evaluating visibility conditions.
+ *
+ * `repeatItem` and `repeatIndex` are only present inside a `repeat` scope
+ * and enable `$item` / `$index` conditions.
  */
 interface VisibilityContext {
     stateModel: StateModel;
-    authState?: AuthState;
+    /** The current repeat item (set inside a repeat scope). */
+    repeatItem?: unknown;
+    /** The current repeat array index (set inside a repeat scope). */
+    repeatIndex?: number;
 }
 /**
- * Evaluate a logic expression against data and auth state
- */
-declare function evaluateLogicExpression(expr: LogicExpression, ctx: VisibilityContext): boolean;
-/**
- * Evaluate a visibility condition
+ * Evaluate a visibility condition.
+ *
+ * - `undefined` → visible
+ * - `boolean` → that value
+ * - `SingleCondition` → evaluate single condition
+ * - `SingleCondition[]` → implicit AND (all must be true)
+ * - `AndCondition` → `{ $and: [...] }`, explicit AND
+ * - `OrCondition` → `{ $or: [...] }`, at least one must be true
  */
 declare function evaluateVisibility(condition: VisibilityCondition | undefined, ctx: VisibilityContext): boolean;
 /**
- * Helper to create visibility conditions
+ * Helper to create visibility conditions.
  */
 declare const visibility: {
     /** Always visible */
     always: true;
     /** Never visible */
     never: false;
-    /** Visible when path is truthy */
-    when: (path: string) => VisibilityCondition;
-    /** Visible when signed in */
-    signedIn: {
-        readonly auth: "signedIn";
-    };
-    /** Visible when signed out */
-    signedOut: {
-        readonly auth: "signedOut";
-    };
-    /** AND multiple conditions */
-    and: (...conditions: LogicExpression[]) => LogicExpression;
-    /** OR multiple conditions */
-    or: (...conditions: LogicExpression[]) => LogicExpression;
-    /** NOT a condition */
-    not: (condition: LogicExpression) => LogicExpression;
+    /** Visible when state path is truthy */
+    when: (path: string) => StateCondition;
+    /** Visible when state path is falsy */
+    unless: (path: string) => StateCondition;
     /** Equality check */
-    eq: (left: DynamicValue, right: DynamicValue) => LogicExpression;
+    eq: (path: string, value: unknown) => StateCondition;
     /** Not equal check */
-    neq: (left: DynamicValue, right: DynamicValue) => LogicExpression;
+    neq: (path: string, value: unknown) => StateCondition;
     /** Greater than */
-    gt: (left: DynamicValue<number>, right: DynamicValue<number>) => LogicExpression;
+    gt: (path: string, value: number | {
+        $state: string;
+    }) => StateCondition;
     /** Greater than or equal */
-    gte: (left: DynamicValue<number>, right: DynamicValue<number>) => LogicExpression;
+    gte: (path: string, value: number | {
+        $state: string;
+    }) => StateCondition;
     /** Less than */
-    lt: (left: DynamicValue<number>, right: DynamicValue<number>) => LogicExpression;
+    lt: (path: string, value: number | {
+        $state: string;
+    }) => StateCondition;
     /** Less than or equal */
-    lte: (left: DynamicValue<number>, right: DynamicValue<number>) => LogicExpression;
+    lte: (path: string, value: number | {
+        $state: string;
+    }) => StateCondition;
+    /** AND multiple conditions */
+    and: (...conditions: VisibilityCondition[]) => AndCondition;
+    /** OR multiple conditions */
+    or: (...conditions: VisibilityCondition[]) => OrCondition;
 };
 
 /**
  * A prop expression that resolves to a value based on state.
  *
- * - `{ $path: string }` reads a value from the state model
+ * - `{ $state: string }` reads a value from the global state model
+ * - `{ $item: string }` reads a field from the current repeat item
+ *    (relative path into the item object; use `""` for the whole item)
+ * - `{ $index: true }` returns the current repeat array index. Uses `true`
+ *    as a sentinel flag because the index is a scalar with no sub-path to
+ *    navigate — unlike `$item` which needs a path into the item object.
+ * - `{ $bindState: string }` two-way binding to a global state path —
+ *    resolves to the value at the path (like `$state`) AND exposes the
+ *    resolved path so the component can write back.
+ * - `{ $bindItem: string }` two-way binding to a field on the current
+ *    repeat item — resolves via `repeatBasePath + path` and exposes the
+ *    absolute state path for write-back.
  * - `{ $cond, $then, $else }` conditionally picks a value
  * - Any other value is a literal (passthrough)
  */
 type PropExpression<T = unknown> = T | {
-    $path: string;
+    $state: string;
+} | {
+    $item: string;
+} | {
+    $index: true;
+} | {
+    $bindState: string;
+} | {
+    $bindItem: string;
 } | {
     $cond: VisibilityCondition;
     $then: PropExpression<T>;
     $else: PropExpression<T>;
 };
+/**
+ * Context for resolving prop expressions.
+ * Extends {@link VisibilityContext} with an optional `repeatBasePath` used
+ * to resolve `$bindItem` paths to absolute state paths.
+ */
+interface PropResolutionContext extends VisibilityContext {
+    /** Absolute state path to the current repeat item (e.g. "/todos/0"). Set inside repeat scopes. */
+    repeatBasePath?: string;
+}
 /**
  * Resolve a single prop value that may contain expressions.
- * Recursively resolves $path and $cond/$then/$else expressions.
+ * Handles $state, $item, $index, $bindState, $bindItem, and $cond/$then/$else in a single pass.
  */
-declare function resolvePropValue(value: unknown, ctx: VisibilityContext): unknown;
+declare function resolvePropValue(value: unknown, ctx: PropResolutionContext): unknown;
 /**
  * Resolve all prop values in an element's props object.
  * Returns a new props object with all expressions resolved.
  */
-declare function resolveElementProps(props: Record<string, unknown>, ctx: VisibilityContext): Record<string, unknown>;
+declare function resolveElementProps(props: Record<string, unknown>, ctx: PropResolutionContext): Record<string, unknown>;
+/**
+ * Scan an element's raw props for `$bindState` / `$bindItem` expressions
+ * and return a map of prop name → resolved absolute state path.
+ *
+ * This is called **before** `resolveElementProps` so the component can
+ * receive both the resolved value (in `props`) and the write-back path
+ * (in `bindings`).
+ *
+ * @example
+ * ```ts
+ * const rawProps = { value: { $bindState: "/form/email" }, label: "Email" };
+ * const bindings = resolveBindings(rawProps, ctx);
+ * // bindings = { value: "/form/email" }
+ * ```
+ */
+declare function resolveBindings(props: Record<string, unknown>, ctx: PropResolutionContext): Record<string, string> | undefined;
+/**
+ * Resolve a single action parameter value.
+ *
+ * Like {@link resolvePropValue} but with special handling for path-valued
+ * params: `{ $item: "field" }` resolves to an **absolute state path**
+ * (e.g. `/todos/0/field`) instead of the field's value, so the path can
+ * be passed to `setState` / `pushState` / `removeState`.
+ *
+ * - `{ $item: "field" }` → absolute state path via `repeatBasePath`
+ * - `{ $index: true }` → current repeat index (number)
+ * - Everything else delegates to `resolvePropValue` ($state, $cond, literals).
+ */
+declare function resolveActionParam(value: unknown, ctx: PropResolutionContext): unknown;
 
 /**
  * Validation check definition
  */
 interface ValidationCheck {
-    /** Function name (built-in or from catalog) */
-    fn: string;
-    /** Additional arguments for the function */
+    /** Validation type (built-in or from catalog) */
+    type: string;
+    /** Additional arguments for the validation */
     args?: Record<string, DynamicValue>;
     /** Error message to display if check fails */
     message: string;
@@ -593,15 +899,15 @@ interface ValidationConfig {
     /** When to run validation */
     validateOn?: "change" | "blur" | "submit";
     /** Condition for when validation is enabled */
-    enabled?: LogicExpression;
+    enabled?: VisibilityCondition;
 }
 /**
  * Schema for validation check
  */
 declare const ValidationCheckSchema: z.ZodObject<{
-    fn: z.ZodString;
+    type: z.ZodString;
     args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodObject<{
-        path: z.ZodString;
+        $state: z.ZodString;
     }, z.core.$strip>]>>>;
     message: z.ZodString;
 }, z.core.$strip>;
@@ -610,9 +916,9 @@ declare const ValidationCheckSchema: z.ZodObject<{
  */
 declare const ValidationConfigSchema: z.ZodObject<{
     checks: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        fn: z.ZodString;
+        type: z.ZodString;
         args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodObject<{
-            path: z.ZodString;
+            $state: z.ZodString;
         }, z.core.$strip>]>>>;
         message: z.ZodString;
     }, z.core.$strip>>>;
@@ -621,7 +927,7 @@ declare const ValidationConfigSchema: z.ZodObject<{
         blur: "blur";
         submit: "submit";
     }>>;
-    enabled: z.ZodOptional<z.ZodType<LogicExpression, unknown, z.core.$ZodTypeInternals<LogicExpression, unknown>>>;
+    enabled: z.ZodOptional<z.ZodType<VisibilityCondition, unknown, z.core.$ZodTypeInternals<VisibilityCondition, unknown>>>;
 }, z.core.$strip>;
 /**
  * Validation function signature
@@ -644,7 +950,7 @@ declare const builtInValidationFunctions: Record<string, ValidationFunction>;
  * Validation result for a single check
  */
 interface ValidationCheckResult {
-    fn: string;
+    type: string;
     valid: boolean;
     message: string;
 }
@@ -674,11 +980,7 @@ declare function runValidationCheck(check: ValidationCheck, ctx: ValidationConte
 /**
  * Run all validation checks for a field
  */
-declare function runValidation(config: ValidationConfig, ctx: ValidationContext & {
-    authState?: {
-        isSignedIn: boolean;
-    };
-}): ValidationResult;
+declare function runValidation(config: ValidationConfig, ctx: ValidationContext): ValidationResult;
 /**
  * Helper to create validation checks
  */
@@ -828,12 +1130,12 @@ interface Schema<TDef extends SchemaDefinition = SchemaDefinition> {
     /** Default rules baked into the schema (injected before customRules) */
     readonly defaultRules?: string[];
     /** Create a catalog from this schema */
-    createCatalog<TCatalog extends InferCatalogInput<TDef["catalog"]>>(catalog: TCatalog): Catalog$1<TDef, TCatalog>;
+    createCatalog<TCatalog extends InferCatalogInput<TDef["catalog"]>>(catalog: TCatalog): Catalog<TDef, TCatalog>;
 }
 /**
  * Catalog instance with methods
  */
-interface Catalog$1<TDef extends SchemaDefinition = SchemaDefinition, TCatalog = unknown> {
+interface Catalog<TDef extends SchemaDefinition = SchemaDefinition, TCatalog = unknown> {
     /** The schema this catalog is based on */
     readonly schema: Schema<TDef>;
     /** The catalog data */
@@ -861,6 +1163,14 @@ interface PromptOptions {
     system?: string;
     /** Additional rules to append */
     customRules?: string[];
+    /**
+     * Output mode for the generated prompt.
+     *
+     * - `"generate"` (default): The LLM should output only JSONL patches (no prose).
+     * - `"chat"`: The LLM should respond conversationally first, then output JSONL patches.
+     *   Includes rules about interleaving text with JSONL and not wrapping in code fences.
+     */
+    mode?: "generate" | "chat";
 }
 /**
  * Context provided to prompt templates
@@ -902,28 +1212,28 @@ interface SpecValidationResult<T> {
  * Extract the components map type from a catalog
  * @example type Components = InferCatalogComponents<typeof myCatalog>;
  */
-type InferCatalogComponents<C extends Catalog$1> = C extends Catalog$1<SchemaDefinition, infer TCatalog> ? TCatalog extends {
+type InferCatalogComponents<C extends Catalog> = C extends Catalog<SchemaDefinition, infer TCatalog> ? TCatalog extends {
     components: infer Comps;
 } ? Comps : never : never;
 /**
  * Extract the actions map type from a catalog
  * @example type Actions = InferCatalogActions<typeof myCatalog>;
  */
-type InferCatalogActions<C extends Catalog$1> = C extends Catalog$1<SchemaDefinition, infer TCatalog> ? TCatalog extends {
+type InferCatalogActions<C extends Catalog> = C extends Catalog<SchemaDefinition, infer TCatalog> ? TCatalog extends {
     actions: infer Acts;
 } ? Acts : never : never;
 /**
  * Infer component props from a catalog by component name
  * @example type ButtonProps = InferComponentProps<typeof myCatalog, 'Button'>;
  */
-type InferComponentProps<C extends Catalog$1, K extends keyof InferCatalogComponents<C>> = InferCatalogComponents<C>[K] extends {
+type InferComponentProps<C extends Catalog, K extends keyof InferCatalogComponents<C>> = InferCatalogComponents<C>[K] extends {
     props: z.ZodType<infer P>;
 } ? P : never;
 /**
  * Infer action params from a catalog by action name
  * @example type ViewCustomersParams = InferActionParams<typeof myCatalog, 'viewCustomers'>;
  */
-type InferActionParams<C extends Catalog$1, K extends keyof InferCatalogActions<C>> = InferCatalogActions<C>[K] extends {
+type InferActionParams<C extends Catalog, K extends keyof InferCatalogActions<C>> = InferCatalogActions<C>[K] extends {
     params: z.ZodType<infer P>;
 } ? P : never;
 type InferCatalogInput<T> = T extends SchemaType<"object", infer Shape> ? {
@@ -965,7 +1275,7 @@ declare function defineSchema<TDef extends SchemaDefinition>(builder: (s: Schema
 /**
  * Shorthand: Define a catalog directly from a schema
  */
-declare function defineCatalog<TDef extends SchemaDefinition, TCatalog extends InferCatalogInput<TDef["catalog"]>>(schema: Schema<TDef>, catalog: TCatalog): Catalog$1<TDef, TCatalog>;
+declare function defineCatalog<TDef extends SchemaDefinition, TCatalog extends InferCatalogInput<TDef["catalog"]>>(schema: Schema<TDef>, catalog: TCatalog): Catalog<TDef, TCatalog>;
 
 /**
  * Options for building a user prompt.
@@ -1002,104 +1312,4 @@ interface UserPromptOptions {
  */
 declare function buildUserPrompt(options: UserPromptOptions): string;
 
-/**
- * Component definition with visibility and validation support
- */
-interface ComponentDefinition<TProps extends ComponentSchema = ComponentSchema> {
-    /** Zod schema for component props */
-    props: TProps;
-    /** Whether this component can have children */
-    hasChildren?: boolean;
-    /** Description for AI generation */
-    description?: string;
-    /** Example prop values used in prompt examples (auto-generated from Zod schema if omitted) */
-    example?: Record<string, unknown>;
-}
-/**
- * Catalog configuration
- */
-interface CatalogConfig<TComponents extends Record<string, ComponentDefinition> = Record<string, ComponentDefinition>, TActions extends Record<string, ActionDefinition> = Record<string, ActionDefinition>, TFunctions extends Record<string, ValidationFunction> = Record<string, ValidationFunction>> {
-    /** Catalog name */
-    name?: string;
-    /** Component definitions */
-    components: TComponents;
-    /** Action definitions with param schemas */
-    actions?: TActions;
-    /** Custom validation functions */
-    functions?: TFunctions;
-    /** Validation mode */
-    validation?: ValidationMode;
-}
-/**
- * Catalog instance
- */
-interface Catalog<TComponents extends Record<string, ComponentDefinition> = Record<string, ComponentDefinition>, TActions extends Record<string, ActionDefinition> = Record<string, ActionDefinition>, TFunctions extends Record<string, ValidationFunction> = Record<string, ValidationFunction>> {
-    /** Catalog name */
-    readonly name: string;
-    /** Component names */
-    readonly componentNames: (keyof TComponents)[];
-    /** Action names */
-    readonly actionNames: (keyof TActions)[];
-    /** Function names */
-    readonly functionNames: (keyof TFunctions)[];
-    /** Validation mode */
-    readonly validation: ValidationMode;
-    /** Component definitions */
-    readonly components: TComponents;
-    /** Action definitions */
-    readonly actions: TActions;
-    /** Custom validation functions */
-    readonly functions: TFunctions;
-    /** Full element schema for AI generation */
-    readonly elementSchema: z.ZodType<UIElement>;
-    /** Full UI spec schema */
-    readonly specSchema: z.ZodType<Spec>;
-    /** Check if component exists */
-    hasComponent(type: string): boolean;
-    /** Check if action exists */
-    hasAction(name: string): boolean;
-    /** Check if function exists */
-    hasFunction(name: string): boolean;
-    /** Validate an element */
-    validateElement(element: unknown): {
-        success: boolean;
-        data?: UIElement;
-        error?: z.ZodError;
-    };
-    /** Validate a UI spec */
-    validateSpec(spec: unknown): {
-        success: boolean;
-        data?: Spec;
-        error?: z.ZodError;
-    };
-}
-/**
- * Create a v2 catalog with visibility, actions, and validation support
- */
-declare function createCatalog<TComponents extends Record<string, ComponentDefinition>, TActions extends Record<string, ActionDefinition> = Record<string, ActionDefinition>, TFunctions extends Record<string, ValidationFunction> = Record<string, ValidationFunction>>(config: CatalogConfig<TComponents, TActions, TFunctions>): Catalog<TComponents, TActions, TFunctions>;
-/**
- * Generate a prompt for AI that describes the catalog
- */
-declare function generateCatalogPrompt<TComponents extends Record<string, ComponentDefinition>, TActions extends Record<string, ActionDefinition>, TFunctions extends Record<string, ValidationFunction>>(catalog: Catalog<TComponents, TActions, TFunctions>): string;
-/**
- * Type helper to infer component props from catalog
- */
-type InferCatalogComponentProps<C extends Catalog<Record<string, ComponentDefinition>>> = {
-    [K in keyof C["components"]]: z.infer<C["components"][K]["props"]>;
-};
-/**
- * Options for generating system prompts
- */
-interface SystemPromptOptions {
-    /** System message intro (replaces default) */
-    system?: string;
-    /** Additional rules to append to the rules section */
-    customRules?: string[];
-}
-/**
- * Generate a complete system prompt for AI that can generate UI from a catalog.
- * This produces a ready-to-use prompt that stays in sync with the catalog definition.
- */
-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;
-
-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 };
+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 };