@seedcord/gateway 0.1.0-next.5 → 0.1.0

package/dist/index.mjs

@@ -1,25 +1,24 @@
 import "reflect-metadata";
 import { installNodeDefaults } from "@seedcord/logger/node";
-import { BaseReplySender, CommandMetadataKey, EventMetadataKey, FaultThrottle, GateNotice, GatedMetadataKey, HmrManager, InteractionMetadataKey, InteractionRouteKeys, InteractionRoutes, MiddlewareMetadataKey, MissingPermissions, NoticeCard, PAGE_MAX, PermissionNames, PublishDefault, areRoutes, asError, decodeComponentRoute, deferFlags, dispatchedPayload, getDevChannel, outcomeFor, pageCursor, pickNotice, prefixOf, queuedMsFor, reportedWrite, routeIdOf, runHandlerGates, sendFlags, setBotColor, slowGateMonitor } from "@seedcord/core/internal";
+import { BaseReplySender, CommandInjector, EventMetadataKey, FaultThrottle, GateNotice, GatedMetadataKey, HmrManager, InteractionMetadataKey, InteractionRouteKeys, InteractionRoutes, MiddlewareMetadataKey, MissingPermissions, NoticeCard, PermissionNames, PublishDefault, accessorStore, areRoutes, asError, clearStore, decodeComponentRoute, deferFlags, dispatchedPayload, guardedAccessor, isEmojiTuple, outcomeFor, pickNotice, prefixOf, queuedMsFor, reportedWrite, routeIdOf, runHandlerGates, sendFlags, setBotColor, slowGateMonitor } from "@seedcord/core/internal";
 import { SeedcordErrorCode } from "@seedcord/errors";
-import { SeedcordError, SeedcordRangeError, SeedcordTypeError, validateDiscordToken } from "@seedcord/errors/internal";
-import { BaseHandler, BuilderComponent, Bus, CustomId, DispatchContext, Fault, Notice, RepliableHandler as RepliableHandler$1, RowComponent, Silence, Subscriber as Subscriber$1, WebhookLog as WebhookLog$1, defineGate, paginate } from "@seedcord/core";
+import { SeedcordError, SeedcordTypeError, validateDiscordToken } from "@seedcord/errors/internal";
+import { ArraySource as ArraySource$1, BaseHandler, BuilderComponent, Bus, CursorSource as CursorSource$1, CustomId, DispatchContext, Fault, Notice, PaginatorBase, RepliableHandler as RepliableHandler$1, RowComponent, Silence, Subscriber as Subscriber$1, WebhookLog as WebhookLog$1, assertPermissions, defineGate } from "@seedcord/core";
 import { Logger, LoggerChannelRegistry, paint } from "@seedcord/logger";
-import { ActionRowBuilder, ButtonBuilder, ContextMenuCommandBuilder, SlashCommandBuilder, TextDisplayBuilder } from "@discordjs/builders";
-import { buildSlashRoute, routeLeavesOf } from "@seedcord/utils/internal";
-import { ApplicationCommandType, ButtonStyle, Client, Collection, ComponentType, DiscordAPIError, Events, Guild, GuildMember, Message, MessageFlags, PermissionFlagsBits, RESTJSONErrorCodes, Role, TextChannel, User, chatInputApplicationCommandMention } from "discord.js";
-import * as crypto from "node:crypto";
+import { ButtonStyle, Client, ComponentType, DiscordAPIError, Events, Guild, GuildMember, Message, MessageFlags, PermissionFlagsBits, RESTJSONErrorCodes, Role, User } from "discord.js";
+import { ButtonBuilder, TextDisplayBuilder } from "@discordjs/builders";
+import { buildSlashRoute } from "@seedcord/utils/internal";
 import { Plugin as Plugin$1 } from "@seedcord/core/plugin";
-import { CoordinatedShutdown, CoordinatedStartup, HealthCheck, Pluggable, ShutdownPhase, StartupPhase, SubscriberLoader, settleWithin } from "@seedcord/core/node/internal";
+import { CommandRegistry, CoordinatedShutdown, CoordinatedStartup, HealthCheck, Pluggable, ShutdownPhase, StartupPhase, SubscriberLoader, settleWithin } from "@seedcord/core/node/internal";
 import { MemoryRateLimiter } from "@seedcord/rate-limiter";
 import { SeedcordBrand } from "@seedcord/types/internal";
 import { Envapter } from "envapt";
 import chalk from "chalk";
 import { Envapt } from "envapt/legacy";
-import { resolve } from "node:path";
 import { HmrModuleHandler } from "@seedcord/core/hmr";
 import { formatFilePath, hasKeys } from "@seedcord/utils";
 import { traverseDirectory } from "@seedcord/utils/node";
+import * as crypto from "node:crypto";
 
 export * from "@seedcord/errors"
 
@@ -224,59 +223,6 @@ var CannotAssignBotRole = class extends Notice {
 		return { components: [new NoticeCard("I cannot assign a managed role.").component] };
 	}
 };
-var HasDangerousPermissions = class extends Notice {
-	subject;
-	dangerousPerms;
-	customLead;
-	constructor(message, subject, dangerousPerms) {
-		super(message ?? "A dangerous permission is enabled.");
-		this.subject = subject;
-		this.dangerousPerms = dangerousPerms;
-		this.customLead = message;
-	}
-	render() {
-		const bullets = this.dangerousPerms.map((perm) => `• ${perm}`).join("\n");
-		return { components: [new NoticeCard(`${this.customLead ?? `${this.subject} has the following permission entries that must not be enabled:`}\n\n${bullets}`).component] };
-	}
-};
-var UserNotFound = class extends Notice {
-	userArg;
-	constructor(userArg) {
-		super(`User not found: ${userArg}`);
-		this.userArg = userArg;
-	}
-	render() {
-		return { components: [new NoticeCard(`User probably doesn't exist or was deleted.\n**User Argument:** \`${this.userArg}\`\nPlease check the user ID and try again. Only pass valid user IDs as the argument.`, "User Not Found").component] };
-	}
-};
-var UserNotInGuild = class extends Notice {
-	constructor(message = "User is not in the guild.") {
-		super(message);
-	}
-	render() {
-		return { components: [new NoticeCard(this.message).component] };
-	}
-};
-var RoleDoesNotExist = class extends Notice {
-	roleId;
-	constructor(message, roleId) {
-		super(message);
-		this.roleId = roleId;
-	}
-	render() {
-		return { components: [new NoticeCard(`The role with ID \`${this.roleId}\` does not exist.`).component] };
-	}
-};
-var CouldNotFindChannel = class extends Notice {
-	channelId;
-	constructor(message, channelId) {
-		super(message);
-		this.channelId = channelId;
-	}
-	render() {
-		return { components: [new NoticeCard(`Could not find channel with ID \`${this.channelId}\`. It could also be that the channel is not a text channel.`).component] };
-	}
-};
 
 //#endregion
 //#region src/bot/gates/catalog/Nsfw.ts
@@ -314,20 +260,15 @@ function Nsfw(options) {
 
 //#endregion
 //#region src/bot/injectors/EmojiInjector.ts
-const emojiStorage = {};
-function isEmojiTuple(v) {
-	return Array.isArray(v) && v.length === 2 && typeof v[0] === "string" && typeof v[1] === "string";
-}
+const emojiStorage = accessorStore();
 /**
-* Global emoji mappings object
-*
-* @see {@link EmojiMap}
+* The bot's resolved emojis, keyed by {@link EmojiMap}. Filled by {@link EmojiInjector} during startup.
+* A read before that throws.
 */
-const Emojis = emojiStorage;
+const Emojis = guardedAccessor("Emojis", emojiStorage);
 /**
-* Loads and injects emojis based on bot configuration.
-*
-* For emojis injected from specific guilds, ensure that the Guilds intent is provided in client options.
+* Loads and injects emojis based on bot configuration. A guild emoji requires the Guilds intent in the client
+* options.
 *
 * @internal
 */
@@ -380,126 +321,10 @@ var EmojiInjector = class {
 		emojiStorage[key] = appEmoji;
 	}
 	clearEmojis() {
-		for (const key of Object.keys(emojiStorage)) Reflect.deleteProperty(emojiStorage, key);
-	}
-};
-
-//#endregion
-//#region src/bot/injectors/CommandMentionInjector.ts
-const mentionStorage = {};
-/**
-* Ready-to-send command mention strings, keyed by {@link SlashOptionRegistry}.
-*
-* A value is a clickable `</name:id>` when the command's id resolved from the deploy, otherwise the plain
-* `/name` text. Populated by {@link CommandMentionInjector} after each deploy.
-*/
-const CommandMentions = mentionStorage;
-const MULTI_GUILD = Symbol("seedcord:commandmentions:multi-guild");
-/**
-* Turns each deployed slash route into a clickable command mention exposed through {@link CommandMentions}.
-*
-* Consumes the ids {@link DeployResult} carries, so it runs after a deploy rather than resolving from a name
-* cache (discord.js offers none for command ids). A global command is clickable everywhere by its app-wide id.
-* A guild command deployed to one guild is clickable by that guild's id. A command deployed to two or more
-* guilds mints a different id per guild, so one accessor key cannot resolve it, and it falls back to plain
-* `/name` text with one warn. On a non-owning shard a guild command also falls back to plain text.
-*
-* @internal
-*/
-var CommandMentionInjector = class {
-	core;
-	logger = new Logger("CommandMentions", { channel: "bot" });
-	constructor(core) {
-		this.core = core;
-	}
-	inject(deploy) {
-		this.clear();
-		const globalIds = this.indexByName(deploy.global);
-		const guildIds = this.indexGuilds(deploy.guilds);
-		const warned = /* @__PURE__ */ new Set();
-		let clickable = 0;
-		for (const command of this.allSlashBuilders()) {
-			const id = this.resolveId(command.name, globalIds, guildIds, warned);
-			for (const leaf of routeLeavesOf(command.toJSON())) {
-				mentionStorage[leaf.route] = id ? this.toMention(leaf.route, id) : this.toPlain(leaf.route);
-				if (id) clickable++;
-			}
-		}
-		this.logger.utils.summary("Linked mentions", {
-			clickable,
-			plain: Object.keys(mentionStorage).length - clickable
-		});
-	}
-	allSlashBuilders() {
-		const registry = this.core.bot.commands;
-		if (!registry) return [];
-		const slash = [...registry.globalCommands, ...registry.guildCommands.values()].flat().filter((command) => command instanceof SlashCommandBuilder);
-		return [...new Set(slash)];
-	}
-	indexByName(collection) {
-		const map = /* @__PURE__ */ new Map();
-		for (const command of collection.values()) map.set(command.name, command.id);
-		return map;
-	}
-	indexGuilds(guilds) {
-		const map = /* @__PURE__ */ new Map();
-		for (const collection of guilds.values()) for (const command of collection.values()) {
-			const existing = map.get(command.name);
-			if (existing === void 0) map.set(command.name, command.id);
-			else if (existing !== command.id) map.set(command.name, MULTI_GUILD);
-		}
-		return map;
-	}
-	resolveId(name, globalIds, guildIds, warned) {
-		const global = globalIds.get(name);
-		if (global) return global;
-		const guild = guildIds.get(name);
-		if (guild === void 0) return void 0;
-		if (guild === MULTI_GUILD) {
-			if (!warned.has(name)) {
-				this.logger.warn(`${name} is deployed to multiple guilds, falling back to plain text (not clickable).`);
-				warned.add(name);
-			}
-			return;
-		}
-		return guild;
-	}
-	toMention(route, id) {
-		const [name, middle, sub] = route.split("/");
-		if (name && middle && sub) return chatInputApplicationCommandMention(name, middle, sub, id);
-		if (name && middle) return chatInputApplicationCommandMention(name, middle, id);
-		return chatInputApplicationCommandMention(name ?? route, id);
-	}
-	toPlain(route) {
-		return `/${route.replaceAll("/", " ")}`;
-	}
-	clear() {
-		for (const key of Object.keys(mentionStorage)) Reflect.deleteProperty(mentionStorage, key);
+		clearStore(emojiStorage);
 	}
 };
 
-//#endregion
-//#region src/bot/utilities/channels/fetchText.ts
-/**
-* Fetches and validates a text channel. Refuses when the channel doesn't exist or isn't a text channel.
-*
-* @param client - The Discord client instance
-* @param channelId - Channel ID or TextChannel instance
-* @returns Promise resolving to the text channel
-*/
-async function fetchText(client, channelId) {
-	if (channelId instanceof TextChannel) return channelId;
-	let channel = client.channels.cache.get(channelId);
-	if (!channel) try {
-		channel = await client.channels.fetch(channelId);
-	} catch (err) {
-		if (err instanceof DiscordAPIError && err.code === RESTJSONErrorCodes.UnknownChannel) throw new CouldNotFindChannel("Channel not found or not a text channel", channelId);
-		throw err;
-	}
-	if (channel?.isTextBased()) return channel;
-	throw new CouldNotFindChannel("Channel not found or not a text channel", channelId);
-}
-
 //#endregion
 //#region src/bot/notices/utils.ts
 function mentionFor(subject) {
@@ -510,48 +335,37 @@ function mentionFor(subject) {
 //#endregion
 //#region src/bot/utilities/permissions/checkPermissions.ts
 function checkPermissions(a, b, c, d, e) {
-	const { for: pFor, in: pIn, scope, inverse = false, missingNotice: missingCtor, dangerousNotice: dangerousCtor } = a instanceof Role || a instanceof GuildMember ? {
+	const { for: pFor, in: pIn, scope, inverse = false, missingNotice, dangerousNotice } = a instanceof Role || a instanceof GuildMember ? {
 		for: a,
 		in: b,
 		scope: c,
 		inverse: d ?? false,
 		...e
 	} : a;
-	const Missing = missingCtor ?? MissingPermissions;
-	const Dangerous = dangerousCtor ?? HasDangerousPermissions;
-	const subject = mentionFor(pFor);
 	const perms = pIn instanceof Guild ? pFor.permissions : pIn.permissionsFor(pFor, true);
-	const names = (bits) => bits.map((bit) => PermissionNames.get(bit) ?? String(bit));
-	if (inverse) {
-		const present = scope.filter((bit) => perms.has(bit, true));
-		if (present.length > 0) throw new Dangerous(void 0, subject, names(present));
-		return;
-	}
-	const missingBits = scope.filter((bit) => !perms.has(bit, true));
-	if (missingBits.length > 0) throw new Missing(void 0, subject, names(missingBits));
+	assertPermissions({
+		subject: mentionFor(pFor),
+		permissions: perms.bitfield,
+		scope,
+		inverse,
+		...missingNotice && { missingNotice },
+		...dangerousNotice && { dangerousNotice }
+	});
 }
 
 //#endregion
 //#region src/bot/utilities/permissions/checkBotPermissions.ts
 /**
-* Checks if the bot has required permissions in a {@link Guild} or {@link TextChannel}. Refuses when a
-* required permission is missing.
-*
-* @param target - Guild or text channel to check in
-* @param scope - Permission bits to validate
-* @param inverse - Whether to check for absence of the given permissions
-* @param errors - Optional custom error constructors
+* Checks the bot's own permissions in a {@link Guild} or {@link TextChannel}. Refuses when a permission in
+* `scope` is missing, or with `inverse` when one is present. When the bot member is uncached, the refusal
+* reports every permission in `scope` as missing.
 *
 * @example
 * ```ts
 * import { PermissionFlagsBits } from 'discord.js';
 * import { checkBotPermissions } from '@seedcord/gateway';
 *
-* // Check if the bot has SendMessages and ViewChannel permissions in a text channel
-* checkBotPermissions(textChannel, [
-*   PermissionFlagsBits.SendMessages,
-*   PermissionFlagsBits.ViewChannel
-* ]);
+* checkBotPermissions(textChannel, [PermissionFlagsBits.SendMessages, PermissionFlagsBits.ViewChannel]);
 * ```
 */
 function checkBotPermissions(target, scope, inverse = false, errors) {
@@ -574,26 +388,17 @@ function checkBotPermissions(target, scope, inverse = false, errors) {
 }
 
 //#endregion
-//#region src/bot/utilities/roles/getBotRole.ts
-/**
-* Gets the bot's managed role in a guild.
-*
-* @param guild - The guild to get the bot role from
-* @returns The bot's managed role in the guild
-* @throws A **SeedcordError** if the client user is unavailable or if the bot role is missing
-*/
-function getBotRole(guild) {
+//#region src/bot/utilities/permissions/hasPermsToAssign.ts
+function botRoleOf(guild) {
 	const botRole = guild.roles.botRoleFor(guild.client.user);
 	if (!botRole) throw new SeedcordError(SeedcordErrorCode.CoreBotRoleMissing, [guild.id]);
 	return botRole;
 }
-
-//#endregion
-//#region src/bot/utilities/permissions/hasPermsToAssign.ts
 /**
-* Validates if the bot can assign a target role. Refuses when the target role is above the bot's, is managed, or the bot lacks Manage Roles.
+* Validates that the bot can assign a target role. Refuses when the target role is above the bot's, is managed, or the bot lacks Manage Roles.
 *
 * @param roleOrOptions - Target role or complete options for the check
+* @throws A `Notice` on refusal, or a `SeedcordError` when the bot has no role in the guild's role cache.
 *
 * @example
 * ```ts
@@ -621,138 +426,123 @@ function hasPermsToAssign(roleOrOptions) {
 	const HigherNotice = errors?.higherNotice ?? RoleHigherThanMe;
 	const ManagedNotice = errors?.managedNotice ?? CannotAssignBotRole;
 	const MissingNotice = errors?.missingNotice ?? MissingPermissions;
-	const botRole = getBotRole(targetRole.guild);
+	const botRole = botRoleOf(targetRole.guild);
 	if (targetRole.comparePositionTo(botRole) >= 0) throw new HigherNotice("Role is higher than me", targetRole, botRole);
 	if (targetRole.managed) throw new ManagedNotice(`Cannot assign managed role ${targetRole.name}`);
 	checkBotPermissions(targetRole.guild, [PermissionFlagsBits.ManageRoles], false, { missingNotice: MissingNotice });
 }
 
 //#endregion
-//#region src/bot/utilities/roles/fetchRole.ts
-function isUnknownRole(err) {
-	return err instanceof DiscordAPIError && err.code === RESTJSONErrorCodes.UnknownRole;
-}
-async function fetchRoleInGuild(guild, roleId) {
-	const cached = guild.roles.cache.get(roleId);
-	if (cached) return cached;
-	try {
-		return await guild.roles.fetch(roleId);
-	} catch (err) {
-		if (isUnknownRole(err)) throw new RoleDoesNotExist("Role not found in specified guild", roleId);
-		throw err;
-	}
-}
-async function scanGuildsForRole(client, roleId) {
-	const cached = client.guilds.cache.map((guild) => guild.roles.cache.get(roleId)).find(Boolean);
-	if (cached) return cached;
-	for (const guild of client.guilds.cache.values()) try {
-		const role = await guild.roles.fetch(roleId);
-		if (role) return role;
-	} catch (err) {
-		if (isUnknownRole(err)) continue;
-		throw err;
-	}
-	return null;
-}
+//#region src/bot/confirm/reserved.ts
+const RESERVED_CONFIRM_PREFIX = "__seedcord_confirm";
 /**
-* Fetches a role by ID from a client or guild. Refuses when the role doesn't exist.
+* The reserved confirm/cancel codec. It has no route, so the dispatcher ignores its clicks and only the
+* in-process collector reads them. Do not mint a real component from it.
 *
-* @param clientOrGuild - Discord client or guild instance
-* @param roleId - The role ID to fetch
-* @returns Promise resolving to the role
+* @internal
 */
-async function fetchRole(clientOrGuild, roleId) {
-	if (!roleId) throw new RoleDoesNotExist("Role ID is null or undefined", roleId);
-	const role = clientOrGuild instanceof Guild ? await fetchRoleInGuild(clientOrGuild, roleId) : await scanGuildsForRole(clientOrGuild, roleId);
-	if (!role) throw new RoleDoesNotExist("Role not found", roleId);
-	return role;
-}
+const CONFIRM_DEF = new CustomId(RESERVED_CONFIRM_PREFIX).oneOf("choice", ["confirm", "cancel"]);
 
 //#endregion
-//#region src/bot/utilities/users/fetchGuildMember.ts
-/**
-* Fetches a guild member by user ID. Refuses when the user is not in the guild.
-*
-* @param guild - The guild to fetch the member from
-* @param userId - The Discord user ID
-* @returns Promise resolving to the guild member
-*/
-async function fetchGuildMember(guild, userId) {
-	let user = guild.members.cache.get(userId);
-	user ??= await guild.members.fetch(userId).catch((err) => {
-		if (err instanceof DiscordAPIError && err.code === RESTJSONErrorCodes.UnknownMember) throw new UserNotInGuild(`User with ID ${userId} not found in guild`);
-		throw err;
-	});
-	return user;
+//#region src/bot/confirm/getConfirmation.ts
+const DEFAULT_TIMEOUT_MS = 3e4;
+const CONFIRM_IDS = {
+	confirm: CONFIRM_DEF.encode({ choice: "confirm" }),
+	cancel: CONFIRM_DEF.encode({ choice: "cancel" })
+};
+var ConfirmButtons = class extends RowComponent {
+	constructor(options) {
+		super("button");
+		this.instance.addComponents(new ButtonBuilder().setCustomId(CONFIRM_IDS.confirm).setLabel(options?.confirmLabel ?? "Confirm").setStyle(options?.confirmStyle ?? ButtonStyle.Danger), new ButtonBuilder().setCustomId(CONFIRM_IDS.cancel).setLabel(options?.cancelLabel ?? "Cancel").setStyle(ButtonStyle.Secondary));
+	}
+};
+var ConfirmPromptCard = class extends BuilderComponent {
+	constructor(text, options) {
+		super("container");
+		this.instance.addTextDisplayComponents(new TextDisplayBuilder().setContent(text)).addActionRowComponents(new ConfirmButtons(options).component);
+	}
+};
+function defaultPrompt(text, options) {
+	return { components: [new ConfirmPromptCard(text, options).component] };
 }
-
-//#endregion
-//#region src/bot/utilities/users/fetchManyGuildMembers.ts
-/**
-* Fetches multiple guild members by user IDs.
-*
-* @param guild - The guild to fetch members from
-* @param userIds - Array of Discord user IDs
-* @returns Promise resolving to array of successfully fetched members
-*/
-async function fetchManyGuildMembers(guild, userIds) {
-	return (await Promise.allSettled(userIds.map((userId) => fetchGuildMember(guild, userId)))).filter((result) => result.status === "fulfilled").map((result) => result.value);
+async function collectChoice(message, userId, timeoutMs) {
+	try {
+		return await message.awaitMessageComponent({
+			componentType: ComponentType.Button,
+			time: timeoutMs,
+			filter: (click) => click.user.id === userId && CONFIRM_DEF.owns(click.customId)
+		});
+	} catch {
+		return null;
+	}
 }
-
-//#endregion
-//#region src/bot/utilities/users/fetchUser.ts
-/**
-* Fetches a Discord user by ID. Refuses when the user doesn't exist, with `options.throwAs` or the default.
-*
-* @param client - The Discord client instance
-* @param userId - The Discord user ID
-* @param options - Optional overrides, including the {@link FetchUserOptions.throwAs} notice
-* @returns Promise resolving to the user
-*/
-async function fetchUser(client, userId, options) {
-	const Throw = options?.throwAs ?? UserNotFound;
-	let user = client.users.cache.get(userId);
-	user ??= await client.users.fetch(userId).catch((err) => {
-		if (err instanceof DiscordAPIError && err.code === RESTJSONErrorCodes.UnknownUser) throw new Throw(userId);
-		throw err;
-	});
-	return user;
+async function settle(sender, message, outcome) {
+	if (outcome === void 0) {
+		await sender.delete(message).catch(() => void 0);
+		return;
+	}
+	await sender.edit(message, typeof outcome === "function" ? await outcome() : outcome);
+}
+async function getConfirmation(handler, prompt, options) {
+	const { ephemeral = true, timeoutMs = DEFAULT_TIMEOUT_MS } = options ?? {};
+	const response = typeof prompt === "string" ? defaultPrompt(prompt, options) : await prompt(CONFIRM_IDS);
+	const interaction = handler.getEvent();
+	const sender = handler.getSender();
+	const message = await sender.send(response, { ephemeral });
+	const winner = await collectChoice(message, interaction.user.id, timeoutMs);
+	if (!winner) {
+		await settle(sender, message, options?.onTimeout);
+		return false;
+	}
+	await winner.deferUpdate().catch(() => void 0);
+	const confirmed = winner.customId === CONFIRM_IDS.confirm;
+	await settle(sender, message, confirmed ? options?.onConfirm : options?.onCancel);
+	return confirmed;
 }
 
 //#endregion
-//#region src/bot/utilities/users/fetchManyUsers.ts
+//#region src/handlers/BaseHandler.ts
 /**
-* Fetches multiple Discord users by IDs.
-*
-* @param client - The Discord client instance
-* @param userIds - Array of Discord user IDs
-* @param options - Optional overrides threaded to each {@link fetchUser} call
-* @returns Promise resolving to array of successfully fetched users
+* The gateway base, fixes the core base's `TCore` to the gateway {@link Core} and adds the `getEvent`
+* gate hook.
 */
-async function fetchManyUsers(client, userIds, options) {
-	return (await Promise.allSettled(userIds.map((userId) => fetchUser(client, userId, options)))).filter((result) => result.status === "fulfilled").map((result) => result.value);
-}
+var BaseHandler$1 = class extends BaseHandler {
+	/** @internal */
+	getEvent() {
+		return this.event;
+	}
+};
 
 //#endregion
-//#region src/bot/utilities/users/updateMemberRoles.ts
+//#region src/handlers/interaction/InteractionMiddleware.ts
 /**
-* Updates a guild member's roles by adding and removing specified roles.
+* Base class for interaction middleware
 *
-* @param rolesToAdd - Array of role IDs to add to the member
-* @param rolesToRemove - Array of role IDs to remove from the member
-* @param member - The guild member to update
-* @returns Promise that resolves when roles are updated
+* Middleware runs before interaction handlers and can modify behavior or block execution.
+* Unlike handlers, middleware should not send responses directly.
+*
+* @typeParam Repliable - The interaction type this middleware processes
 */
-async function updateMemberRoles(rolesToAdd, rolesToRemove, member) {
-	const current = new Set(member.roles.cache.map((r) => r.id));
-	const toAdd = new Set(rolesToAdd);
-	const toRemove = new Set(rolesToRemove);
-	const updated = current.union(toAdd).difference(toRemove);
-	await member.roles.set([...updated]);
-}
+var InteractionMiddleware = class extends BaseHandler$1 {
+	constructor(event, core) {
+		super(event, core, void 0, "interactions");
+	}
+};
 
 //#endregion
 //#region src/bot/ReplySender.ts
+function isReplyFile(file) {
+	return typeof file === "object" && "data" in file && ArrayBuffer.isView(file.data);
+}
+function toDjsFile(file) {
+	if (!isReplyFile(file)) return file;
+	return {
+		attachment: Buffer.from(file.data),
+		name: file.name,
+		...file.description !== void 0 && { description: file.description },
+		...file.title !== void 0 && { title: file.title }
+	};
+}
 function seedState(interaction) {
 	if (interaction.deferred && interaction.ephemeral === null) return "deferred-update";
 	if (interaction.replied) return "replied";
@@ -835,7 +625,7 @@ var ReplySender = class extends BaseReplySender {
 			components: reply.components,
 			flags,
 			...reply.allowedMentions && { allowedMentions: reply.allowedMentions },
-			...reply.files && { files: [...reply.files] }
+			...reply.files && { files: reply.files.map(toDjsFile) }
 		};
 	}
 	editOptions(response) {
@@ -844,7 +634,7 @@ var ReplySender = class extends BaseReplySender {
 			components: reply.components,
 			flags: MessageFlags.IsComponentsV2,
 			...reply.allowedMentions && { allowedMentions: reply.allowedMentions },
-			...reply.files && { files: [...reply.files] }
+			...reply.files && { files: reply.files.map(toDjsFile) }
 		};
 	}
 	updateOptions(response) {
@@ -853,7 +643,7 @@ var ReplySender = class extends BaseReplySender {
 			components: reply.components,
 			flags: MessageFlags.IsComponentsV2,
 			...reply.allowedMentions && { allowedMentions: reply.allowedMentions },
-			...reply.files && { files: [...reply.files] }
+			...reply.files && { files: reply.files.map(toDjsFile) }
 		};
 	}
 	createdMessage(result) {
@@ -861,266 +651,6 @@ var ReplySender = class extends BaseReplySender {
 	}
 };
 
-//#endregion
-//#region src/bot/utilities/miscellaneous/slashRouteOf.ts
-/**
-* Computes the dispatch route for a chat-input or autocomplete interaction. The controller and
-* `seedcord codegen` both assemble route keys through the same {@link buildSlashRoute}, so a dispatched
-* interaction and a generated registry key always match.
-*
-* @internal
-*/
-function slashRouteOf(interaction) {
-	const group = interaction.options.getSubcommandGroup(false) ?? void 0;
-	const subcommand = interaction.options.getSubcommand(false) ?? void 0;
-	return buildSlashRoute(interaction.commandName, subcommand, group);
-}
-
-//#endregion
-//#region src/miscellaneous/extractErrorResponse.ts
-const logger$2 = new Logger("ErrorsHandling", { channel: "errors" });
-/**
-* Processes an error into a user-facing reply and routes its report.
-*
-* A {@link Notice} always renders its own reply. A reporting denial (`report: true`) additionally
-* publishes `handledException` on the interaction path. A raw, non-denial throw publishes
-* `unknownException` and renders the configured `defaultError` (or a generic {@link Fault}). One uuid is
-* threaded into both the reply and the bus payload.
-*/
-function extractErrorResponse(error, core, origin) {
-	const uuid = crypto.randomUUID();
-	const developerUsername = core.config.notifications?.developerUsername;
-	const ctx = developerUsername === void 0 ? { uuid } : {
-		uuid,
-		developerUsername
-	};
-	if (error instanceof Notice) {
-		if (error.report) reportFault(error, core, origin, uuid);
-		return {
-			uuid,
-			response: error.render(ctx)
-		};
-	}
-	reportRawFault(error, core, origin, uuid);
-	const override = core.config.errors?.defaultError;
-	return {
-		uuid,
-		response: override ? new override(uuid).render(ctx) : new Fault().render(ctx)
-	};
-}
-function withThrottle(core, origin, error, publish) {
-	const throttle = FaultThrottle.for(core);
-	const key = faultKey(origin, error);
-	if (!throttle.shouldReport(key)) {
-		logger$2.debug(`throttled duplicate fault ${key}`);
-		return;
-	}
-	publish();
-	throttle.markReported(key);
-}
-function reportFault(denial, core, origin, uuid) {
-	logger$2.error(`${denial.name}: ${uuid}`, denial);
-	withThrottle(core, origin, denial, () => {
-		if (origin.interaction) core.bus[PublishDefault]("handledException", {
-			denial,
-			uuid,
-			source: buildInteractionSource(origin.interaction)
-		});
-		else if (origin.event) core.bus[PublishDefault]("handledException", {
-			denial,
-			uuid,
-			source: buildEventSource(origin.event, origin)
-		});
-		else core.bus[PublishDefault]("unknownException", {
-			uuid,
-			error: denial,
-			...scalarActors(origin),
-			metadata: metadataFor(origin)
-		});
-	});
-}
-function causeLine(error) {
-	const { cause } = error;
-	if (!Error.isError(cause)) return "";
-	const [first] = cause.message.split("\n");
-	return `\ncaused by ${cause.name}: ${first ?? cause.message}`;
-}
-function reportRawFault(error, core, origin, uuid) {
-	if (core.config.errors?.errorStack ?? false) logger$2.error(uuid, error);
-	else logger$2.error(`${uuid} | ${error.message}${causeLine(error)}`);
-	withThrottle(core, origin, error, () => {
-		core.bus[PublishDefault]("unknownException", {
-			uuid,
-			error,
-			...scalarActors(origin),
-			metadata: metadataFor(origin)
-		});
-	});
-}
-function scalarActors(origin) {
-	return {
-		guild: origin.guild ? {
-			id: origin.guild.id,
-			name: origin.guild.name
-		} : void 0,
-		user: origin.user ? {
-			id: origin.user.id,
-			username: origin.user.username
-		} : void 0
-	};
-}
-function metadataFor(origin) {
-	if (origin.event) return {
-		eventName: origin.event.name,
-		handler: origin.event.handler,
-		args: origin.event.args
-	};
-	return origin.metadata;
-}
-function buildEventSource(event, origin) {
-	return {
-		kind: "event",
-		eventName: event.name,
-		handler: event.handler,
-		userId: origin.user?.id ?? null,
-		guildId: origin.guild?.id ?? null,
-		channelId: event.channelId,
-		raw: event.args
-	};
-}
-function faultKey(origin, error) {
-	const name = error instanceof Notice ? error.name : error instanceof DiscordAPIError ? String(error.code) : error.constructor.name;
-	if (origin.event) return `${origin.event.name}:${origin.event.handler}:${name}`;
-	if (origin.interaction) return `${interactionRoute(origin.interaction)}:${name}`;
-	if (origin.route) return `autocomplete:${origin.route}:${name}`;
-	return `autocomplete:${name}`;
-}
-/** The stable route id of a repliable interaction, its slash route path, command name, or customId prefix. */
-function interactionRoute(interaction) {
-	if (interaction.isChatInputCommand()) return slashRouteOf(interaction);
-	if (interaction.isContextMenuCommand()) return interaction.commandName;
-	if (interaction.isButton() || interaction.isAnySelectMenu() || interaction.isModalSubmit()) return prefixOf(interaction.customId) || interaction.customId;
-	return "interaction";
-}
-function buildInteractionSource(interaction) {
-	const command = interaction.isChatInputCommand() ? slashRouteOf(interaction) : interaction.isContextMenuCommand() ? interaction.commandName : null;
-	const customId = interaction.isButton() || interaction.isAnySelectMenu() || interaction.isModalSubmit() ? interaction.customId : null;
-	return {
-		kind: "interaction",
-		interactionKind: interactionKind(interaction),
-		command,
-		customId,
-		userId: interaction.user.id,
-		guildId: interaction.guildId,
-		channelId: interaction.channelId,
-		interactionId: interaction.id,
-		raw: interaction
-	};
-}
-function interactionKind(interaction) {
-	if (interaction.isChatInputCommand()) return "slash";
-	if (interaction.isContextMenuCommand()) return "context-menu";
-	if (interaction.isButton()) return "button";
-	if (interaction.isAnySelectMenu()) return "select";
-	return "modal";
-}
-
-//#endregion
-//#region src/bot/confirm/reserved.ts
-const RESERVED_CONFIRM_PREFIX = "__seedcord_confirm";
-/**
-* The reserved confirm/cancel codec. It has no route, so the dispatcher ignores its clicks and only the
-* in-process collector reads them. Do not mint a real component from it.
-*
-* @internal
-*/
-const CONFIRM_DEF = new CustomId(RESERVED_CONFIRM_PREFIX).oneOf("choice", ["confirm", "cancel"]);
-
-//#endregion
-//#region src/bot/confirm/getConfirmation.ts
-const DEFAULT_TIMEOUT_MS = 3e4;
-const CONFIRM_IDS = {
-	confirm: CONFIRM_DEF.encode({ choice: "confirm" }),
-	cancel: CONFIRM_DEF.encode({ choice: "cancel" })
-};
-var ConfirmButtons = class extends RowComponent {
-	constructor(options) {
-		super("button");
-		this.instance.addComponents(new ButtonBuilder().setCustomId(CONFIRM_IDS.confirm).setLabel(options?.confirmLabel ?? "Confirm").setStyle(options?.confirmStyle ?? ButtonStyle.Danger), new ButtonBuilder().setCustomId(CONFIRM_IDS.cancel).setLabel(options?.cancelLabel ?? "Cancel").setStyle(ButtonStyle.Secondary));
-	}
-};
-var ConfirmPromptCard = class extends BuilderComponent {
-	constructor(text, options) {
-		super("container");
-		this.instance.addTextDisplayComponents(new TextDisplayBuilder().setContent(text)).addActionRowComponents(new ConfirmButtons(options).component);
-	}
-};
-function defaultPrompt(text, options) {
-	return { components: [new ConfirmPromptCard(text, options).component] };
-}
-async function collectChoice(message, userId, timeoutMs) {
-	try {
-		return await message.awaitMessageComponent({
-			componentType: ComponentType.Button,
-			time: timeoutMs,
-			filter: (click) => click.user.id === userId && CONFIRM_DEF.owns(click.customId)
-		});
-	} catch {
-		return null;
-	}
-}
-async function settle(sender, message, outcome) {
-	if (outcome === void 0) {
-		await sender.delete(message).catch(() => void 0);
-		return;
-	}
-	await sender.edit(message, typeof outcome === "function" ? await outcome() : outcome);
-}
-async function getConfirmation(interaction, prompt, options) {
-	const { ephemeral = true, timeoutMs = DEFAULT_TIMEOUT_MS } = options ?? {};
-	const response = typeof prompt === "string" ? defaultPrompt(prompt, options) : await prompt(CONFIRM_IDS);
-	const sender = new ReplySender(interaction, interactionRoute(interaction));
-	const message = await sender.send(response, { ephemeral });
-	const winner = await collectChoice(message, interaction.user.id, timeoutMs);
-	if (!winner) {
-		await settle(sender, message, options?.onTimeout);
-		return false;
-	}
-	await winner.deferUpdate().catch(() => void 0);
-	const confirmed = winner.customId === CONFIRM_IDS.confirm;
-	await settle(sender, message, confirmed ? options?.onConfirm : options?.onCancel);
-	return confirmed;
-}
-
-//#endregion
-//#region src/handlers/BaseHandler.ts
-/**
-* The gateway base, fixes the core base's `TCore` to the gateway {@link Core} and adds the `getEvent`
-* gate hook.
-*/
-var BaseHandler$1 = class extends BaseHandler {
-	/** @internal */
-	getEvent() {
-		return this.event;
-	}
-};
-
-//#endregion
-//#region src/handlers/interaction/InteractionMiddleware.ts
-/**
-* Base class for interaction middleware
-*
-* Middleware runs before interaction handlers and can modify behavior or block execution.
-* Unlike handlers, middleware should not send responses directly.
-*
-* @typeParam Repliable - The interaction type this middleware processes
-*/
-var InteractionMiddleware = class extends BaseHandler$1 {
-	constructor(event, core) {
-		super(event, core, void 0, "interactions");
-	}
-};
-
 //#endregion
 //#region src/handlers/RepliableHandler.ts
 /**
@@ -1166,6 +696,21 @@ var InteractionHandler = class extends RepliableHandler {
 	}
 };
 
+//#endregion
+//#region src/bot/utilities/miscellaneous/slashRouteOf.ts
+/**
+* Computes the dispatch route for a chat-input or autocomplete interaction. The controller and
+* `seedcord codegen` both assemble route keys through the same {@link buildSlashRoute}, so a dispatched
+* interaction and a generated registry key always match.
+*
+* @internal
+*/
+function slashRouteOf(interaction) {
+	const group = interaction.options.getSubcommandGroup(false) ?? void 0;
+	const subcommand = interaction.options.getSubcommand(false) ?? void 0;
+	return buildSlashRoute(interaction.commandName, subcommand, group);
+}
+
 //#endregion
 //#region src/handlers/interaction/SlashHandler.ts
 /**
@@ -1485,7 +1030,22 @@ var ButtonHandler = class extends ComponentHandler {};
 * }
 * ```
 */
-var ModalHandler = class extends ComponentHandler {};
+var ModalHandler = class extends ComponentHandler {
+	/** Rewrite the message this modal was opened from. Throws when a command opened the modal. */
+	update(response) {
+		this.ensureSourceMessage("update");
+		return super.update(response);
+	}
+	/** Acknowledge the submit without changing the source message. Throws when a command opened the modal. */
+	deferUpdate() {
+		this.ensureSourceMessage("deferUpdate");
+		return super.deferUpdate();
+	}
+	ensureSourceMessage(method) {
+		if (this.event.isFromMessage()) return;
+		throw new SeedcordError(SeedcordErrorCode.ReplyUpdateWithoutSource, [method, this.routeId]);
+	}
+};
 
 //#endregion
 //#region src/handlers/interaction/components/SelectMenuHandler.ts
@@ -1599,138 +1159,14 @@ var EventMiddleware = class extends BaseHandler$1 {
 	}
 	/**
 	* The event that fired this middleware. Read it on a catchall or multi-event middleware, where `this.event`
-	* is `never`, to do work that does not depend on the payload shape. A single-event middleware reads
-	* `this.event` directly and does not need this.
-	*/
-	get eventName() {
-		if (this.firedEvent === void 0) throw new SeedcordError(SeedcordErrorCode.EventMiddlewareNameUnavailable);
-		return this.firedEvent;
-	}
-};
-
-//#endregion
-//#region src/pagination/controls.ts
-const DEFAULT_LABEL = {
-	first: "First",
-	prev: "Prev",
-	indicator: "",
-	next: "Next",
-	last: "Last"
-};
-const CONTROL_SLOT = {
-	first: 0,
-	prev: 1,
-	indicator: 2,
-	next: 3,
-	last: 4
-};
-const MAX_BUTTONS_PER_ROW = 5;
-var Controls = class {
-	cursor;
-	view;
-	constructor(cursor, view) {
-		this.cursor = cursor;
-		this.view = view;
-	}
-	button(key, cosmetics) {
-		const { target, disabled } = this.navState(key);
-		const defaultLabel = key === "indicator" ? this.indicatorText() : DEFAULT_LABEL[key];
-		const label = cosmetics?.label ?? (key === "indicator" || !cosmetics?.emoji ? defaultLabel : void 0);
-		const button = new ButtonBuilder().setCustomId(this.cursor.encode({
-			page: Math.min(Math.max(0, target), PAGE_MAX),
-			slot: CONTROL_SLOT[key]
-		})).setStyle(cosmetics?.style ?? ButtonStyle.Secondary).setDisabled(disabled);
-		if (label !== void 0) button.setLabel(label);
-		if (cosmetics?.emoji) button.setEmoji(cosmetics.emoji);
-		return button;
-	}
-	navState(key) {
-		const { page, totalPages, hasPrev, hasNext } = this.view;
-		const knownTotal = totalPages !== void 0;
-		return {
-			target: {
-				first: 0,
-				prev: page - 1,
-				indicator: page,
-				next: page + 1,
-				last: knownTotal ? totalPages - 1 : page
-			}[key],
-			disabled: {
-				first: !hasPrev,
-				prev: !hasPrev,
-				indicator: true,
-				next: !hasNext || page + 1 > PAGE_MAX,
-				last: !hasNext || !knownTotal || totalPages - 1 > PAGE_MAX
-			}[key]
-		};
-	}
-	row(...keys) {
-		if (keys.length === 0) throw new SeedcordRangeError(SeedcordErrorCode.PaginationEmptyControls);
-		if (keys.length > MAX_BUTTONS_PER_ROW) throw new SeedcordRangeError(SeedcordErrorCode.PaginationTooManyControls, [keys.length]);
-		const seen = /* @__PURE__ */ new Set();
-		for (const key of keys) {
-			if (seen.has(key)) throw new SeedcordTypeError(SeedcordErrorCode.PaginationDuplicateControls, [key]);
-			seen.add(key);
-		}
-		return new ActionRowBuilder().addComponents(keys.map((key) => this.button(key)));
-	}
-	indicatorText() {
-		const { page, totalPages } = this.view;
-		return totalPages === void 0 ? `Page ${page + 1}` : `Page ${page + 1} of ${totalPages}`;
-	}
-};
-
-//#endregion
-//#region src/pagination/render.ts
-var PageContainer = class extends BuilderComponent {
-	constructor(view, renderItem, controlRow) {
-		super("container");
-		const base = view.page * view.perPage;
-		let lines = [];
-		const flush = () => {
-			if (lines.length === 0) return;
-			this.instance.addTextDisplayComponents(new TextDisplayBuilder().setContent(lines.join("\n")));
-			lines = [];
-		};
-		view.items.forEach((item, offset) => {
-			const rendered = renderItem(item, base + offset);
-			if (typeof rendered === "string") {
-				lines.push(rendered);
-				return;
-			}
-			flush();
-			this.instance.addSectionComponents(rendered.component);
-		});
-		flush();
-		this.instance.addActionRowComponents(controlRow);
+	* is `never`, to do work that does not depend on the payload shape. A single-event middleware reads
+	* `this.event` directly and does not need this.
+	*/
+	get eventName() {
+		if (this.firedEvent === void 0) throw new SeedcordError(SeedcordErrorCode.EventMiddlewareNameUnavailable);
+		return this.firedEvent;
 	}
 };
-function toReplyResponse(renderable) {
-	if (typeof renderable === "string") return { components: [new TextDisplayBuilder().setContent(renderable)] };
-	if (Array.isArray(renderable)) return { components: renderable };
-	return renderable;
-}
-const ARRAY_KEYS = [
-	"first",
-	"prev",
-	"indicator",
-	"next",
-	"last"
-];
-const CURSOR_KEYS = [
-	"prev",
-	"indicator",
-	"next"
-];
-/**
-* Build a page's V2 reply. A `render` override builds the whole tree, otherwise the default container lists
-* the items and appends the controls (all five for a known total, prev/indicator/next for a cursor source).
-*/
-function renderPage(view, cursor, config) {
-	const controls = new Controls(cursor, view);
-	if (config.render) return toReplyResponse(config.render(view, controls));
-	return { components: [new PageContainer(view, config.renderItem ?? String, controls.row(...view.totalPages === void 0 ? CURSOR_KEYS : ARRAY_KEYS)).component] };
-}
 
 //#endregion
 //#region src/pagination/Paginator.ts
@@ -1739,7 +1175,7 @@ function contextOf(interaction, core) {
 		interaction,
 		user: interaction.user,
 		guild: interaction.guild,
-		...core && { core }
+		core
 	};
 }
 /**
@@ -1761,15 +1197,11 @@ function contextOf(interaction, core) {
 * export class BansNav extends Bans.Handler {}
 * ```
 */
-var Paginator = class {
-	/** The page cursor, pass it to your `@ButtonRoute`. */
-	cursor;
+var Paginator = class extends PaginatorBase {
 	/** The nav handler base. Extend it with an empty body and decorate it, `@ButtonRoute(p.cursor)`. */
 	Handler;
-	config;
 	constructor(config) {
-		this.cursor = pageCursor(config.prefix);
-		this.config = config;
+		super(config);
 		const loadPage = (ctx, n) => this.page(ctx, n);
 		this.Handler = class Nav extends ButtonHandler {
 			async execute() {
@@ -1780,7 +1212,8 @@ var Paginator = class {
 		};
 	}
 	/**
-	* Render page 0 and send it through the handler's sender, picking reply or followUp from its ack state.
+	* Render page 0 and send it through the handler's sender, which picks reply, edit, or followUp from its
+	* ack state.
 	*
 	* @param handler - The handler starting the paginator, normally `this`.
 	*/
@@ -1789,34 +1222,18 @@ var Paginator = class {
 		const response = await this.page(contextOf(interaction, handler.core), 0);
 		return handler.getSender().send(response, { ephemeral: this.config.ephemeral ?? false });
 	}
-	/** Render a page as a {@link ReplyResponse}. To post it elsewhere, add `flags: MessageFlags.IsComponentsV2`. */
-	async page(ctx, n) {
-		return renderPage(await this.config.source.page(ctx, n), this.cursor, this.config);
-	}
 };
 
 //#endregion
 //#region src/pagination/sources.ts
-const DEFAULT_PER_PAGE = 10;
 /**
 * A source for a bounded list you can load whole. It loads the full list on every click, then slices the
-* page via {@link paginate}, so the real total is known (a real last button, "Page X of Y"). Cache inside
-* your loader if the load is expensive.
+* page, so the real total is known (a real last button, "Page X of Y"). Cache inside your loader if the
+* load is expensive.
 *
 * @typeParam Item - The item type, inferred from the loader's return.
 */
-var ArraySource = class {
-	load;
-	perPage;
-	constructor(load, opts) {
-		this.load = load;
-		this.perPage = opts?.perPage ?? DEFAULT_PER_PAGE;
-		if (!Number.isSafeInteger(this.perPage) || this.perPage <= 0) throw new SeedcordRangeError(SeedcordErrorCode.PaginationInvalidPerPage, [this.perPage]);
-	}
-	async page(ctx, n) {
-		return paginate(await this.load(ctx), n, this.perPage);
-	}
-};
+var ArraySource = class extends ArraySource$1 {};
 /**
 * A source for a large or unknown-length set you fetch one page at a time (SQL LIMIT/OFFSET, a paged API).
 * The fetcher receives the page index and the page size and reports whether a next page exists. A cursor
@@ -1825,26 +1242,7 @@ var ArraySource = class {
 *
 * @typeParam Item - The item type, inferred from the fetcher's slice.
 */
-var CursorSource = class {
-	fetch;
-	perPage;
-	constructor(fetch, opts) {
-		this.fetch = fetch;
-		this.perPage = opts?.perPage ?? DEFAULT_PER_PAGE;
-		if (!Number.isSafeInteger(this.perPage) || this.perPage <= 0) throw new SeedcordRangeError(SeedcordErrorCode.PaginationInvalidPerPage, [this.perPage]);
-	}
-	async page(ctx, n) {
-		const page = Math.max(0, Math.trunc(n));
-		const { items, hasNext } = await this.fetch(ctx, page, this.perPage);
-		return {
-			items: [...items],
-			page,
-			perPage: this.perPage,
-			hasPrev: page > 0,
-			hasNext
-		};
-	}
-};
+var CursorSource = class extends CursorSource$1 {};
 
 //#endregion
 //#region src/subscribers/index.ts
@@ -1868,236 +1266,12 @@ var WebhookLog = class extends WebhookLog$1 {};
 * Base class for a gateway plugin, binding `this.core` to the gateway {@link Core}.
 *
 * A plugin that runs on either transport extends the base from `@seedcord/core/plugin`, whose
-* `this.core` carries the shared members only.
+* `this.core` is typed to the shared members only.
 *
-* @typeParam Opts - The transport, runtime, and capabilities the plugin declares.
+* @typeParam Opts - The transport and runtime the plugin declares.
 */
 var Plugin = class extends Plugin$1 {};
 
-//#endregion
-//#region src/bot/utilities/miscellaneous/contextMenuLeaves.ts
-/**
-* Collects the names of every registered context-menu command across a set of command builders, split into a
-* user set and a message set. The same builder may appear more than once (a guild command is pushed once per
-* guild), and slash commands carry no context-menu name, so both collapse here. The split mirrors the
-* controller's two name-keyed maps, so the boot guard checks each name against its own kind.
-*
-* @internal
-*/
-function contextMenuLeaves(commands) {
-	const user = /* @__PURE__ */ new Set();
-	const message = /* @__PURE__ */ new Set();
-	for (const command of commands) {
-		if (!(command instanceof ContextMenuCommandBuilder)) continue;
-		if (command.type === ApplicationCommandType.User) user.add(command.name);
-		else message.add(command.name);
-	}
-	return {
-		user,
-		message
-	};
-}
-
-//#endregion
-//#region src/bot/utilities/miscellaneous/slashRouteLeaves.ts
-/**
-* Collects the route keys of every executable slash leaf across a set of command builders, deduplicated. The
-* same builder may appear more than once (a guild command is pushed once per guild), and context-menu
-* commands carry no slash route, so both collapse here. Route keys come from the same {@link routeLeavesOf}
-* that `seedcord codegen` reads, so the boot-time check compares against the generated registry's keys.
-*
-* @internal
-*/
-function slashRouteLeaves(commands) {
-	const leaves = /* @__PURE__ */ new Set();
-	for (const command of commands) {
-		if (!(command instanceof SlashCommandBuilder)) continue;
-		for (const leaf of routeLeavesOf(command.toJSON())) leaves.add(leaf.route);
-	}
-	return leaves;
-}
-
-//#endregion
-//#region src/bot/controllers/CommandRegistry.ts
-/**
-* Manages Discord application command registration and deployment.
-*
-* Scans command directories, builds command structures, and registers both global and guild-scoped commands
-* to Discord's API. Accessed via `core.bot.commands`. Do not construct it directly.
-*/
-var CommandRegistry = class {
-	core;
-	onDeployed;
-	logger = new Logger("Commands", { channel: "commands" });
-	isInitialised = false;
-	globalCommands = [];
-	guildCommands = new Collection();
-	ctorToCommand = /* @__PURE__ */ new Map();
-	loading = false;
-	loadedCommands = [];
-	hmrHandler;
-	pendingEvents = /* @__PURE__ */ new Map();
-	constructor(core, onDeployed) {
-		this.core = core;
-		this.onDeployed = onDeployed;
-		const commandsDir = this.core.config.bot.commands.path;
-		if (!commandsDir) throw new SeedcordError(SeedcordErrorCode.CoreControllerPathMissing, ["CommandRegistry", "commands"]);
-		if (!Envapter.isDevelopment && !Envapter.isTest) return;
-		this.hmrHandler = new HmrModuleHandler({
-			handlersDir: commandsDir,
-			isHandler: this.isCommandClass.bind(this),
-			registerHandler: this.registerCommand.bind(this),
-			unregisterHandler: this.unregisterCommand.bind(this),
-			getArtifacts: this.getArtifacts.bind(this),
-			logger: this.logger
-		});
-	}
-	getArtifacts(ctor) {
-		return this.ctorToCommand.get(ctor);
-	}
-	/** @internal */
-	async init() {
-		if (this.isInitialised) return;
-		this.isInitialised = true;
-		const commandsDir = this.core.config.bot.commands.path;
-		if (!commandsDir) return;
-		this.loading = true;
-		this.loadedCommands.length = 0;
-		try {
-			await this.loadCommands(commandsDir);
-		} finally {
-			this.loading = false;
-		}
-		this.reportLoad();
-		getDevChannel()?.on("seedcord:refresh-commands", (data) => {
-			this.refresh(data.shouldRefresh);
-		});
-	}
-	reportLoad() {
-		const { utils } = this.logger;
-		utils.summary("Loaded commands", {
-			global: this.globalCommands.length,
-			"guild groups": this.guildCommands.size
-		});
-		let slash = 0;
-		let menu = 0;
-		for (const command of this.loadedCommands) if (command.kind === "slash command") slash++;
-		else menu++;
-		utils.block("Loaded commands", [...utils.entries(this.loadedCommands), ...utils.counts({
-			"slash commands": slash,
-			"context menus": menu
-		})]);
-	}
-	/** @internal */
-	async refresh(shouldRefresh = true) {
-		if (!shouldRefresh) {
-			this.logger.info(chalk.italic("Command refresh cancelled."));
-			this.pendingEvents.clear();
-			return;
-		}
-		this.logger.info(chalk.italic("Refreshing commands..."));
-		for (const event of this.pendingEvents.values()) await this.hmrHandler?.handle(event);
-		this.pendingEvents.clear();
-		await this.setCommands();
-	}
-	/** @internal */
-	async onHmr(event) {
-		const commandsDir = this.core.config.bot.commands.path;
-		if (commandsDir && event.file.startsWith(resolve(process.cwd(), commandsDir))) {
-			this.pendingEvents.delete(event.file);
-			this.pendingEvents.set(event.file, event);
-			getDevChannel()?.send("seedcord:commands-update-prompt", { files: [...this.pendingEvents.keys()].map((f) => formatFilePath(f)) });
-		} else await this.hmrHandler?.handle(event);
-	}
-	async loadCommands(dir) {
-		await traverseDirectory(dir, (fullPath, rel, mod) => {
-			for (const exported of Object.values(mod)) if (this.isCommandClass(exported)) {
-				this.registerCommand(exported, rel);
-				this.hmrHandler?.trackHandler(fullPath, exported);
-			}
-		});
-	}
-	isCommandClass(obj) {
-		if (typeof obj !== "function") return false;
-		return obj.prototype instanceof BuilderComponent && Reflect.hasMetadata(CommandMetadataKey, obj);
-	}
-	registerCommand(ctor, rel) {
-		const meta = Reflect.getMetadata(CommandMetadataKey, ctor);
-		if (!meta) return;
-		const comp = new ctor().component;
-		const kind = comp instanceof SlashCommandBuilder ? "slash command" : "context menu";
-		if (meta.scope === "global") this.globalCommands.push(comp);
-		else for (const g of meta.guilds) {
-			const arr = this.guildCommands.get(g) ?? [];
-			arr.push(comp);
-			this.guildCommands.set(g, arr);
-		}
-		this.ctorToCommand.set(ctor, {
-			name: comp.name,
-			scope: meta.scope,
-			...meta.scope === "guild" && { guilds: meta.guilds }
-		});
-		if (this.loading) {
-			this.loadedCommands.push({
-				name: comp.name,
-				from: formatFilePath(rel),
-				kind
-			});
-			return;
-		}
-		this.logger.utils.registration(comp.name, rel, `${meta.scope} ${kind}`);
-	}
-	unregisterCommand(ctor, artifacts) {
-		const info = artifacts ?? this.ctorToCommand.get(ctor);
-		if (!info) return;
-		if (info.scope === "global") {
-			const idx = this.globalCommands.findIndex((c) => c.name === info.name);
-			if (idx !== -1) this.globalCommands.splice(idx, 1);
-		} else for (const g of info.guilds ?? []) {
-			const arr = this.guildCommands.get(g);
-			if (arr) {
-				const idx = arr.findIndex((c) => c.name === info.name);
-				if (idx !== -1) arr.splice(idx, 1);
-			}
-		}
-		this.ctorToCommand.delete(ctor);
-	}
-	/** @internal */
-	async setCommands() {
-		const result = {
-			global: new Collection(),
-			guilds: new Collection()
-		};
-		if (this.globalCommands.length > 0) {
-			const deployed = await this.core.bot.client.application?.commands.set(this.globalCommands);
-			if (deployed) result.global = deployed;
-			const tag = this.globalCommands.length === 1 ? "command" : "commands";
-			this.logger.utils.block(`Deployed ${this.globalCommands.length} global ${tag}`, this.logger.utils.wrap(this.globalCommands.map((command) => command.name)), "info");
-		}
-		for (const [guildId, commands] of this.guildCommands.entries()) {
-			const guild = this.core.bot.client.guilds.cache.get(guildId);
-			if (!guild) {
-				this.logger.warn(`Guild with ID ${guildId} not found, skipping command registration.`);
-				continue;
-			}
-			const deployed = await guild.commands.set(commands);
-			result.guilds.set(guildId, deployed);
-			const tag = commands.length === 1 ? "command" : "commands";
-			this.logger.utils.block(`Deployed ${commands.length} ${tag} to ${paint.amber.bold(guild.name)}`, this.logger.utils.wrap(commands.map((command) => command.name)), "info");
-		}
-		this.onDeployed?.(result);
-		return result;
-	}
-	/** The deduplicated slash route keys across every global and guild command. @internal */
-	routeLeaves() {
-		return slashRouteLeaves([...this.globalCommands, ...this.guildCommands.values()].flat());
-	}
-	/** The registered context-menu command names, split by kind, across every global and guild command. @internal */
-	contextMenuLeaves() {
-		return contextMenuLeaves([...this.globalCommands, ...this.guildCommands.values()].flat());
-	}
-};
-
 //#endregion
 //#region src/miscellaneous/deriveEventActor.ts
 function deriveEventActor(args) {
@@ -2175,6 +1349,154 @@ function eventGateContext(eventName, args, core) {
 	};
 }
 
+//#endregion
+//#region src/miscellaneous/extractErrorResponse.ts
+const logger$2 = new Logger("ErrorsHandling", { channel: "errors" });
+/**
+* Processes an error into a user-facing reply and routes its report.
+*
+* A {@link Notice} always renders its own reply. A reporting denial (`report: true`) additionally
+* publishes `handledException` on the interaction path. A raw, non-denial throw publishes
+* `unknownException` and renders the configured `defaultError` (or a generic {@link Fault}). One uuid is
+* threaded into both the reply and the bus payload.
+*/
+function extractErrorResponse(error, core, origin) {
+	const uuid = crypto.randomUUID();
+	const developerUsername = core.config.notifications?.developerUsername;
+	const ctx = developerUsername === void 0 ? { uuid } : {
+		uuid,
+		developerUsername
+	};
+	if (error instanceof Notice) {
+		if (error.report) reportFault(error, core, origin, uuid);
+		return {
+			uuid,
+			response: error.render(ctx)
+		};
+	}
+	reportRawFault(error, core, origin, uuid);
+	const override = core.config.errors?.defaultError;
+	return {
+		uuid,
+		response: override ? new override(uuid).render(ctx) : new Fault().render(ctx)
+	};
+}
+function withThrottle(core, origin, error, publish) {
+	const throttle = FaultThrottle.for(core);
+	const key = faultKey(origin, error);
+	if (!throttle.shouldReport(key)) {
+		logger$2.debug(`throttled duplicate fault ${key}`);
+		return;
+	}
+	publish();
+	throttle.markReported(key);
+}
+function reportFault(denial, core, origin, uuid) {
+	logger$2.error(`${denial.name}: ${uuid}`, denial);
+	withThrottle(core, origin, denial, () => {
+		if (origin.interaction) core.bus[PublishDefault]("handledException", {
+			denial,
+			uuid,
+			source: buildInteractionSource(origin.interaction)
+		});
+		else if (origin.event) core.bus[PublishDefault]("handledException", {
+			denial,
+			uuid,
+			source: buildEventSource(origin.event, origin)
+		});
+		else core.bus[PublishDefault]("unknownException", {
+			uuid,
+			error: denial,
+			...scalarActors(origin),
+			metadata: metadataFor(origin)
+		});
+	});
+}
+function causeLine(error) {
+	const { cause } = error;
+	if (!Error.isError(cause)) return "";
+	const [first] = cause.message.split("\n");
+	return `\ncaused by ${cause.name}: ${first ?? cause.message}`;
+}
+function reportRawFault(error, core, origin, uuid) {
+	if (core.config.errors?.errorStack ?? false) logger$2.error(uuid, error);
+	else logger$2.error(`${uuid} | ${error.message}${causeLine(error)}`);
+	withThrottle(core, origin, error, () => {
+		core.bus[PublishDefault]("unknownException", {
+			uuid,
+			error,
+			...scalarActors(origin),
+			metadata: metadataFor(origin)
+		});
+	});
+}
+function scalarActors(origin) {
+	return {
+		guild: origin.guild ? {
+			id: origin.guild.id,
+			name: origin.guild.name
+		} : void 0,
+		user: origin.user ? {
+			id: origin.user.id,
+			username: origin.user.username
+		} : void 0
+	};
+}
+function metadataFor(origin) {
+	if (origin.event) return {
+		eventName: origin.event.name,
+		handler: origin.event.handler,
+		args: origin.event.args
+	};
+	return origin.metadata;
+}
+function buildEventSource(event, origin) {
+	return {
+		kind: "event",
+		eventName: event.name,
+		handler: event.handler,
+		userId: origin.user?.id ?? null,
+		guildId: origin.guild?.id ?? null,
+		channelId: event.channelId,
+		raw: event.args
+	};
+}
+function faultKey(origin, error) {
+	const name = error instanceof Notice ? error.name : error instanceof DiscordAPIError ? String(error.code) : error.constructor.name;
+	if (origin.event) return `${origin.event.name}:${origin.event.handler}:${name}`;
+	if (origin.interaction) return `${interactionRoute(origin.interaction)}:${name}`;
+	if (origin.route) return `autocomplete:${origin.route}:${name}`;
+	return `autocomplete:${name}`;
+}
+function interactionRoute(interaction) {
+	if (interaction.isChatInputCommand()) return slashRouteOf(interaction);
+	if (interaction.isContextMenuCommand()) return interaction.commandName;
+	if (interaction.isButton() || interaction.isAnySelectMenu() || interaction.isModalSubmit()) return prefixOf(interaction.customId) || interaction.customId;
+	return "interaction";
+}
+function buildInteractionSource(interaction) {
+	const command = interaction.isChatInputCommand() ? slashRouteOf(interaction) : interaction.isContextMenuCommand() ? interaction.commandName : null;
+	const customId = interaction.isButton() || interaction.isAnySelectMenu() || interaction.isModalSubmit() ? interaction.customId : null;
+	return {
+		kind: "interaction",
+		interactionKind: interactionKind(interaction),
+		command,
+		customId,
+		userId: interaction.user.id,
+		guildId: interaction.guildId,
+		channelId: interaction.channelId,
+		interactionId: interaction.id,
+		raw: interaction
+	};
+}
+function interactionKind(interaction) {
+	if (interaction.isChatInputCommand()) return "slash";
+	if (interaction.isContextMenuCommand()) return "context-menu";
+	if (interaction.isButton()) return "button";
+	if (interaction.isAnySelectMenu()) return "select";
+	return "modal";
+}
+
 //#endregion
 //#region src/bot/handleEventFault.ts
 const logger$1 = new Logger("EventBoundary", { channel: "errors" });
@@ -2608,21 +1930,9 @@ var InteractionDispatcher = class {
 			logger: this.logger
 		});
 	}
-	/**
-	* Warns for each command route with no registered `@SlashRoute` handler, which would fall through to
-	* UnhandledRepliable at runtime. A bot may route commands outside the registry, so this does not throw.
-	*
-	* @internal
-	*/
 	warnUnhandledRoutes(commandLeaves) {
 		for (const route of commandLeaves) if (!this.slashMap.has(route)) this.logger.warn(`Slash route ${paint.sky.bold(route)} has no registered ${chalk.bold("@SlashRoute")} handler.`);
 	}
-	/**
-	* Warns for each context-menu command with no matching handler, which would fall through to UnhandledRepliable
-	* at runtime. Checked per kind since a user and a message command can share a name.
-	*
-	* @internal
-	*/
 	warnUnhandledContextMenuRoutes(leaves) {
 		for (const name of leaves.user) if (!this.userContextMenuMap.has(name)) this.logger.warn(`User context menu ${paint.sky.bold(name)} has no registered ${chalk.bold("@ContextMenuRoute")} handler.`);
 		for (const name of leaves.message) if (!this.messageContextMenuMap.has(name)) this.logger.warn(`Message context menu ${paint.sky.bold(name)} has no registered ${chalk.bold("@ContextMenuRoute")} handler.`);
@@ -2963,29 +2273,39 @@ var Bot = class {
 	interactions;
 	events;
 	emojiInjector;
-	commands;
-	emojis = Emojis;
-	mentions = CommandMentions;
+	commandRegistry;
 	/** @internal */
 	async onHmr(event) {
 		if (this.interactions) await this.interactions.onHmr(event);
 		if (this.events) await this.events.onHmr(event);
-		if (this.commands) await this.commands.onHmr(event);
+		if (this.commandRegistry) await this.commandRegistry.onHmr(event);
 	}
 	/** @internal */
 	constructor(core) {
 		this._client = new Client(core.config.bot.clientOptions);
 		if (core.config.bot.interactions.path) this.interactions = new InteractionDispatcher(core);
 		if (core.config.bot.events.path) this.events = new EventDispatcher(core);
-		if (core.config.bot.commands.path) {
-			const mentionInjector = new CommandMentionInjector(core);
-			this.commands = new CommandRegistry(core, (result) => {
-				mentionInjector.inject(result);
+		const commandsDir = core.config.bot.commands.path;
+		if (commandsDir) {
+			const injector = new CommandInjector();
+			const registry = new CommandRegistry({
+				dir: commandsDir,
+				rest: this._client.rest,
+				applicationId: () => this.applicationId(),
+				onDeployed: (result) => {
+					injector.inject(result, registry.allCommands());
+				}
 			});
+			this.commandRegistry = registry;
 		}
 		this.emojiInjector = new EmojiInjector(core);
 		this.registerShutdownTasks(core);
 	}
+	applicationId() {
+		const { application } = this._client;
+		if (!application) throw new SeedcordError(SeedcordErrorCode.CoreApplicationUnavailable);
+		return application.id;
+	}
 	registerShutdownTasks(core) {
 		core.shutdown.addTask(ShutdownPhase.Unbind, "stop-dispatch", () => {
 			this.stopAccepting();
@@ -3010,11 +2330,11 @@ var Bot = class {
 		if (this.events) await this.events.init();
 		await this.login(token);
 		await this.emojiInjector.init();
-		if (this.commands) {
-			await this.commands.init();
-			await this.commands.setCommands();
-			this.interactions?.warnUnhandledRoutes(this.commands.routeLeaves());
-			this.interactions?.warnUnhandledContextMenuRoutes(this.commands.contextMenuLeaves());
+		if (this.commandRegistry) {
+			await this.commandRegistry.init();
+			await this.commandRegistry.setCommands();
+			this.interactions?.warnUnhandledRoutes(this.commandRegistry.routeLeaves());
+			this.interactions?.warnUnhandledContextMenuRoutes(this.commandRegistry.contextMenuLeaves());
 		}
 	}
 	/** @internal */
@@ -3043,7 +2363,7 @@ __decorate([Envapt("DISCORD_BOT_TOKEN", { converter: (raw) => validateDiscordTok
 //#endregion
 //#region src/version.ts
 /** Package version */
-const version = "0.1.0-next.5";
+const version = "0.1.0";
 
 //#endregion
 //#region src/Seedcord.ts
@@ -3066,6 +2386,8 @@ var Seedcord = class Seedcord extends Pluggable {
 	subscribers;
 	/** @see {@link Bot} */
 	bot;
+	/** The discord.js client's REST client. Its token is set during the Login phase. */
+	rest;
 	/** @see {@link IRateLimiter} */
 	rateLimiter;
 	/**
@@ -3082,6 +2404,7 @@ var Seedcord = class Seedcord extends Pluggable {
 		this.bus = new Bus(this);
 		this.subscribers = new SubscriberLoader(this.bus, config.subscribers.path);
 		this.bot = new Bot(this);
+		this.rest = this.bot.client.rest;
 		this.rateLimiter = config.store ?? new MemoryRateLimiter();
 		this.healthCheck = HealthCheck.fromOption(this.shutdown, config.healthCheck);
 		this.registerStartupTasks();
@@ -3090,13 +2413,6 @@ var Seedcord = class Seedcord extends Pluggable {
 	get username() {
 		return this.bot.client.user?.username;
 	}
-	pluginCapabilities() {
-		return {
-			client: this.bot.client,
-			token: this.bot.botToken,
-			rest: this.bot.client.rest
-		};
-	}
 	static reset() {
 		super.reset();
 		LoggerChannelRegistry.instance.reset();
@@ -3146,5 +2462,5 @@ var Seedcord = class Seedcord extends Pluggable {
 };
 
 //#endregion
-export { ArraySource, AutocompleteHandler, ButtonHandler, CommandMentions, ContextMenuHandler, CursorSource, Emojis, EventHandler, EventMiddleware, Gated, IgnoreBots, InteractionHandler, InteractionMiddleware, Middleware, MiddlewareType, ModalHandler, Nsfw, Paginator, Plugin, RegisterEvent, RepliableHandler, Seedcord, SelectMenuHandler, SlashHandler, Subscriber, WebhookLog, checkBotPermissions, checkPermissions, fetchGuildMember, fetchManyGuildMembers, fetchManyUsers, fetchRole, fetchText, fetchUser, getBotRole, getConfirmation, hasPermsToAssign, updateMemberRoles, version };
+export { ArraySource, AutocompleteHandler, ButtonHandler, ContextMenuHandler, CursorSource, Emojis, EventHandler, EventMiddleware, Gated, IgnoreBots, InteractionHandler, InteractionMiddleware, Middleware, MiddlewareType, ModalHandler, Nsfw, Paginator, Plugin, RegisterEvent, RepliableHandler, Seedcord, SelectMenuHandler, SlashHandler, Subscriber, WebhookLog, checkBotPermissions, checkPermissions, getConfirmation, hasPermsToAssign, version };
 //# sourceMappingURL=index.mjs.map