rpg-engine 0.0.0-stage → 0.1.0

package/dist/core/length.js

@@ -0,0 +1,49 @@
+// Lengths and speeds (D-262, ROA-1, TRV-1): always written in metric and read in metres; told in the units of the story, imperial with the game's factors.
+/** The units of measure of the story (D-33). */
+export const unitSystems = ["metric", "imperial"];
+export const trueImperialUnits = { mile: 1609.344, foot: 0.3048 };
+/** How to write a length, for messages. */
+export const lengthHelp = "in km or m, such as 8 km, 1.5 km or 500 m: the engine keeps every measure in metric, and its outputs give them in the player's units";
+/** How to write a speed, for messages. */
+export const speedHelp = "the distance of an hour in metric, such as 4.5 km or 4.5 km/h";
+const metresIn = { km: 1000, m: 1 };
+const lengthPattern = /^(\d+(?:\.\d+)?)\s*([a-z]+)$/i;
+/** A length in metres from a number and its metric unit, such as 8 km, 1.5 km or 500 m; undefined for anything else, miles, a number without a unit and 0 among them. */
+export function readLength(value) {
+    const match = typeof value === "string" ? lengthPattern.exec(value.trim()) : null;
+    const unit = match === null ? undefined : metresIn[match[2].toLowerCase()];
+    const metres = match === null || unit === undefined ? 0 : Number(match[1]) * unit;
+    return metres > 0 ? metres : undefined;
+}
+/** A speed in metres an hour (TRV-1): the distance of an hour, with or without /h, such as 4.5 km or 4.5 km/h; undefined for anything else. */
+export function readSpeed(value) {
+    return readLength(typeof value === "string" ? value.trim().replace(/\s*\/\s*h$/i, "") : undefined);
+}
+/** A length in the units of the story, with one decimal at most: 12 km, 800 m; in imperial with the game's units, 8 miles, 300 feet. */
+export function formatLength(metres, units, imperial = trueImperialUnits) {
+    if (units === "imperial") {
+        const miles = oneDecimal(metres / imperial.mile);
+        return miles >= 1 ? `${miles} ${miles === 1 ? "mile" : "miles"}` : `${Math.round(metres / imperial.foot)} feet`;
+    }
+    return metres >= 999.5 ? `${oneDecimal(metres / 1000)} km` : `${Math.round(metres)} m`;
+}
+/** A speed in the units of the story: 4.5 km an hour, 3 miles an hour. */
+export function formatSpeed(metresAnHour, units, imperial = trueImperialUnits) {
+    return `${formatLength(metresAnHour, units, imperial)} an hour`;
+}
+/** A short length, as on the map of a place (GRD-5), in the units of the story: 7.5 m; in imperial with the game's foot, 25 feet. */
+export function formatStep(metres, units, imperial = trueImperialUnits) {
+    return units === "imperial" ? `${Math.round(metres / imperial.foot)} feet` : `${oneDecimal(metres)} m`;
+}
+/** A text with the lengths it writes in feet told in the units of the story, as a speed of the sheet (D-328): 30 ft., fly 60 ft. is 9 m, fly 18 m in metric. */
+export function lengthsInUnits(text, units, imperial = trueImperialUnits) {
+    return units === "imperial" ? text : text.replace(/(\d+(?:\.\d+)?)\s*(?:ft\.?|feet|foot)(?![a-z])/gi, (_, number) => formatStep(Number(number) * imperial.foot, units, imperial));
+}
+/** The first length a text gives, in metres, as a sheet writes a speed: 30 ft., 30 feet, 9 m; undefined when it gives none, or a number without its unit. */
+export function readFirstLength(value, imperial = trueImperialUnits) {
+    const match = typeof value === "string" ? /(\d+(?:\.\d+)?)\s*(ft|feet|foot|m)(?![a-z])/i.exec(value) : null;
+    return match === null ? undefined : Number(match[1]) * (match[2].toLowerCase() === "m" ? 1 : imperial.foot);
+}
+function oneDecimal(value) {
+    return Math.round(value * 10) / 10;
+}

package/dist/core/log.d.ts

@@ -0,0 +1,27 @@
+import type { Context } from "./context.ts";
+import type { Problem } from "./problem.ts";
+/** One line of the campaign's log: something that changed in the game. */
+export interface LogEntry {
+    id: string;
+    /** Real time, ISO 8601. */
+    at: string;
+    /** The game date, such as day 2, 14:10, once the game has one. */
+    date?: string;
+    type: string;
+    /** Who acted: the master, the player or a companion. */
+    by: string;
+    /** Public lines are what the player may see; hidden ones are for the master only. */
+    visibility: "public" | "hidden";
+    data: Record<string, unknown>;
+}
+/** The log of a campaign, at its top. */
+export declare const logFileName = "log.jsonl";
+/** A new line for the log, stamped with a new id, the real time, the game date when there is one, and who acts. */
+export declare function newLogEntry(context: Context, type: string, visibility: LogEntry["visibility"], data: Record<string, unknown>, date?: string): LogEntry;
+export declare function appendLogEntry(folder: string, entry: LogEntry): void;
+/** An entry as the log writes it: one line of JSON. */
+export declare function logLine(entry: LogEntry): string;
+/** The entries of the log; lines that are not entries, such as lines edited by hand, are left out: checkLog reports them. */
+export declare function readLog(folder: string): LogEntry[];
+/** The lines of the log that are not log entries, such as lines edited by hand. */
+export declare function checkLog(folder: string): Problem[];

package/dist/core/log.js

@@ -0,0 +1,38 @@
+import { join } from "node:path";
+import { files } from "./store.js";
+/** The log of a campaign, at its top. */
+export const logFileName = "log.jsonl";
+/** A new line for the log, stamped with a new id, the real time, the game date when there is one, and who acts. */
+export function newLogEntry(context, type, visibility, data, date) {
+    return { id: context.newId(), at: context.now().toISOString(), date, type, by: context.actor, visibility, data };
+}
+export function appendLogEntry(folder, entry) {
+    files().append(join(folder, logFileName), logLine(entry));
+}
+/** An entry as the log writes it: one line of JSON. */
+export function logLine(entry) {
+    return JSON.stringify(entry) + "\n";
+}
+/** The entries of the log; lines that are not entries, such as lines edited by hand, are left out: checkLog reports them. */
+export function readLog(folder) {
+    return logLines(folder).flatMap((read) => (read !== undefined && "entry" in read ? [read.entry] : []));
+}
+/** The lines of the log that are not log entries, such as lines edited by hand. */
+export function checkLog(folder) {
+    return logLines(folder).flatMap((read, index) => read === undefined || "entry" in read ? [] : [{ path: logFileName, message: `line ${index + 1} ${read.problem}.`, fix: "repair or remove that line by hand" }]);
+}
+/** Each line of the log, read once in a call: its entry, what keeps it from being one, or nothing for an empty line. */
+function logLines(folder) {
+    return files().read(join(folder, logFileName), "log", (text) => text.split("\n").map((line) => (line.trim() === "" ? undefined : readEntry(line)))) ?? [];
+}
+/** A line of the log read once: the entry, or what keeps it from being one. */
+function readEntry(line) {
+    try {
+        const entry = JSON.parse(line);
+        const hasData = typeof entry.data === "object" && entry.data !== null && !Array.isArray(entry.data);
+        return typeof entry.id === "string" && typeof entry.type === "string" && typeof entry.at === "string" && hasData ? { entry: entry } : { problem: "is not an entry: it needs id, at, type and data" };
+    }
+    catch {
+        return { problem: "is not valid JSON" };
+    }
+}

package/dist/core/memo.d.ts

@@ -0,0 +1,2 @@
+/** `compute` remembered for the texts it has seen, up to `limit` of them, after which they are all forgotten at once; what it gives is frozen. */
+export declare function rememberedByText<T>(compute: (text: string) => T, limit?: number): (text: string) => T;

package/dist/core/memo.js

@@ -0,0 +1,17 @@
+// Work repeated on the same texts, such as the names of the pages or the links of their text, done once while the server runs (step 11, D-194).
+import { frozen } from "./frozen.js";
+/** `compute` remembered for the texts it has seen, up to `limit` of them, after which they are all forgotten at once; what it gives is frozen. */
+export function rememberedByText(compute, limit = 50_000) {
+    const seen = new Map();
+    return (text) => {
+        if (seen.has(text)) {
+            return seen.get(text);
+        }
+        if (seen.size >= limit) {
+            seen.clear();
+        }
+        const value = frozen(compute(text));
+        seen.set(text, value);
+        return value;
+    };
+}

package/dist/core/mood.d.ts

@@ -0,0 +1,6 @@
+/** Every mood, the neutral one first. */
+export declare const moods: readonly ["neutral", "happy", "delighted", "curious", "focused", "determined", "worried", "surprised", "afraid", "sad", "angry", "disgusted", "mischievous"];
+export type Mood = (typeof moods)[number];
+export declare function isMood(value: unknown): value is Mood;
+/** The mood a value holds, as a page's field or state.yaml writes it; neutral for anything else. */
+export declare function readMood(value: unknown): Mood;

package/dist/core/mood.js

@@ -0,0 +1,11 @@
+// The moods of the master and of the characters (MOOD-1, D-305): one closed list for both, since the dashboard draws each; neutral is no mood at all.
+/** Every mood, the neutral one first. */
+export const moods = ["neutral", "happy", "delighted", "curious", "focused", "determined", "worried", "surprised", "afraid", "sad", "angry", "disgusted", "mischievous"];
+export function isMood(value) {
+    return typeof value === "string" && moods.includes(value);
+}
+/** The mood a value holds, as a page's field or state.yaml writes it; neutral for anything else. */
+export function readMood(value) {
+    const written = typeof value === "string" ? value.trim().toLowerCase() : value;
+    return isMood(written) ? written : "neutral";
+}

package/dist/core/problem.d.ts

@@ -0,0 +1,6 @@
+/** Something wrong in a campaign, the file it is in, and how to fix it. */
+export interface Problem {
+    path?: string;
+    message: string;
+    fix?: string;
+}

package/dist/core/problem.js

@@ -0,0 +1 @@
+export {};

package/dist/core/progression-rule.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The list whose items give the row of their page's table at their number, such as classes; the column of the features, the columns that give nothing, and the
+ * list of the pages that add features by level in the item they name in a field, such as subclasses with their class (D-219, PRO-1–PRO-3).
+ */
+export interface ProgressionRule {
+    list: string;
+    features: string;
+    skip: string[];
+    /** `lists`: the character's lists a part's page adds to by the level of its item, written as its features, such as a domain's spells always prepared (PRO-7). */
+    parts?: {
+        list: string;
+        field: string;
+        lists?: string[];
+    };
+    /** The field of the experience points, the table of the points each level needs, and the rule to read when they reach a new one (PRO-6). */
+    experience?: {
+        field: string;
+        table: string;
+        rules?: string;
+    };
+}

package/dist/core/progression-rule.js

@@ -0,0 +1,2 @@
+// How a game system says that the classes of a character give the rows of their tables (D-219): shared by the system that declares it and the world that reads it.
+export {};

package/dist/core/registry.d.ts

@@ -0,0 +1,31 @@
+import type { z } from "zod";
+import type { Context } from "./context.ts";
+/** A command is defined once: the command line, the MCP server and later the dashboard API are generated from it. */
+export interface Command<Schema extends z.ZodObject = z.ZodObject, Result = unknown> {
+    name: string;
+    /** Written for an AI: what the command does (the first sentence, shown in the list of commands), when to use it, an example. */
+    description: string;
+    /** Commands that set up the campaign, or that are used while playing. */
+    group: "campaign" | "game";
+    input: Schema;
+    /** The command changes nothing: hosts may run it without asking. */
+    readOnly?: boolean;
+    /** Hosts load the tool at once instead of on demand: for the ones the AI calls at the start of every chat. */
+    alwaysLoad?: boolean;
+    /** Fields the command line takes as positional arguments, in order. */
+    positionals?: string[];
+    /** The command asks the player directly: it exists only where the surface can (Context.player), never on the command line. */
+    needsPlayer?: boolean;
+    /** The command may take minutes, as an installation: the MCP server reports its progress meanwhile, so that a host does not give up on it. */
+    slow?: boolean;
+    run(input: z.infer<Schema>, context: Context): Result | Promise<Result>;
+    /** Plain-text rendering of the result. */
+    format(result: Result): string;
+}
+export declare function defineCommand<Schema extends z.ZodObject, Result>(command: Command<Schema, Result>): Command<Schema, Result>;
+/** Whether a field of a command's input is a flag, true or false, as --hidden. */
+export declare function isBoolean(field: z.ZodType): boolean;
+/** A list option can be given more than once, as in --set a=1 --set b=2; a field that also takes an object, through MCP, is a list here. */
+export declare function isList(field: z.ZodType): boolean;
+/** The type of a field of a command's input, past optional, default and nullable: string, boolean, array… */
+export declare function baseType(field: z.ZodType): string;

package/dist/core/registry.js

@@ -0,0 +1,25 @@
+import { FileStore, withFiles } from "./store.js";
+export function defineCommand(command) {
+    // Each call reads and writes through a store of its own, which reads each file once, or through the session's that the MCP server keeps (D-137).
+    return { ...command, run: (input, context) => withFiles(context.files ?? new FileStore(context.systemFolders), () => command.run(input, context)) };
+}
+/** Whether a field of a command's input is a flag, true or false, as --hidden. */
+export function isBoolean(field) {
+    return baseType(field) === "boolean";
+}
+/** A list option can be given more than once, as in --set a=1 --set b=2; a field that also takes an object, through MCP, is a list here. */
+export function isList(field) {
+    const definition = baseDefinition(field);
+    return definition.type === "array" || (definition.type === "union" && (definition.options ?? []).some(isList));
+}
+/** The type of a field of a command's input, past optional, default and nullable: string, boolean, array… */
+export function baseType(field) {
+    return baseDefinition(field).type;
+}
+function baseDefinition(field) {
+    let definition = field.def;
+    while (definition.innerType && ["optional", "default", "nullable"].includes(definition.type)) {
+        definition = definition.innerType.def;
+    }
+    return definition;
+}

package/dist/core/session-store.d.ts

@@ -0,0 +1,90 @@
+import { FileStore } from "./store.ts";
+/** Tells which names change in one folder, not in the folders inside it, and when it can no longer tell: Node's fs.watch, or a fake one in the tests. */
+export type WatchFolder = (folder: string, changed: (name: string | undefined) => void, failed: () => void) => {
+    close(): void;
+};
+/** A file of a campaign changed outside the session's own writes: by hand, by another chat or by the command line (OUT-1). */
+export interface OutsideChange {
+    path: string;
+    /** Its text as the session kept it; undefined for a new file. */
+    before?: string;
+    /** Its text now; undefined for a file gone. */
+    after?: string;
+}
+/** The files of a session of the MCP server, kept between calls and watched (D-193). */
+export declare class SessionStore extends FileStore {
+    private readonly watchers;
+    private readonly roots;
+    private readonly reported;
+    private readonly passing;
+    private readonly changeListeners;
+    private readonly systemFolders;
+    private readonly watchFolder;
+    private checking;
+    private checkAll;
+    private unwatchable;
+    private changes;
+    private wrote;
+    private readonly outside;
+    private beforeOutside;
+    /** `systemFolders` hold the game systems, kept for the whole session; `watchFolder` is Node's watcher, unless a test gives its own. */
+    constructor(options?: {
+        systemFolders?: string[];
+        watchFolder?: WatchFolder;
+    });
+    /** Starts watching a campaign, the first time a call finds it; what was kept of it before is read again. */
+    track(root: string): void;
+    /** Calls `listener` whenever a watcher sees a file of a campaign change, or loses track of one (D-272), until the function it returns is called. */
+    onChange(listener: () => void): () => void;
+    /** Calls `hook` before the session lets in changes made outside it, while what it kept is still as it was: the world before them can be read (OUT-3). */
+    beforeOutsideChanges(hook: () => void): void;
+    /** The files of the campaigns changed outside the session since this was last asked, with their text before and now; those back as they were are left out. */
+    takeOutsideChanges(): OutsideChange[];
+    /**
+     * Makes the store right for a call: forgets what lasts only for a call, lets the watchers' last events in and reads again the files they named; first it
+     * compares every file kept with the disk when `everything` is asked, as at instructions, when a watcher failed or could not start, or after too many
+     * changes. One full check runs at a time: a call that comes while one is under way waits for it.
+     */
+    ready(everything?: boolean): Promise<void>;
+    /**
+     * The text on the disk, before a write. A file kept with another text was changed by hand without the store knowing: what the command worked out from it no
+     * longer holds, so it stops before writing, and the next call checks everything (D-196).
+     */
+    fresh(path: string): string | undefined;
+    write(path: string, text: string): void;
+    append(path: string, text: string): void;
+    writeBytes(path: string, bytes: Uint8Array): void;
+    remove(path: string): void;
+    /** Stops watching, as the server closes. */
+    close(): void;
+    /** What a call keeps outside the campaigns watched and the game systems lasts for that call only. */
+    protected onKept(path: string): void;
+    /** Whether what is kept of a path lasts from a call to the next: a file of a campaign watched, or of a game system. */
+    private lasts;
+    /** A path as messages give it: inside a campaign, from its folder. */
+    private shownPath;
+    /** Forgets what lasts only for a call, such as a campaign.yaml not there yet, which another process may write: the next call reads it again. */
+    private forgetPassing;
+    /** Watches each folder of the campaigns that holds what is kept, those that came into it too; one that cannot be watched makes every call check everything. */
+    private watchFolders;
+    /** A change a watcher saw: a name in its folder; without one, or with its own folder's path as Windows gives it when the folder goes, it has lost track. */
+    private report;
+    /** A watcher that failed: it is closed, and everything is checked at the next call. */
+    private lose;
+    /**
+     * Whether what a watcher named changed outside the session (OUT-1): a file of a campaign kept with another text, or gone; or a new one, missing from the
+     * listing of a folder that holds it. The session's own writes are kept as they are written, so they never differ.
+     */
+    private isOutside;
+    /** Notes the files changed outside the session, with their text as it kept them; first who reads the world as it was, once for those that come together. */
+    private noteOutside;
+    /** A file changed outside that the session now writes: what changed outside is what the disk had before this write, never what the session writes. */
+    private freezeOutside;
+    /** What a watcher named: a file kept with another text, a new file or one gone; or a folder that came or went, read again and watched whole. */
+    private recheck;
+    /** Compares every file kept of the campaigns with the disk, lists their folders again, and watches the folders that came. */
+    private checkEverything;
+    /** Forgets what is kept under a path, the listings that may have held it, and what was built from it. `files` false keeps the files' texts. */
+    private forgetUnder;
+    private closeWatchersUnder;
+}

package/dist/core/session-store.js

@@ -0,0 +1,289 @@
+// The files as the MCP server keeps them for a whole session (D-137, D-193): what a call read of a campaign stays for the next ones, until a watcher says
+// that a file changed. At the start, at every instructions, and whenever a watcher fails or cannot start, a full check compares the text of every file kept
+// of the campaigns with the disk. The game systems stay as they were read: they do not change while the server runs. Anything else is read at every call.
+import { watch } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { filesIn, foldersIn } from "./files.js";
+import { FileStore, isInside, readText } from "./store.js";
+// The folders of a campaign below its own that hold what is kept: its pages, its house rules and its pictures. The campaign's folder holds its settings, state
+// and log.
+const watchedTrees = ["world", "rules", "images"];
+// More changes than this between two calls, and a watcher on Linux may have lost some without a word: inotify keeps 16384 by default, then drops the rest.
+const tooManyChanges = 10_000;
+/** The files of a session of the MCP server, kept between calls and watched (D-193). */
+export class SessionStore extends FileStore {
+    watchers = new Map();
+    roots = new Set();
+    reported = new Set();
+    passing = new Set();
+    changeListeners = new Set();
+    systemFolders;
+    watchFolder;
+    checking;
+    checkAll = false;
+    unwatchable = false;
+    changes = 0;
+    wrote = false;
+    // The files changed outside the session since they were last taken, each with its text before; and who reads the world before they are let in (OUT-1).
+    outside = new Map();
+    beforeOutside;
+    /** `systemFolders` hold the game systems, kept for the whole session; `watchFolder` is Node's watcher, unless a test gives its own. */
+    constructor(options = {}) {
+        super();
+        this.systemFolders = (options.systemFolders ?? []).map((folder) => resolve(folder));
+        this.watchFolder = options.watchFolder ?? watchWithNode;
+    }
+    /** Starts watching a campaign, the first time a call finds it; what was kept of it before is read again. */
+    track(root) {
+        const key = resolve(root);
+        if (this.roots.has(key)) {
+            return;
+        }
+        this.roots.add(key);
+        this.watchFolders(key);
+        this.forgetUnder(key);
+    }
+    /** Calls `listener` whenever a watcher sees a file of a campaign change, or loses track of one (D-272), until the function it returns is called. */
+    onChange(listener) {
+        this.changeListeners.add(listener);
+        return () => this.changeListeners.delete(listener);
+    }
+    /** Calls `hook` before the session lets in changes made outside it, while what it kept is still as it was: the world before them can be read (OUT-3). */
+    beforeOutsideChanges(hook) {
+        this.beforeOutside = hook;
+    }
+    /** The files of the campaigns changed outside the session since this was last asked, with their text before and now; those back as they were are left out. */
+    takeOutsideChanges() {
+        const taken = [...this.outside].map(([path, change]) => ({ path, before: change.before, after: change.after === undefined ? this.text(path) : change.after.text }));
+        this.outside.clear();
+        return taken.filter((change) => change.before !== change.after);
+    }
+    /**
+     * Makes the store right for a call: forgets what lasts only for a call, lets the watchers' last events in and reads again the files they named; first it
+     * compares every file kept with the disk when `everything` is asked, as at instructions, when a watcher failed or could not start, or after too many
+     * changes. One full check runs at a time: a call that comes while one is under way waits for it.
+     */
+    async ready(everything = false) {
+        await new Promise((done) => setImmediate(done));
+        this.wrote = false;
+        this.forgetPassing();
+        if (everything || this.checkAll || this.unwatchable || this.changes > tooManyChanges) {
+            this.checking ??= this.checkEverything().finally(() => (this.checking = undefined));
+        }
+        await this.checking;
+        const reported = [...this.reported].map((path) => ({ path, now: readNow(path) }));
+        this.reported.clear();
+        this.changes = 0;
+        this.noteOutside(reported.filter(({ path, now }) => this.isOutside(path, now)).map(({ path }) => path));
+        for (const { path, now } of reported) {
+            this.recheck(path, now);
+        }
+    }
+    /**
+     * The text on the disk, before a write. A file kept with another text was changed by hand without the store knowing: what the command worked out from it no
+     * longer holds, so it stops before writing, and the next call checks everything (D-196).
+     */
+    fresh(path) {
+        const now = readText(resolve(path));
+        if (now !== this.text(path)) {
+            this.changed(path, { text: now }, now !== undefined);
+            this.checkAll = true;
+            const name = this.shownPath(resolve(path));
+            throw new Error(this.wrote
+                ? `${name} was changed by hand since this call read it, so the command stopped before writing it, after other files: look at them again with status and validate, and finish by hand only what is missing.`
+                : `${name} was changed by hand since this call read it, so the command wrote nothing: look at it again, as with show or status, and repeat the command if it still fits.`);
+        }
+        return now;
+    }
+    write(path, text) {
+        this.freezeOutside(path);
+        super.write(path, text);
+        this.wrote = true;
+    }
+    append(path, text) {
+        this.freezeOutside(path);
+        super.append(path, text);
+        this.wrote = true;
+    }
+    writeBytes(path, bytes) {
+        this.freezeOutside(path);
+        super.writeBytes(path, bytes);
+        this.wrote = true;
+    }
+    remove(path) {
+        this.freezeOutside(path);
+        super.remove(path);
+        this.wrote = true;
+    }
+    /** Stops watching, as the server closes. */
+    close() {
+        for (const watcher of this.watchers.values()) {
+            watcher.close();
+        }
+        this.watchers.clear();
+    }
+    /** What a call keeps outside the campaigns watched and the game systems lasts for that call only. */
+    onKept(path) {
+        if (!this.lasts(path)) {
+            this.passing.add(path);
+        }
+    }
+    /** Whether what is kept of a path lasts from a call to the next: a file of a campaign watched, or of a game system. */
+    lasts(path) {
+        return [...this.roots, ...this.systemFolders].some((folder) => path === folder || isInside(folder, path));
+    }
+    /** A path as messages give it: inside a campaign, from its folder. */
+    shownPath(path) {
+        const root = [...this.roots].find((folder) => isInside(folder, path));
+        return root === undefined ? path : relative(root, path).replaceAll(sep, "/");
+    }
+    /** Forgets what lasts only for a call, such as a campaign.yaml not there yet, which another process may write: the next call reads it again. */
+    forgetPassing() {
+        for (const path of [...this.passing].filter((passing) => !this.lasts(passing))) {
+            this.kept.delete(path);
+            this.listings.delete(path);
+            this.forgetBuiltFrom(path);
+        }
+        this.passing.clear();
+    }
+    /** Watches each folder of the campaigns that holds what is kept, those that came into it too; one that cannot be watched makes every call check everything. */
+    watchFolders(root) {
+        const folders = [root, ...watchedTrees.flatMap((tree) => foldersIn(join(root, tree)))].filter((folder) => !this.watchers.has(folder));
+        for (const folder of folders) {
+            try {
+                this.watchers.set(folder, this.watchFolder(folder, (name) => this.report(folder, name), () => this.lose(folder)));
+            }
+            catch {
+                this.unwatchable = true;
+            }
+        }
+    }
+    /** A change a watcher saw: a name in its folder; without one, or with its own folder's path as Windows gives it when the folder goes, it has lost track. */
+    report(folder, name) {
+        this.changes++;
+        this.changeListeners.forEach((listener) => listener());
+        if (name === undefined || name === "" || isAbsolute(name)) {
+            this.lose(folder);
+            return;
+        }
+        this.reported.add(join(folder, name));
+    }
+    /** A watcher that failed: it is closed, and everything is checked at the next call. */
+    lose(folder) {
+        this.watchers.get(folder)?.close();
+        this.watchers.delete(folder);
+        this.checkAll = true;
+        // The next call checks everything and watches the folder again: who listens calls again.
+        this.changeListeners.forEach((listener) => listener());
+    }
+    /**
+     * Whether what a watcher named changed outside the session (OUT-1): a file of a campaign kept with another text, or gone; or a new one, missing from the
+     * listing of a folder that holds it. The session's own writes are kept as they are written, so they never differ.
+     */
+    isOutside(path, now) {
+        if (now === undefined || ![...this.roots].some((root) => isInside(root, path))) {
+            return false;
+        }
+        const kept = this.kept.get(path);
+        if (kept !== undefined) {
+            return kept.text !== now.text;
+        }
+        return now.text !== undefined && [...this.listings].some(([folder, listing]) => isInside(folder, path) && !listing.includes(path));
+    }
+    /** Notes the files changed outside the session, with their text as it kept them; first who reads the world as it was, once for those that come together. */
+    noteOutside(paths) {
+        if (paths.length > 0) {
+            this.beforeOutside?.();
+        }
+        for (const path of paths.filter((one) => !this.outside.has(one))) {
+            this.outside.set(path, { before: this.kept.get(path)?.text });
+        }
+    }
+    /** A file changed outside that the session now writes: what changed outside is what the disk had before this write, never what the session writes. */
+    freezeOutside(path) {
+        const change = this.outside.get(resolve(path));
+        if (change !== undefined && change.after === undefined) {
+            change.after = { text: readNow(resolve(path))?.text };
+        }
+    }
+    /** What a watcher named: a file kept with another text, a new file or one gone; or a folder that came or went, read again and watched whole. */
+    recheck(path, read) {
+        if (read === undefined) {
+            // A folder, or a file being written: what is under it is read again, and a new folder is watched.
+            this.forgetUnder(path);
+            this.roots.forEach((root) => this.watchFolders(root));
+            return;
+        }
+        const now = read.text;
+        // Only a name that is gone may be a folder watched, or one that held what is kept: looked for only then.
+        const under = `${path}${sep}`;
+        if (now === undefined && (this.watchers.has(path) || [...this.kept.keys(), ...this.listings.keys(), ...this.watchers.keys()].some((other) => other.startsWith(under)))) {
+            // A folder that went, renamed or removed, with all it held: only its name comes, and on Linux nothing more from its own watcher.
+            this.forgetUnder(path);
+            this.closeWatchersUnder(path);
+            return;
+        }
+        const kept = this.kept.get(path);
+        if (kept === undefined || kept.text !== now) {
+            this.changed(path, kept === undefined ? undefined : { text: now }, now !== undefined);
+        }
+    }
+    /** Compares every file kept of the campaigns with the disk, lists their folders again, and watches the folders that came. */
+    async checkEverything() {
+        this.reported.clear();
+        this.checkAll = false;
+        this.changes = 0;
+        const paths = [...this.kept.keys()].filter((path) => [...this.roots].some((root) => isInside(root, path)));
+        const texts = await Promise.all(paths.map((path) => readFile(path, "utf8").catch(() => undefined)));
+        // The files that came into a folder listed, which the session did not write: new, outside it (OUT-1).
+        const listed = [...this.listings].filter(([folder]) => [...this.roots].some((root) => folder === root || isInside(root, folder)));
+        const added = listed.flatMap(([folder, listing]) => {
+            const known = new Set(listing);
+            return filesIn(folder, () => true).filter((path) => !known.has(path) && !this.kept.has(path));
+        });
+        this.noteOutside([...paths.filter((path, index) => this.kept.get(path)?.text !== texts[index]), ...new Set(added)]);
+        paths.forEach((path, index) => {
+            if (this.kept.get(path)?.text !== texts[index]) {
+                this.changed(path, { text: texts[index] }, texts[index] !== undefined);
+            }
+        });
+        this.roots.forEach((root) => {
+            this.forgetUnder(root, false);
+            this.watchFolders(root);
+        });
+    }
+    /** Forgets what is kept under a path, the listings that may have held it, and what was built from it. `files` false keeps the files' texts. */
+    forgetUnder(path, files = true) {
+        for (const kept of [...this.kept.keys()].filter((other) => files && (other === path || isInside(path, other)))) {
+            this.kept.delete(kept);
+        }
+        for (const listed of [...this.listings.keys()].filter((folder) => folder === path || isInside(folder, path) || isInside(path, folder))) {
+            this.listings.delete(listed);
+        }
+        this.forgetBuiltFrom(path);
+    }
+    closeWatchersUnder(path) {
+        for (const [folder, watcher] of this.watchers) {
+            if (folder === path || isInside(path, folder)) {
+                watcher.close();
+                this.watchers.delete(folder);
+            }
+        }
+    }
+}
+/** Node's watcher for one folder, which never keeps the process alive by itself. */
+function watchWithNode(folder, changed, failed) {
+    const watcher = watch(folder, { persistent: false }, (_event, name) => changed(name === null ? undefined : String(name)));
+    watcher.on("error", failed);
+    return watcher;
+}
+/** A file's text as it is now, none for a file gone; undefined for a folder, or a file being written, which cannot be read. */
+function readNow(path) {
+    try {
+        return { text: readText(path) };
+    }
+    catch {
+        return undefined;
+    }
+}