Widget Taxonomy
Data (widget.message*, widget.html)
Widgets intentionally focused on rendering discrete variables and histories outputted by AI workflows.
widget.message: Singularly renders one complete message object payload (ideal for rendering a final output response). Supports Markdown, JSON, and Raw views.widget.messages: Capable of mapping and rendering an entire chronological array of message objects dynamically as a scrolling list.widget.html: Renders a standalone HTML document carried in amessagesession object, in a sandboxed frame that follows the app’s light or dark theme. Seewidget.html.
Controls (widget.chat)
Interactive widgets granting user control over data injection straight into active workflow endpoints or components.
widget.chat: A rich text entry prompt featuring a submission button. Specifically designed to dispatch user messages dynamically to a nominatedworkflow_aliasrunning an agent or chat session. The port’s value type keeps the nameworkflow_alias— renaming it would silently reset every saved selection — but it also accepts the path form for a definition anywhere the caller can read, not only a bare alias in the session’s own revision. A previously saved bare alias is still a valid value; nothing needs migrating.
Session Objects (widget.thread, widget.graph)
Widgets that bind to live session objects and render their state in real time.
widget.thread: Renders an append-only thread of messages with live tail. Displays items as they are posted to the thread session object, supporting Markdown, JSON, and Raw views. The composer attaches files by its+menu, drag-drop, and clipboard paste, placing each at its point in the text.widget.graph: Renders an interactive property graph with configurable layout and traversal. Binds to a graph session object and supports complete or subset display modes.
Financial (widget.tradingview)
Targeted components for financial developers and analytical traders.
widget.tradingview: Instantiates a fully functional instance of TV’s charting library bound directly to streaming market data or historical symbols provided.
widget.html
Renders a standalone HTML document, carried in a message session object, inside a sandboxed frame.
The frame
The document runs sandboxed: withallow-scripts, or with no permissions when scripts is disabled, and never
allow-same-origin. It has an origin of its own, cannot reach the app or its storage, and sends no referrer.
Light and dark
The frame tells the document which theme the app is showing, and keeps it current:- The document’s
<html>carriesdata-theme="light"ordata-theme="dark"from the first byte: the app’s resolved theme, neversystem. The frame owns this attribute. Adata-themethe document writes on its own<html>has no effect, and its other attributes, such aslang, are kept. - With scripts enabled, a theme change updates
data-themein place, andwindowthen receives ablobhub:settingsevent whosedetailis{ theme }. The document is not reloaded, so a running page keeps its state. - With scripts disabled, a theme change reloads the document with the new attribute.
- A document that does not style for
data-themeis shown as it is today: light, whatever the app’s theme. prefers-color-schemeinside the frame does not follow the app. Usedata-theme.
color-scheme: dark is there to darken the frame’s own backdrop, scrollbars and form controls.
The blobhub:settings event fires only when the theme changes, so a script that draws reads data-theme once at start, as the example does.
widget.thread
Renders an append-only thread of messages with live tail. Items posted to the bound thread session
object appear in the widget in real time as they arrive.
Attachments
The composer attaches files three ways: the+ menu, dragging a file onto the composer, and pasting
from the clipboard. Before upload, the widget applies the same checks the server enforces — 4 MiB per
file, 10 files per thread item, and the file session object’s content-type allow-list
— so a rejected file is caught client-side rather than round-tripping to the API.
Attaching also marks where the file belongs in the message. A [name] token is inserted at the cursor,
and on send the posted content[]
interleaves each file block at its token’s position — so a file lands where it was placed in the text
rather than after it. The token edits and deletes as a single unit, and removing an attachment from the
composer takes its token with it; a file left with no token in the text is appended at the end.
Rendering depends on the attached file’s content type:

