Decorations

Declare decorations to add content below messages, next to authors’ names and next to names in the member list. The plugin describes blocks and FluxPlugs draws them in Fluxer’s style. Plugin code never touches the page.

Register a provider

cleanup.push(
  await api.decorations.registerProvider(
    { surfaces: ["messageAccessory", "memberRow"] },
    (request) => ({
      decorations: request.anchors.map((anchor) => ({
        key: anchor.key,
        blocks:
          anchor.kind === "message"
            ? [
                {
                  kind: "text",
                  text: "Posted in #" + anchor.channelId,
                  tone: "muted",
                },
                { kind: "button", id: "thanks", label: "Thanks" },
              ]
            : anchor.bot
              ? [{ kind: "badge", label: "AUTO", color: "#5865f2" }]
              : [],
      })),
    }),
    async (action) => {
      if (action.blockId === "thanks") await api.ui.notify("Thanked!");
    },
  ),
);

Surface	Where	Blocks allowed
messageAccessory	Below a message’s content and embeds, above its reactions	Up to 8, any kind
messageHeader	After the author’s name and badges	Up to 3, text and badge
memberRow	After a name in the member list and its badges	Up to 3, text and badge

Grouped follow-up messages have no header, so they get no header content. Messages from blocked users get nothing.

What the provider hears

FluxPlugs asks about places on screen, up to 25 at a time, and remembers the answers. Each anchor has a key to return with your blocks.

• message anchors: messageId, channelId, guildId, authorId, type (Fluxer’s message type name), flags, and text only with the message_content capability.
• member anchors: guildId, userId, bot and self.

Names are never included. A place is asked about again when its flags change, or its text with message_content, for example after an edit.

The pending flag is true while Fluxer hasn’t confirmed a message: it is still sending, or failed. Once sent, Fluxer replaces the placeholder with the confirmed message, which has a new id, so count or act on a message only once pending is false. Call api.decorations.refresh(keys?) after your own data changes; calls merge and run at most twice a second.

Leave a key out of your answer, or return no blocks, to show nothing there.

Blocks

kind	Fields	Notes
text	text up to 200, tone: normal, muted, positive, warning, danger	Always plain text
badge	label, color, icon, tooltip	Same rules as role badges
button	id, label up to 40, primary	Clicks reach onAction and count as a user action
link	label up to 40, url	Needs external_links and a public HTTPS address, otherwise shown as text
image	handle from images.load, alt, width up to 400, height up to 240	Needs images; the handle must still be yours
progress	value, max (default 1), label, color	A meter bar

A message accessory holds at most 2 images and 4 buttons or links, and each place’s blocks are at most 2 KiB as JSON. An entry that breaks a rule is dropped on its own; the rest of the answer still counts.

Every group of blocks carries a tooltip naming your plugin, and styling comes from FluxPlugs, not from the plugin. Badge labels that read as Fluxer’s own tags are refused.

Answering in time

The provider has one second per batch and at most two batches waiting. A failed batch is tried again after 30 seconds; after five failures in a row, FluxPlugs leaves the provider alone for a minute. Answer from data you already have and fetch in the background, then call refresh.

A plugin has one provider. Registering again fails with decoration_provider_exists until the first is disposed. decorations_unavailable means the runtime can’t draw decorations on this page.

Privacy

A decorations plugin learns the ids of messages, authors and members on screen, even without the user clicking anything. With message_content it also reads the text of messages on screen. Together with images, which fetches any public address, or network, which reaches the plugin’s listed hosts, that data could leave the computer, so review such plugins carefully.