@azurioh/discord-kernel 0.1.0

package/dist/discord/ui/card.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_CARD_TEXT_CHARACTERS = exports.MAX_CARD_COMPONENTS = void 0;
+exports.createCard = createCard;
+const discord_js_1 = require("discord.js");
+const button_1 = require("../../discord/interaction/button");
+/** Discord refuses a message carrying more components than this, container included. */
+exports.MAX_CARD_COMPONENTS = 40;
+/** Discord's cap on the characters carried by every `TextDisplay` in a message, summed. */
+exports.MAX_CARD_TEXT_CHARACTERS = 4000;
+/**
+ * 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(block) {
+    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(block) {
+    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(block) {
+    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(blocks) {
+    // +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 = [];
+    if (totalComponents > exports.MAX_CARD_COMPONENTS) {
+        problems.push(`${totalComponents} components (container included), Discord allows ${exports.MAX_CARD_COMPONENTS} — ${totalComponents - exports.MAX_CARD_COMPONENTS} over`);
+    }
+    if (totalCharacters > exports.MAX_CARD_TEXT_CHARACTERS) {
+        problems.push(`${totalCharacters} characters across its text, Discord allows ${exports.MAX_CARD_TEXT_CHARACTERS} — ${totalCharacters - exports.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(container, block, state, forceDisabled) {
+    const text = new discord_js_1.TextDisplayBuilder().setContent(entryContent(block));
+    if (block.action !== undefined) {
+        container.addSectionComponents(new discord_js_1.SectionBuilder()
+            .addTextDisplayComponents(text)
+            .setButtonAccessory(block.action.apply(state, forceDisabled)));
+        return;
+    }
+    if (block.thumbnail !== undefined) {
+        container.addSectionComponents(new discord_js_1.SectionBuilder()
+            .addTextDisplayComponents(text)
+            .setThumbnailAccessory(new discord_js_1.ThumbnailBuilder().setURL(block.thumbnail)));
+        return;
+    }
+    container.addTextDisplayComponents(text);
+}
+/** Render one block onto the container being built, for the given state. */
+function applyBlock(container, block, state, forceDisabled) {
+    switch (block.kind) {
+        case "text":
+            container.addTextDisplayComponents(new discord_js_1.TextDisplayBuilder().setContent(block.content));
+            return;
+        case "entry":
+            applyEntry(container, block, state, forceDisabled);
+            return;
+        case "controls":
+            container.addActionRowComponents((0, button_1.createActionRow)([...block.buttons], state, { disableAll: forceDisabled }));
+            return;
+        case "select":
+            container.addActionRowComponents(new discord_js_1.ActionRowBuilder().addComponents(block.menu.apply(forceDisabled)));
+            return;
+        case "separator": {
+            const separator = new discord_js_1.SeparatorBuilder();
+            if (block.spacing !== undefined) {
+                separator.setSpacing(block.spacing === "large" ? discord_js_1.SeparatorSpacingSize.Large : discord_js_1.SeparatorSpacingSize.Small);
+            }
+            if (block.divider !== undefined) {
+                separator.setDivider(block.divider);
+            }
+            container.addSeparatorComponents(separator);
+            return;
+        }
+        case "gallery":
+            container.addMediaGalleryComponents(new discord_js_1.MediaGalleryBuilder().addItems(...block.images.map((image) => {
+                const item = new discord_js_1.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.
+ */
+function createCard(def) {
+    const blocks = def.blocks.filter((block) => block !== null);
+    assertFitsBudget(blocks);
+    return {
+        apply(state, forceDisabled = false) {
+            const container = new discord_js_1.ContainerBuilder();
+            if (def.accent !== undefined) {
+                container.setAccentColor(def.accent);
+            }
+            for (const block of blocks) {
+                applyBlock(container, block, state, forceDisabled);
+            }
+            return container;
+        },
+    };
+}
+//# sourceMappingURL=card.js.map

package/dist/discord/ui/card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.js","sourceRoot":"","sources":["../../../src/discord/ui/card.ts"],"names":[],"mappings":"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"}

package/dist/discord/ui/color-input-errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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 declare class ColorAliasTooLongError extends Error {
+    readonly alias: string;
+    readonly maxLength: number;
+    constructor(alias: string, maxLength: number);
+}
+//# sourceMappingURL=color-input-errors.d.ts.map

package/dist/discord/ui/color-input-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-input-errors.d.ts","sourceRoot":"","sources":["../../../src/discord/ui/color-input-errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAE/C,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM;gBADjB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM;CAO3B"}

package/dist/discord/ui/color-input-errors.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ColorAliasTooLongError = void 0;
+/**
+ * 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.
+ */
+class ColorAliasTooLongError extends Error {
+    alias;
+    maxLength;
+    constructor(alias, maxLength) {
+        super(`Colour alias "${alias}" is ${alias.length} characters, over the ${maxLength} the input field accepts`);
+        this.alias = alias;
+        this.maxLength = maxLength;
+        this.name = "ColorAliasTooLongError";
+    }
+}
+exports.ColorAliasTooLongError = ColorAliasTooLongError;
+//# sourceMappingURL=color-input-errors.js.map

package/dist/discord/ui/color-input-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-input-errors.js","sourceRoot":"","sources":["../../../src/discord/ui/color-input-errors.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACH,MAAa,sBAAuB,SAAQ,KAAK;IAEtC;IACA;IAFV,YACU,KAAa,EACb,SAAiB;QAE1B,KAAK,CACJ,iBAAiB,KAAK,QAAQ,KAAK,CAAC,MAAM,yBAAyB,SAAS,0BAA0B,CACtG,CAAC;QALO,UAAK,GAAL,KAAK,CAAQ;QACb,cAAS,GAAT,SAAS,CAAQ;QAK1B,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACtC,CAAC;CACD;AAVD,wDAUC"}

package/dist/discord/ui/color-input.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 declare const COLOR_ALIASES: Readonly<Record<string, string>>;
+/**
+ * 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 declare const MAX_COLOR_INPUT_LENGTH: number;
+/**
+ * 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 declare function registerColorAliases(aliases: Readonly<Record<string, string>>): void;
+/**
+ * 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 declare function parseColorInput(raw: string): string | null;
+//# sourceMappingURL=color-input.d.ts.map

package/dist/discord/ui/color-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-input.d.ts","sourceRoot":"","sources":["../../../src/discord/ui/color-input.ts"],"names":[],"mappings":"AAgGA;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE1D,CAAC;AAcF;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,QAGlC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAWpF;AAKD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAa1D"}

package/dist/discord/ui/color-input.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_COLOR_INPUT_LENGTH = exports.COLOR_ALIASES = void 0;
+exports.registerColorAliases = registerColorAliases;
+exports.parseColorInput = parseColorInput;
+const color_input_errors_1 = require("../../discord/ui/color-input-errors");
+const colors_1 = require("../../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 = {
+    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: colors_1.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) {
+    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.
+ */
+exports.COLOR_ALIASES = {
+    ...BUILT_IN_COLOR_ALIASES,
+};
+const COLORS_BY_NORMALIZED_NAME = new Map(Object.entries(exports.COLOR_ALIASES).map(([name, hex]) => [normalizeColorName(name), hex]));
+/** The `#rrggbb` a recognised colour name stands for, `null` for anything else. */
+function resolveNamedColor(raw) {
+    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.
+ */
+exports.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.
+ */
+function registerColorAliases(aliases) {
+    for (const [name, hex] of Object.entries(aliases)) {
+        if (name.length > exports.MAX_COLOR_INPUT_LENGTH) {
+            throw new color_input_errors_1.ColorAliasTooLongError(name, exports.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.
+        exports.COLOR_ALIASES[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.
+ */
+function parseColorInput(raw) {
+    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}`;
+}
+//# sourceMappingURL=color-input.js.map

package/dist/discord/ui/color-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-input.js","sourceRoot":"","sources":["../../../src/discord/ui/color-input.ts"],"names":[],"mappings":"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"}

package/dist/discord/ui/colors.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 declare function toDiscordColor(hex: string): number;
+/** Discord's own brand colour, the fallback for a bot that declares no palette. */
+export declare 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 declare const DEFAULT_EMBED_COLORS: Readonly<EmbedColors>;
+/**
+ * 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 declare const EMBED_COLORS: EmbedColors;
+/**
+ * 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 declare function configureEmbedColors(overrides: Partial<EmbedColors>): void;
+//# sourceMappingURL=colors.d.ts.map

package/dist/discord/ui/colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../../../src/discord/ui/colors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,mFAAmF;AACnF,eAAO,MAAM,eAAe,YAAY,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,WAAW,CAMtD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,EAAE,WAAyC,CAAC;AAErE;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,CAE1E"}

package/dist/discord/ui/colors.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMBED_COLORS = exports.DEFAULT_EMBED_COLORS = exports.DISCORD_BLURPLE = void 0;
+exports.toDiscordColor = toDiscordColor;
+exports.configureEmbedColors = configureEmbedColors;
+/** Convert a `#rrggbb` string to the integer discord.js wants for `setColor`. */
+function toDiscordColor(hex) {
+    return Number.parseInt(hex.slice(1), 16);
+}
+/** Discord's own brand colour, the fallback for a bot that declares no palette. */
+exports.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.
+ */
+exports.DEFAULT_EMBED_COLORS = {
+    success: toDiscordColor("#22c55e"),
+    warning: toDiscordColor("#e67e22"),
+    danger: toDiscordColor("#ef4444"),
+    brand: toDiscordColor(exports.DISCORD_BLURPLE),
+    neutral: toDiscordColor(exports.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.
+ */
+exports.EMBED_COLORS = { ...exports.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.
+ */
+function configureEmbedColors(overrides) {
+    Object.assign(exports.EMBED_COLORS, overrides);
+}
+//# sourceMappingURL=colors.js.map

package/dist/discord/ui/colors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.js","sourceRoot":"","sources":["../../../src/discord/ui/colors.ts"],"names":[],"mappings":";;;AAgBA,wCAEC;AAqCD,oDAEC;AA1CD,iFAAiF;AACjF,SAAgB,cAAc,CAAC,GAAW;IACzC,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED,mFAAmF;AACtE,QAAA,eAAe,GAAG,SAAS,CAAC;AAEzC;;;;GAIG;AACU,QAAA,oBAAoB,GAA0B;IAC1D,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC;IAClC,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC;IAClC,MAAM,EAAE,cAAc,CAAC,SAAS,CAAC;IACjC,KAAK,EAAE,cAAc,CAAC,uBAAe,CAAC;IACtC,OAAO,EAAE,cAAc,CAAC,uBAAe,CAAC;CACxC,CAAC;AAEF;;;;;;;;;;;;GAYG;AACU,QAAA,YAAY,GAAgB,EAAE,GAAG,4BAAoB,EAAE,CAAC;AAErE;;;GAGG;AACH,SAAgB,oBAAoB,CAAC,SAA+B;IACnE,MAAM,CAAC,MAAM,CAAC,oBAAY,EAAE,SAAS,CAAC,CAAC;AACxC,CAAC"}

package/dist/discord/ui/embed.d.ts

@@ -0,0 +1,16 @@
+import { EmbedBuilder } from "discord.js";
+/** 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 declare function appendBoundedFields(embed: EmbedBuilder, fields: EmbedField[], overflowFooter: (hiddenCount: number) => string): void;
+/** Build a plain titled embed. */
+export declare function buildEmbed(title: string, description: string): EmbedBuilder;
+//# sourceMappingURL=embed.d.ts.map

package/dist/discord/ui/embed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.d.ts","sourceRoot":"","sources":["../../../src/discord/ui/embed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAa1C,4BAA4B;AAC5B,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,UAAU,EAAE,EACpB,cAAc,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,GAC7C,IAAI,CAsBN;AASD,kCAAkC;AAClC,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,YAAY,CAE3E"}

package/dist/discord/ui/embed.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendBoundedFields = appendBoundedFields;
+exports.buildEmbed = buildEmbed;
+const discord_js_1 = require("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;
+/**
+ * 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).
+ */
+function appendBoundedFields(embed, fields, overflowFooter) {
+    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, max) {
+    if (text.length <= max) {
+        return text;
+    }
+    return `${text.slice(0, max - 1)}…`;
+}
+/** Build a plain titled embed. */
+function buildEmbed(title, description) {
+    return new discord_js_1.EmbedBuilder().setTitle(title).setDescription(description);
+}
+//# sourceMappingURL=embed.js.map

package/dist/discord/ui/embed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.js","sourceRoot":"","sources":["../../../src/discord/ui/embed.ts"],"names":[],"mappings":";;AAyBA,kDA0BC;AAUD,gCAEC;AA/DD,2CAA0C;AAE1C,4DAA4D;AAC5D,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAC5B,iDAAiD;AACjD,MAAM,cAAc,GAAG,GAAG,CAAC;AAC3B,kDAAkD;AAClD,MAAM,eAAe,GAAG,IAAI,CAAC;AAC7B,mEAAmE;AACnE,MAAM,eAAe,GAAG,IAAI,CAAC;AAC7B,8EAA8E;AAC9E,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAQtC;;;;;GAKG;AACH,SAAgB,mBAAmB,CAClC,KAAmB,EACnB,MAAoB,EACpB,cAA+C;IAE/C,IAAI,SAAS,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,IAAI,CAAC,CAAC,CAAC;IACxF,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,KAAK,IAAI,gBAAgB,EAAE,CAAC;YAC/B,MAAM;QACP,CAAC;QACD,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;QAClD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;QACrD,IAAI,SAAS,GAAG,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,eAAe,GAAG,yBAAyB,EAAE,CAAC;YAC1F,MAAM;QACP,CAAC;QACD,KAAK,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACjC,SAAS,IAAI,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QACxC,KAAK,IAAI,CAAC,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC;IACrC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAChB,KAAK,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACnD,CAAC;AACF,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY,EAAE,GAAW;IAC1C,IAAI,IAAI,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC;IACb,CAAC;IACD,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;AACrC,CAAC;AAED,kCAAkC;AAClC,SAAgB,UAAU,CAAC,KAAa,EAAE,WAAmB;IAC5D,OAAO,IAAI,yBAAY,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;AACvE,CAAC"}

package/dist/discord/ui/message-attachments.d.ts

@@ -0,0 +1,40 @@
+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 declare function toMessageUpload(file: MessageFile): MessageUpload;
+/**
+ * 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 declare function planMessageAttachments(existing: readonly Attachment[], wanted: readonly MessageFile[]): PlannedAttachments;
+//# sourceMappingURL=message-attachments.d.ts.map