Documentation mismatch: useUIStream expects JSONL patch format but API route example outputs plain JSON

[vkboo]

Problem

The documentation for API route setup in AI SDK Integration and Streaming shows a simple example that directly returns result.textStream:

// From docs (https://json-render.dev/docs/ai-sdk)
export async function POST(req: Request) {
  const { prompt } = await req.json();
  const systemPrompt = generateCatalogPrompt(catalog);

  const result = streamText({
    model: 'anthropic/claude-haiku-4.5',
    system: systemPrompt,
    prompt,
  });

  return new Response(result.textStream, {
    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
  });
}

I followed this pattern with a minor difference (using @ai-sdk/openai provider instead of AI Gateway string format):

// My implementation
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { generateCatalogPrompt } from '@json-render/core';
import { catalog } from '@/lib/catalog';

export async function POST(req: Request) {
  const { prompt } = await req.json();
  const systemPrompt = generateCatalogPrompt(catalog);

  const result = streamText({
    model: openai('gpt-5.2'),  // Using @ai-sdk/openai provider
    system: systemPrompt,
    prompt,
  });

  return new Response(result.textStream, {
    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
  });
}

Actual Output

The AI model outputs nested JSON (not JSONL patch format):

{
  "type": "Card",
  "props": {
    "title": "Claim Form"
  },
  "children": [
    {
      "type": "Text",
      "props": {
        "text": "Please review your details and submit your claim."
      }
    },
    {
      "type": "Button",
      "props": {
        "text": "Submit Claim",
        "action": {
          "type": "submit"
        }
      }
    }
  ]
}

Expected Format by useUIStream

However, looking at the source code of useUIStream, it expects JSONL patch format (one JSON patch per line):

{"op":"set","path":"/root","value":"el-1"}
{"op":"add","path":"/elements/el-1","value":{"key":"el-1","type":"Card","props":{...}}}
{"op":"add","path":"/elements/el-2","value":{"key":"el-2","type":"Text","props":{...},"parentKey":"el-1"}}

The hook parses each line as a patch operation:

// From @json-render/react source
const lines = buffer.split("\n");
for (const line of lines) {
  const patch = parsePatchLine(line);
  if (patch) {
    currentTree = applyPatch(currentTree, patch);
  }
}

Result

When following the documentation example:

1. AI model outputs nested JSON (as shown above)
2. useUIStream tries to parse each line as a JSON patch
3. Parsing fails because the format doesn't match
4. tree remains { root: "", elements: {} } (empty)
5. Nothing renders on the page

Environment

• @json-render/core: ^0.3.0
• @json-render/react: ^0.2.0
• ai: ^6.0.44
• @ai-sdk/openai: latest

[KayneWang]

I have the same problem.

[ubmit]

Unfortunately the docs are misleading in this part. What I would suggest is to look at the examples available in the repo: the landing page demo and the dashboard. You'll notice that const systemPrompt = generateCatalogPrompt(catalog); won't be enough, as this only generates something like:

   '# unnamed Component Catalog\n' +
    '\n' +
    '## Available Components\n' +
    '\n' +
    '### Card\n' +
    '\n' +
    '### Button\n' +
    '\n' +
    '### Text\n' +
    '\n' +
    '## Available Actions\n' +
    '\n' +
    '- `submit`\n' +
    '- `navigate`\n' +
    '\n' +
    '## Visibility Conditions\n' +
    '\n' +
    'Components can have a `visible` property:\n' +
    '- `true` / `false` - Always visible/hidden\n' +
    '- `{ "path": "/data/path" }` - Visible when path is truthy\n' +
    '- `{ "auth": "signedIn" }` - Visible when user is signed in\n' +
    '- `{ "and": [...] }` - All conditions must be true\n' +
    '- `{ "or": [...] }` - Any condition must be true\n' +
    '- `{ "not": {...} }` - Negates a condition\n' +
    '- `{ "eq": [a, b] }` - Equality check\n' +
    '\n' +
    '## Validation Functions\n' +
    '\n' +
    'Built-in: `required`, `email`, `minLength`, `maxLength`, `pattern`, `min`, `max`, `url`\n'

So the LLM will have no idea about which format should be used for the output and it's totally blind regarding what they are expected to do. Here's an example of a system prompt that would actually give you the expected result:

You are a UI generator that outputs JSONL (JSON Lines) patches.

AVAILABLE COMPONENTS:
Card, Button, Text

COMPONENT DETAILS:
- Card: { title: string, description?: string | null } - Container with title, can have children
- Button: { label: string, action: string, params?: object, variant?: "default" | "outline" | "ghost", size?: "default" | "sm" | "lg" } - Clickable button that triggers an action
- Text: { content: string } - Text paragraph

ACTIONS (use these for Button action):
- submit: params { formId: string }
- navigate: params { url: string }

OUTPUT FORMAT:
Output JSONL where each line is a patch operation. Use a FLAT key-based structure:

OPERATIONS:
- {"op":"set","path":"/root","value":"main-card"} - Set the root element key
- {"op":"add","path":"/elements/main-card","value":{...}} - Add an element by unique key

ELEMENT STRUCTURE:
{
  "key": "unique-key",
  "type": "ComponentType",
  "props": { ... },
  "children": ["child-key-1", "child-key-2"]  // Array of child element keys (only for Card)
}

RULES:
1. First set /root to the root element's key
2. Add each element with a unique key using /elements/{key}
3. Parent elements list child keys in their "children" array
4. Stream elements progressively - parent first, then children
5. Each element must have: key, type, props
6. Children array contains STRING KEYS, not nested objects
7. Only Card can have children

EXAMPLE - Welcome Card:
{"op":"set","path":"/root","value":"welcome-card"}
{"op":"add","path":"/elements/welcome-card","value":{"key":"welcome-card","type":"Card","props":{"title":"Welcome","description":"Hello there!"},"children":["greeting-text","action-btn"]}}
{"op":"add","path":"/elements/greeting-text","value":{"key":"greeting-text","type":"Text","props":{"content":"Thanks for visiting our app."}}}
{"op":"add","path":"/elements/action-btn","value":{"key":"action-btn","type":"Button","props":{"label":"Get Started","action":"navigate","params":{"url":"/home"}}}}

I went into more details on the issue #20