chapterjs 0.4.0 → 0.5.0

package/dist/components/button.d.ts

@@ -31,8 +31,12 @@ export interface ButtonLook<Data extends DataShape = DataShape> {
 export type ButtonContext<Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> = InteractiveContext<Data> & TranslationContext & PlaceOf<Where, ComponentInteraction>;
 /** What a file gives to `button()`. */
 export interface ButtonConfig<Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> extends ButtonLook<Data>, InteractiveConfig<Data, Where> {
-    /** What to do when someone clicks the button. */
-    run: (context: ButtonContext<Data, Where>) => unknown;
+    /**
+     * What to do when someone clicks the button. Leave it out for a button
+     * that is only waited for (`message.waitForClick()`): once nothing waits,
+     * a click answers that it is not available any more.
+     */
+    run?: (context: ButtonContext<Data, Where>) => unknown;
 }
 /**
  * What `button()` returns: a declaration the framework finds in the exports
@@ -71,7 +75,8 @@ export interface LoadedButton {
     readonly where: ComponentWhere;
     readonly who: 'everyone' | 'author';
     readonly ephemeral: boolean;
-    readonly run: (context: ButtonContext<DataShape, ComponentWhere>) => unknown;
+    /** `undefined` for a button that is only waited for. */
+    readonly run: ((context: ButtonContext<DataShape, ComponentWhere>) => unknown) | undefined;
 }
 /** Checks what a message gives to change the look of a button. */
 export declare function readLook(what: string, look: unknown): ButtonLook;

package/dist/components/declaration.d.ts

@@ -1,4 +1,4 @@
-import type { Declaration } from '../loader/loader.js';
+import { type Declaration } from '../loader/loader.js';
 import { type LoadedButton } from './button.js';
 import { isEmbedDeclaration } from './embed.js';
 import { type ComponentKind } from './declared.js';
@@ -29,7 +29,7 @@ export declare function findDuplicates<T extends {
         kind: ComponentKind;
         name: string;
     };
-}>(entries: readonly T[]): {
+}>(entries: readonly T[], running?: ReadonlySet<string>): {
     valid: T[];
     conflicts: {
         file: string;

package/dist/components/declaration.js

@@ -4,6 +4,7 @@
 // bound to the name of its export, which is its id and what makes its
 // instances.
 import { Limits } from '../discord/api.js';
+import { bySite } from '../loader/loader.js';
 import { checkEmbed } from '../structures/payload.js';
 import { isDynamic } from './component.js';
 import { readLook, renderButton, } from './button.js';
@@ -93,6 +94,17 @@ function checkRun(what, value, example) {
         fail(`${what} has no "run": the function to run when someone uses it, like ${example}`);
     }
 }
+/**
+ * The `run` of a button or a menu: optional, since one may only be waited
+ * for (`message.waitForClick()`); when given, a function.
+ */
+function checkOptionalRun(what, value, example) {
+    if (value === undefined)
+        return;
+    if (typeof value !== 'function') {
+        fail(`"run" of ${what} is the function to run when someone uses it, like ${example}. Leave it out for one that is only waited for with message.waitForClick().`);
+    }
+}
 function readButton(name, config) {
     if (!isRecord(config)) {
         return fail(`button() needs an object: button({ label: '...', run({ interaction }) { ... } })`);
@@ -118,7 +130,7 @@ function readButton(name, config) {
     if (look.label === undefined && look.emoji === undefined) {
         fail('A button needs a label or an emoji.');
     }
-    checkRun(what, config.run, `async run({ interaction }) { await interaction.update('Done!'); }`);
+    checkOptionalRun(what, config.run, `async run({ interaction }) { await interaction.update('Done!'); }`);
     return Object.freeze({
         kind: 'button',
         name,
@@ -168,7 +180,7 @@ function readSelect(name, config) {
     }
     const options = type === 'string' ? readOptions(what, config.options) : [];
     const placeholder = readPlaceholder(what, config.placeholder);
-    checkRun(what, config.run, `async run({ interaction, values }) { ... }`);
+    checkOptionalRun(what, config.run, `async run({ interaction, values }) { ... }`);
     return Object.freeze({
         kind: 'select',
         name,
@@ -310,18 +322,10 @@ export const componentDeclaration = {
     },
 };
 /** Two components of the same kind with the same name: the later one is left out. */
-export function findDuplicates(entries) {
+export function findDuplicates(entries, running) {
     const seen = new Map();
     const conflicts = [];
-    const valid = [...entries]
-        .sort((a, b) => a.file === b.file
-        ? a.export < b.export
-            ? -1
-            : 1
-        : a.file < b.file
-            ? -1
-            : 1)
-        .filter(entry => {
+    const valid = bySite(entries, running).filter(entry => {
         const key = `${entry.component.kind}:${entry.component.name}`;
         const first = seen.get(key);
         if (!first) {

package/dist/components/render.js

@@ -46,6 +46,11 @@ export function renderComponents(components, t = missingTranslator(null)) {
     const v2 = rows.some(one => one.kind !== 'row');
     // The texts of a piece may be computed now, for who will read the message.
     const raw = rows.map(one => resolve(one, t).raw);
+    // Without the pieces of the new layout, a message is rows only, and
+    // Discord takes 5 of them.
+    if (!v2 && raw.length > Limits.MessageActionRows) {
+        throw new RangeError(`The message has ${raw.length} rows of components: Discord accepts ${Limits.MessageActionRows} at most. A menu takes a row by itself and up to 5 buttons share one: send the rest in another message.`);
+    }
     const total = count(raw);
     if (total > Limits.MessageComponents) {
         throw new RangeError(`The message has ${total} components once its rows are made: Discord accepts ${Limits.MessageComponents} at most.`);

package/dist/components/router.js

@@ -10,6 +10,7 @@ import { ComponentInteraction, ModalInteraction, } from '../structures/interacti
 import { remember } from '../structures/known.js';
 import { toCamelCase } from '../util/case.js';
 import { decodeCustomId, readData } from './custom-id.js';
+import { componentStateOf } from './declared.js';
 import { SELECT_TYPES } from './select.js';
 /** What a component is called, for the person and the developer. */
 const WHAT_OF = {
@@ -130,6 +131,32 @@ export class ComponentRouter {
             this.#options.onError(file, error);
             return refuse(interaction, 'failed', { what });
         }
+        // A click a function of the files waits for (`message.waitForClick()`)
+        // is theirs: the `run` of the component does not run.
+        if (component.kind !== 'modal' && ctx.waiters?.wants('click')) {
+            const click = Object.freeze({
+                messageId: message.id,
+                interaction: interaction,
+                user,
+                member: place.member ?? null,
+                name,
+                data: Object.freeze(values),
+                values: Object.freeze([
+                    ...(data.values ?? []),
+                ]),
+                is: (declared) => {
+                    const state = componentStateOf(declared);
+                    return state?.kind === component.kind && state.bound?.name === name;
+                },
+            });
+            if (ctx.waiters.offer('click', click)) {
+                return this.#waited(interaction);
+            }
+        }
+        if (!component.run) {
+            // Only waited for, and nothing waits any more.
+            return refuse(interaction, 'gone', { what });
+        }
         const context = Object.freeze({
             interaction,
             user,
@@ -160,6 +187,20 @@ export class ComponentRouter {
             run: () => component.run(context),
         });
     }
+    /**
+     * A click taken by a wait: the files answer it where they waited. When
+     * they did not after 2 seconds, nothing changes on screen
+     * (`deferUpdate()`), so the person never sees "This interaction failed".
+     */
+    #waited(interaction) {
+        const timer = setTimeout(() => {
+            if (!interaction.answered && !interaction.deferred) {
+                interaction.deferUpdate().catch(() => { });
+            }
+        }, this.#options.deferAfter ?? 2000);
+        timer.unref();
+        return Promise.resolve();
+    }
     /** What the person picked in a menu, as structures where it applies. */
     #readValues(ctx, raw, type, data) {
         const values = resolveValues(ctx, raw, type, data.values ?? [], data.resolved ?? {});

package/dist/components/select.d.ts

@@ -67,8 +67,11 @@ export interface StringSelectConfig<Options extends SelectOptions, Data extends
      * shown to what your code receives, or a list of `RichOption`.
      */
     options: Options;
-    /** What to do when something is picked. */
-    run: (context: SelectContext<OptionValue<Options>, Data, Where>) => unknown;
+    /**
+     * What to do when something is picked. Leave it out for a menu that is
+     * only waited for (`message.waitForClick()`).
+     */
+    run?: (context: SelectContext<OptionValue<Options>, Data, Where>) => unknown;
 }
 /** A menu of users, roles, users and roles, or channels of the server. */
 export interface EntitySelectConfig<Type extends EntitySelectType, Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> extends SelectConfigBase<Data, Where> {
@@ -76,8 +79,11 @@ export interface EntitySelectConfig<Type extends EntitySelectType, Data extends
     type: Type;
     /** For a menu of channels: the kinds of channels listed. All by default. */
     channelTypes?: readonly ChannelType[];
-    /** What to do when something is picked. */
-    run: (context: SelectContext<EntityValues[Type], Data, Where>) => unknown;
+    /**
+     * What to do when something is picked. Leave it out for a menu that is
+     * only waited for (`message.waitForClick()`).
+     */
+    run?: (context: SelectContext<EntityValues[Type], Data, Where>) => unknown;
 }
 /** What a select file gives to `select()`: a menu of texts, or of things of the server. */
 export type SelectConfig<Options extends SelectOptions = SelectOptions, Type extends EntitySelectType = EntitySelectType, Data extends DataShape = {}, Where extends ComponentWhere = 'guild'> = StringSelectConfig<Options, Data, Where> | EntitySelectConfig<Type, Data, Where>;
@@ -126,7 +132,8 @@ export interface LoadedSelect {
     readonly where: ComponentWhere;
     readonly who: 'everyone' | 'author';
     readonly ephemeral: boolean;
-    readonly run: (context: SelectContext<unknown, DataShape, ComponentWhere>) => unknown;
+    /** `undefined` for a menu that is only waited for. */
+    readonly run: ((context: SelectContext<unknown, DataShape, ComponentWhere>) => unknown) | undefined;
 }
 /** Checks `min` and `max` of a menu, a group of checkboxes or a file upload. */
 export declare function readRange(what: string, given: {

package/dist/core/bot.d.ts

@@ -5,6 +5,7 @@ import { Gateway, type GatewayOptions } from '../gateway/gateway.js';
 import type { ShardEvent } from '../gateway/shard.js';
 import { type RestOptions } from '../rest/rest.js';
 import type { Context } from '../structures/context.js';
+import { type Waiters } from '../waiting/waiters.js';
 /** What a dispatched event is, besides its data. */
 export interface DispatchInfo {
     shardId: number;
@@ -71,11 +72,17 @@ export interface BotOptions {
      * (an outage of Discord). Default: 15000.
      */
     guildsTimeout?: number;
+    /**
+     * What the files wait for (`channel.waitForMessage()`...): in memory by
+     * default.
+     */
+    waiters?: Waiters;
     /** Only tests change these. */
     rest?: Partial<RestOptions>;
     gateway?: Pick<GatewayOptions, 'backoff' | 'identifyInterval'>;
     voice?: {
         secure?: boolean;
+        unavailable?: string;
     };
 }
 export interface Bot {

package/dist/core/bot.js

@@ -9,6 +9,34 @@ import { createContext } from '../structures/entities.js';
 import { GatewayOpcode } from '../discord/codes.js';
 import { GatewayIntent } from '../discord/intents.js';
 import { VoiceManager } from '../voice/connection.js';
+import { MemoryWaiters } from '../waiting/waiters.js';
+import { GetUser } from '../discord/endpoints.js';
+import { toCamelCase } from '../util/case.js';
+/**
+ * Gives a reaction to what waits for one, with who reacted: the member
+ * Discord sends in a server, else the user the bot knows, else asked.
+ * @see https://docs.discord.com/developers/events/gateway-events#message-reaction-add
+ */
+function offerReaction(ctx, data) {
+    const member = data.member && data.guild_id
+        ? ctx.entities.member(data.guild_id, data.member)
+        : null;
+    const known = member?.user ?? ctx.cache.users.get(data.user_id);
+    const user = known
+        ? Promise.resolve(known)
+        : ctx.rest
+            .request(GetUser, [data.user_id])
+            .then(raw => ctx.entities.user(raw));
+    user
+        .then(user => ctx.waiters?.offer('reaction', {
+        messageId: data.message_id,
+        emoji: toCamelCase(data.emoji),
+        user,
+        member,
+    }))
+        // Who reacted could not be known: nothing to give.
+        .catch(() => { });
+}
 /** The server a gateway event belongs to, when it belongs to one. */
 function guildIdOf(event, data) {
     if (typeof data !== 'object' || data === null)
@@ -38,6 +66,8 @@ export function createBot(options) {
         ...options.rest,
     });
     const ctx = createContext({ rest, cache: new Cache(options.cache) });
+    const waiters = options.waiters ?? new MemoryWaiters();
+    ctx.waiters = waiters;
     /** Servers announced by Ready whose data has not come yet, per shard. */
     const pending = new Map();
     let guildsReady = null;
@@ -129,6 +159,15 @@ export function createBot(options) {
             else if (event === 'VOICE_SERVER_UPDATE') {
                 voice.onVoiceServer(data);
             }
+            // What the files wait for: built only when a wait wants it.
+            if (event === 'MESSAGE_CREATE' && waiters.wants('message')) {
+                const message = data;
+                waiters.offer('message', ctx.entities.message(message));
+            }
+            else if (event === 'MESSAGE_REACTION_ADD' &&
+                waiters.wants('reaction')) {
+                offerReaction(ctx, data);
+            }
             options.onDispatch?.(event, data, { shardId, joined, before });
             if (awaited)
                 checkGuilds();
@@ -143,6 +182,9 @@ export function createBot(options) {
         ...(options.voice?.secure === undefined
             ? {}
             : { secure: options.voice.secure }),
+        ...(options.voice?.unavailable === undefined
+            ? {}
+            : { unavailable: options.voice.unavailable }),
     });
     ctx.voice = voice;
     return {
@@ -167,6 +209,8 @@ export function createBot(options) {
                 clearTimeout(guildsTimer);
             guildsTimer = null;
             voice.closeAll();
+            // What the files waited for will not come: they go on with nothing.
+            waiters.close();
             await gateway.close();
         },
         setPresence: presence => gateway.setPresence(presence),

package/dist/discord/api.d.ts

@@ -74,6 +74,8 @@ export declare const Limits: {
     readonly CustomId: 100;
     /** @see https://docs.discord.com/developers/components/reference#component-object */
     readonly MessageComponents: 40;
+    /** @see https://docs.discord.com/developers/components/reference#legacy-message-component-behavior */
+    readonly MessageActionRows: 5;
     /** @see https://docs.discord.com/developers/components/reference#action-row */
     readonly ActionRowButtons: 5;
     /** @see https://docs.discord.com/developers/components/reference#button-button-structure */

package/dist/discord/api.js

@@ -77,6 +77,8 @@ export const Limits = {
     CustomId: 100,
     /** @see https://docs.discord.com/developers/components/reference#component-object */
     MessageComponents: 40,
+    /** @see https://docs.discord.com/developers/components/reference#legacy-message-component-behavior */
+    MessageActionRows: 5,
     /** @see https://docs.discord.com/developers/components/reference#action-row */
     ActionRowButtons: 5,
     /** @see https://docs.discord.com/developers/components/reference#button-button-structure */

package/dist/discord/permissions.d.ts

@@ -12,11 +12,11 @@ export declare const ALL_PERMISSIONS: bigint;
  */
 export declare const ELEVATED_PERMISSIONS: readonly PermissionName[];
 /**
- * A set of permissions that never changes: every operation returns a new
- * set. Discord serializes permissions as text because they don't fit in a
- * regular number.
- * @see https://docs.discord.com/developers/topics/permissions
+ * A permission as people read it: `BanMembers` is "Ban Members". For what
+ * the bot says to the people of a server, never to the developer, who
+ * writes the names as they are.
  */
+export declare function permissionWords(name: PermissionName): string;
 export declare class Permissions {
     /** The permissions as one number, each bit being a permission. */
     readonly bits: bigint;

package/dist/discord/permissions.js

@@ -42,6 +42,19 @@ function resolve(permission) {
  * regular number.
  * @see https://docs.discord.com/developers/topics/permissions
  */
+/** Letters that are said one by one in the name of a permission. */
+const ACRONYMS = { Tts: 'TTS', Vad: 'VAD' };
+/**
+ * A permission as people read it: `BanMembers` is "Ban Members". For what
+ * the bot says to the people of a server, never to the developer, who
+ * writes the names as they are.
+ */
+export function permissionWords(name) {
+    return name
+        .split(/(?=[A-Z])/)
+        .map(word => ACRONYMS[word] ?? word)
+        .join(' ');
+}
 export class Permissions {
     /** The permissions as one number, each bit being a permission. */
     bits;

package/dist/events/registry.d.ts

@@ -1,7 +1,7 @@
 import type { CacheLimits } from '../cache/cache.js';
 import type { Snowflake } from '../discord/types/common.js';
 import type { GatewayDispatchEventName, GatewayDispatchEvents } from '../discord/types/gateway-events.js';
-import type { Channel, DMChannel, GuildChannel, GuildTextBasedChannel, TextBasedChannel, ThreadChannel, VoiceChannel } from '../structures/channel.js';
+import type { DMChannel, GuildChannel, GuildTextBasedChannel, TextBasedChannel, ThreadChannel, VoiceChannel } from '../structures/channel.js';
 import type { Context } from '../structures/context.js';
 import type { GuildEmoji } from '../structures/emoji.js';
 import type { AuditLogEntry, Guild, ScheduledEvent, VoiceState } from '../structures/guild.js';
@@ -220,23 +220,32 @@ export interface EventContexts {
     /** A channel was created. */
     channelCreate: {
         /** The new channel or thread. */
-        channel: GuildChannel | ThreadChannel | Channel;
-        /** The server of the channel; `null` for a private conversation. */
-        guild: Guild | null;
+        channel: GuildChannel | ThreadChannel;
+        /**
+         * The server of the channel: Discord only sends these events, with the
+         * Guilds intent, for the channels of a server.
+         */
+        guild: Guild;
     };
     /** A channel changed: name, topic, permissions... */
     channelUpdate: {
         /** The channel or thread, as it is now. */
-        channel: GuildChannel | ThreadChannel | Channel;
-        /** The server of the channel; `null` for a private conversation. */
-        guild: Guild | null;
+        channel: GuildChannel | ThreadChannel;
+        /**
+         * The server of the channel: Discord only sends these events, with the
+         * Guilds intent, for the channels of a server.
+         */
+        guild: Guild;
     };
     /** A channel was deleted. */
     channelDelete: {
         /** The channel or thread as it was. */
-        channel: GuildChannel | ThreadChannel | Channel;
-        /** The server of the channel; `null` for a private conversation. */
-        guild: Guild | null;
+        channel: GuildChannel | ThreadChannel;
+        /**
+         * The server of the channel: Discord only sends these events, with the
+         * Guilds intent, for the channels of a server.
+         */
+        guild: Guild;
     };
     /** A role was created. */
     roleCreate: {

package/dist/events/registry.js

@@ -15,16 +15,22 @@ const ofGuild = ({ guild }) => guild;
 const channel = (on) => ({
     on,
     build: (ctx, data) => {
+        // A server's channel only: what the types promise.
         const found = ctx.cache.channels.get(data.id);
-        return found ? { channel: found, guild: found.guild } : null;
+        return found?.isGuildChannel() || found?.isThread()
+            ? { channel: found, guild: found.guild }
+            : null;
     },
 });
 const deletedChannel = (on) => ({
     on,
     before: (ctx, data) => ctx.cache.channels.get(data.id) ?? null,
-    build: (_ctx, _data, { before }) => before
-        ? { channel: before, guild: before.guild }
-        : null,
+    build: (_ctx, _data, { before }) => {
+        const channel = before;
+        return channel?.isGuildChannel() || channel?.isThread()
+            ? { channel, guild: channel.guild }
+            : null;
+    },
 });
 /**
  * Discord refused what an event needs before it can be given to its files:

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { command } from './commands/command.js';
-export type { AutocompleteContext, ChannelOption, CommandAutocomplete, CommandConfig, CommandContext, CommandInDm, CommandInGuild, CommandInPrivate, CommandWhere, CommandDeclaration, CommandLocales, CommandName, CommandOption, CommandOptions, CommandTranslation, Cooldown, Duration, NumberOption, OptionsSoFar, OptionTranslation, OptionValuesOf, SimpleOption, StringOption, Suggestion, } from './commands/command.js';
+export type { AutocompleteContext, ChannelOption, CommandAutocomplete, CommandConfig, CommandContext, CommandInDm, CommandInGuild, CommandInPrivate, CommandWhere, CommandDeclaration, CommandLocales, CommandName, CommandOption, CommandOptions, CommandTranslation, Cooldown, MenuConfig, MenuContext, MenuDeclaration, MenuLocales, MenuTranslation, MenuType, Duration, NumberOption, OptionsSoFar, OptionTranslation, OptionValuesOf, SimpleOption, StringOption, Suggestion, } from './commands/command.js';
 export type { CommandInteraction, ComponentInteraction, DmCommandInteraction, GuildCommandInteraction, PrivateCommandInteraction, Interaction, InteractionReply, InteractionReplyOptions, ModalInteraction, } from './structures/interaction.js';
 export type { DynamicText, TextContext } from './components/component.js';
 export { button } from './components/button.js';
@@ -25,10 +25,11 @@ export type { AuditLog, AuditLogEntry, AutoModerationRule, Ban, ChannelCreateOpt
 export type { Invite } from './structures/invite.js';
 export type { BanOptions, GuildMember, MemberEditOptions, } from './structures/member.js';
 export type { Attachment, EmojiInput, DmMessage, GuildMessage, MemberMessage, Message, PrivateMessage, MessageFlagName, Reaction, ReactionEmoji, } from './structures/message.js';
+export type { Click, CollectMessagesOptions, PersonInput, WaitedReaction, WaitForClickOptions, WaitForMessageOptions, WaitForReactionOptions, } from './structures/wait.js';
 export { language } from './messages/messages.js';
 export type { CommandsTranslations, FrameworkTexts, LanguageConfig, LanguageDeclaration, MergedMessages, MessagesOf, MessageText, MessageTexts, PluralText, ProjectCommands, ProjectLanguageDefaults, ParamsArgs, ParamsOf, Placeholders, ProjectLocale, ProjectLocales, LocaleGiven, ProjectMessages, TranslationContext, Translator, } from './messages/messages.js';
 export { presence } from './presence/presence.js';
-export type { Activity, ActivityKind, PlainActivity, PresenceConfig, PresenceDeclaration, PresenceStatusName, StreamingActivity, } from './presence/presence.js';
+export type { Activities, Activity, ActivityKind, ActivityText, PlainActivity, PresenceConfig, PresenceContext, PresenceDeclaration, PresenceStatusName, RotatingPresenceConfig, SinglePresenceConfig, StreamingActivity, } from './presence/presence.js';
 export { store } from './store/store.js';
 export type { ScopedStore, Store, StoreConfig, StoreEntry, StoreKey, StoreScope, StoreSetOptions, StoreStorage, } from './store/store.js';
 export { ranking } from './ranking/ranking.js';

package/dist/index.js

@@ -9,7 +9,7 @@
 // (in events, commands...) and never creates them: classes are exported as
 // types only, and nothing here lets user code connect to Discord or send
 // requests by itself.
-// Slash commands: what the files of src/commands/ are written with.
+// Commands (slash and menu): what the files of src/commands/ are written with.
 export { command } from './commands/command.js';
 export { button } from './components/button.js';
 export { select } from './components/select.js';

package/dist/interactions/dispatch.js

@@ -8,7 +8,7 @@ import { setTimeout as sleep } from 'node:timers/promises';
 import { phrase } from '../messages/phrases.js';
 import { DiscordApiError } from '../rest/errors.js';
 import { ctxOf } from '../structures/base.js';
-import { isUpdating } from '../structures/interaction.js';
+import { answersSent, isUpdating, } from '../structures/interaction.js';
 /** Who did it, as Discord sent it: the member in a server, the user elsewhere. */
 export function authorOf(raw) {
     const user = raw.member?.user ?? raw.user;
@@ -87,7 +87,9 @@ export function runInteraction(options) {
         .then(() => options.defer())
         .catch(() => { });
     return new Promise(resolve => resolve(withGuild(options.guildId, options.run)))
-        .then(() => {
+        .then(async () => {
+        // An answer asked without await is on its way: not a missing one.
+        await answersSent(interaction);
         if (!interaction.answered) {
             reporter.onWarning(file, `${name} ${options.unanswered}`);
         }

package/dist/loader/loader.d.ts

@@ -50,6 +50,22 @@ export declare const siteName: (site: {
     file: string;
     export?: string;
 }) => string;
+/** What tells one export of the project from another: `src/a.ts#ban`. */
+export declare const siteKey: (site: {
+    file: string;
+    export: string;
+}) => string;
+/**
+ * The order in which declarations that can't both be kept (two with one
+ * name) are read, the first one winning: what already ran first (`running`,
+ * the `siteKey`s of the declarations of the last load), so that a file saved
+ * in dev never takes its name from one that works, then by file and export,
+ * so that the choice never depends on the order the files were found in.
+ */
+export declare function bySite<T extends {
+    file: string;
+    export: string;
+}>(entries: readonly T[], running?: ReadonlySet<string>): T[];
 /** A file of the project, found but not run. */
 export interface FoundFile {
     /** The path from the project folder, with `/`: `src/ping.ts`. */

package/dist/loader/loader.js

@@ -11,6 +11,28 @@ import { importFile } from './hot.js';
 export const siteName = (site) => site.export === undefined || site.export === 'default'
     ? site.file
     : `${site.file} (${site.export})`;
+/** What tells one export of the project from another: `src/a.ts#ban`. */
+export const siteKey = (site) => `${site.file}#${site.export}`;
+/**
+ * The order in which declarations that can't both be kept (two with one
+ * name) are read, the first one winning: what already ran first (`running`,
+ * the `siteKey`s of the declarations of the last load), so that a file saved
+ * in dev never takes its name from one that works, then by file and export,
+ * so that the choice never depends on the order the files were found in.
+ */
+export function bySite(entries, running = new Set()) {
+    const before = (entry) => (running.has(siteKey(entry)) ? 0 : 1);
+    return [...entries].sort((a, b) => before(a) - before(b) ||
+        (a.file === b.file
+            ? a.export < b.export
+                ? -1
+                : a.export > b.export
+                    ? 1
+                    : 0
+            : a.file < b.file
+                ? -1
+                : 1));
+}
 const SOURCE = /\.(?:ts|mts|js|mjs)$/;
 const DECLARATION = /\.d\.m?ts$/;
 /** Tests next to the code: they are for a test runner, not for the bot. */
@@ -68,7 +90,7 @@ export async function loadFiles(files) {
             result.modules.push({ file, exports: await importFile(path) });
         }
         catch (error) {
-            result.failed.push({ file, error });
+            result.failed.push({ file, error: readable(error) });
         }
     }));
     const byFile = (a, b) => a.file < b.file ? -1 : 1;
@@ -76,6 +98,19 @@ export async function loadFiles(files) {
     result.failed.sort(byFile);
     return result;
 }
+/**
+ * A file Node can't read as TypeScript gets the words of its parser
+ * ("Expected ',', got ';'"): what they mean is said after them. The error
+ * is the same, so its line is still found.
+ */
+function readable(error) {
+    if (error instanceof SyntaxError &&
+        error.code === 'ERR_INVALID_TYPESCRIPT_SYNTAX' &&
+        !error.message.includes('This line can not be read')) {
+        error.message = `${error.message.replace(/\.?$/, '.')} This line can not be read: look for a bracket, a comma or a quote missing or in excess, here or just before.`;
+    }
+    return error;
+}
 /** The name of a file, without its folders and its extension. */
 const baseName = (file) => file
     .split('/')
@@ -103,22 +138,32 @@ export function readDeclarations(modules, declaration) {
             export: exported,
             name: exported === 'default' ? baseName(file) : exported,
         };
-        const read = (one) => {
+        const read = (one, at) => {
             if (seen.has(one))
                 return;
             seen.add(one);
-            result.loaded.push({ ...site, value: declaration.read(one, site) });
+            result.loaded.push({ ...at, value: declaration.read(one, at) });
         };
         try {
             if (declaration.is(value))
-                read(value);
+                read(value, site);
             else if (Array.isArray(value) && value.some(declaration.is)) {
                 if (!declaration.list) {
                     throw new TypeError(`This export is a list with a ${declaration.one} in it: export each ${declaration.one} on its own (export const ${site.name} = ...), its name is the name of its export.`);
                 }
-                for (const one of value)
-                    if (declaration.is(one))
-                        read(one);
+                // Each one of the list is told apart by its place in it (`events[2]`),
+                // and read on its own: one that is wrong leaves the others running.
+                value.forEach((one, index) => {
+                    if (!declaration.is(one))
+                        return;
+                    const at = { ...site, export: `${exported}[${index}]` };
+                    try {
+                        read(one, at);
+                    }
+                    catch (error) {
+                        result.failed.push({ file, export: at.export, error });
+                    }
+                });
             }
         }
         catch (error) {