Crate mxblocks 

mxblocks: structured extras (“blocks”) on an ordinary Matrix m.room.message (buttons, chips, tables, charts, cards, progress, …), under the content key RICH_KEY. Clients that know the key (the Element Web module in packages/mxblocks-element/) render it; everyone else sees body/formatted_body and can use reactions, so the text must stand alone. Normative spec: docs/spec.md.

"com.ianm.mtrix": {
  "v": 1,
  "blocks": [
    { "type": "buttons", "buttons": [
      { "label": "Send", "style": "primary", "action": { "type": "react", "key": "✅" } },
      { "label": "Drop", "style": "danger",  "action": { "type": "react", "key": "❌" } }
    ] },
    { "type": "table", "columns": ["item", "price"], "rows": [["A", 10]] }
  ]
}

A react action makes the client send an m.reaction annotation with key on the message; a send action sends body as a message from the clicking user. Action blocks (buttons, chips) are typed. Display blocks (DISPLAY_TYPES) are carried as JSON and only checked for their required fields and size; the renderer parses them defensively anyway. Unknown block types load as Block::Unknown (so newer payloads still deserialize) but don’t Rich::validate.

A stream block marks a reply the sender is still writing: {"type": "stream", "id": "<id>", "url": "https://…/stream/<id>", "state": "live"}, "done" in the final edit. The renderer may follow url (SSE) while it is live; the body is the fallback, kept current by edits.

Content keys

Default readers accept RICH_KEYS. Writers use WriteKey (including caller-selected keys), while ContentKeys configures both the write key and the exact read aliases. Applications can choose their own namespace.

Structs

Button

One button or chip: a label and what a click does.

ContentKeys

A writer namespace and an explicit, ordered set of reader namespaces.

Math

A math block’s TeX and whether it is display math (the default).

Prompts

The items of a buttons/chips block plus the fields every block may carry. Shaped after MSC4139 m.prompts: the items are preset prompts with stable ids, scope lists who may answer.

Rich

A rich payload: the object stored under the content key ({"v":1,"blocks":[...]}).

Enums

Action

What a button click does, tagged by type on the wire.

Block

One entry of blocks, tagged by its type field on the wire.

Kind

The JSON kind a required display-block field must have.

StreamState

A stream block’s state.

Style

A button’s look.

WriteKey

Which key a writer puts the payload (and a click’s .used, and an album’s .album) under. Default readers accept the public compatibility keys; use ContentKeys for custom reader namespaces.

Constants

ALBUM_KEYS

<key>.album: the gallery marker on album images, for every key in RICH_KEYS, in the same order.

BLOCK_VERSION

The block version every block type is at.

DISPLAY_TYPES

JSON block types (display blocks, plus form), with the fields each must have (docs/spec.md).

FORM_KINDS

The field kinds a form may use (fields[].kind).

FORM_REPLY_FORMAT

What a submit click sends (documentation; the Element module builds it).

MAX_BLOCKS

Blocks in one payload.

MAX_BLOCK_BYTES

Serialized size of one display block, in bytes.

MAX_BUTTONS

Buttons in one buttons block.

MAX_CAPTION

Captions, alt texts and gallery titles, in characters.

MAX_CARD_ACTIONS

card.actions (ChatGPT Apps SDK: an inline card has at most 2 actions).

MAX_CAROUSEL

Items in cards (ChatGPT inline carousel: 3 to 8; fewer render as single cards).

MAX_CAROUSEL_ACTIONS

Actions per carousel item.

MAX_CHIPS

Chips in one chips block.

MAX_FALLBACK

A block’s fallback text, in characters.

MAX_FILE_NAME

A file name, in characters.

MAX_FORM_FIELDS

Fields in one form.

MAX_FORM_OPTIONS

Options in one select or radio field.

MAX_FORM_TEXT

A text field’s maxlength cap (and default).

MAX_GALLERY

Most images in a gallery.

MAX_KEY

A reaction key, in characters.

MAX_LABEL

Button, chip and form labels, in characters: a whole sentence, which the renderer wraps.

MAX_MATH_LINE

math.alt / math.caption, in characters.

MAX_OPTION_VALUE

An option’s value, in characters.

MAX_PAYLOAD_BYTES

Serialized size of the whole payload, in bytes (Matrix caps the whole event at 65536, and body/formatted_body need room too).

MAX_PREVIEW_BYTES

A file block’s preview, in bytes (UTF-8).

MAX_PREVIEW_LINES

A file block’s preview: the first lines of a text file.

MAX_SAFE_INT

The largest integer canonical JSON allows (2^53 - 1); the smallest is its negation.

MAX_SCOPE

scope entries.

MAX_SEEDS

Reaction seeds on one message.

MAX_SEND_BODY

In UTF-16 code units, as the Element module (JS length) counts.

MAX_STREAM_ID

Longest stream block id.

MAX_TEX

math.tex, in characters (the reference math renderer refuses longer input too).

MAX_TRACKER_ITEMS

tracker.items.

MAX_TRACKER_STAGES

tracker.stages.

MIN_GALLERY

Images in a gallery (validation refuses fewer or more; renderers draw 1 and drop past 20).

RICH_KEY

The content key written today (WriteKey::Legacy, the default).

RICH_KEYS

Every content key a reader must accept, in the order to try them.

RICH_KEY_NEW

The new content key (WriteKey::New). Readers accept it now; writers switch to it once every renderer they target reads it.

RICH_VERSION

The only payload version so far.

STEP_STATUSES

progress.steps[].status and tracker.stages[].status.

TRACKER_KINDS

tracker.kind.

TRACKER_STATES

tracker.state; the final edit sets done or cancelled.

USED_KEYS

<key>.used: what a click sent (on the clicking user’s message), for every key in RICH_KEYS, in the same order.

Functions

canonical_content

content (a whole event content, m.new_content included) as canonical JSON, ready to send: floats become integers or decimal strings (canonical_numbers). Borrowed when it has no float; also borrowed, unchanged, when it can’t be fixed (an integer beyond ±MAX_SAFE_INT), so the homeserver’s own error reaches the caller.

canonical_numbers

Every number in v (any JSON, e.g. a whole event content with its m.new_content) made canonical: number::canonicalize from the top.

canonicalize_value

Rewrites every number in v for canonical JSON: a float with no fractional part in range becomes an integer, any other float its shortest decimal string (62.99 → "62.99"). Integers outside ±(2^53 - 1) are an error (they would be rejected by the homeserver), as are NaN/Inf.

form_fallback

A plain-text fallback for a (valid) form, for body: the title, each field numbered with its options numbered, and how to answer by typing, e.g.

from_args

The payload from --button specs (one buttons block) or a --rich JSON text (not both); None when neither is given.

from_args_math

from_args plus --math: the math block first, then the buttons (--rich with --math is refused: put the math block in the JSON).

has_float

Whether v has a float anywhere (cheap check before canonical_numbers).

html_escape

Escapes text for an HTML text node or a double-quoted attribute.

image_size

Width and height of a PNG, GIF, JPEG or WebP from its header, for info.w/info.h (Element X sizes the image tile before loading it).

is_decimal

^-?\d+(\.\d+)?([eE][-+]?\d+)?$.

is_mxc

mxc://server/mediaId (the renderer’s check, byte for byte).

is_num

A numeric field’s value: an integer in ±(2^53 - 1) or a decimal string.

math_block

A math block (--math TEX [--inline]).

non_canonical

The path of the first float or out-of-range integer in v, if any.

norm_key

A reaction key as compared: without the U+FE0F variation selector (clients add or drop it).

parse_button

A --button spec: [STYLE:]LABEL=react:KEY or [STYLE:]LABEL=send:BODY, STYLE one of primary, danger, default. The label can’t contain = (use --rich for that).

parse_seeds

--react-seed KEYS: comma-separated keys; "" or none: no seeds.

read_album

An album marker under any of ALBUM_KEYS (newest first).

read_rich

The payload of an event content under any of RICH_KEYS: the first key, newest first, whose value deserializes. Not validated: the payload may come from a newer sender (unknown blocks load as crate::Block::Unknown).

read_used

A click’s .used echo under any of USED_KEYS (newest first).

rich_from_value

A payload from JSON, made canonical (Rich::canonicalize) and validated, as Rich::parse does with text.

rich_value

The raw payload of an event content under any of RICH_KEYS (the newest key present wins), with the key it was under.

seeds

The reactions to seed: given (--react-seed), else the react keys.

strip_rich

Removes the payload under every key in RICH_KEYS (an edit that drops the blocks). Whether any was there.

text_preview

The start of a text file for a file block’s preview: at most MAX_PREVIEW_LINES lines and MAX_PREVIEW_BYTES bytes, cut at a character boundary. None for binary data (a NUL, or invalid UTF-8 before the cut) and for blank text.

validate_id

An MSC4139 prompt id (buttons, forms, form fields): 1 to 64 of [A-Za-z0-9_.:-].

validate_key

A reaction key: 1..=MAX_KEY characters, no whitespace.

validate_seeds

Reaction seeds: valid keys, at most MAX_SEEDS, no duplicates.