meocord 4.2.2 → 4.2.3

package/dist/esm/core/scalar-types.js

@@ -21,34 +21,70 @@ const UNIT_MS = lookupTable({
     w: 604800000
 });
 /** A number written in full, `whole` for an integer: `undefined` for anything else. */ function number(word, whole) {
-    if (!(whole ? /^[+-]?\d+$/ : /^[+-]?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i).test(word)) return undefined;
+    // Each run of digits splits only one way, so refusing a word takes time linear in its length
+    if (!(whole ? /^[+-]?\d+$/ : /^[+-]?(\d+(?:\.\d*)?|\.\d+)(e[+-]?\d+)?$/i).test(word)) return undefined;
     const value = Number(word);
     return Number.isFinite(value) && (!whole || Number.isSafeInteger(value)) ? value : undefined;
 }
 /** `yes`, `no`, `true`, `false`, `on` or `off`, in any case, as a boolean. */ const bool = (word)=>BOOLEANS[word.toLowerCase()];
-/** A length of time written as amounts and units, such as `90s`, `2h30m` or `1.5d`, in milliseconds. */ function duration(word) {
-    const parts = word.toLowerCase().match(/(\d+(?:\.\d+)?)(ms|s|m|h|d|w)/g);
+/**
+ * A length of time written as amounts and units, such as `90s`, `2h30m` or `1.5d`, in milliseconds: `undefined` for one
+ * too long to add up.
+ */ function duration(word) {
+    // Sticky: each part starts where the last ended, so the scan stops at the first that doesn't and reads each part once
+    const parts = word.toLowerCase().match(/(\d+(?:\.\d+)?)(ms|s|m|h|d|w)/gy);
     if (!parts || parts.join('') !== word.toLowerCase()) return undefined;
-    return parts.reduce((total, part)=>{
+    const total = parts.reduce((sum, part)=>{
         const [, amount, unit] = /^(\d+(?:\.\d+)?)(ms|s|m|h|d|w)$/.exec(part);
-        return total + Number(amount) * UNIT_MS[unit];
+        return sum + Number(amount) * UNIT_MS[unit];
     }, 0);
+    // Too long to add up, as number() refuses a value past the largest number
+    return Number.isFinite(total) ? total : undefined;
 }
 /** The largest snowflake: Discord's IDs are unsigned 64-bit integers. */ const MAX_SNOWFLAKE = 2n ** 64n - 1n;
+/** The fewest and most digits a snowflake has, and the words of that many digits, with no leading zero. */ const SNOWFLAKE_DIGITS = {
+    min: 17,
+    max: 20
+};
+const SNOWFLAKE = new RegExp(`^[1-9]\\d{${SNOWFLAKE_DIGITS.min - 1},${SNOWFLAKE_DIGITS.max - 1}}$`);
 /**
  * A Discord ID, kept as its text: 17 to 20 digits, no leading zero, up to the largest 64-bit value. An ID's top 42 bits
  * are milliseconds since 2015-01-01, so every ID made from 2015-01-28 on has 17 digits or more, and none is a safe
  * integer.
- */ const snowflake = (word)=>/^[1-9]\d{16,19}$/.test(word) && BigInt(word) <= MAX_SNOWFLAKE ? word : undefined;
-/** A UUID in its canonical 8-4-4-4-12 form, in either case, kept as written. */ const uuid = (word)=>/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i.test(word) ? word : undefined;
+ */ const snowflake = (word)=>SNOWFLAKE.test(word) && BigInt(word) <= MAX_SNOWFLAKE ? word : undefined;
+/** A UUID's canonical 8-4-4-4-12 form, 36 characters with its dashes. */ const UUID = /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i;
+const UUID_LENGTH = 36;
+/** A UUID in its canonical 8-4-4-4-12 form, in either case, kept as written. */ const uuid = (word)=>UUID.test(word) ? word : undefined;
 /** The words a type such as `on|off` chooses from, or `undefined` for any other type. */ const choicesOf = (type)=>type.includes('|') ? type.split('|') : undefined;
-/** The types a component's customId segment can take: each parsed from the segment alone, with no request. */ const SEGMENT_TYPES = lookupTable({
-    string: (segment)=>segment,
-    int: (segment)=>number(segment, true),
-    number: (segment)=>number(segment, false),
-    bool,
-    snowflake,
-    uuid
+/** The shortest segment of any type: one character. */ const SHORTEST_SEGMENT = 1;
+/**
+ * The types a component's customId segment can take: each parsed from the segment alone, with no request, and the
+ * fewest characters a segment of it has, which the check for a pattern no customId can match counts.
+ */ const SEGMENT_TYPES = lookupTable({
+    string: {
+        parse: (segment)=>segment,
+        shortest: SHORTEST_SEGMENT
+    },
+    int: {
+        parse: (segment)=>number(segment, true),
+        shortest: SHORTEST_SEGMENT
+    },
+    number: {
+        parse: (segment)=>number(segment, false),
+        shortest: SHORTEST_SEGMENT
+    },
+    bool: {
+        parse: bool,
+        shortest: Math.min(...Object.keys(BOOLEANS).map((word)=>word.length))
+    },
+    snowflake: {
+        parse: snowflake,
+        shortest: SNOWFLAKE_DIGITS.min
+    },
+    uuid: {
+        parse: uuid,
+        shortest: UUID_LENGTH
+    }
 });
 /**
  * Whether `type` can type a customId segment: `string`, `int`, `number`, `bool`, `snowflake`, `uuid`, or words to
@@ -57,7 +93,12 @@ const UNIT_MS = lookupTable({
 /** A customId segment as its type's value, words to choose from compared as written: `undefined` when it is not one. */ function parseSegment(type, segment) {
     const choices = choicesOf(type);
     if (choices) return choices.includes(segment) ? segment : undefined;
-    return SEGMENT_TYPES[type](segment);
+    return SEGMENT_TYPES[type].parse(segment);
+}
+/** The fewest characters a customId segment of `type` has: words to choose from count their shortest word. */ function shortestSegment(type) {
+    const choices = choicesOf(type);
+    if (choices) return Math.min(...choices.map((word)=>word.length));
+    return SEGMENT_TYPES[type]?.shortest ?? SHORTEST_SEGMENT;
 }
 
-export { bool, choicesOf, duration, isSegmentType, lookupTable, number, parseSegment, snowflake, uuid };
+export { bool, choicesOf, duration, isSegmentType, lookupTable, number, parseSegment, shortestSegment, snowflake, uuid };

package/dist/esm/core/shard-context.js

@@ -1,19 +1,20 @@
 import { randomUUID } from 'node:crypto';
 import { Logger } from '../common/logger.js';
-import './theme-scope.js';
-import './theme-validation.js';
+import '../common/theme.js';
 import '../common/decorator.js';
 import 'reflect-metadata';
 import 'discord.js';
+import '../common/deprecation.js';
 import '../common/response/response-state.js';
+import './theme-scope.js';
 import '../common/errors.js';
+import '../common/cooldown-store.js';
 import '../decorator/controller.decorator.js';
 import './scalar-types.js';
-import 'path';
-import 'node:fs';
-import 'node:url';
+import '../util/refusal.util.js';
 import '../common/translator.js';
 import '../common/meocord-text.js';
+import './theme-resolvers.js';
 
 /** Where each shard's client keeps the function that runs a `ShardContext.call` in that shard. */ const SHARD_CALL_KEY = Symbol.for('meocord.shardCall');
 const packArgs = (args)=>Object.assign({
@@ -122,11 +123,11 @@ async function withTimeout(promise, ms, what) {
    *
    * With process sharding that is one result per shard; with one process, a single result listing every
    * shard. The arguments and the result pass as JSON in every mode, one process and tests included, so a
-   * `Date` arrives as a string and a `Map` as `{}` wherever it runs, and a value JSON cannot carry, such as a
-   * `BigInt`, fails the call. A method whose params JSON would change, such as one taking a `Date`, cannot be called:
-   * the argument is refused, naming what to declare instead. An `undefined` argument arrives as `undefined`. A process
-   * that throws, lacks the service, or does not answer within 10 seconds gives an error result instead of failing the
-   * others.
+   * `Date` arrives as a string, a `Map` as `{}` and a class instance as its own fields, without its getters, wherever
+   * it runs, and a value JSON cannot carry, such as a `BigInt`, fails the call. A method whose params JSON would
+   * change, such as one taking a `Date`, cannot be called: the argument is refused, naming what to declare instead. An
+   * `undefined` argument arrives as `undefined`. A process that throws, lacks the service, or does not answer within
+   * 10 seconds gives an error result instead of failing the others.
    *
    * @param service - The controller, the service, or a class a provider stands in for; each process resolves its own
    *   instance.

package/dist/esm/core/shard-exit.js

@@ -1,4 +1,5 @@
 import { isExplainedError, markExplained } from '../common/explained-error.js';
+import { processState } from './process-state.js';
 import { REFUSED_CODE } from './shard-messages.js';
 import { sendToParent } from '../util/parent-send.util.js';
 import { isRefusal, describeRefusal, handOffRefusal } from '../util/refusal.util.js';
@@ -9,14 +10,13 @@ import { isRefusal, describeRefusal, handOffRefusal } from '../util/refusal.util
  */ async function tellManager(message) {
     await sendToParent(message);
 }
-/** Whether this shard is already ending, so a failure reported twice, as one going on uncaught is, ends it once. */ let ending = false;
 /**
  * Ends a shard whose startup failed, which its manager restarts unless it was told the failure is one every shard
  * meets: a refusal, told here first, which the manager logs before stopping them all, or a login Discord refused, told
  * as it failed. The exit waits until the caller has handled the error and the manager has the reason.
  */ function endFailedShard(error) {
-    if (ending) return;
-    ending = true;
+    if (processState.shardEnding) return;
+    processState.shardEnding = true;
     const refused = isRefusal(error);
     const reason = refused && describeRefusal(error, process.cwd());
     if (refused) {

package/dist/esm/core/shard-manager.js

@@ -1,10 +1,11 @@
 import { fetchRecommendedShardCount, ShardingManager, REST, Routes } from 'discord.js';
 import { Logger, hideInLogs } from '../common/logger.js';
-import './theme-scope.js';
-import './theme-validation.js';
+import '../common/theme.js';
 import '../common/decorator.js';
 import 'reflect-metadata';
+import '../common/deprecation.js';
 import '../common/response/response-state.js';
+import './theme-scope.js';
 import '../common/errors.js';
 import { MemoryCooldownStore } from '../common/cooldown-store.js';
 import 'node:crypto';
@@ -13,10 +14,11 @@ import './scalar-types.js';
 import { answerCooldown } from '../common/sharded-cooldown-store.js';
 import '../common/translator.js';
 import '../common/meocord-text.js';
+import './theme-resolvers.js';
 import { registerCommands } from './command-registration.js';
 import { SHUTDOWN_MARGIN_MS, shutdownTimeoutOf } from '../util/shutdown-timeout.util.js';
 import { bundleEntry } from '../util/bundle-entry.util.js';
-import { FORCE_REGISTER_ENV } from '../util/registration-mode.util.js';
+import { FORCE_REGISTER_ENV, registersAsDevelopment } from '../util/registration-mode.util.js';
 import { isShardMessage, REFUSED_CODE } from './shard-messages.js';
 import { tokenMessage, isRefusedToken } from './login-failure.js';
 import { onDevRunnerStop, tellDevRunner, underDevRunner } from '../util/dev-runner.util.js';
@@ -54,7 +56,10 @@ const sleep = (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
             return this.exit(1);
         }
         this.logger.log('Starting shards in separate processes...');
-        if (!await this.register()) return this.exitForLogin();
+        const registered = await this.register();
+        // A stop that came while it waited ends the start here: nothing after it asks Discord, spawns, listens or exits
+        if (this.stopping) return;
+        if (!registered) return this.exitForLogin();
         process.on('SIGINT', ()=>void this.stopAndExit());
         process.on('SIGTERM', ()=>void this.stopAndExit());
         // How `meocord start --dev` stops the bot to restart it; no stop request of the user's, whose first Ctrl+C joins it
@@ -64,6 +69,7 @@ const sleep = (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
             const shards = config.sharding?.shards ?? 'auto';
             total = shards === 'auto' ? await (this.options.recommendedShardCount ?? fetchRecommendedShardCount)(token) : shards;
         } catch (error) {
+            if (this.stopping) return;
             if (isRefusedToken(error)) {
                 this.logger.error(tokenMessage(token));
                 this.logger.debug('Asking for the shard count failed:', error);
@@ -72,6 +78,7 @@ const sleep = (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
             }
             return this.exitForLogin();
         }
+        if (this.stopping) return;
         const manager = (this.options.createManager ?? ((path, opts)=>new ShardingManager(path, opts)))(file, {
             token,
             totalShards: total,
@@ -105,13 +112,15 @@ const sleep = (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
         try {
             const rest = this.options.createRest?.(token) ?? new REST().setToken(token);
             const applicationId = (await rest.get(Routes.currentApplication())).id;
+            // Stopped while it asked: the commands are left as they are
+            if (this.stopping) return true;
             await registerCommands({
                 rest,
                 applicationId,
                 controllerClasses,
                 logger: this.logger,
                 config: config.commands,
-                development: process.env.NODE_ENV === 'development',
+                development: registersAsDevelopment(),
                 force: process.env[FORCE_REGISTER_ENV] === '1'
             });
         } catch (error) {
@@ -153,7 +162,8 @@ const sleep = (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
         if (this.now() - state.spawnedAt >= RESPAWN_RESET_MS) state.attempts = 0;
         const delay = Math.min(RESPAWN_BASE_MS * 2 ** state.attempts, RESPAWN_CAP_MS);
         state.attempts++;
-        this.logger.warn(`Shard ${shard.id} exited with code ${child?.exitCode ?? 'unknown'}; restarting it in ${delay} ms.`);
+        const how = child?.signalCode ? `on ${child.signalCode}` : `with code ${child?.exitCode ?? 'unknown'}`;
+        this.logger.warn(`Shard ${shard.id} exited ${how}; restarting it in ${delay} ms.`);
         state.timer = setTimeout(()=>{
             state.timer = undefined;
             if (!this.stopping && !this.fatal) void this.spawn(shard);

package/dist/esm/core/startup-roots.js

@@ -5,6 +5,7 @@ import { reachableClasses, assertTypedParameters } from './providers.js';
 import { themeResolverClass } from './theme-resolvers.js';
 import { isAppClassToken } from './lifecycle-order.js';
 import { ExecutionContext } from '../common/execution-context.js';
+import { getEventHandlers } from '../decorator/event.decorator.js';
 import { META } from '../util/metadata-keys.js';
 import { startupError } from '../util/refusal.util.js';
 
@@ -63,19 +64,38 @@ import { startupError } from '../util/refusal.util.js';
     seen.add(cls);
     return injectedTokens(cls).some((token)=>token === ExecutionContext || isAppClassToken(token) && !providers.has(token) && !seen.has(token) && reachesContext(token, providers, seen));
 }
-/**
- * The classes the app's stages and presenter inject, which they would make only at their first call. Made with the
- * app's own classes, a service among them gets its lifecycle hooks. One that reaches the call's `ExecutionContext` is
- * made for each call, so it is left out, and a stage a test replaces is not among the stages, so what it would inject
- * is not made.
- */ function stageDependencies({ decorators }, providers, presenter) {
+/** The app's classes the stages and presenter inject. */ function stageInjected({ decorators }, presenter) {
     const stages = [
         ...decorators
     ].filter(([, decorator])=>decorator !== '@Controller()').map(([stage])=>stage);
     if (typeof presenter === 'function') stages.push(presenter);
     return [
         ...new Set(stages.flatMap((stage)=>injectedTokens(stage)))
-    ].filter(isAppClassToken).filter((cls)=>!reachesContext(cls, providers));
+    ].filter(isAppClassToken);
+}
+/**
+ * The classes the app's stages and presenter inject, which they would make only at their first call. Made with the
+ * app's own classes, a service among them gets its lifecycle hooks. One that reaches the call's `ExecutionContext` is
+ * made for each call, so it is left out, and a stage a test replaces is not among the stages, so what it would inject
+ * is not made.
+ */ function stageDependencies(startup, providers, presenter) {
+    return stageInjected(startup, presenter).filter((cls)=>!reachesContext(cls, providers));
+}
+/**
+ * A warning for each `@On` and `@Once` handler on a class the stages and presenter reach that is made for each call,
+ * as it reaches `ExecutionContext`: no one instance of it receives events.
+ */ function perCallEventWarnings(startup, providers, presenter) {
+    const perCall = new Set();
+    // What a class made for each call injects is made for each call too only if it also reaches the context
+    const visit = (cls)=>{
+        if (perCall.has(cls) || providers.has(cls) || !reachesContext(cls, providers)) return;
+        perCall.add(cls);
+        injectedTokens(cls).filter(isAppClassToken).forEach(visit);
+    };
+    stageInjected(startup, presenter).forEach(visit);
+    return [
+        ...perCall
+    ].flatMap((cls)=>getEventHandlers(cls.prototype).map(({ event, method, once })=>`${cls.name}.${method}: @${once ? 'Once' : 'On'}('${event}') is on a class made for each call, as it injects ` + 'ExecutionContext or a class that does, so it receives no events. The next major version (5.0) refuses it; ' + 'move the handler to a service that does not.'));
 }
 /** How a container checks a guard first met at a call: the guard and what it injects, as the startup checks would. */ function lateGuardCheck(providers, translator) {
     return (guard)=>assertStartupClasses({
@@ -98,4 +118,4 @@ import { startupError } from '../util/refusal.util.js';
     for (const needsOne of classes.filter((cls)=>injectedTokens(cls).includes(Translator)))startupError(missingTranslatorError(needsOne));
 }
 
-export { assertStartupClasses, lateGuardCheck, stageDependencies, startupClasses };
+export { assertStartupClasses, lateGuardCheck, perCallEventWarnings, stageDependencies, startupClasses };

package/dist/esm/core/theme-resolvers.js

@@ -1,6 +1,9 @@
+import { User } from 'discord.js';
 import { Logger } from '../common/logger.js';
 import { themeProblems } from './theme-validation.js';
 import { outsideThemeScope, copyLayer } from './theme-scope.js';
+import { quoteForLog } from '../util/user-text.util.js';
+import { shared } from '../util/shared-state.util.js';
 
 /** How long a resolver's result is kept, in seconds, unless `themeCache.ttlSeconds` says otherwise. */ const DEFAULT_THEME_TTL_SECONDS = 300;
 /** How many servers' results are kept, unless `themeCache.maxGuilds` says otherwise. */ const DEFAULT_THEME_MAX_GUILDS = 10000;
@@ -113,15 +116,25 @@ const logger = new Logger('Theme');
         ]).finally(()=>clearTimeout(timer));
     }
     /**
-   * A result as a layer: copied, then checked; one with problems is left out, with a warning once per id when `report`.
-   * `null`, as a database gives for a missing row, is no theme, as `undefined` is.
+   * A result as a layer: copied, then checked; one with problems, or that throws as it is read, is left out, with a
+   * warning once per id when `report`. `null`, as a database gives for a missing row, is no theme, as `undefined` is.
    */ accept(id, result, report) {
         if (result === undefined || result === null) return undefined;
-        const layer = copyLayer(result);
-        // A value from the app's data, such as a user's saved choice, shown as a log line shows outside text
-        const problems = themeProblems(layer, `themeFor.${this.kind} for ${this.kind} ${id}`, {
-            forLog: true
-        });
+        const where = `themeFor.${this.kind} for ${this.kind} ${id}`;
+        let layer;
+        let problems;
+        try {
+            layer = copyLayer(result);
+            // A value from the app's data, such as a user's saved choice, shown as a log line shows outside text
+            problems = themeProblems(layer, where, {
+                forLog: true
+            });
+        } catch (error) {
+            // A cycle overflows the copy, and a getter may throw: the result is left out as one with problems is
+            problems = [
+                `${where}: theme cannot be read: ${quoteForLog(String(error?.message ?? error))}`
+            ];
+        }
         if (problems.length === 0) {
             if (report) this.warned.delete(id);
             return layer;
@@ -250,13 +263,14 @@ const logger = new Logger('Theme');
 const idOf = (value)=>typeof value === 'string' ? value : undefined;
 /**
  * The server and user a call comes from: an interaction's or a message's server and its user or author; a
- * reaction's message's server and the user who reacted, which a reaction handler gets second; an event argument's
- * server and user, when it has them.
+ * reaction's message's server and the user who reacted, which a reaction handler gets second as `{ user }` and a
+ * reaction event as the `User`; an event argument's server and user, when it has them.
  */ function themeTargets(args) {
     const [first, second] = args;
     if (!first || typeof first !== 'object') return {};
     const guildId = idOf(first.guildId) ?? idOf(first.guild?.id) ?? idOf(first.message?.guildId);
-    const userId = idOf(first.user?.id) ?? idOf(first.author?.id) ?? idOf(second?.user?.id);
+    // Only a User's own id: an event of an old and a new channel, role or message would give the new one's otherwise
+    const userId = idOf(first.user?.id) ?? idOf(first.author?.id) ?? idOf(second?.user?.id) ?? (second instanceof User ? idOf(second.id) : undefined);
     return {
         guildId,
         userId
@@ -283,7 +297,8 @@ const idOf = (value)=>typeof value === 'string' ? value : undefined;
         user
     ];
 }
-const stores = new WeakMap();
+// One per process for this meocord version, as the rest of an app's theme state is
+const stores = shared('themeCaches', ()=>new WeakMap());
 /**
  * An app's cache of the themes `@MeoCord({ themeFor })` looked up, by server and by user.
  *

package/dist/esm/core/theme-runtime.js

@@ -1,12 +1,14 @@
 import 'reflect-metadata';
-import { stageClasses, sourcePrototype } from './guard-runner.js';
+import { stageClasses, stageOwners } from './guard-runner.js';
 import { makeInjectable } from '../util/injectable.util.js';
 import { lookupLayers, resolverCaches, ThemeCache, attachThemeCache } from './theme-resolvers.js';
-import { releaseAmbientTheme, claimAmbientTheme, mergeTheme, defaultTheme, themeLayersVersion, ambientThemeVersion, ownsAmbientTheme, hasAmbientTheme, setThemeOutsideCalls, useTheme } from './theme-scope.js';
+import { setThemeOutsideCalls, releaseAmbientTheme, claimAmbientTheme, defaultTheme, mergeTheme, themeLayersVersion, ambientThemeVersion, ownsAmbientTheme, useTheme } from './theme-scope.js';
 import { META } from '../util/metadata-keys.js';
+import { shared } from '../util/shared-state.util.js';
 
-/** Classes with a `@UseTheme`, on the class or one of its methods. */ const THEMED_CLASSES = new WeakSet();
-const apps = new WeakMap();
+/** Classes with a `@UseTheme`, on the class or one of its methods, from either build of this version. */ const THEMED_CLASSES = shared('themedClasses', ()=>new WeakSet());
+// One per process for this meocord version, so an app started through one build finds its theme from the other
+const apps = shared('appThemes', ()=>new WeakMap());
 /** The classes on `cls`'s prototype chain, itself first. */ function chainOf(cls) {
     const chain = [];
     for(let prototype = cls.prototype; prototype && prototype !== Object.prototype; prototype = Object.getPrototypeOf(prototype)){
@@ -37,6 +39,13 @@ const apps = new WeakMap();
     }
     attachThemeCache(container.get(ThemeCache), resolvers);
 }
+/** Counts `classes`, whose handlers are prepared once the app's providers are made, among those a theme can vary by. */ function prepareLateThemes(container, classes) {
+    const themes = apps.get(container);
+    if (!themes || themes.varies || !classes.some((cls)=>chainOf(cls).some((link)=>THEMED_CLASSES.has(link)))) return;
+    themes.varies = true;
+    // Built again on its next read, with each handler's own theme
+    themes.version = -1;
+}
 /** The app's themes, built again when the layers beneath the app's have changed. */ function current(container) {
     const themes = apps.get(container);
     if (themes && themes.version !== themeLayersVersion()) {
@@ -51,13 +60,12 @@ const apps = new WeakMap();
 }
 /**
  * Decides whether the app's calls need a scope, again whenever the layers beneath it or the app read outside a call
- * change. They do when the handlers can differ in theme. Otherwise a call reads the theme outside a call, so it
- * needs one unless that is its own theme: when the app owns it, or when no app does and the app's theme is MeoCord's
- * defaults.
+ * change. They do when the handlers can differ in theme. Otherwise a call reads the theme outside a call, so it needs
+ * one unless its app owns that theme: another app may claim it while the call runs, and the call keeps the theme it
+ * started with.
  */ function rescope(container, themes) {
     themes.ambientVersion = ambientThemeVersion();
-    const readsOwnTheme = ownsAmbientTheme(container) || !hasAmbientTheme() && themes.app === defaultTheme();
-    themes.scoped = themes.varies || !readsOwnTheme ? themes.app : undefined;
+    themes.scoped = themes.varies || !ownsAmbientTheme(container) ? themes.app : undefined;
 }
 /** The app's theme: MeoCord's defaults and the app's `@MeoCord({ theme })`, or the defaults for a container with none. */ function appTheme(container) {
     return current(container)?.app ?? defaultTheme();
@@ -75,8 +83,10 @@ const apps = new WeakMap();
     for (const cls of stageClasses(prototype, methodName)){
         theme = mergeTheme(theme, Reflect.getOwnMetadata(META.classTheme, cls));
     }
-    const source = sourcePrototype(prototype, methodName);
-    if (source) theme = mergeTheme(theme, Reflect.getOwnMetadata(META.methodTheme, source, methodName));
+    // The method's layer over its class's, and an override's over the method it overrides
+    for (const owner of stageOwners(prototype, methodName)){
+        theme = mergeTheme(theme, Reflect.getOwnMetadata(META.methodTheme, owner, methodName));
+    }
     byMethod.set(methodName, theme);
     return theme;
 }
@@ -115,7 +125,7 @@ const apps = new WeakMap();
         ready
     };
 }
-const clientApps = new WeakMap();
+const clientApps = shared('clientThemes', ()=>new WeakMap());
 /** Records which app a client's interactions come to, so an answer outside any call can find its theme. */ function registerClientTheme(client, container) {
     clientApps.set(client, container);
 }
@@ -139,4 +149,4 @@ setThemeOutsideCalls((interaction)=>{
     releaseAmbientTheme(container);
 }
 
-export { THEMED_CLASSES, appTheme, beginCallTheme, claimAmbientAppTheme, configureThemes, registerClientTheme, releaseAmbientAppTheme };
+export { THEMED_CLASSES, appTheme, beginCallTheme, claimAmbientAppTheme, configureThemes, prepareLateThemes, registerClientTheme, releaseAmbientAppTheme };

package/dist/esm/core/theme-scope.js

@@ -64,50 +64,50 @@ const merges = new WeakMap();
     if (!merged) byLayer.set(layer, merged = deepFreeze(mergeInto(theme, layer)));
     return merged;
 }
-// Written by the deprecated `Theme` statics: beneath every theme an app sets
-let legacyLayer;
-let legacyVersion = 0;
-let defaults = DEFAULT_THEME;
+/**
+ * The theme state outside a call, one for both builds of this version so either reads what the other set: the defaults
+ * with what the deprecated `Theme` statics set beneath every theme, the app whose theme is read outside a call, and how
+ * an answer outside a call finds its theme.
+ */ const state = shared('themeState', ()=>({
+        defaults: DEFAULT_THEME,
+        legacyVersion: 0,
+        ambient: undefined,
+        ambientVersion: 0,
+        themeOutsideCalls: undefined
+    }));
 /** MeoCord's defaults, with what the deprecated `Theme` statics set over them. */ function defaultTheme() {
-    return defaults;
+    return state.defaults;
 }
 /** The number of times the legacy layer has changed, so a theme built on an older one is built again. */ function themeLayersVersion() {
-    return legacyVersion;
+    return state.legacyVersion;
 }
 /** Sets the layer the deprecated `Theme` statics write, merged over MeoCord's defaults. */ function setLegacyThemeLayer(layer) {
-    legacyLayer = layer === undefined ? undefined : copyLayer(layer);
-    defaults = mergeTheme(DEFAULT_THEME, legacyLayer);
-    legacyVersion++;
+    state.defaults = mergeTheme(DEFAULT_THEME, layer === undefined ? undefined : copyLayer(layer));
+    state.legacyVersion++;
 }
-// The theme outside any call: the one of the app or testing module that claimed it, until it gives it up
-let ambient;
-let ambientVersion = 0;
 /** The number of times the app read outside a call has changed, so each app decides again whether its calls need a scope. */ function ambientThemeVersion() {
-    return ambientVersion;
-}
-/** Whether some app's theme is the one read outside a call. */ function hasAmbientTheme() {
-    return ambient !== undefined;
+    return state.ambientVersion;
 }
 /**
  * Makes an app's theme the one read outside a call, when no other app has: a bot runs one app, and code it runs
  * outside a handler, such as a scheduled job, then reads that app's theme. A second app in the same process keeps
  * its theme to its own calls.
  */ function claimAmbientTheme(owner, theme) {
-    if (ambient && ambient.owner !== owner) return false;
-    if (!ambient) ambientVersion++;
-    ambient = {
+    if (state.ambient && state.ambient.owner !== owner) return false;
+    if (!state.ambient) state.ambientVersion++;
+    state.ambient = {
         owner,
         theme
     };
     return true;
 }
 /** Gives up the theme read outside a call, when `owner` has it: its start failed, or it has shut down. */ function releaseAmbientTheme(owner) {
-    if (ambient?.owner !== owner) return;
-    ambient = undefined;
-    ambientVersion++;
+    if (state.ambient?.owner !== owner) return;
+    state.ambient = undefined;
+    state.ambientVersion++;
 }
 /** Whether `owner` is the app whose theme is read outside a call. */ function ownsAmbientTheme(owner) {
-    return ambient?.owner === owner;
+    return state.ambient?.owner === owner;
 }
 /** Runs `fn` with `theme` as the theme of the call, for everything it runs, awaits or starts. */ function runWithTheme(theme, fn) {
     return scope.run({
@@ -123,10 +123,8 @@ let ambientVersion = 0;
 /** Runs `fn` in `themeScope`, whose theme may be replaced while it runs, as a per-server theme is found. */ function runInThemeScope(themeScope, fn) {
     return scope.run(themeScope, fn);
 }
-// Set by the runtime: the theme an app gives an interaction answered outside any call, as in a collector
-let themeOutsideCalls;
 /** Sets how an answer outside any call finds its theme: from the interaction's app, server and user. */ function setThemeOutsideCalls(resolve) {
-    themeOutsideCalls = resolve;
+    state.themeOutsideCalls = resolve;
 }
 /**
  * The theme an answer to `interaction` uses: the running call's, or, outside any call, as in a collector's callback,
@@ -134,7 +132,7 @@ let themeOutsideCalls;
  */ function themeForInteraction(interaction) {
     const call = scope.getStore();
     if (call) return call.theme;
-    return themeOutsideCalls?.(interaction) ?? useTheme();
+    return state.themeOutsideCalls?.(interaction) ?? useTheme();
 }
 /**
  * The theme of the running call, with every role present.
@@ -163,7 +161,7 @@ let themeOutsideCalls;
  *
  * @group Responses
  */ function useTheme() {
-    return scope.getStore()?.theme ?? ambient?.theme() ?? defaults;
+    return scope.getStore()?.theme ?? state.ambient?.theme() ?? state.defaults;
 }
 /**
  * Makes a function run in the theme of the call that binds it, wherever it is called from later.
@@ -198,4 +196,4 @@ let themeOutsideCalls;
     };
 }
 
-export { ambientThemeVersion, bindTheme, claimAmbientTheme, copyLayer, defaultTheme, hasAmbientTheme, mergeTheme, outsideThemeScope, ownsAmbientTheme, releaseAmbientTheme, runInThemeScope, runWithTheme, setLegacyThemeLayer, setThemeOutsideCalls, themeForInteraction, themeLayersVersion, useTheme };
+export { ambientThemeVersion, bindTheme, claimAmbientTheme, copyLayer, defaultTheme, mergeTheme, outsideThemeScope, ownsAmbientTheme, releaseAmbientTheme, runInThemeScope, runWithTheme, setLegacyThemeLayer, setThemeOutsideCalls, themeForInteraction, themeLayersVersion, useTheme };

package/dist/esm/core/theme-validation.js

@@ -51,7 +51,7 @@ const describeGroup = (value, quote = asWritten)=>Array.isArray(value) ? 'an arr
     const prototype = Object.getPrototypeOf(value);
     return prototype === Object.prototype || prototype === null;
 };
-const PLAIN = "give a plain object, such as { ...value }, or a row's toObject(), since anything else would replace the whole";
+const PLAIN = "give a plain object: a database row's plain form, such as Mongoose's toObject() or Sequelize's get({ plain: true }), or an object literal of the values you set, since anything else would replace the whole";
 /** What a non-plain object is: by its class, or as one without a plain prototype when it has none named. */ const describeInstance = (value)=>{
     const name = value.constructor?.name;
     return typeof name === 'string' && name ? `a ${name}` : 'an object without a plain prototype';

package/dist/esm/decorator/app.decorator.js

@@ -8,10 +8,12 @@ import { assertObservers } from '../core/observer-runner.js';
 import { assertValidTheme, themeForProblem } from '../core/theme-validation.js';
 import { copyLayer } from '../core/theme-scope.js';
 import { declaring, deprecatedOnMethod, refuse } from '../util/refusal.util.js';
-import { timeoutProblem } from '../util/timer-limit.util.js';
+import { timeoutProblem, timerKeepsSeconds, MAX_TIMER_SECONDS } from '../util/timer-limit.util.js';
+import { Logger } from '../common/logger.js';
 import { isConstructor, describeValue } from '../util/value.util.js';
 import { META } from '../util/metadata-keys.js';
 
+const logger = new Logger('MeoCord');
 /** Refuses a `messages` option of the wrong type where the app is declared, rather than at the first message. */ function assertMessageOptions(appName, messages, i18n) {
     if (!messages) return;
     const { prefix, mention, caseSensitive } = messages;
@@ -39,6 +41,9 @@ import { META } from '../util/metadata-keys.js';
     if (deleteUsageRepliesAfter !== undefined && !(typeof deleteUsageRepliesAfter === 'number' && deleteUsageRepliesAfter >= 0 && Number.isFinite(deleteUsageRepliesAfter))) {
         throw refuse(new TypeError(`${appName}: @MeoCord({ messages: { deleteUsageRepliesAfter } }) takes a number of seconds, or 0 to keep usage replies.`));
     }
+    if (deleteUsageRepliesAfter !== undefined && !timerKeepsSeconds(deleteUsageRepliesAfter)) {
+        logger.warn(`${appName}: @MeoCord({ messages: { deleteUsageRepliesAfter } }) is ${deleteUsageRepliesAfter} seconds, longer than a timer ` + `can wait (${MAX_TIMER_SECONDS}), so usage replies are kept. The next major version (5.0) refuses it.`);
+    }
     const { help } = messages;
     // One word each, since help is asked for by its first word
     const isWord = (value)=>typeof value === 'string' && /^\S+$/.test(value);

package/dist/esm/decorator/command-builder.decorator.js

@@ -2,7 +2,15 @@ import 'reflect-metadata';
 import { makeInjectable } from '../util/injectable.util.js';
 import { META } from '../util/metadata-keys.js';
 import { declaring, deprecatedOnMethod } from '../util/refusal.util.js';
+import { Logger } from '../common/logger.js';
 
+const logger = new Logger('CommandBuilder');
+/** The nearest base class of `target` that gives `guilds`, which `target` inherits when it gives none. */ function guildsBase(target) {
+    for(let base = Object.getPrototypeOf(target); base && base !== Function.prototype; base = Object.getPrototypeOf(base)){
+        if (Reflect.hasOwnMetadata(META.builderGuilds, base)) return base;
+    }
+    return undefined;
+}
 /**
  * Marks a class as a command's builder, which describes the command MeoCord registers with Discord.
  *
@@ -40,6 +48,12 @@ import { declaring, deprecatedOnMethod } from '../util/refusal.util.js';
         if (options.guilds) Reflect.defineMetadata(META.builderGuilds, [
             ...options.guilds
         ], target);
+        else {
+            const base = guildsBase(target);
+            if (base) {
+                logger.warn(`${target.name} gives no guilds and inherits ${base.name}'s; declare guilds on ${target.name} to keep them. ` + 'The next major version (5.0) registers it in the configured scope.');
+            }
+        }
     });
 }