@type control() :: {:control, attrs :: control_attrs()}

A control widget.

All controls have the following properties:

• :type - one of the recognised control types

• :ref - a unique identifier

• :destination - the process to send event messages to

On top of that, each control type may have additional attributes.

events

Events

All control events are sent to :destination as {:event, id, info}, where info is a map including additional details. In particular, it always includes :origin, which is an opaque identifier of the client that triggered the event.

@type frame() :: {:frame, outputs :: [t()], frame_info()}

Outputs placeholder.

Frame with type :default includes the initial list of outputs. Other types can be used to update outputs within the given frame.

In all cases the outputs order is reversed, that is, most recent outputs are at the top of the stack.

@type grid() :: {:grid, outputs :: [t()], grid_info()}

Multiple outputs arranged in a grid.

@type ignored() :: :ignored

An empty output that should be ignored whenever encountered.

@type image() :: {:image, content :: binary(), mime_type :: binary()}

A raw image in the given format.

pixel-data

Pixel data

Note that a special image/x-pixel MIME type is supported. The binary consists of the following consecutive parts:

• height - 32 bits (unsigned big-endian integer)
• width - 32 bits (unsigned big-endian integer)
• channels - 8 bits (unsigned integer)
• data - pixel data in HWC order

Pixel data consists of 8-bit unsigned integers. The number of channels can be either: 1 (grayscale), 2 (grayscale + alpha), 3 (RGB), or 4 (RGB + alpha).

@type input() :: {:input, attrs :: input_attrs()}

An input field.

All inputs have the following properties:

• :type - one of the recognised input types

• :ref - a unique identifier

• :id - a persistent input identifier, the same on every reevaluation

• :label - an arbitrary text used as the input caption

• :default - the initial input value

• :destination - the process to send event messages to

On top of that, each input type may have additional attributes.

@type js() :: {:js, info :: js_info()}

JavaScript powered output with dynamic data and events.

See Kino.JS and Kino.JS.Live for more details.

@type js_info() :: %{
  js_view: js_view(),
  export: nil | %{info_string: String.t(), key: nil | term()}
}

Data describing a JS output.

export

Export

The :export map describes how the output should be persisted. The output data is put in a Markdown fenced code block.

• :info_string - used as the info string for the Markdown code block

• :key - in case the data is a map and only a specific part should be exported

@type js_view() :: %{
  ref: ref(),
  pid: Process.dest(),
  assets: %{
    archive_path: String.t(),
    hash: String.t(),
    js_path: String.t(),
    cdn_url: String.t() | nil
  }
}

A JavaScript view definition.

JS view is a component rendered on the client side and possibly interacting with a server process within the runtime.

• :ref - unique identifier

• :pid - the server process holding the data and handling interactions

assets

Assets

The :assets map includes information about the relevant files.

• :archive_path - an absolute path to a .tar.gz archive with all the assets

• :hash - a checksum of all assets in the archive

• :js_path - a relative asset path pointing to the JavaScript entrypoint module

• :cdn_url - an absolute URL to a CDN directory where the asset files can be accessed from. Note that this URL is not guaranteed to be accessible, since it may be pointing to a private package

communication-protocol

Communication protocol

A client process should connect to the server process by sending:

{:connect, pid(), info :: %{ref: ref(), origin: term()}}

And expect the following reply:

{:connect_reply, payload, info :: %{ref: ref()}}

The server process may then keep sending one of the following events:

{:event, event :: String.t(), payload, info :: %{ref: ref()}}

The client process may keep sending one of the following events:

{:event, event :: String.t(), payload, info :: %{ref: ref(), origin: term()}}

The client can also send a ping message:

{:ping, pid(), metadata :: term(), info :: %{ref: ref()}}

And the server should respond with:

{:pong, metadata :: term(), info :: %{ref: ref()}}

@type markdown() :: {:markdown, binary()}

Markdown content.

@type plain_text() :: {:plain_text, binary()}

Plain text content.

Similar to markdown/0, but with no special markup.

@type stdout() :: {:stdout, binary()}

IO text output, adjacent such outputs are treated as a whole.

Supports ANSI escape codes.

@type t() ::
  ignored()
  | stdout()
  | text()
  | plain_text()
  | markdown()
  | image()
  | js()
  | frame()
  | tabs()
  | grid()
  | input()
  | control()

Livebook cell output may be one of these values and gets rendered accordingly.

@type tabs() :: {:tabs, outputs :: [t()], tabs_info()}

Multiple outputs arranged into tabs.

@type text() :: {:text, binary()}

Standalone text block visually matching stdout/0.

Supports ANSI escape codes.