Module media 

IM.3 — the descriptor for an inline media block.

An image (later: a LaTeX fragment, a chart) drawn where it appears in the buffer. Design: docs/dev/architecture/inline-media.md.

The shape is BrandingBlock’s, deliberately

A media block is a contiguous group of virtual rows tagged VirtualRowKind::MediaBlock, carrying ordinary cells that spell out the alt text. The GPUI peer intercepts the group and paints an image over the region instead; the TUI peer paints the cells it was given and needs no code at all.

That is exactly how the dashboard’s branding block already works, and it is why the TUI stays a first-class peer for a feature it cannot render: the fallback is not a special case bolted on afterwards, it is what the rows literally contain.

Why the descriptor names a path and not bytes

Three reasons, and none of them is size alone:

• The UI thread must not decode. A descriptor is cheap to build and cheap to publish; the read + decode happens off-thread (IM.4) and lands through the inbound primitive. Handing around bytes invites decoding wherever they are needed.
• Capability gating stays host-side. A plugin (IM.6) names a file and the host decides whether that plugin may read it. If the guest sent pixels, it could put anything on screen regardless of its fs:read grant.
• The cache has a key. (path, mtime, target size) is a cache key; an opaque buffer is not.

Why rows is authoritative and intrinsic is not

rows — the reserved display-row count — is what the core’s scroll arithmetic uses, and both peers agree on it. intrinsic is the image’s natural pixel size, known only once something has read the file header, and only meaningful to a peer that draws pixels.

Keeping the row count authoritative is what lets a document have the same number of display rows on both peers while only one shows a picture. It is also what stops a decoding image from reflowing the buffer: the block reserves its space before its pixels exist.

Structs

MediaBlock

An inline media block: what to draw, how big, and what to say instead.

Enums

MediaFit

How the intrinsic size maps into the block’s box.

MediaSource

Where a block’s pixels come from.

Functions

media_block_rows

Build the virtual rows for a media block anchored below anchor_line.

Type Aliases

MediaBlockRef

Shared handle — blocks are cloned into every row of their group.