Bridge protocol

Hugs › Reference

A hug’s page and its host (the Hub page, or cliqd’s local page) talk only through postMessage. Every message is a JSON object { v, type, id?, … }, checked against its schema on both sides. The runtime API sends and receives these for you; this page is for reading traffic, or writing a host. Version: v: 1. The page lists the versions it speaks in ready, the host lists its own in init, and both use the highest they share — or the page fails with protocol_unsupported.

Host → page

`type`	When	Carries
`init`	after `ready`	`protocols` (the host’s), `hug` (`id`, `name`, `title`, `summary`, `status`, `expires_at`, `requester`, `run`), `params`, `files` (upload slots), `attachments`, `viewer` (`name`, `via`), `mine`, `viewing`, `draft`, `progress`, `theme`, `locale`, `mode`
`update`	the open Hug changes	`progress`, `expires_at`
`status`	it closes, expires or is cancelled	`status`, `mode: "view"`, `viewing`
`mode`	the page switches between editing and showing an answer	`mode`; `viewing` (view), or `mine` and `draft` (answer)
`upload_result`	an upload finished	`id`, `ok`, `ref` or `error`
`file`	a read finished	`id`, `ok`, a `Blob` or `error`
`submit_result`	after Submit	`ok`, with the stored `answer` or `problems`

Page → host

`type`	Means	The host
`ready`	loaded; `protocols` it speaks	sends `init`
`values`	the current answer: `values`, `valid`, `problems?`, `submit?` (`{ label, tone }`), `summary?`	keeps it; draws Submit with that label, enabled while `valid`; sends `values` and `summary` when pressed
`upload`	`id`, `key` — a file for an upload slot	opens its file picker, uploads, replies `upload_result`
`read_file`	`id`, `ref`	fetches it with the viewer’s permissions, replies `file`
`download`	`ref`	saves it for the person
`open_link`	`url` (`http`/`https`)	opens it if it’s in the params, else shows it first
`resize`	`height`	sets the frame height

In view mode the host ignores values, upload and Submit. Not in the protocol, on purpose: submitting (the host’s button), network, navigation, storage, other people’s answers.

The host’s checks


Source	Messages only from the frame’s own window, origin `"null"` (the sandbox)
`values`	At most 256 KB; file references only ones the host returned for a declared slot (or, when changing an answer, ones in `mine`)
`upload`	Only for declared slots
`read_file`	Only the Hug’s attachments, the viewer’s own uploads, and the files of the answer being shown
`submit.label`	Plain text, at most 40 characters
Rates	`values` at most 20 a second (the last wins); one file picker and one link dialog at a time; 10 reads at once, 50 MB per page

CliqHub checks uploads, reads and answers again.

Start

Hugs

Agents

CLI

Integrations

Bridge protocol

Host → page

Page → host

The host’s checks

​Host → page

​Page → host

​The host’s checks

Host → page

Page → host

The host’s checks