Documentation Index
Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
Use this file to discover all available pages before exploring further.
A Playground Definition is a JSON object mapping heavily to the Workflow Definition structure, but it is explicitly designed to define customizable, interactive application layouts rather than invisible backend processes.
High-Level Structure
Every Playground Definition uses the following JSON signature:
{
"type": "playground_definition",
"version": "1.1.0",
"layout": {
// Layout block — see "Layout Types" below for the allowed shapes
},
"components": [
// Array of UI Widget Objects
],
"connections": [
// Array of Interactive Connections
]
}
Top-Level Properties
| Property | Type | Description |
|---|
type | string | Constant identifier. Must be exactly "playground_definition". |
version | string | Schema version. Currently "1.1.0". Definitions created before this version may carry "1.0.1" and have no layout block — see Layout Types. |
layout | object | Layout type and configuration. See Layout Types below. Optional for backwards compatibility — if absent, the definition is treated as {"type": "free_form"}. |
components | array | A list of distinct interactive UI instances to render (e.g., chat boxes, charts). |
connections | array | A list of connections describing interaction pathways between widgets or external resources. |
Layout Types
A Playground Definition is rendered with one of two layouts. The layout type is chosen when the playground is created and is immutable — it cannot be changed later. Attempting to upload a definition whose layout block differs from the persisted layout will fail with invalid_layout.
The default. Widgets are positioned with absolute pixel coordinates on a 2D canvas; widget size comes from width / height ports declared per-widget. Suited to ad-hoc canvases where widgets are placed anywhere by drag-and-drop.
{
"type": "playground_definition",
"version": "1.1.0",
"layout": {
"type": "free_form",
"zoom": 1.25
},
"components": [ /* ... */ ],
"connections": []
}
layout block, version: "1.0.1") is equivalent to {"type": "free_form"} and continues to be served as-is. Newly created free-form playgrounds always carry the explicit layout block.
zoom is optional on free-form layouts as well — same range and semantics as in grid (see zoom below): the value is the canvas zoom level the user last saved, and it’s the only mutable field on layout.
Grid Layout
Widgets are placed on a fixed-column grid. Widget position and size are expressed in grid units rather than pixels, and the grid configuration (columns, row_height) is set at creation time.
{
"type": "playground_definition",
"version": "1.1.0",
"layout": {
"type": "grid",
"columns": 12,
"row_height": 30,
"margin": [10, 10],
"container_padding": [10, 10],
"zoom": 1.25
},
"components": [ /* ... */ ],
"connections": []
}
layout Properties (grid)
| Property | Type | Description |
|---|
type | string | Must be exactly "grid". |
columns | integer | Number of columns the grid is divided into. Range: 4–128. Required at creation. |
row_height | integer | Row height in pixels. Range: 10–200. Required at creation. |
margin | array of 2 integers | Optional. Horizontal and vertical margin between widgets, in pixels. Defaults to [10, 10]. |
container_padding | array of 2 integers | Optional. Padding around the canvas, in pixels. Defaults to [10, 10]. |
zoom | number | Optional. Last user zoom setting; mutable across uploads. Range: 0.5–2. Defaults to 1 if absent. Also valid on free-form layouts. |
columns, row_height, margin, container_padding) are immutable for the lifetime of the playground. Only zoom may be updated freely.
Just like Workflow Components, Playground widgets rely on interfaces to define their behavior. However, they generally pertain to user-facing interactions.
The shape of each component’s position field depends on the layout type.
{
"id": "302e66bc-8b8b-4d49-a88d-500f8c422f8d",
"category": "widget",
"type": "widget.tradingview",
"name": "TradingView Chart",
"ports": [
{
"category": "data_input",
"route": "message",
"value": {
"type": "component_alias",
"alias": "ticker_viz_AAPL_1m"
}
},
{
"category": "data_input",
"route": "width",
"value": {
"type": "integer",
"integer": 700
}
},
{
"category": "data_input",
"route": "height",
"value": {
"type": "integer",
"integer": 500
}
}
],
"position": {
"x": -3341.5386043389353,
"y": -1843.5798926414566
}
}
position.x and position.y are pixel coordinates on the canvas (negative values are valid — they correspond to panning offsets). Widget size is read from the width / height ports.
Grid Component
{
"id": "302e66bc-8b8b-4d49-a88d-500f8c422f8d",
"category": "widget",
"type": "widget.tradingview",
"name": "TradingView Chart",
"ports": [
{
"category": "data_input",
"route": "message",
"value": {
"type": "component_alias",
"alias": "ticker_viz_AAPL_1m"
}
}
],
"position": {
"x": 0,
"y": 0,
"width": 6,
"height": 6,
"min_width": 2,
"min_height": 2
}
}
position field carries grid-unit coordinates and dimensions:
| Property | Type | Description |
|---|
x | integer | Column index of the widget’s top-left corner (0-based). |
y | integer | Row index of the widget’s top-left corner (0-based). |
width | integer | Widget width in grid columns. Required. |
height | integer | Widget height in grid rows. Required. |
min_width | integer | Optional minimum width in columns. |
max_width | integer | Optional maximum width in columns. |
min_height | integer | Optional minimum height in rows. |
max_height | integer | Optional maximum height in rows. |
position.x + position.width must not exceed layout.columns. Violations are rejected with invalid_component_position.
Grid components do not carry width / height ports — widget size is derived from the grid units and the playground’s row_height / column width.
