Docs: clarify best practice for mixed inline message rendering with useJsonRenderMessage

[songkeys]

Hi json-render team,

I’m looking for guidance on the recommended rendering pattern when a single assistant message contains a mix of:

• text parts
• json-render spec data parts
• other parts such as reasoning / tool / source parts

The docs example seems "inline", but not truly mixed inline

The current useJsonRenderMessage(parts) example shows this pattern:

const { spec, text, hasSpec } = useJsonRenderMessage(message.parts);

return (
  <div>
    {text && <Markdown>{text}</Markdown>}
    {hasSpec && <MyRenderer spec={spec} />}
  </div>
);

This is clear for a message-level composition of:

• one merged text block
• one merged spec block

But it does not answer what the best practice is when the UI wants to preserve the relative ordering of parts inside the message.

For example, if a message contains something conceptually like:

1. text
2. tool part
3. more text
4. spec patch / spec part
5. more text
6. another spec patch

useJsonRenderMessage appears to merge all spec data parts into one final spec, which is great, but then it is unclear how the renderer is supposed to place that spec in a truly mixed inline layout.

Practical consequence

In our app, we iterate message.parts to render the full mixed message UI.

When we encounter spec parts, we only want to render the merged spec once, so we ended up needing local guard logic to avoid rendering the same final spec multiple times.

That works, but it feels like a workaround rather than an obvious best practice.

Question

What is the intended / recommended pattern for "mixed inline" rendering?

Should consumers:

1. Ignore the exact spec-part position and render the merged spec once per message?
2. Render the merged spec at the first spec-part position and ignore subsequent spec parts?
3. Treat spec parts as standalone blocks in some other recommended way?
4. Use a different API for this use case?

Suggestion

It would help a lot to have either:

• a docs example for rendering a message with interleaved text + tools + sources + spec parts, or
• a helper API that returns render-ready segments for mixed inline rendering, instead of only { text, spec, hasSpec }.

Right now the existing example reads more like "message-level inline" than a full mixed-inline example for part-by-part rendering.

Thanks — even a short note on the intended pattern would help.