@json-render/yaml

YAML wire format for @json-render/core. Progressive rendering and surgical edits via streaming YAML.

Installation

npm install @json-render/yaml @json-render/core yaml

Key Concepts

• YAML wire format: Uses yaml-spec, yaml-edit, yaml-patch, and diff code fences instead of JSONL
• Streaming parser: Incrementally parses YAML as it arrives, emitting JSON Patch operations
• Edit modes: Supports patch (RFC 6902), merge (RFC 7396), and unified diff for surgical edits
• AI SDK transform: Drop-in TransformStream that converts YAML fences into json-render patch data parts

Quick Start

Generate a YAML System Prompt

import { yamlPrompt } from "@json-render/yaml";
import { catalog } from "./catalog";

const systemPrompt = yamlPrompt(catalog, {
  mode: "standalone",
  editModes: ["merge"],
});

Stream YAML Specs (AI SDK)

import { pipeYamlRender } from "@json-render/yaml";
import { createUIMessageStream, createUIMessageStreamResponse } from "ai";

const stream = createUIMessageStream({
  execute: async ({ writer }) => {
    writer.merge(pipeYamlRender(result.toUIMessageStream()));
  },
});
return createUIMessageStreamResponse({ stream });

Streaming Parser (Low-Level)

import { createYamlStreamCompiler } from "@json-render/yaml";

const compiler = createYamlStreamCompiler<Spec>();

// Feed chunks as they arrive
const { result, newPatches } = compiler.push("root: main\n");
compiler.push("elements:\n  main:\n    type: Card\n");

// Flush remaining data
const { result: final } = compiler.flush();

API Reference

yamlPrompt(catalog, options?)

Generate a YAML-format system prompt from any json-render catalog.

| Option | Type | Default | Description | |--------|------|---------|-------------| | system | string | "You are a UI generator that outputs YAML." | Custom system message intro | | mode | "standalone" \| "inline" | "standalone" | Output mode | | customRules | string[] | [] | Additional rules | | editModes | EditMode[] | ["merge"] | Edit modes to document |

createYamlTransform(options?)

Creates a TransformStream that converts YAML spec/edit fences in AI SDK stream chunks into json-render patch data parts.

| Option | Type | Description | |--------|------|-------------| | previousSpec | Spec | Seed with a previous spec for multi-turn edit support |

pipeYamlRender(stream, options?)

Convenience wrapper that pipes an AI SDK stream through the YAML transform. Drop-in replacement for pipeJsonRender from @json-render/core.

createYamlStreamCompiler(initial?)

Create a streaming YAML compiler that incrementally parses YAML text and emits JSON Patch operations.

Returns YamlStreamCompiler<T> with methods:

| Method | Description | |--------|-------------| | push(chunk) | Push a chunk of text. Returns { result, newPatches } | | flush() | Flush remaining buffer and return final result | | getResult() | Get the current compiled result | | getPatches() | Get all patches applied so far | | reset(initial?) | Reset to initial state |

Fence Constants

Exported constants for fence detection:

• YAML_SPEC_FENCE — ```yaml-spec
• YAML_EDIT_FENCE — ```yaml-edit
• YAML_PATCH_FENCE — ```yaml-patch
• DIFF_FENCE — ```diff
• FENCE_CLOSE — ```

Re-exports from @json-render/core

• diffToPatches(oldObj, newObj) — Generate RFC 6902 JSON Patch from object diff
• deepMergeSpec(base, patch) — RFC 7396 JSON Merge Patch