json-render/packages/yaml

@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