@azurioh/discord-kernel 0.1.0

package/src/discord/ui/card.ts

@@ -0,0 +1,303 @@
+import {
+	ActionRowBuilder,
+	ContainerBuilder,
+	MediaGalleryBuilder,
+	MediaGalleryItemBuilder,
+	SectionBuilder,
+	SeparatorBuilder,
+	SeparatorSpacingSize,
+	TextDisplayBuilder,
+	ThumbnailBuilder,
+} from "discord.js";
+import { type Button, createActionRow } from "@/discord/interaction/button";
+import type { AnySelectMenuBuilder } from "@/discord/interaction/select-menu";
+
+/** Discord refuses a message carrying more components than this, container included. */
+export const MAX_CARD_COMPONENTS = 40;
+
+/** Discord's cap on the characters carried by every `TextDisplay` in a message, summed. */
+export const MAX_CARD_TEXT_CHARACTERS = 4000;
+
+/** One image inside a `gallery` block. */
+export interface CardImage {
+	/** A URL, `attachment://` included for a file the message itself carries. */
+	readonly url: string;
+	readonly description?: string;
+	readonly spoiler?: boolean;
+}
+
+/**
+ * The two shapes an `entry` may carry besides its text, plus the bare one with
+ * neither.
+ *
+ * Modelled as a three-way union rather than one shape with two optional
+ * fields: Discord's `Section` accepts exactly **one** accessory, so `action`
+ * and `thumbnail` together is not a looser version of the block, it is an
+ * invalid one. A two-optional-field shape would only catch that at
+ * `apply()`, with Discord's own rejection as the first symptom; this union
+ * makes the combination fail to compile instead. Each arm carries the other
+ * field as `?: never` — without it, TypeScript's leniency on excess
+ * properties across a union (a property valid on *any* arm is accepted on
+ * all of them) would let both through anyway.
+ */
+export type CardEntryAccessory<S> =
+	| { readonly action?: never; readonly thumbnail?: never }
+	| { readonly action: Button<S>; readonly thumbnail?: never }
+	| { readonly action?: never; readonly thumbnail: string };
+
+/**
+ * What a compiled select menu must offer for a card to render it — `apply`
+ * only, never `onSelect`.
+ *
+ * `SelectMenu<B, I>` (the DSL's own compiled shape) is contravariant in `I`,
+ * so a `SelectMenu<StringSelectMenuBuilder, StringSelectMenuInteraction>` —
+ * what `createStringSelect` hands back — is not assignable to a version
+ * fixed at the union `AnySelectMenuInteraction`. A card never reads
+ * `onSelect` (that is wired separately, through the module's
+ * `ComponentRouter`), so this asks for nothing beyond what it actually
+ * calls, and every flavour of compiled select menu satisfies it as-is.
+ */
+export interface CardSelectMenu {
+	readonly id: string;
+	apply(forceDisabled?: boolean): AnySelectMenuBuilder;
+}
+
+/**
+ * One piece of a card, declared as data rather than built. `createCard`
+ * compiles a list of these into a `ContainerBuilder`, the same split
+ * `createButton`/`createModal`/`createStringSelect` keep between a
+ * definition and the builder it compiles to.
+ */
+export type CardBlock<S> =
+	| { readonly kind: "text"; readonly content: string }
+	| ({
+			readonly kind: "entry";
+			readonly title: string;
+			readonly lines?: readonly string[];
+	  } & CardEntryAccessory<S>)
+	| { readonly kind: "controls"; readonly buttons: readonly Button<S>[] }
+	| { readonly kind: "select"; readonly menu: CardSelectMenu }
+	| {
+			readonly kind: "separator";
+			readonly spacing?: "small" | "large";
+			readonly divider?: boolean;
+	  }
+	| { readonly kind: "gallery"; readonly images: readonly CardImage[] };
+
+export interface CardDef<S> {
+	/** The container's left-edge accent colour — see `EMBED_COLORS` for the bot's palette. */
+	readonly accent?: number;
+	/**
+	 * The card's content, top to bottom.
+	 *
+	 * `null` entries are accepted and skipped: a conditional block is declared
+	 * in place, at the position it would occupy, rather than assembled into a
+	 * separate array the caller builds beside this one and has to keep in
+	 * sync.
+	 */
+	readonly blocks: readonly (CardBlock<S> | null)[];
+}
+
+/**
+ * A compiled card: knows how to render itself for a given state. Mirrors
+ * `Button<S>.apply` (`src/core/discord/interaction/button.ts`) on purpose —
+ * same parameters, same meaning for `forceDisabled` — which is what lets
+ * `disabledControls` neutralise a card exactly the way it neutralises a
+ * button row: by applying it a second time with `true`, no special case
+ * required.
+ */
+export interface Card<S> {
+	apply(state: S, forceDisabled?: boolean): ContainerBuilder;
+}
+
+/**
+ * The text an `entry` block renders, whether it ends up alone in a
+ * `TextDisplay` or riding along inside a `Section`.
+ *
+ * Composed as one `TextDisplay` — the title in bold, then each line on its
+ * own row — rather than one `TextDisplay` per line: a `Section` holds at
+ * most three text children, so a title plus more than two lines would
+ * already be out of room, and a single block reads as one paragraph instead
+ * of a list of unrelated fragments.
+ */
+function entryContent<S>(block: Extract<CardBlock<S>, { kind: "entry" }>): string {
+	const lines = block.lines ?? [];
+	return lines.length === 0 ? `**${block.title}**` : `**${block.title}**\n${lines.join("\n")}`;
+}
+
+/** How many characters of the 4000-character `TextDisplay` budget a block spends. */
+function textCharacters<S>(block: CardBlock<S>): number {
+	if (block.kind === "text") {
+		return block.content.length;
+	}
+	if (block.kind === "entry") {
+		return entryContent(block).length;
+	}
+	return 0;
+}
+
+/** How many components a block compiles to, container itself excluded. */
+function componentCount<S>(block: CardBlock<S>): number {
+	switch (block.kind) {
+		case "text":
+			return 1;
+		case "entry":
+			// No accessory: one `TextDisplay`. Either accessory: the `Section`
+			// itself, its one `TextDisplay` child, and the accessory — three.
+			return block.action !== undefined || block.thumbnail !== undefined ? 3 : 1;
+		case "controls":
+			// The `ActionRow` plus every button it carries.
+			return 1 + block.buttons.length;
+		case "select":
+			// The `ActionRow` plus the menu itself.
+			return 2;
+		case "separator":
+			return 1;
+		case "gallery":
+			// Discord counts the gallery as one component; its items are data on
+			// it, not components of their own, the same way an embed's fields
+			// are not counted individually.
+			return 1;
+	}
+}
+
+/**
+ * Refuse a card Discord would refuse, naming what is over budget and by how
+ * much — the pattern `settings-editor.view.ts` (`assertFits`) already uses
+ * for a select menu's option cap. Checked once, at `createCard`, rather than
+ * at `apply()`: the block list does not vary with state, so failing here
+ * names the declaration instead of surfacing as a rejected message at
+ * whichever render happens to trip it first.
+ */
+function assertFitsBudget<S>(blocks: readonly CardBlock<S>[]): void {
+	// +1 for the container itself, which is a component in its own right.
+	const totalComponents = 1 + blocks.reduce((sum, block) => sum + componentCount(block), 0);
+	const totalCharacters = blocks.reduce((sum, block) => sum + textCharacters(block), 0);
+
+	const problems: string[] = [];
+	if (totalComponents > MAX_CARD_COMPONENTS) {
+		problems.push(
+			`${totalComponents} components (container included), Discord allows ${MAX_CARD_COMPONENTS} — ${
+				totalComponents - MAX_CARD_COMPONENTS
+			} over`,
+		);
+	}
+	if (totalCharacters > MAX_CARD_TEXT_CHARACTERS) {
+		problems.push(
+			`${totalCharacters} characters across its text, Discord allows ${MAX_CARD_TEXT_CHARACTERS} — ${
+				totalCharacters - MAX_CARD_TEXT_CHARACTERS
+			} over`,
+		);
+	}
+	if (problems.length > 0) {
+		throw new Error(`Card exceeds Discord's budget: ${problems.join("; ")}.`);
+	}
+}
+
+/** Render one `entry` block: a `Section` with an accessory, or a bare `TextDisplay`. */
+function applyEntry<S>(
+	container: ContainerBuilder,
+	block: Extract<CardBlock<S>, { kind: "entry" }>,
+	state: S,
+	forceDisabled: boolean,
+): void {
+	const text = new TextDisplayBuilder().setContent(entryContent(block));
+	if (block.action !== undefined) {
+		container.addSectionComponents(
+			new SectionBuilder()
+				.addTextDisplayComponents(text)
+				.setButtonAccessory(block.action.apply(state, forceDisabled)),
+		);
+		return;
+	}
+	if (block.thumbnail !== undefined) {
+		container.addSectionComponents(
+			new SectionBuilder()
+				.addTextDisplayComponents(text)
+				.setThumbnailAccessory(new ThumbnailBuilder().setURL(block.thumbnail)),
+		);
+		return;
+	}
+	container.addTextDisplayComponents(text);
+}
+
+/** Render one block onto the container being built, for the given state. */
+function applyBlock<S>(
+	container: ContainerBuilder,
+	block: CardBlock<S>,
+	state: S,
+	forceDisabled: boolean,
+): void {
+	switch (block.kind) {
+		case "text":
+			container.addTextDisplayComponents(new TextDisplayBuilder().setContent(block.content));
+			return;
+		case "entry":
+			applyEntry(container, block, state, forceDisabled);
+			return;
+		case "controls":
+			container.addActionRowComponents(
+				createActionRow([...block.buttons], state, { disableAll: forceDisabled }),
+			);
+			return;
+		case "select":
+			container.addActionRowComponents(
+				new ActionRowBuilder<AnySelectMenuBuilder>().addComponents(block.menu.apply(forceDisabled)),
+			);
+			return;
+		case "separator": {
+			const separator = new SeparatorBuilder();
+			if (block.spacing !== undefined) {
+				separator.setSpacing(
+					block.spacing === "large" ? SeparatorSpacingSize.Large : SeparatorSpacingSize.Small,
+				);
+			}
+			if (block.divider !== undefined) {
+				separator.setDivider(block.divider);
+			}
+			container.addSeparatorComponents(separator);
+			return;
+		}
+		case "gallery":
+			container.addMediaGalleryComponents(
+				new MediaGalleryBuilder().addItems(
+					...block.images.map((image) => {
+						const item = new MediaGalleryItemBuilder().setURL(image.url);
+						if (image.description !== undefined) {
+							item.setDescription(image.description);
+						}
+						if (image.spoiler !== undefined) {
+							item.setSpoiler(image.spoiler);
+						}
+						return item;
+					}),
+				),
+			);
+			return;
+	}
+}
+
+/**
+ * Declare a card: a definition compiling to a `ContainerBuilder`, the
+ * Components V2 analogue of an embed. Follows the same split as
+ * `createButton`/`createModal`/`createStringSelect` — data in, a compiled
+ * value with an `apply` out — so a caller never touches a V2 builder
+ * directly.
+ */
+export function createCard<S>(def: CardDef<S>): Card<S> {
+	const blocks = def.blocks.filter((block): block is CardBlock<S> => block !== null);
+	assertFitsBudget(blocks);
+
+	return {
+		apply(state, forceDisabled = false) {
+			const container = new ContainerBuilder();
+			if (def.accent !== undefined) {
+				container.setAccentColor(def.accent);
+			}
+			for (const block of blocks) {
+				applyBlock(container, block, state, forceDisabled);
+			}
+			return container;
+		},
+	};
+}

package/src/discord/ui/color-input-errors.ts

@@ -0,0 +1,17 @@
+/**
+ * A bot registered a colour name longer than the field an administrator types
+ * it into. Raised while the composition root registers its aliases at boot —
+ * the alternative is a name Discord silently truncates, which then never
+ * resolves and looks like the parser rejecting a colour it actually knows.
+ */
+export class ColorAliasTooLongError extends Error {
+	constructor(
+		readonly alias: string,
+		readonly maxLength: number,
+	) {
+		super(
+			`Colour alias "${alias}" is ${alias.length} characters, over the ${maxLength} the input field accepts`,
+		);
+		this.name = "ColorAliasTooLongError";
+	}
+}

package/src/discord/ui/color-input.ts

@@ -0,0 +1,179 @@
+import { ColorAliasTooLongError } from "@/discord/ui/color-input-errors";
+import { DISCORD_BLURPLE } from "@/discord/ui/colors";
+
+/**
+ * The generic web colours, at the value the name carries everywhere else — an
+ * administrator typing `orange` gets the orange they would get in CSS, not a
+ * shade this module invented.
+ */
+const RED = "#ff0000";
+const BLUE = "#0000ff";
+const GREEN = "#008000";
+const YELLOW = "#ffff00";
+const ORANGE = "#ffa500";
+const PURPLE = "#800080";
+const PINK = "#ffc0cb";
+const WHITE = "#ffffff";
+
+/**
+ * Not `#000000`: Discord reads a zero colour as "no colour set" and renders the
+ * default grey bar instead, so pure black is the one value an administrator
+ * could ask for and never see. One step off zero reads as black.
+ */
+const BLACK = "#010101";
+
+const GREY = "#808080";
+const CYAN = "#00ffff";
+const BROWN = "#a52a2a";
+const SILVER = "#c0c0c0";
+const TURQUOISE = "#40e0d0";
+const MAGENTA = "#ff00ff";
+const NAVY = "#000080";
+
+/**
+ * Colour names an administrator may type instead of a hex code, French and
+ * English side by side.
+ *
+ * This table is **input vocabulary, not display text**. Nothing in it is ever
+ * shown to anyone, and its keys must never be translated at runtime: a catalog
+ * lookup resolves against the reply locale, which would make `rouge` stop
+ * working the moment an admin's Discord is set to English — the opposite of the
+ * point. Both spellings are accepted from everyone, always, which only a flat
+ * table can promise.
+ *
+ * These are the names the kernel ships. A bot adds its own — the colour it
+ * calls by its brand's name — through {@link registerColorAliases}, which is
+ * also why this table is not the one lookups read: {@link COLOR_ALIASES} is.
+ */
+const BUILT_IN_COLOR_ALIASES: Readonly<Record<string, string>> = {
+	red: RED,
+	rouge: RED,
+	blue: BLUE,
+	bleu: BLUE,
+	green: GREEN,
+	vert: GREEN,
+	yellow: YELLOW,
+	jaune: YELLOW,
+	orange: ORANGE,
+	purple: PURPLE,
+	// French for purple, not the CSS `violet` (a pale pink): an admin typing it
+	// here is asking for the colour the word means in their own language.
+	violet: PURPLE,
+	pink: PINK,
+	rose: PINK,
+	white: WHITE,
+	blanc: WHITE,
+	black: BLACK,
+	noir: BLACK,
+	grey: GREY,
+	gray: GREY,
+	gris: GREY,
+	cyan: CYAN,
+	brown: BROWN,
+	marron: BROWN,
+	silver: SILVER,
+	argent: SILVER,
+	argenté: SILVER,
+	turquoise: TURQUOISE,
+	magenta: MAGENTA,
+	navy: NAVY,
+	marine: NAVY,
+	blurple: DISCORD_BLURPLE,
+};
+
+/**
+ * Accents must not be a trap: `dore` and `doré` are the same request, and an
+ * administrator has no way of knowing which one this file happened to spell.
+ * Case and surrounding whitespace are folded for the same reason.
+ */
+function normalizeColorName(raw: string): string {
+	return raw
+		.trim()
+		.toLowerCase()
+		.normalize("NFD")
+		.replace(/\p{Diacritic}/gu, "");
+}
+
+/**
+ * Every name a lookup answers to: the kernel's own, plus whatever the bot
+ * registered. Exposed for inspection — a screen listing the colours it accepts
+ * reads this — never for mutation, which goes through
+ * {@link registerColorAliases} so the length check cannot be skipped.
+ */
+export const COLOR_ALIASES: Readonly<Record<string, string>> = {
+	...BUILT_IN_COLOR_ALIASES,
+};
+
+const COLORS_BY_NORMALIZED_NAME = new Map(
+	Object.entries(COLOR_ALIASES).map(([name, hex]) => [normalizeColorName(name), hex]),
+);
+
+/** The `#rrggbb` a recognised colour name stands for, `null` for anything else. */
+function resolveNamedColor(raw: string): string | null {
+	return COLORS_BY_NORMALIZED_NAME.get(normalizeColorName(raw)) ?? null;
+}
+
+/** `#RRGGBB` — the longest hexadecimal form the parser accepts. */
+const HEX_INPUT_LENGTH = 7;
+
+/**
+ * What a colour input field may hold.
+ *
+ * Derived from the built-in table rather than written down, so adding a longer
+ * name here cannot leave the field silently truncating it at the client — and
+ * fixed rather than recomputed on registration, because field definitions read
+ * it once at module load, long before a bot registers anything.
+ */
+export const MAX_COLOR_INPUT_LENGTH = Math.max(
+	HEX_INPUT_LENGTH,
+	...Object.keys(BUILT_IN_COLOR_ALIASES).map((name) => name.length),
+);
+
+/**
+ * Teach the parser the colours this bot calls by name — its brand gold, its
+ * team colours — from the composition root, before any module is constructed.
+ *
+ * A name over {@link MAX_COLOR_INPUT_LENGTH} is refused rather than accepted:
+ * the input field is already sized, so registering a longer name would let an
+ * administrator type a colour the client cuts short, which then reads as the
+ * parser rejecting a name it actually knows.
+ *
+ * @throws ColorAliasTooLongError when a name cannot fit the input field.
+ */
+export function registerColorAliases(aliases: Readonly<Record<string, string>>): void {
+	for (const [name, hex] of Object.entries(aliases)) {
+		if (name.length > MAX_COLOR_INPUT_LENGTH) {
+			throw new ColorAliasTooLongError(name, MAX_COLOR_INPUT_LENGTH);
+		}
+		// Both views are written: the table is what a screen lists, the map is what
+		// a lookup reads, and a name present in one but not the other would be a
+		// colour the bot advertises and refuses.
+		(COLOR_ALIASES as Record<string, string>)[name] = hex;
+		COLORS_BY_NORMALIZED_NAME.set(normalizeColorName(name), hex);
+	}
+}
+
+/** Discord accepts `#RGB` and `#RRGGBB`, with or without the leading hash. */
+const HEX_COLOR_PATTERN = /^#?(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+/**
+ * Normalize a colour input to `#RRGGBB`, from a hexadecimal code or from one of
+ * the names in {@link COLOR_ALIASES} — an administrator picking a colour should
+ * not have to look a hex code up. `null` for anything that is neither: the
+ * refusal an administrator reads belongs to whichever screen asked, so core
+ * reports that it could not read the value and leaves the wording to the caller.
+ */
+export function parseColorInput(raw: string): string | null {
+	const value = raw.trim();
+	const named = resolveNamedColor(value);
+	if (named !== null) {
+		return named;
+	}
+	if (!HEX_COLOR_PATTERN.test(value)) {
+		return null;
+	}
+	const digits = value.replace("#", "").toLowerCase();
+	const expanded =
+		digits.length === 3 ? [...digits].map((digit) => `${digit}${digit}`).join("") : digits;
+	return `#${expanded}`;
+}

package/src/discord/ui/colors.ts

@@ -0,0 +1,58 @@
+/**
+ * The five roles an embed colour can play. A bot restyles by supplying its own
+ * values for these, never by adding a sixth: a role the kernel does not know is
+ * a module's own constant, not a theme entry.
+ */
+export interface EmbedColors {
+	success: number;
+	warning: number;
+	danger: number;
+	/** The bot's own identity, for embeds that should not read as Discord's. */
+	brand: number;
+	/** Neutral informational embeds — listings, recaps, previews. */
+	neutral: number;
+}
+
+/** Convert a `#rrggbb` string to the integer discord.js wants for `setColor`. */
+export function toDiscordColor(hex: string): number {
+	return Number.parseInt(hex.slice(1), 16);
+}
+
+/** Discord's own brand colour, the fallback for a bot that declares no palette. */
+export const DISCORD_BLURPLE = "#5865f2";
+
+/**
+ * What every embed renders as until the composition root says otherwise. Kept
+ * deliberately unbranded: a kernel that shipped one bot's colours would make
+ * every other bot start out wearing them.
+ */
+export const DEFAULT_EMBED_COLORS: Readonly<EmbedColors> = {
+	success: toDiscordColor("#22c55e"),
+	warning: toDiscordColor("#e67e22"),
+	danger: toDiscordColor("#ef4444"),
+	brand: toDiscordColor(DISCORD_BLURPLE),
+	neutral: toDiscordColor(DISCORD_BLURPLE),
+};
+
+/**
+ * The live palette every embed reads, in the kernel and in the modules alike.
+ *
+ * This is the one piece of module-level state the kernel keeps, and it is a
+ * deliberate exception to "DI, no singletons". A colour is read deep inside pure
+ * view functions that build an embed from a value object — threading a theme
+ * through every one of them would put a parameter nobody reasons about on the
+ * whole rendering surface, to express something that is global by nature: a bot
+ * has one palette, decided once, for its entire run.
+ *
+ * Read it, never copy it: destructuring at module load captures the defaults
+ * before {@link configureEmbedColors} has run.
+ */
+export const EMBED_COLORS: EmbedColors = { ...DEFAULT_EMBED_COLORS };
+
+/**
+ * Replace some or all of the palette. Call it from the composition root, before
+ * any module is constructed — after that, an embed may already have rendered.
+ */
+export function configureEmbedColors(overrides: Partial<EmbedColors>): void {
+	Object.assign(EMBED_COLORS, overrides);
+}

package/src/discord/ui/embed.ts

@@ -0,0 +1,64 @@
+import { EmbedBuilder } from "discord.js";
+
+/** Discord hard limit on the number of fields per embed. */
+const MAX_EMBED_FIELDS = 25;
+/** Discord hard limit on a field name length. */
+const MAX_FIELD_NAME = 256;
+/** Discord hard limit on a field value length. */
+const MAX_FIELD_VALUE = 1024;
+/** Discord hard limit on the total character count of an embed. */
+const MAX_EMBED_TOTAL = 6000;
+/** Headroom kept free for footer/title so the total stays under the limit. */
+const EMBED_TOTAL_SAFETY_MARGIN = 256;
+
+/** A single embed field. */
+export interface EmbedField {
+	name: string;
+	value: string;
+}
+
+/**
+ * Add fields to an embed while respecting Discord's size limits. Truncates
+ * over-long names/values, stops before exceeding the 25-field or 6000-character
+ * caps, and appends an overflow footer when some fields were dropped — so the
+ * embed can always be sent (no `MAX_EMBED_SIZE_EXCEEDED` rejection).
+ */
+export function appendBoundedFields(
+	embed: EmbedBuilder,
+	fields: EmbedField[],
+	overflowFooter: (hiddenCount: number) => string,
+): void {
+	let usedChars = (embed.data.title?.length ?? 0) + (embed.data.description?.length ?? 0);
+	let shown = 0;
+
+	for (const field of fields) {
+		if (shown >= MAX_EMBED_FIELDS) {
+			break;
+		}
+		const name = truncate(field.name, MAX_FIELD_NAME);
+		const value = truncate(field.value, MAX_FIELD_VALUE);
+		if (usedChars + name.length + value.length > MAX_EMBED_TOTAL - EMBED_TOTAL_SAFETY_MARGIN) {
+			break;
+		}
+		embed.addFields({ name, value });
+		usedChars += name.length + value.length;
+		shown += 1;
+	}
+
+	const hidden = fields.length - shown;
+	if (hidden > 0) {
+		embed.setFooter({ text: overflowFooter(hidden) });
+	}
+}
+
+function truncate(text: string, max: number): string {
+	if (text.length <= max) {
+		return text;
+	}
+	return `${text.slice(0, max - 1)}…`;
+}
+
+/** Build a plain titled embed. */
+export function buildEmbed(title: string, description: string): EmbedBuilder {
+	return new EmbedBuilder().setTitle(title).setDescription(description);
+}

package/src/discord/ui/message-attachments.ts

@@ -0,0 +1,57 @@
+import type { Attachment } from "discord.js";
+
+/**
+ * A file a message carries: the bytes, and the name an embed resolves an
+ * `attachment://` reference on.
+ *
+ * `Uint8Array` rather than `Buffer` so a caller can produce one without
+ * reaching for a Node-specific type; the conversion happens here, at the edge
+ * that hands it to discord.js.
+ */
+export interface MessageFile {
+	readonly name: string;
+	readonly bytes: Uint8Array;
+}
+
+/** A file as discord.js takes it on a send or an edit. */
+export interface MessageUpload {
+	readonly attachment: Buffer;
+	readonly name: string;
+}
+
+/** What an edit has to state for a message to end up carrying exactly what was asked. */
+export interface PlannedAttachments {
+	readonly attachments: Attachment[];
+	readonly files: MessageUpload[];
+}
+
+export function toMessageUpload(file: MessageFile): MessageUpload {
+	return { attachment: Buffer.from(file.bytes), name: file.name };
+}
+
+/**
+ * Split what a message should carry into what is already up there and what has
+ * to be uploaded.
+ *
+ * Discord reads an edit's `attachments` field as the complete set the message
+ * keeps — so `attachments: []` strips whatever it was published with, and
+ * re-sending the bytes to hold on to a file would upload the same one again on
+ * every unrelated re-render. Existing attachments are matched by name because
+ * that is what an embed resolves `attachment://` on, so a file already up there
+ * under the wanted name is the very one to keep.
+ *
+ * A caller carrying no files of its own never reaches this: it states neither
+ * field, and Discord leaves the message's own alone.
+ */
+export function planMessageAttachments(
+	existing: readonly Attachment[],
+	wanted: readonly MessageFile[],
+): PlannedAttachments {
+	const kept = existing.filter((attachment) =>
+		wanted.some((file) => file.name === attachment.name),
+	);
+	const uploaded = wanted.filter(
+		(file) => !kept.some((attachment) => attachment.name === file.name),
+	);
+	return { attachments: kept, files: uploaded.map(toMessageUpload) };
+}