meocord 4.1.2 → 4.2.1

package/dist/cjs/_shared/{providers-BMMLp2SN.cjs → providers-BZgJyfZS.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var controller_decorator = require('./controller.decorator-BywwkU9O.cjs');
+var controller_decorator = require('./controller.decorator-XKMlcUZz.cjs');
 require('reflect-metadata');
 var node_async_hooks = require('node:async_hooks');
 var inversify = require('inversify');
@@ -101,7 +101,7 @@ var Table__default = /*#__PURE__*/_interopDefaultCompat(Table);
 
 function eventDecorator(event, once) {
     // Generic over the method, so it is checked against the event's arguments rather than required to match exactly
-    return function(target, propertyKey, _descriptor) {
+    return controller_decorator.declaring(function(target, propertyKey, _descriptor) {
         controller_decorator.refuseOnClass(once ? '@Once' : '@On', target, propertyKey);
         const handlers = controller_decorator.ownHandlerList(controller_decorator.META.eventHandlers, target);
         handlers.push({
@@ -110,7 +110,7 @@ function eventDecorator(event, once) {
             once
         });
         Reflect.defineMetadata(controller_decorator.META.eventHandlers, handlers, target);
-    };
+    });
 }
 /**
  * Handles a discord.js client event every time it is emitted, on a controller or a service.
@@ -138,7 +138,7 @@ function eventDecorator(event, once) {
  * @group Decorators
  * @category Handlers
  * @see {@link Once}
- * @see {@link https://meocord.dev/docs/4.1/gateway-events | Gateway events}
+ * @see {@link https://meocord.dev/docs/4.2/gateway-events | Gateway events}
  */ function On(event) {
     return eventDecorator(event, false);
 }
@@ -165,7 +165,7 @@ function eventDecorator(event, once) {
  * @group Decorators
  * @category Handlers
  * @see {@link On}
- * @see {@link https://meocord.dev/docs/4.1/gateway-events | Gateway events}
+ * @see {@link https://meocord.dev/docs/4.2/gateway-events | Gateway events}
  */ function Once(event) {
     return eventDecorator(event, true);
 }
@@ -505,14 +505,27 @@ const wrapperCount = perHandler((prototype, methodName)=>{
     else marks.delete(methodName);
     return true;
 }
+/** The container that made each instance, so a direct call runs in its own app or testing module. */ const instanceContainers = new WeakMap();
+/**
+ * Records each instance `container` makes of `classes` as its own. Two testing modules made from one class each run a
+ * direct call on their own instance in themselves, where the class's metadata names only the last.
+ */ function recordInstanceContainers(container, classes) {
+    for (const cls of classes){
+        container.onActivation(cls, (_context, instance)=>{
+            if (typeof instance === 'object' && instance !== null) instanceContainers.set(instance, container);
+            return instance;
+        });
+    }
+}
 /**
  * Runs a direct call to a guarded handler: the handler's guards, as dispatch resolves them, then the
  * call with a pass for each wrapper inside the one entered, so no guard runs twice.
  */ async function runDirectCall(instance, methodName, args, call) {
     const prototype = Object.getPrototypeOf(instance);
     const controller = instance.constructor;
-    // The app that made the class, or a class it extends: a subclass the app's code makes runs as its base does
-    const container = Reflect.getMetadata(controller_decorator.META.container, controller);
+    // The container that made the instance, or else the app that made the class or a class it extends: a subclass the
+    // app's code makes runs as its base does
+    const container = instanceContainers.get(instance) ?? Reflect.getMetadata(controller_decorator.META.container, controller);
     if (!container) {
         throw new Error(`${controller.name}.${methodName}: @UseGuard runs its guards through the app that made ${controller.name}, and this ` + `instance was made outside one. Inject ${controller.name}, or call it on an instance the app made.`);
     }
@@ -767,19 +780,37 @@ const logger$3 = new controller_decorator.Logger('Cooldown');
         const value = by ? await by(context, params) : undefined;
         // Encoded, so a value holding a colon cannot count under another value's key. Without a value, `:by` alone keeps
         // the call apart from a cooldown with no `by` over the same window.
-        const suffix = !by ? '' : value === undefined ? ':by' : `:by:${encodeURIComponent(String(value))}`;
+        const suffix = !by ? '' : value === undefined ? ':by' : `:by:${encodeKeyPart(String(value))}`;
+        const scope = scopeId(per, first);
+        // The caller, for a notice of a refusal under a scope that counts more than one caller
+        const user = scope.startsWith('user:') ? undefined : caller(first).user;
         counted.push({
-            key: `${controller.name}.${methodName}#${id}:${per}:${scopeId(per, first)}${suffix}`,
+            key: `${controller.name}.${methodName}#${id}:${per}:${scope}${suffix}`,
             windowMs,
             uses,
-            per
+            per,
+            user
         });
     }
     return counted;
 }
+// A surrogate with no partner beside it, which encodeURIComponent refuses
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+/**
+ * A value as part of a store key: each well-formed run as `encodeURIComponent` writes it, and each lone surrogate as `%u`
+ * and its four hex digits, which no other value encodes to, since `encodeURIComponent` writes `%` only before two.
+ */ function encodeKeyPart(value) {
+    let encoded = '';
+    let from = 0;
+    for (const { 0: surrogate, index } of value.matchAll(LONE_SURROGATE)){
+        encoded += `${encodeURIComponent(value.slice(from, index))}%u${surrogate.charCodeAt(0).toString(16).toUpperCase()}`;
+        from = index + 1;
+    }
+    return encoded + encodeURIComponent(value.slice(from));
+}
 /**
- * The store key and window of the cooldown each refusal came from, and when its wait ends by the store's clock if
- * the store said, for {@link claimCooldownNotice}.
+ * The store key and window of the cooldown each refusal came from, when its wait ends by the store's clock if the
+ * store said, and the refused caller when the key counts more than one, for {@link claimCooldownNotice}.
  */ const refusalKeys = new WeakMap();
 /** Asks the store about the call under the app's policy, and throws what the answer means for it. */ async function ask(container, counted, peek, call) {
     const store = cooldownStoreOf(container);
@@ -812,7 +843,8 @@ const logger$3 = new controller_decorator.Logger('Cooldown');
     refusalKeys.set(refusal, {
         key: blocking.key,
         windowMs: blocking.windowMs,
-        endsAt: verdict.retryTimestamp
+        endsAt: verdict.retryTimestamp,
+        user: blocking.user
     });
     throw refusal;
 }
@@ -835,16 +867,18 @@ const logger$3 = new controller_decorator.Logger('Cooldown');
     // retry landing a moment late is refused on the earlier, which its wait holds, before taking the later, which a wait
     // ending then needs for its own notice.
     const bucket = Math.floor(refusal.retryAt.getTime() / NOTICE_BUCKET_MS);
+    // A key counting a server, a channel or everyone is shared by every caller it refuses, each told once
+    const key = refused.user === undefined ? refused.key : `${refused.key}:user:${refused.user}`;
     const notices = refused.endsAt !== undefined ? [
         {
-            key: `${refused.key}:notice:at:${refused.endsAt}`,
+            key: `${key}:notice:at:${refused.endsAt}`,
             limit
         }
     ] : [
         bucket - 1,
         bucket
     ].map((at)=>({
-            key: `${refused.key}:notice:${at}`,
+            key: `${key}:notice:${at}`,
             limit
         }));
     try {
@@ -1066,19 +1100,35 @@ const scopeKey = (scope)=>scope === 'global' ? 'global' : `guild-${scope.guild}`
     const guilds = options.config?.guilds ?? [];
     return !everythingTarget(options) && guilds.length > 0 && ids(guilds).length === 0;
 }
+/** Whether a command is an activity's primary entry point, which Discord takes only globally. */ const isEntryPoint = (command)=>command.body.type === discord_js.ApplicationCommandType.PrimaryEntryPoint;
+/** What a blank guild to register every command to says, as an unset variable gives one. */ const BLANK_GUILD = 'No commands were registered: the guild to register to is blank. Give a guild id, or leave it out to register where commands.* says.';
 /**
  * Where each command is sent: one bulk update per scope. A scope's update replaces everything the application has
  * there, so the default scope is included even when it ends up empty, unless `commands.guilds` lists no guild id.
+ *
+ * A primary entry point command goes in the global update, as Discord refuses a guild update that holds one. A run
+ * that sends everything to one guild sends nothing global, so it leaves the entry point out.
  */ function planTargets(commands, options, logger) {
+    // Registering to the default scopes instead could publish everywhere
+    if (options.onlyGuild !== undefined && !options.onlyGuild.trim()) {
+        logger.error(BLANK_GUILD);
+        return [];
+    }
     const everythingTo = everythingTarget(options);
-    if (everythingTo) return [
-        {
-            scope: {
-                guild: everythingTo
-            },
-            commands
+    if (everythingTo) {
+        // A global update from here would hold only what this run sends, deleting the application's other global commands
+        for (const command of commands.filter(isEntryPoint)){
+            logger.warn(`Entry point command "${command.name}" is registered globally only; a production run or \`meocord register\` registers it.`);
         }
-    ];
+        return [
+            {
+                scope: {
+                    guild: everythingTo
+                },
+                commands: commands.filter((command)=>!isEntryPoint(command))
+            }
+        ];
+    }
     const defaultGuilds = ids(options.config?.guilds);
     const nowhere = defaultGuildsEmpty(options);
     const targets = new Map();
@@ -1096,7 +1146,12 @@ const scopeKey = (scope)=>scope === 'global' ? 'global' : `guild-${scope.guild}`
     });
     const unregistered = [];
     for (const command of commands){
-        if (command.guilds) {
+        if (isEntryPoint(command)) {
+            if (command.guilds) {
+                logger.warn(`Entry point command "${command.name}" can only be registered globally, so the guilds its builder lists are ignored.`);
+            }
+            add('global', command);
+        } else if (command.guilds) {
             const own = ids(command.guilds);
             // Falling back to the default scope could publish a staff-only command everywhere.
             if (own.length === 0) logger.warn(`Command "${command.name}" lists no guild ids in its builder, so it is not registered.`);
@@ -1114,7 +1169,7 @@ const scopeKey = (scope)=>scope === 'global' ? 'global' : `guild-${scope.guild}`
         }
     }
     if (nowhere) {
-        const outcome = unregistered.length === 0 ? 'nothing is registered globally' : `${unregistered.join(', ')} ${unregistered.length === 1 ? 'is' : 'are'} not registered, rather than registered globally`;
+        const outcome = unregistered.length === 0 ? targets.has('global') ? 'only the entry point command is registered globally' : 'nothing is registered globally' : `${unregistered.join(', ')} ${unregistered.length === 1 ? 'is' : 'are'} not registered, rather than registered globally`;
         logger.warn(`commands.guilds lists no guild id, as an unset environment variable leaves it, so ${outcome}. ` + `Set the guild ids, or remove commands.guilds to register globally.`);
     }
     return [
@@ -1143,28 +1198,57 @@ const describeScope = (scope)=>scope === 'global' ? 'globally' : `to guild ${sco
     return path__default.default.join(nodeModules, '.cache', 'meocord', `commands-${applicationId}-${scopeKey(scope)}.json`);
 }
 const hashOf = (commands)=>crypto.createHash('sha256').update(JSON.stringify(commands.map(({ body })=>body))).digest('hex');
-function readHash(file, logger) {
+function readRecord(file, logger) {
     if (!file || !fs.existsSync(file)) return undefined;
     try {
-        return JSON.parse(fs.readFileSync(file, 'utf8')).hash;
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
     } catch (error) {
         logger.debug(`Could not read the registered commands, so they are sent again: ${String(error)}`);
         return undefined;
     }
 }
-function writeHash(file, hash, logger) {
+function writeRecord(file, record, logger) {
     if (!file) return;
     try {
         fs.mkdirSync(path__default.default.dirname(file), {
             recursive: true
         });
-        fs.writeFileSync(file, `${JSON.stringify({
-            hash
-        })}\n`);
+        fs.writeFileSync(file, `${JSON.stringify(record)}\n`);
     } catch (error) {
         logger.debug(`Could not record the registered commands: ${String(error)}`);
     }
 }
+/** Forgets what development last sent to a scope, once that scope is written some other way. */ function forgetRecord(file, logger) {
+    if (!file || !fs.existsSync(file)) return;
+    try {
+        fs.rmSync(file);
+    } catch (error) {
+        logger.debug(`Could not forget the registered commands: ${String(error)}`);
+    }
+}
+/**
+ * Each command's `id:version`, sorted, from what Discord lists or answers a bulk update with; `undefined` for anything
+ * else. Discord gives a command a new version whenever it is updated, so the set changes with any edit, removal or
+ * re-registration, from this checkout or any other.
+ */ function versionsOf(commands) {
+    if (!Array.isArray(commands)) return undefined;
+    const versions = commands.map((command)=>{
+        const { id, version } = command ?? {};
+        return typeof id === 'string' && typeof version === 'string' ? `${id}:${version}` : undefined;
+    });
+    return versions.every((version)=>version !== undefined) ? versions.sort() : undefined;
+}
+/** Whether Discord still holds a scope as development last sent it, by each command's version; a failed listing doesn't. */ async function stillAsSent(rest, route, record, scope, logger) {
+    if (!record.versions) return false;
+    let registered;
+    try {
+        registered = await rest.get(route);
+    } catch (error) {
+        logger.debug(`Could not list the commands registered ${describeScope(scope)}, so they are sent again: ${String(error)}`);
+        return false;
+    }
+    return versionsOf(registered)?.join('\n') === record.versions.join('\n');
+}
 function logRegistered(target, logger) {
     const table = new Table__default.default({
         head: [
@@ -1187,22 +1271,29 @@ function logRegistered(target, logger) {
     };
     for (const { name, body } of target.commands){
         const options = Array.isArray(body.options) ? body.options : [];
+        // A subcommand or a subcommand group, not a plain option
+        const subcommands = options.filter((option)=>option.type === 1 || option.type === 2);
         table.push([
             name,
             typeNames[typeof body.type === 'number' ? body.type : 1] ?? 'Command',
-            options.map((option)=>option.name).join(', ')
+            subcommands.map((option)=>option.name).join(', ')
         ]);
     }
     logger.log(`Registered ${target.commands.length} bot commands ${describeScope(target.scope)}:\n${table.toString()}`);
 }
 /**
- * Registers the commands, one bulk update per scope; development skips a scope unchanged since its last send, unless
- * `force`. Once one is sent, and not to `onlyGuild`, the other scopes the configuration names are checked for
+ * Registers the commands, one bulk update per scope; development skips a scope unchanged since its last send and still
+ * registered as sent, which one listing per skipped scope checks by each command's version, unless `force`. A blank `onlyGuild` registers nothing. Once one is sent, and not to `onlyGuild`, the other scopes the configuration names are checked for
  * leftovers, which `clearOther` removes; a development-guild run or a `commands.guilds` with no id only warns. Never
  * throws.
  * @returns Whether every scope was sent or unchanged, and `commands.guilds`, if set, lists a guild id.
  */ async function registerCommands(options) {
     const { rest, applicationId, controllerClasses, logger, config, development, onlyGuild, force = false } = options;
+    // An unset variable passed as the guild; registering to the default scopes instead could publish everywhere
+    if (onlyGuild !== undefined && !onlyGuild.trim()) {
+        logger.error(BLANK_GUILD);
+        return false;
+    }
     const commands = collectCommands(controllerClasses, logger);
     if (!commands) return false;
     const targets = planTargets(commands, {
@@ -1219,18 +1310,26 @@ function logRegistered(target, logger) {
     let succeeded = !guildsEmpty;
     let sent = false;
     for (const target of targets){
-        const file = development ? cacheFile(applicationId, target.scope) : undefined;
+        const file = cacheFile(applicationId, target.scope);
         const hash = hashOf(target.commands);
-        if (development && !force && readHash(file, logger) === hash) {
+        const route = routeFor(applicationId, target.scope);
+        // Unchanged since development last sent it, and still what Discord holds there
+        const record = development && !force ? readRecord(file, logger) : undefined;
+        if (record?.hash === hash && await stillAsSent(rest, route, record, target.scope, logger)) {
             logger.log(`Commands ${describeScope(target.scope)} are unchanged; not registering them again.`);
             continue;
         }
         try {
-            await rest.put(routeFor(applicationId, target.scope), {
+            const answered = await rest.put(route, {
                 body: target.commands.map(({ body })=>body)
             });
             sent = true;
-            if (development) writeHash(file, hash, logger);
+            // Outside development the record would be stale, so the next development start sends again
+            if (development) writeRecord(file, {
+                hash,
+                versions: versionsOf(answered)
+            }, logger);
+            else forgetRecord(file, logger);
             logRegistered(target, logger);
         } catch (error) {
             succeeded = false;
@@ -1259,13 +1358,17 @@ function logRegistered(target, logger) {
         if (!Array.isArray(existing) || existing.length === 0) continue;
         const names = existing.map(({ name })=>name).join(', ');
         if (!config?.clearOther || keptBecause) {
-            logger.warn(`${existing.length} command(s) are still registered ${describeScope(scope)} (${names}), which this ` + `configuration does not register to, so Discord keeps showing them there. ` + (config?.clearOther ? `clearOther is on, but they are not removed ${keptBecause}.` : 'Set commands.clearOther to remove them.'));
+            // Advising clearOther when it would not apply sends the reader to a setting that changes nothing
+            const advice = !keptBecause ? 'Set commands.clearOther to remove them.' : config?.clearOther ? `clearOther is on, but they are not removed ${keptBecause}.` : `They are not removed ${keptBecause}, even with commands.clearOther.`;
+            logger.warn(`${existing.length} command(s) are still registered ${describeScope(scope)} (${names}), which this ` + `configuration does not register to, so Discord keeps showing them there. ${advice}`);
             continue;
         }
         try {
             await rest.put(routeFor(applicationId, scope), {
                 body: []
             });
+            // What development last sent there is gone, so its next start sends again
+            forgetRecord(cacheFile(applicationId, scope), logger);
             logger.log(`Removed ${existing.length} command(s) left registered ${describeScope(scope)}: ${names}`);
         } catch (error) {
             logger.error(`Error removing the commands left registered ${describeScope(scope)}:`, error);
@@ -1376,7 +1479,7 @@ function isInterceptorWithParams(entry) {
 });
 /** Binds `cls` and its unbound dependencies as singletons, refusing any that injects `ExecutionContext`. */ function bindShared(container, cls) {
     if (container.isBound(cls)) return;
-    if (injectedTokens(cls).includes(controller_decorator.ExecutionContext)) throw controller_decorator.refuse(singletonContextError(cls));
+    if (injectedTokens(cls).includes(controller_decorator.ExecutionContext)) return controller_decorator.startupError(singletonContextError(cls));
     assertStartupChecked(container, cls);
     makeInjectable(cls);
     container.bind(cls).toSelf().inSingletonScope();
@@ -1571,7 +1674,7 @@ function isInterceptorWithParams(entry) {
 /** Binds a filter as a singleton, after checking it is one. */ function prepareFilter(container, entry) {
     const cls = filterClass(entry);
     if (!Reflect.hasOwnMetadata(controller_decorator.META.catchTypes, cls)) {
-        throw controller_decorator.refuse(new Error(`${cls.name || 'A filter'}: used as an exception filter, but not decorated with @Catch().`));
+        return controller_decorator.startupError(new Error(`${cls.name || 'A filter'}: used as an exception filter, but not decorated with @Catch().`));
     }
     bindShared(container, cls);
 }
@@ -1683,11 +1786,12 @@ const asList = (entries)=>Array.isArray(entries) ? entries : [
 
 /** Where a container keeps the observers its calls are reported to, in order. */ const OBSERVERS = Symbol('observers');
 const logger$1 = new controller_decorator.Logger('Observer');
-/** Throws unless every entry is an `@Observer` class, naming where it was listed. */ function assertObservers(where, observers) {
+/** Reports each entry that is not an `@Observer` class, naming where it was listed. */ function assertObservers(where, observers) {
     for (const observer of observers){
         if (typeof observer !== 'function' || !Reflect.getMetadata(controller_decorator.META.observerClass, observer)) {
             const name = typeof observer === 'function' ? observer.name : String(observer);
-            throw controller_decorator.refuse(new Error(`${where} takes classes decorated with @Observer(), not ${name}.`));
+            controller_decorator.startupError(new Error(`${where} takes classes decorated with @Observer(), not ${name}.`));
+            continue;
         }
     }
 }
@@ -1942,12 +2046,16 @@ const NO_GLOBAL_STAGES = {
  */ function bindAppPresenter(container, app, client) {
     const options = Reflect.getMetadata(controller_decorator.META.appOptions, app);
     if (!options?.presenter) return undefined;
-    bindShared(container, options.presenter);
+    prepareAppPresenter(container, app);
     const presenter = container.get(options.presenter);
     container.bind(APP_PRESENTER).toConstantValue(presenter);
     if (client) controller_decorator.setPresenter(client, presenter);
     return presenter;
 }
+/** Binds the app's presenter class as a shared stage, checking it as one, without making it. */ function prepareAppPresenter(container, app) {
+    const options = Reflect.getMetadata(controller_decorator.META.appOptions, app);
+    if (options?.presenter) bindShared(container, options.presenter);
+}
 /** Where a container keeps the application's presenter. */ const APP_PRESENTER = Symbol('app_presenter');
 /** The presenter `bindAppPresenter` resolved into `container`, if any. */ function appPresenterOf(container) {
     return container.isBound(APP_PRESENTER) ? container.get(APP_PRESENTER) : undefined;
@@ -2037,18 +2145,21 @@ const stagesByGlobals = new WeakMap();
 /**
  * Binds the interceptors, filters and pipes every handler of `controllers` uses, and the global ones, as singletons, so
  * one that cannot be shared, or a filter without `@Catch`, fails at startup; refuses there `@Defer`, `@Validate`,
- * `@UsePipe` and `@Cooldown` where they cannot apply, and two classes that keep state under one name.
+ * `@UsePipe` and `@Cooldown` where they cannot apply, and two classes that keep state under one name. Binds only; it
+ * makes nothing, so it runs with the other startup checks.
  */ function prepareHandlerStages(container, controllers) {
     assertDistinctNamesWhereKeyed(controllers);
     const globals = globalStagesOf(container);
-    configureThemes(container, globals.theme, controllers, globals.themeFor);
     for (const entry of globals.interceptors)prepareInterceptor(container, entry);
     for (const entry of globals.filters)prepareFilter(container, entry);
     for (const controller of controllers){
         const prototype = controller.prototype;
         for (const method of handlerMethods(prototype)){
             const kind = handlerDefer(prototype, method) ? nonInteractionHandler(prototype, method) : undefined;
-            if (kind) throw controller_decorator.refuse(deferMisuseError(controller.name, method, kind));
+            if (kind) {
+                controller_decorator.startupError(deferMisuseError(controller.name, method, kind));
+                continue;
+            }
             for (const entry of handlerInterceptors(prototype, method))prepareInterceptor(container, entry);
             for (const entry of handlerFilterLevels(prototype, method, []).flat())prepareFilter(container, entry);
             for (const { entry } of handlerInputStages(prototype, method).pipes)preparePipe(container, entry);
@@ -2056,6 +2167,10 @@ const stagesByGlobals = new WeakMap();
         assertInputStagesOnInteractions(controller, prototype);
     }
 }
+/** Records the app's theme for the handlers of `controllers`, once the startup checks have passed: it makes the theme cache. */ function prepareThemes(container, controllers) {
+    const globals = globalStagesOf(container);
+    configureThemes(container, globals.theme, controllers, globals.themeFor);
+}
 /** Whether a class has state keyed by its name: a cooldown on a handler, or a `@Once` handler. */ function keyedByName(cls) {
     const prototype = cls.prototype;
     const handlers = [
@@ -2072,7 +2187,8 @@ const stagesByGlobals = new WeakMap();
     for (const cls of classes){
         const other = byName.get(cls.name);
         if (other && other !== cls && (keyedByName(cls) || keyedByName(other))) {
-            throw controller_decorator.refuse(new Error(`${cls.name}: two classes have this name; @Cooldown and @Once tell classes apart by name, so they would share ` + `their counts. Rename one of them.`));
+            controller_decorator.startupError(new Error(`${cls.name}: two classes have this name; @Cooldown and @Once tell classes apart by name, so they would share ` + `their counts. Rename one of them.`));
+            continue;
         }
         byName.set(cls.name, cls);
     }
@@ -2100,11 +2216,12 @@ const stagesByGlobals = new WeakMap();
         const { schema, pipes } = handlerInputStages(prototype, method);
         const handler = kind === 'message' ? 'a message handler without a pattern' : `${kind === 'autocomplete' || kind === 'event' ? 'an' : 'a'} ${kind} handler`;
         if (schema || pipes.length > 0) {
-            throw controller_decorator.refuse(new Error(`${controller.name}.${method}: @Validate and @UsePipe are for interaction and patterned message handlers, ` + `whose options, customId params, modal fields and pattern params they check, and this is ${handler}.`));
+            controller_decorator.startupError(new Error(`${controller.name}.${method}: @Validate and @UsePipe are for interaction and patterned message handlers, ` + `whose options, customId params, modal fields and pattern params they check, and this is ${handler}.`));
+            continue;
         }
         // A controller's own @Cooldown skips these handlers; one on the method itself is a mistake.
         if (kind !== 'message' && methodCooldowns(prototype, method).length > 0) {
-            throw controller_decorator.refuse(new Error(`${controller.name}.${method}: @Cooldown is for interaction and message handlers, and this is ${handler}.`));
+            controller_decorator.startupError(new Error(`${controller.name}.${method}: @Cooldown is for interaction and message handlers, and this is ${handler}.`));
         }
     }
 }
@@ -3261,7 +3378,8 @@ const FLAG = /^\{--(\w+)(?::([\w-]+(?:\|[\w-]+)*))?(\?)?\}$/;
                 if (own.hidden !== undefined && typeof own.hidden !== 'boolean') throw new Error(`hidden is true or false, not ${JSON.stringify(own.hidden)}.`);
                 aliases = aliasPatterns(pattern, parsed.tokens, own.aliases);
             } catch (error) {
-                throw controller_decorator.refuse(new Error(`${controllerClass.name}.${method}: @MessageHandler('${pattern}'): ${error.message}`));
+                controller_decorator.startupError(new Error(`${controllerClass.name}.${method}: @MessageHandler('${pattern}'): ${error.message}`));
+                continue;
             }
             const shared = {
                 controllerClass,
@@ -3300,7 +3418,7 @@ const FLAG = /^\{--(\w+)(?::([\w-]+(?:\|[\w-]+)*))?(\?)?\}$/;
                 routes.splice(j--, 1);
                 continue;
             }
-            throw controller_decorator.refuse(new Error(`${a.controllerClass.name}.${a.method}: ${describeRoute(a)} and ${describeRoute(b)} in ${b.controllerClass.name}.${b.method} ` + `match the same messages, so only one of them could ever answer those. Change one pattern, or give one its own prefix.`));
+            controller_decorator.startupError(new Error(`${a.controllerClass.name}.${a.method}: ${describeRoute(a)} and ${describeRoute(b)} in ${b.controllerClass.name}.${b.method} ` + `match the same messages, so only one of them could ever answer those. Change one pattern, or give one its own prefix.`));
         }
     }
     return routes;
@@ -4179,7 +4297,7 @@ const COMMAND_TYPES = new Set([
  *
  * @group Controllers
  * @see {@link HandlerEntry}
- * @see {@link https://meocord.dev/docs/4.1/handler-discovery | Handler discovery}
+ * @see {@link https://meocord.dev/docs/4.2/handler-discovery | Handler discovery}
  */ class HandlerRegistry {
     /**
    * Lists the registered handlers.
@@ -4424,7 +4542,7 @@ async function withTimeout(promise, ms, what) {
  *
  * @group Controllers
  * @see {@link ShardCallResult}
- * @see {@link https://meocord.dev/docs/4.1/sharding | Sharding}
+ * @see {@link https://meocord.dev/docs/4.2/sharding | Sharding}
  */ class ShardContext {
     /** The ids of the shards this process runs. With process sharding, one id; otherwise every shard, once ready. */ get ids() {
         if (this.client?.shard) return [
@@ -4601,9 +4719,9 @@ const isFactoryProvider = (provider)=>'useFactory' in provider;
 }
 const isToken = (value)=>typeof value === 'function' || typeof value === 'string' || typeof value === 'symbol';
 /**
- * Checks each provider's shape and indexes them by token, throwing on the first that cannot be bound, such as one with
- * no token, not exactly one of `useValue`, `useClass` and `useFactory`, one that injects `ExecutionContext`, or a
- * token provided twice.
+ * Checks each provider's shape and indexes them by token, reporting each that cannot be bound, such as one with no
+ * token, not exactly one of `useValue`, `useClass` and `useFactory`, one that injects `ExecutionContext`, or a token
+ * provided twice, as a startup error; see `startupError`.
  */ function providerMap(providers, where) {
     const map = new Map();
     for (const provider of providers){
@@ -4612,10 +4730,12 @@ const isToken = (value)=>typeof value === 'function' || typeof value === 'string
         if (typeof entry === 'function') {
             const name = tokenName(entry);
             const listing = where.includes('@MeoCord') ? 'list a service in @MeoCord({ services })' : 'a class a controller or service injects is bound for you, so it needs no listing';
-            throw controller_decorator.refuse(new Error(`${where}: ${name} is a class, not a provider: ${listing}. To put something in its place, write ` + `{ provide: ${name}, useValue } or { provide: ${name}, useClass }.`));
+            controller_decorator.startupError(new Error(`${where}: ${name} is a class, not a provider: ${listing}. To put something in its place, write ` + `{ provide: ${name}, useValue } or { provide: ${name}, useClass }.`));
+            continue;
         }
         if (!entry || typeof entry !== 'object' || !isToken(entry.provide)) {
-            throw controller_decorator.refuse(new Error(`${where}: a provider has no token: set provide to a class, a string or a symbol.`));
+            controller_decorator.startupError(new Error(`${where}: a provider has no token: set provide to a class, a string or a symbol.`));
+            continue;
         }
         const name = tokenName(entry.provide);
         const kinds = [
@@ -4624,26 +4744,35 @@ const isToken = (value)=>typeof value === 'function' || typeof value === 'string
             'useFactory'
         ].filter((kind)=>kind in entry);
         if (kinds.length !== 1) {
-            throw controller_decorator.refuse(new Error(`${where}: the provider for ${name} needs exactly one of useValue, useClass and useFactory.`));
+            controller_decorator.startupError(new Error(`${where}: the provider for ${name} needs exactly one of useValue, useClass and useFactory.`));
+            continue;
         }
         if ('useClass' in entry && typeof entry.useClass !== 'function') {
-            throw controller_decorator.refuse(new Error(`${where}: the provider for ${name} has a useClass that is not a class.`));
+            controller_decorator.startupError(new Error(`${where}: the provider for ${name} has a useClass that is not a class.`));
+            continue;
         }
         if ('useClass' in entry && injectedTokens(entry.useClass).includes(controller_decorator.ExecutionContext)) {
-            throw controller_decorator.refuse(new Error(`${where}: the provider for ${name} uses ${tokenName(entry.useClass)}, which injects ExecutionContext, but it is ` + "made once and shared, so it would keep the first call's context for every later call. Inject " + 'ExecutionContext only into guards.'));
+            controller_decorator.startupError(new Error(`${where}: the provider for ${name} uses ${tokenName(entry.useClass)}, which injects ExecutionContext, but it is ` + "made once and shared, so it would keep the first call's context for every later call. Inject " + 'ExecutionContext only into guards.'));
+            continue;
         }
         if ('useFactory' in entry) {
             if (typeof entry.useFactory !== 'function') {
-                throw controller_decorator.refuse(new Error(`${where}: the provider for ${name} has a useFactory that is not a function.`));
+                controller_decorator.startupError(new Error(`${where}: the provider for ${name} has a useFactory that is not a function.`));
+                continue;
             }
             if (entry.inject !== undefined && !(Array.isArray(entry.inject) && entry.inject.every(isToken))) {
-                throw controller_decorator.refuse(new Error(`${where}: the provider for ${name} has an inject that is not a list of tokens.`));
+                controller_decorator.startupError(new Error(`${where}: the provider for ${name} has an inject that is not a list of tokens.`));
+                continue;
             }
             if (entry.inject?.includes(controller_decorator.ExecutionContext)) {
-                throw controller_decorator.refuse(new Error(`${where}: the provider for ${name} injects ExecutionContext, but its factory runs once and its value is ` + "shared, so it would keep the first call's context for every later call. Inject ExecutionContext only into guards."));
+                controller_decorator.startupError(new Error(`${where}: the provider for ${name} injects ExecutionContext, but its factory runs once and its value is ` + "shared, so it would keep the first call's context for every later call. Inject ExecutionContext only into guards."));
+                continue;
             }
         }
-        if (map.has(entry.provide)) throw controller_decorator.refuse(new Error(`${where}: ${name} is provided twice.`));
+        if (map.has(entry.provide)) {
+            controller_decorator.startupError(new Error(`${where}: ${name} is provided twice.`));
+            continue;
+        }
         map.set(entry.provide, provider);
     }
     return map;
@@ -4696,22 +4825,23 @@ const isToken = (value)=>typeof value === 'function' || typeof value === 'string
     for (const dependency of inject)if (isAppClassToken(dependency)) bindClass(dependency);
 }
 /**
- * Throws when a class or a factory asks for a string or symbol token that nothing binds, naming both,
- * rather than failing when the class is first resolved. A class token is bound on demand, so it is
- * never missing.
+ * Reports a class or a factory that asks for a string or symbol token nothing binds, naming both, rather than failing
+ * when the class is first resolved. A class token is bound on demand, so it is never missing.
  */ function assertProvided(container, providers, classes, where) {
     const missing = (token)=>(typeof token === 'string' || typeof token === 'symbol') && !container.isBound(token);
     for (const cls of classes){
         const token = injectedTokens(cls).find(missing);
         if (token !== undefined) {
-            throw controller_decorator.refuse(new Error(`${cls.name}: it injects ${tokenName(token)}, which nothing provides: add a provider for it to ${where}.`));
+            controller_decorator.startupError(new Error(`${cls.name}: it injects ${tokenName(token)}, which nothing provides: add a provider for it to ${where}.`));
+            continue;
         }
     }
     for (const [provided, provider] of providers){
         const dependencies = isFactoryProvider(provider) ? provider.inject ?? [] : isClassProvider(provider) ? injectedTokens(provider.useClass) : [];
         const token = dependencies.find(missing);
         if (token !== undefined) {
-            throw controller_decorator.refuse(new Error(`${tokenName(provided)}: its provider injects ${tokenName(token)}, which nothing provides: add a provider for it to ${where}.`));
+            controller_decorator.startupError(new Error(`${tokenName(provided)}: its provider injects ${tokenName(token)}, which nothing provides: add a provider for it to ${where}.`));
+            continue;
         }
     }
 }
@@ -4744,16 +4874,21 @@ const isToken = (value)=>typeof value === 'function' || typeof value === 'string
  */ function assertTypedParameters(classes, decorators) {
     for (const cls of classes){
         const instead = meocordClassAdvice(cls);
-        if (instead && undecoratedConstructor(cls)) throw controller_decorator.refuse(new Error(`${cls.name}: MeoCord does not inject it; ${instead}.`));
+        if (instead && undecoratedConstructor(cls)) {
+            controller_decorator.startupError(new Error(`${cls.name}: MeoCord does not inject it; ${instead}.`));
+            continue;
+        }
         if (undecoratedConstructor(cls)) {
             const decorator = decorators.get(cls);
-            throw controller_decorator.refuse(new Error(`${cls.name}: its constructor takes parameters, but ${cls.name} has no decorator, so TypeScript recorded none of ` + `their types and it cannot be created. ${decorator ? `Decorate it with ${decorator}.` : 'Decorate it with @Service(), or give a class from a package a provider in @MeoCord({ providers }).'}`));
+            controller_decorator.startupError(new Error(`${cls.name}: its constructor takes parameters, but ${cls.name} has no decorator, so TypeScript recorded none of ` + `their types and it cannot be created. ${decorator ? `Decorate it with ${decorator}.` : 'Decorate it with @Service(), or give a class from a package a provider in @MeoCord({ providers }).'}`));
+            continue;
         }
         const index = untypedParameter(cls);
         if (index === -1) continue;
         const injectors = classes.filter((other)=>other !== cls && injectedTokens(other).includes(cls)).map((other)=>other.name);
         const injectedBy = injectors.length === 0 ? '' : ` (${injectors.length === 1 ? injectors[0] : `${injectors.slice(0, -1).join(', ')} and ${injectors.at(-1)}`} ` + `inject${injectors.length === 1 ? 's' : ''} ${cls.name})`;
-        throw controller_decorator.refuse(new Error(`${cls.name}: parameter ${index + 1} of its constructor has no runtime type, so it cannot be created. Usually ` + `${cls.name} and a class it injects import each other${injectedBy}, or the parameter is typed with an ` + 'interface or an `import type`. Move what they both need into a third service, or inject the parameter ' + 'with @Inject(token).'));
+        controller_decorator.startupError(new Error(`${cls.name}: parameter ${index + 1} of its constructor has no runtime type, so it cannot be created. Usually ` + `${cls.name} and a class it injects import each other${injectedBy}, or the parameter is typed with an ` + 'interface or an `import type`. Move what they both need into a third service, or inject the parameter ' + 'with @Inject(token).'));
+        continue;
     }
 }
 /** For each container, the tokens MeoCord binds itself, each to the app's class it stands for, if any. */ const ownTokens = new WeakMap();
@@ -4822,15 +4957,20 @@ const isToken = (value)=>typeof value === 'function' || typeof value === 'string
 }
 /**
  * Runs every factory in `order`, awaiting those that return a promise, so each value is made before
- * anything that injects it is resolved. Rejects with {@link providerFailure} for the first that fails.
- */ async function resolveProviders(container, providers, order) {
+ * anything that injects it is resolved. Rejects with {@link providerFailure} for the first that fails. With `control`,
+ * it makes no further value once the app is stopping.
+ */ async function resolveProviders(container, providers, order, control) {
     for (const token of order){
         const provider = providers.get(token);
         if (!provider || !isFactoryProvider(provider)) continue;
+        if (control?.stopped()) return;
+        control?.pending(tokenName(token));
         try {
             await container.getAsync(token);
         } catch (error) {
             throw providerFailure(token, error);
+        } finally{
+            control?.pending(undefined);
         }
     }
 }
@@ -4904,9 +5044,12 @@ exports.messageStartsFor = messageStartsFor;
 exports.needsGuild = needsGuild;
 exports.nonInteractionHandler = nonInteractionHandler;
 exports.observeUnclaimed = observeUnclaimed;
+exports.prepareAppPresenter = prepareAppPresenter;
 exports.prepareHandlerStages = prepareHandlerStages;
+exports.prepareThemes = prepareThemes;
 exports.providerMap = providerMap;
 exports.reachableClasses = reachableClasses;
+exports.recordInstanceContainers = recordInstanceContainers;
 exports.registerClientTheme = registerClientTheme;
 exports.registerCommands = registerCommands;
 exports.registrationKey = registrationKey;