meocord 3.0.0 → 3.1.0

package/dist/esm/bin/builder-template/controller/autocomplete.controller.template

@@ -0,0 +1,16 @@
+import { AutocompleteInteraction } from 'discord.js'
+import { Controller, Autocomplete } from 'meocord/decorator'
+
+@Controller()
+export class {{className}}AutocompleteController {
+
+  // The option this completes must be declared with `.setAutocomplete(true)` on the
+  // slash command builder, otherwise Discord never sends the interaction.
+  @Autocomplete('sample-slash', 'query')
+  async completeQuery(interaction: AutocompleteInteraction) {
+    const { value } = interaction.options.getFocused(true)
+    const choices = ['alpha', 'beta', 'gamma'].filter(choice => choice.startsWith(value))
+
+    await interaction.respond(choices.map(choice => ({ name: choice, value: choice })))
+  }
+}

package/dist/esm/bin/builder-template/controller/channel-select-menu.controller.template

@@ -0,0 +1,12 @@
+import { ChannelSelectMenuInteraction } from 'discord.js'
+import { Controller, Command } from 'meocord/decorator'
+import { CommandType } from 'meocord/enum'
+
+@Controller()
+export class {{className}}ChannelSelectMenuController {
+
+  @Command('channel-select-menu', CommandType.CHANNEL_SELECT_MENU)
+  async handleChannelSelectMenu(interaction: ChannelSelectMenuInteraction) {
+    await interaction.reply(`Selected: ${interaction.channels.map(channel => channel.toString()).join(', ')}`)
+  }
+}

package/dist/esm/bin/builder-template/controller/context-menu.controller.template

@@ -1,6 +1,6 @@
 import { UserContextMenuCommandInteraction, MessageContextMenuCommandInteraction } from 'discord.js'
-import { Controller, Command, CommandType } from 'meocord/decorator'
-import { SampleCommandBuilder } from '@src/controllers/context-menu/builders/sample.builder'
+import { Controller, Command } from 'meocord/decorator'
+import { SampleCommandBuilder } from '{{builderImportPath}}'
 
 @Controller()
 export class {{className}}ContextMenuController {

package/dist/esm/bin/builder-template/controller/mentionable-select-menu.controller.template

@@ -0,0 +1,12 @@
+import { MentionableSelectMenuInteraction } from 'discord.js'
+import { Controller, Command } from 'meocord/decorator'
+import { CommandType } from 'meocord/enum'
+
+@Controller()
+export class {{className}}MentionableSelectMenuController {
+
+  @Command('mentionable-select-menu', CommandType.MENTIONABLE_SELECT_MENU)
+  async handleMentionableSelectMenu(interaction: MentionableSelectMenuInteraction) {
+    await interaction.reply(`Selected ${interaction.users.size} user(s) and ${interaction.roles.size} role(s).`)
+  }
+}

package/dist/esm/bin/builder-template/controller/modal-submit.controller.template

@@ -3,7 +3,7 @@ import { Controller, Command } from 'meocord/decorator'
 import { CommandType } from 'meocord/enum'
 
 @Controller()
-export class {{className}}ModalController {
+export class {{className}}ModalSubmitController {
 
   @Command('submit-modal', CommandType.MODAL_SUBMIT)
   async handleModal(interaction: ModalSubmitInteraction) {

package/dist/esm/bin/builder-template/controller/primary-entry-point.controller.template

@@ -0,0 +1,12 @@
+import { PrimaryEntryPointCommandInteraction } from 'discord.js'
+import { Controller, Command } from 'meocord/decorator'
+import { SampleCommandBuilder } from '{{builderImportPath}}'
+
+@Controller()
+export class {{className}}PrimaryEntryPointController {
+
+  @Command('sample-entry-point', SampleCommandBuilder)
+  async handleEntryPoint(interaction: PrimaryEntryPointCommandInteraction) {
+    await interaction.reply('Launching the activity.')
+  }
+}

package/dist/esm/bin/builder-template/controller/role-select-menu.controller.template

@@ -0,0 +1,12 @@
+import { RoleSelectMenuInteraction } from 'discord.js'
+import { Controller, Command } from 'meocord/decorator'
+import { CommandType } from 'meocord/enum'
+
+@Controller()
+export class {{className}}RoleSelectMenuController {
+
+  @Command('role-select-menu', CommandType.ROLE_SELECT_MENU)
+  async handleRoleSelectMenu(interaction: RoleSelectMenuInteraction) {
+    await interaction.reply(`Selected: ${interaction.roles.map(role => role.name).join(', ')}`)
+  }
+}

package/dist/esm/bin/builder-template/controller/slash.controller.template

@@ -1,6 +1,6 @@
 import { ChatInputCommandInteraction } from 'discord.js'
 import { Controller, Command } from 'meocord/decorator'
-import { SampleCommandBuilder } from '@src/controllers/slash/builders/sample.builder'
+import { SampleCommandBuilder } from '{{builderImportPath}}'
 
 @Controller()
 export class {{className}}SlashController {

package/dist/esm/bin/builder-template/controller/user-select-menu.controller.template

@@ -0,0 +1,12 @@
+import { UserSelectMenuInteraction } from 'discord.js'
+import { Controller, Command } from 'meocord/decorator'
+import { CommandType } from 'meocord/enum'
+
+@Controller()
+export class {{className}}UserSelectMenuController {
+
+  @Command('user-select-menu', CommandType.USER_SELECT_MENU)
+  async handleUserSelectMenu(interaction: UserSelectMenuInteraction) {
+    await interaction.reply(`Selected: ${interaction.users.map(user => user.username).join(', ')}`)
+  }
+}

package/dist/esm/bin/generator.js

@@ -1,4 +1,5 @@
 import { Argument } from 'commander';
+import { ControllerType } from '../enum/controller.enum.js';
 import { ControllerGeneratorHelper } from './helper/controller-generator.helper.js';
 import { Logger } from '../common/logger.js';
 import '../common/theme.js';
@@ -9,15 +10,9 @@ import wait from '../util/wait.util.js';
 class GeneratorCLI {
     register(program) {
         const generatorCommand = program.command('generate').alias('g').description('Generate components');
-        generatorCommand.command('controller').alias('co').description('Generate a controller component').addArgument(new Argument('<type>', 'Type of the controller (e.g., button, context-menu, etc.)').choices([
-            'button',
-            'context-menu',
-            'message',
-            'modal-submit',
-            'reaction',
-            'select-menu',
-            'slash'
-        ])).addArgument(new Argument('<name>', 'Name of the controller')).action(async (type, name)=>{
+        generatorCommand.command('controller').alias('co').description('Generate a controller component').addArgument(// Derived from the enum rather than listed by hand, so a new controller kind
+        // cannot be added to the framework and stay unreachable from the CLI.
+        new Argument('<type>', 'Type of the controller (e.g., button, context-menu, etc.)').choices(Object.values(ControllerType))).addArgument(new Argument('<name>', 'Name of the controller')).action(async (type, name)=>{
             await this.handleGenerateComponent({
                 component: 'controller',
                 type: type,

package/dist/esm/bin/helper/controller-generator.helper.js

@@ -14,7 +14,7 @@ class ControllerGeneratorHelper {
    */ generateController(args, type) {
         const { parts, kebabCaseName, className } = validateAndFormatName(args.controllerName);
         const controllerDir = path.join(process.cwd(), 'src', 'controllers', type, ...parts);
-        const template = this.buildControllerTemplate(className, type);
+        const template = this.buildControllerTemplate(className, type, parts);
         this.generateControllerStructure(controllerDir, kebabCaseName, className, type, template);
     }
     /**
@@ -23,8 +23,8 @@ class ControllerGeneratorHelper {
    * @param type - The type of the controller, defined in the `ControllerType` enum.
    * @returns The populated template string for the controller.
    * @throws Will throw an error if the controller type is unsupported.
-   */ buildControllerTemplate(className, type) {
-        const templateConfig = this.getTemplateConfig(type, className);
+   */ buildControllerTemplate(className, type, parts = []) {
+        const templateConfig = this.getTemplateConfig(type, className, parts);
         if (!templateConfig) {
             throw new Error(`Unsupported controller type: ${type}`);
         }
@@ -35,22 +35,38 @@ class ControllerGeneratorHelper {
    * @param type - The type of the controller, defined in the `ControllerType` enum.
    * @param className - The name of the controller class.
    * @returns An object containing the template path and variables, or `undefined` if not found.
-   */ getTemplateConfig(type, className) {
+   */ getTemplateConfig(type, className, parts = []) {
         const baseDir = path.resolve(__dirname$1, '..', 'builder-template', 'controller');
         const templates = {
             [ControllerType.BUTTON]: 'button.controller.template',
             [ControllerType.MODAL_SUBMIT]: 'modal-submit.controller.template',
             [ControllerType.SELECT_MENU]: 'select-menu.controller.template',
+            [ControllerType.USER_SELECT_MENU]: 'user-select-menu.controller.template',
+            [ControllerType.ROLE_SELECT_MENU]: 'role-select-menu.controller.template',
+            [ControllerType.MENTIONABLE_SELECT_MENU]: 'mentionable-select-menu.controller.template',
+            [ControllerType.CHANNEL_SELECT_MENU]: 'channel-select-menu.controller.template',
             [ControllerType.REACTION]: 'reaction.controller.template',
             [ControllerType.MESSAGE]: 'message.controller.template',
             [ControllerType.CONTEXT_MENU]: 'context-menu.controller.template',
-            [ControllerType.SLASH]: 'slash.controller.template'
+            [ControllerType.SLASH]: 'slash.controller.template',
+            [ControllerType.AUTOCOMPLETE]: 'autocomplete.controller.template',
+            [ControllerType.PRIMARY_ENTRY_POINT]: 'primary-entry-point.controller.template'
         };
         const template = templates[type] ? path.resolve(baseDir, templates[type]) : undefined;
+        // The builder is written beside the controller, so a nested controller name moves
+        // it too. Hard-coding `@src/controllers/<type>/builders/...` only ever pointed at
+        // the top-level one, which for a nested name does not exist.
+        const builderImportPath = [
+            '@src/controllers',
+            type,
+            ...parts,
+            'builders/sample.builder'
+        ].join('/');
         return template ? {
             template,
             variables: {
-                className
+                className,
+                builderImportPath
             }
         } : undefined;
     }
@@ -99,7 +115,8 @@ class ControllerGeneratorHelper {
         const baseDir = path.resolve(__dirname$1, '..', 'builder-template', 'builder');
         const templates = {
             [ControllerType.CONTEXT_MENU]: 'context-menu.builder.template',
-            [ControllerType.SLASH]: 'slash.builder.template'
+            [ControllerType.SLASH]: 'slash.builder.template',
+            [ControllerType.PRIMARY_ENTRY_POINT]: 'primary-entry-point.builder.template'
         };
         const template = templates[type] ? path.resolve(baseDir, templates[type]) : undefined;
         return template ? {

package/dist/esm/core/meocord.app.js

@@ -1,22 +1,66 @@
 import { SlashCommandBuilder, MessageFlagsBitField } from 'discord.js';
 import { Logger } from '../common/logger.js';
 import '../common/theme.js';
-import { getCommandMap, findAmbiguousRoutes, PARAM_SEPARATOR, getMessageHandlers, getReactionHandlers } from '../decorator/controller.decorator.js';
+import { getCommandMap, findAmbiguousRoutes, PARAM_SEPARATOR, getAutocompleteHandlers, getMessageHandlers, getReactionHandlers } from '../decorator/controller.decorator.js';
 import { sample } from 'lodash-es';
 import { createErrorEmbed } from '../util/embed.util.js';
+import { describeInteraction, hasCustomId, matchesCommandType, resolveCommandPaths, focusedOptionName, resolveOptionParams } from '../util/interaction.util.js';
 import { ReactionHandlerAction, CommandType } from '../enum/controller.enum.js';
 import CliTable3 from 'cli-table3';
 
-/** Identifies an unmatched interaction for the log, by whichever field would have routed it. */ function describeUnmatched(interaction) {
-    if (interaction.isChatInputCommand() || interaction.isContextMenuCommand()) {
-        return `command "${interaction.commandName}"`;
+/**
+ * The name a builder registers under, which is what Discord deduplicates on.
+ *
+ * Read from the built payload rather than from the `@Command` argument: a builder is
+ * free to name the command something other than the string it was handed, and it is
+ * the payload Discord sees.
+ */ function commandNameOf(builder) {
+    try {
+        const json = typeof builder.toJSON === 'function' ? builder.toJSON() : builder;
+        return typeof json?.name === 'string' ? json.name : undefined;
+    } catch  {
+        // A builder missing a required field throws from toJSON. Surfacing that is the
+        // registration call's job, where it is reported against the command Discord
+        // rejected -- deduplication should not be what turns it into a startup crash.
+        return undefined;
     }
-    if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
-        return `customId "${interaction.customId}"`;
-    }
-    return `interaction type ${interaction.type}`;
 }
 class MeoCordApp {
+    /**
+   * Runs an event handler so a failure inside it cannot take the process down.
+   *
+   * discord.js calls listeners without awaiting them, so a rejection escaping one has
+   * nothing left to settle it: Node reports an unhandled rejection, which terminates
+   * the process by default. Losing the whole bot because one reaction landed on a
+   * deleted message, or one controller could not be resolved, is a worse failure than
+   * the one that caused it -- every other user is served by the same process.
+   *
+   * Nothing is silenced. The error is logged against the event that produced it, so a
+   * genuine misconfiguration -- an unbound controller, a missing dependency -- shows
+   * up on the very first interaction rather than staying hidden.
+   *
+   * @param event - The gateway event being handled, named in the log.
+   * @param run - The handler to run.
+   */ async runListener(event, run) {
+        try {
+            await run();
+        } catch (error) {
+            this.logger.error(`Unhandled error while handling "${event}":`, error);
+        }
+    }
+    /**
+   * Rotates the bot's activity.
+   *
+   * Guarded separately from {@link runListener}: this runs on a timer rather than an
+   * event, and a throw from a timer callback is an uncaught exception no listener
+   * wrapper can reach.
+   */ updateActivity() {
+        try {
+            this.bot.user?.setActivity(sample(this.activities));
+        } catch (error) {
+            this.logger.error('Could not update the bot activity:', error);
+        }
+    }
     getInstance(controllerClass) {
         if (!this.controllerInstancesCache.has(controllerClass)) {
             this.controllerInstancesCache.set(controllerClass, this.container.get(controllerClass));
@@ -26,30 +70,20 @@ class MeoCordApp {
     async start() {
         try {
             this.logger.log('Starting bot...');
-            this.bot.on('clientReady', async ()=>{
-                this.activityInterval = setInterval(()=>{
-                    this.bot.user?.setActivity(sample(this.activities));
-                }, 10000);
-                await this.registerCommands();
-            });
-            this.bot.on('interactionCreate', async (interaction)=>{
-                await this.handleInteraction(interaction);
-            });
-            this.bot.on('messageCreate', async (message)=>{
-                await this.handleMessage(message);
-            });
-            this.bot.on('messageReactionAdd', async (reaction, user)=>{
-                await this.handleReaction(reaction, {
-                    user,
-                    action: ReactionHandlerAction.ADD
-                });
-            });
-            this.bot.on('messageReactionRemove', async (reaction, user)=>{
-                await this.handleReaction(reaction, {
-                    user,
-                    action: ReactionHandlerAction.REMOVE
-                });
-            });
+            this.bot.on('clientReady', ()=>this.runListener('clientReady', async ()=>{
+                    this.activityInterval = setInterval(()=>this.updateActivity(), 10000);
+                    await this.registerCommands();
+                }));
+            this.bot.on('interactionCreate', (interaction)=>this.runListener('interactionCreate', ()=>this.handleInteraction(interaction)));
+            this.bot.on('messageCreate', (message)=>this.runListener('messageCreate', ()=>this.handleMessage(message)));
+            this.bot.on('messageReactionAdd', (reaction, user)=>this.runListener('messageReactionAdd', ()=>this.handleReaction(reaction, {
+                        user,
+                        action: ReactionHandlerAction.ADD
+                    })));
+            this.bot.on('messageReactionRemove', (reaction, user)=>this.runListener('messageReactionRemove', ()=>this.handleReaction(reaction, {
+                        user,
+                        action: ReactionHandlerAction.REMOVE
+                    })));
             await this.bot.login(this.discordToken);
             this.logger.log('Bot is online!');
         } catch (error) {
@@ -57,7 +91,11 @@ class MeoCordApp {
         }
     }
     async registerCommands() {
-        const builders = [];
+        // Keyed by registered name: a command whose subcommands live in separate methods
+        // declares the same name more than once, and sending its builder twice makes
+        // Discord reject the whole payload. The first builder wins, and a second one that
+        // is not the same object is reported rather than silently dropped.
+        const buildersByName = new Map();
         for (const controllerClass of this.controllerClasses){
             const instance = this.getInstance(controllerClass);
             const commandMap = getCommandMap(instance);
@@ -65,12 +103,20 @@ class MeoCordApp {
                 const commandMetadataArray = commandMap[commandName];
                 if (!Array.isArray(commandMetadataArray)) continue;
                 for (const { builder, type } of commandMetadataArray){
-                    if (type in CommandType && builder) {
-                        builders.push(builder);
+                    if (!(type in CommandType) || !builder) continue;
+                    const registeredName = commandNameOf(builder) ?? commandName;
+                    const existing = buildersByName.get(registeredName);
+                    if (existing === undefined) {
+                        buildersByName.set(registeredName, builder);
+                    } else if (existing !== builder) {
+                        this.logger.warn(`Command "${registeredName}" is built more than once; only the first builder is registered. ` + `Declare the builder on one @Command and give the others the plain CommandType.`);
                     }
                 }
             }
         }
+        const builders = [
+            ...buildersByName.values()
+        ];
         try {
             if (this.bot.application) {
                 await this.bot.application.commands.set(builders);
@@ -89,7 +135,7 @@ class MeoCordApp {
                 });
                 for (const builder of builders){
                     const json = typeof builder.toJSON === 'function' ? builder.toJSON() : builder;
-                    const typeName = json?.type === 1 ? 'SlashCommand' : json?.type === 2 ? 'UserContextMenu' : json?.type === 3 ? 'MessageContextMenu' : builder instanceof SlashCommandBuilder ? 'SlashCommand' : 'Command';
+                    const typeName = json?.type === 1 ? 'SlashCommand' : json?.type === 2 ? 'UserContextMenu' : json?.type === 3 ? 'MessageContextMenu' : json?.type === 4 ? 'PrimaryEntryPoint' : builder instanceof SlashCommandBuilder ? 'SlashCommand' : 'Command';
                     const name = json?.name || builder.name;
                     const subCommands = Array.isArray(json?.options) && json.options.length ? json.options.map((opt)=>opt.name).join(', ') : '';
                     table.push([
@@ -130,16 +176,74 @@ class MeoCordApp {
    * Warns rather than throws: an app whose patterns overlap boots and works today, and
    * refusing to start would turn a latent mis-route into an outage on upgrade.
    */ reportAmbiguousRoutes(routes) {
-        const collisions = findAmbiguousRoutes(routes.map(({ pattern })=>pattern));
+        // Grouped by command type first: dispatch only considers routes whose component
+        // type matches the interaction, so a button and a select menu sharing a pattern
+        // are never in competition and reporting them would be a false alarm.
+        const byType = new Map();
+        for (const { meta, pattern } of routes){
+            const patterns = byType.get(meta.type) ?? [];
+            patterns.push(pattern);
+            byType.set(meta.type, patterns);
+        }
+        const collisions = [
+            ...byType.values()
+        ].flatMap((patterns)=>findAmbiguousRoutes(patterns));
         if (collisions.length === 0) return;
         this.logger.warn(`${collisions.length} pattern pair(s) can match the same customId, so which one runs is decided by ` + `ranking rather than by the ids themselves:\n` + collisions.map(([left, right])=>`  "${left}"  vs  "${right}"`).join('\n') + `\nA parameter stops at "${PARAM_SEPARATOR}", so separating these segments with it makes them distinct.`);
     }
-    async handleInteraction(interaction) {
+    getAutocompleteRoutes() {
+        if (this.autocompleteRoutes) return this.autocompleteRoutes;
+        const routes = [];
+        for (const controllerClass of this.controllerClasses){
+            for (const meta of getAutocompleteHandlers(this.getInstance(controllerClass))){
+                routes.push({
+                    controllerClass,
+                    meta
+                });
+            }
+        }
+        routes.sort((a, b)=>Number(Boolean(b.meta.optionName)) - Number(Boolean(a.meta.optionName)));
+        this.autocompleteRoutes = routes;
+        return routes;
+    }
+    /**
+   * Dispatches an interaction, and makes sure a failure anywhere in that still reaches
+   * the person who triggered it.
+   *
+   * {@link executeCommand} already reports what a handler throws, but everything
+   * *before* the handler can fail too — resolving a controller through the container
+   * is the common case — and a component that fails there would otherwise look dead
+   * with nothing said to the user and nothing in the log.
+   */ async handleInteraction(interaction) {
+        try {
+            await this.dispatchInteraction(interaction);
+        } catch (error) {
+            this.logger.error(`Error dispatching ${describeInteraction(interaction)}:`, error);
+            // Autocomplete has no reply to fall back on; closing its window is the only
+            // thing that stops the client showing a loading state until it times out.
+            if (interaction.isAutocomplete()) {
+                await this.respondEmpty(interaction);
+                return;
+            }
+            await this.replyWithError(interaction, 'An error occurred while executing the command.');
+        }
+    }
+    async dispatchInteraction(interaction) {
+        // Autocomplete first, and on its own path: it is answered with `respond()` rather
+        // than a reply, it has no customId to route on, and the "Command not found!" reply
+        // the other paths end in cannot be sent to it at all.
+        if (interaction.isAutocomplete()) {
+            await this.handleAutocomplete(interaction);
+            return;
+        }
         // Component interactions route on a pattern, so they go through the ranked table.
-        // Slash and context-menu commands match their name exactly and cannot overlap.
-        if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
+        // Commands match their registered name exactly and cannot overlap.
+        if (hasCustomId(interaction)) {
             const customId = interaction.customId;
             for (const { controllerClass, meta } of this.getComponentRoutes()){
+                // A button and a select menu may legitimately share a customId shape, so the
+                // pattern alone does not identify the handler -- the component type does.
+                if (!matchesCommandType(meta.type, interaction)) continue;
                 const match = meta.regex.exec(customId);
                 if (!match) continue;
                 interaction.dynamicParams = match.groups ?? {};
@@ -147,19 +251,15 @@ class MeoCordApp {
                 return;
             }
         }
-        for (const controllerClass of this.controllerClasses){
-            const controllerInstance = this.getInstance(controllerClass);
-            const commandMap = getCommandMap(controllerInstance);
-            if (!commandMap) continue;
-            let commandMetadataArray = undefined;
-            let commandIdentifier = undefined;
-            if (interaction.isChatInputCommand() || interaction.isContextMenuCommand()) {
-                commandIdentifier = interaction.commandName;
-                commandMetadataArray = commandMap[commandIdentifier];
-            }
-            if (commandMetadataArray && commandMetadataArray.length > 0) {
-                const commandMetadata = commandMetadataArray[0];
-                await this.executeCommand(controllerInstance, commandMetadata, interaction, commandIdentifier);
+        // Paths are walked outside the controller loop so the full subcommand path always
+        // beats the bare command name, whatever order the controllers were registered in.
+        for (const path of this.resolveNameRoutes(interaction)){
+            for (const controllerClass of this.controllerClasses){
+                const controllerInstance = this.getInstance(controllerClass);
+                const commandMap = getCommandMap(controllerInstance);
+                const commandMetadata = commandMap?.[path]?.find((meta)=>matchesCommandType(meta.type, interaction));
+                if (!commandMetadata) continue;
+                await this.executeCommand(controllerInstance, commandMetadata, interaction, path);
                 return;
             }
         }
@@ -167,15 +267,58 @@ class MeoCordApp {
         // about which id was unroutable, so a control that is emitted but never routed --
         // a customId whose value broke its pattern, or a handler nobody wrote -- stays
         // invisible until somebody reports the dead button.
-        this.logger.warn(`No handler matched ${describeUnmatched(interaction)}. Check that a @Command pattern is ` + `declared for it and that its controller is registered.`);
-        if (interaction.isRepliable()) {
-            const embed = createErrorEmbed('Command not found!');
-            await interaction.reply({
-                embeds: [
-                    embed
-                ],
-                flags: MessageFlagsBitField.Flags.Ephemeral
-            });
+        this.logger.warn(`No handler matched ${describeInteraction(interaction)}. Check that a @Command pattern is ` + `declared for it and that its controller is registered.`);
+        await this.replyWithError(interaction, 'Command not found!');
+    }
+    /**
+   * The names a command interaction can be handled under, most specific first.
+   *
+   * Empty for anything that is not a registered command, which is how a component
+   * whose customId matched no pattern falls through to the unmatched warning instead
+   * of being looked up under a name it does not have.
+   */ resolveNameRoutes(interaction) {
+        if (interaction.isChatInputCommand()) return resolveCommandPaths(interaction);
+        if (interaction.isContextMenuCommand() || interaction.isPrimaryEntryPointCommand()) {
+            return [
+                interaction.commandName
+            ];
+        }
+        return [];
+    }
+    /**
+   * Answers an autocomplete interaction from the `@Autocomplete` handler that claims it.
+   *
+   * Discord closes the window after three seconds and shows a loading state until
+   * something arrives, so an unclaimed option is answered with an empty list rather
+   * than left to time out -- a visibly empty menu is a better failure than a stuck one,
+   * and the warning says which option is missing a handler.
+   */ async handleAutocomplete(interaction) {
+        const focusedName = focusedOptionName(interaction);
+        for (const path of resolveCommandPaths(interaction)){
+            for (const { controllerClass, meta } of this.getAutocompleteRoutes()){
+                if (meta.commandPath !== path) continue;
+                if (meta.optionName !== undefined && meta.optionName !== focusedName) continue;
+                try {
+                    const controllerInstance = this.getInstance(controllerClass);
+                    this.logger.log('[AUTOCOMPLETE]', `[${path}]`, `[${meta.methodName}]`);
+                    await controllerInstance[meta.methodName](interaction, resolveOptionParams(interaction));
+                } catch (error) {
+                    this.logger.error(`Error handling ${describeInteraction(interaction)}:`, error);
+                    await this.respondEmpty(interaction);
+                }
+                return;
+            }
+        }
+        this.logger.warn(`No handler matched ${describeInteraction(interaction)}. Declare an @Autocomplete handler for it, ` + `or drop setAutocomplete(true) from the option.`);
+        await this.respondEmpty(interaction);
+    }
+    /** Closes an autocomplete window that nothing else answered. */ async respondEmpty(interaction) {
+        if (interaction.responded) return;
+        try {
+            await interaction.respond([]);
+        } catch (error) {
+            // The three-second window may already have closed, which is not actionable.
+            this.logger.debug(`Could not close autocomplete window: ${String(error)}`);
         }
     }
     /**
@@ -183,33 +326,43 @@ class MeoCordApp {
    * component and a named slash command behave identically once the route is chosen.
    */ async executeCommand(controllerInstance, commandMetadata, interaction, commandIdentifier) {
         const { methodName, type } = commandMetadata;
+        // No interaction-type check here: both callers pick the route with
+        // `matchesCommandType` before getting this far, and `@Command` re-checks the
+        // interaction on the way into the handler.
         try {
-            if (type === CommandType.SLASH && interaction.isChatInputCommand() || type === CommandType.BUTTON && interaction.isButton() || type === CommandType.SELECT_MENU && interaction.isStringSelectMenu() || type === CommandType.CONTEXT_MENU && interaction.isUserContextMenuCommand() || type === CommandType.CONTEXT_MENU && interaction.isMessageContextMenuCommand() || type === CommandType.MODAL_SUBMIT && interaction.isModalSubmit()) {
-                this.logger.log('[INTERACTION]', `[${CommandType[type]}]`, `[${methodName}]`);
-                let dynamicParams = {};
-                if (interaction.isChatInputCommand() && interaction.options) {
-                    dynamicParams = interaction.options.data.reduce((acc, opt)=>{
-                        acc[opt.name] = opt.value;
-                        return acc;
-                    }, {});
-                } else if (interaction.isButton() || interaction.isStringSelectMenu() || interaction.isModalSubmit()) {
-                    dynamicParams = interaction.dynamicParams ?? {};
-                }
-                await controllerInstance[methodName](interaction, dynamicParams);
-                return;
+            this.logger.log('[INTERACTION]', `[${type}]`, `[${methodName}]`);
+            let dynamicParams = {};
+            if (interaction.isChatInputCommand()) {
+                dynamicParams = resolveOptionParams(interaction);
+            } else if (hasCustomId(interaction)) {
+                dynamicParams = interaction.dynamicParams ?? {};
             }
-            this.logger.warn(`Interaction type mismatch for command "${commandIdentifier}". Interaction type: ${interaction.type}.`);
+            await controllerInstance[methodName](interaction, dynamicParams);
         } catch (error) {
             this.logger.error(`Error executing command "${commandIdentifier}":`, error);
-            if (interaction.isRepliable()) {
-                const embed = createErrorEmbed('An error occurred while executing the command.');
-                await interaction.reply({
-                    embeds: [
-                        embed
-                    ],
-                    flags: MessageFlagsBitField.Flags.Ephemeral
-                });
-            }
+            await this.replyWithError(interaction, 'An error occurred while executing the command.');
+        }
+    }
+    /**
+   * Tells the user something went wrong, if the interaction can still hear it.
+   *
+   * A handler that replies and *then* throws is the common shape of a failure, and
+   * replying twice throws in turn -- out of the catch block, where nothing is left to
+   * handle it. Whatever the interaction's state, reporting an error must not be able
+   * to become a second, worse one.
+   */ async replyWithError(interaction, message) {
+        if (!interaction.isRepliable() || interaction.replied || interaction.deferred) return;
+        try {
+            const embed = createErrorEmbed(message);
+            await interaction.reply({
+                embeds: [
+                    embed
+                ],
+                flags: MessageFlagsBitField.Flags.Ephemeral
+            });
+        } catch (error) {
+            // Unknown or already-acknowledged interaction; the user cannot be told anything.
+            this.logger.debug(`Could not deliver the error reply: ${String(error)}`);
         }
     }
     async handleMessage(message) {
@@ -241,7 +394,15 @@ class MeoCordApp {
         }
     }
     async handleReaction(reaction, { user, action }) {
-        await reaction.message.fetch();
+        // A reaction arrives for messages the bot may no longer be able to read -- deleted,
+        // or in a channel it lost access to -- and `fetch` rejects for all of them. That is
+        // an ordinary outcome rather than a fault, so the reaction is skipped quietly.
+        try {
+            await reaction.message.fetch();
+        } catch (error) {
+            this.logger.debug(`Skipping a reaction whose message could not be fetched: ${String(error)}`);
+            return;
+        }
         const relevantControllers = this.controllerClasses.filter((controllerClass)=>{
             const instance = this.getInstance(controllerClass);
             const reactionHandlers = getReactionHandlers(instance);