rpg-engine 0.0.0-stage → 0.1.0

package/dist/pages/check.js

@@ -0,0 +1,345 @@
+import { frozen } from "../core/frozen.js";
+import { comparableText, withArticle } from "../core/text.js";
+import { readEnvironment } from "./environment.js";
+import { baseChain, baseFieldOf, baseProblem, derivedPages, shownPart } from "./inheritance.js";
+import { links, readSection, repeatedNames, unreadSecretLines } from "./markdown.js";
+import { readStops } from "./roads.js";
+import { canHold, containerFieldOf, containerFields, heldTypesText, isEmptyField, isStandardField, misspelledStandardField, standardFieldProblem } from "./standard-fields.js";
+import { alwaysInList, alwaysInMessage, systemKnowsReason, systemLabel } from "./system-pages.js";
+import { linksIn, locate, systemFirstFix, systemPageNamed, textsIn, validHoldersOf } from "./world.js";
+/**
+ * The exact checks on the world's pages (D-58, first level): files that cannot be read, repeated names, standard fields, links, containers, environments.
+ * A world never changes: its problems are found once, and a session of the MCP server keeps the world while its files do not change (D-194).
+ */
+export function checkWorld(world) {
+    let problems = checked.get(world);
+    if (problems === undefined) {
+        problems = frozen(worldProblems(world));
+        checked.set(world, problems);
+    }
+    return problems;
+}
+const checked = new WeakMap();
+function worldProblems(world) {
+    // Built once, so that the checks cost as much as reading the pages, however many there are.
+    const pagesByName = groupBy(world.pages, (page) => [page.name]);
+    const listingsByName = groupBy(world.pages.flatMap(listingsOf), (listing) => linksIn(listing.entry));
+    return [
+        ...world.problems.map((message) => ({ message })),
+        ...[...pagesByName.values()].filter((pages) => pages.length > 1).map(repeatedPageProblem),
+        ...world.pages.flatMap((page) => hidingProblems(world, page)),
+        ...world.pages.flatMap((page) => [
+            ...pageAlone.fields(page),
+            ...linkProblems(world, pagesByName, page),
+            ...publicKnowsProblems(world, pagesByName, page),
+            ...containerProblems(world, pagesByName, listingsByName, page),
+            ...equippedProblems(world, pagesByName, page),
+            ...stopProblems(world, pagesByName, page),
+            ...pageAlone.environment(page),
+            ...pageAlone.sections(page),
+            ...inheritanceProblems(world, page),
+        ]),
+    ];
+}
+/** A check that reads the page alone, made once for each page: a page never changes, and a session keeps those whose files do not (D-194). */
+function onceForEachPage(check) {
+    const done = new WeakMap();
+    return (page) => {
+        let problems = done.get(page);
+        if (problems === undefined) {
+            problems = frozen(check(page));
+            done.set(page, problems);
+        }
+        return problems;
+    };
+}
+const pageAlone = { fields: onceForEachPage(fieldProblems), environment: onceForEachPage(environmentProblems), sections: onceForEachPage(sectionProblems) };
+function groupBy(items, namesOf) {
+    const groups = new Map();
+    for (const item of items) {
+        for (const key of new Set(namesOf(item).map(comparableText))) {
+            groups.set(key, [...(groups.get(key) ?? []), item]);
+        }
+    }
+    return groups;
+}
+/** The entries of a page's container field, by its type (CON-1). */
+function listingsOf(holder) {
+    const field = containerFieldOf(holder.type);
+    return field === undefined ? [] : textsIn(holder.fields[field]).map((entry) => ({ holder, field, entry }));
+}
+/** A page of the campaign with the name of a page of the game system, which it hides (SYS-4): what derives from that name reads it instead. */
+function hidingProblems(world, page) {
+    const hidden = systemPageNamed(world, page.name);
+    if (hidden === undefined) {
+        return [];
+    }
+    const readers = derivedPages(world, page).map((derived) => derived.name);
+    const listed = `${readers.slice(0, 10).join(", ")}${readers.length > 10 ? `, and ${readers.length - 10} more,` : ""}`;
+    const who = readers.length === 0 ? "" : `, and ${listed} ${readers.length === 1 ? "derives" : "derive"} from it instead`;
+    return [{
+            path: page.path,
+            message: `${page.name} hides ${hidden.name}, ${systemLabel(hidden)}: links to that name lead to this page${who}.`,
+            fix: `if the file was made by mistake, such as by clicking a link in Obsidian, delete it; otherwise rename it by hand, with a name of its own`,
+        }];
+}
+function repeatedPageProblem(pages) {
+    return {
+        path: pages[1].path,
+        message: `Two pages have the same name: ${pages.map((page) => page.path).join(" and ")}.`,
+        fix: `rename one of them by its path, such as rename "${pages[1].path}" "a new name": names must be unique in the campaign`,
+    };
+}
+function fieldProblems(page) {
+    const standard = Object.keys(page.fields).flatMap((field) => {
+        const problem = standardFieldProblem(page.type, page.fields, field);
+        const name = misspelledStandardField(page.type, field);
+        const fix = name === undefined ? `write ${page.name}, set ${field} again with an allowed value` : `write ${page.name}, unset ${field} and write its value again as ${name}`;
+        return problem === undefined ? [] : [{ path: page.path, message: problem, fix }];
+    });
+    return [...standard, ...repeatedFieldProblems(page)];
+}
+/** A free field written twice with a value in different cases, such as hp and HP: the engine reads only the last one (INH-5). Empty ones count as missing; standard fields written another way are reported above. */
+function repeatedFieldProblems(page) {
+    const free = Object.keys(page.fields).filter((field) => !isEmptyField(page.fields[field]) && misspelledStandardField(page.type, field) === undefined && !isStandardField(page.type, field));
+    return [...groupBy(free, (field) => [field]).values()].filter((names) => names.length > 1).map((names) => ({
+        path: page.path,
+        message: `${page.name} writes the field ${names[0]} ${names.length} times: ${names.join(", ")}. Only the last one, ${names.at(-1)}, is read.`,
+        fix: `write ${page.name}, unset ${names.slice(0, -1).join(", unset ")}`,
+    }));
+}
+/** Links, in the fields and in the text, to pages, sections or secrets that do not exist. */
+function linkProblems(world, pagesByName, page) {
+    const inFields = Object.entries(page.fields).flatMap(([field, value]) => textsIn(value).flatMap((entry) => links(entry).map((link) => ({ link, field, entry, inList: Array.isArray(value) }))));
+    const inText = links(page.body).map((link) => ({ link, field: undefined, entry: undefined, inList: false }));
+    return [...inFields, ...inText].flatMap((found) => {
+        const broken = brokenLink(world, pagesByName, found.link);
+        // While the campaign's system is missing, the link may be to one of its pages: removing it would break what derives from it.
+        const missing = broken === "which does not exist";
+        const first = missing ? systemFirstFix(world) : undefined;
+        const own = missing ? missingFix(world, page, found.link.page, found.field, found.entry, found.inList) : linkFix(page, found.field, found.entry, found.inList);
+        const fix = first === undefined ? own : `${first}; otherwise ${own}`;
+        return broken === undefined ? [] : [{ path: page.path, message: `${found.field ?? "The text"} links to ${written(found.link)}, ${broken}.`, fix }];
+    });
+}
+function brokenLink(world, pagesByName, link) {
+    const target = pagesByName.get(comparableText(link.page))?.[0] ?? systemPageNamed(world, link.page);
+    if (target === undefined) {
+        return "which does not exist";
+    }
+    const section = link.section;
+    const bases = baseChain(world, target);
+    if (section === undefined || [target, ...bases].some((holder) => readSection(holder.body, section) !== undefined)) {
+        return undefined;
+    }
+    return `but ${target.name} has no section or secret "${section}"${bases.length > 0 ? ", nor do the pages it derives from" : ""}`;
+}
+/**
+ * Sections everyone can read, listed in knows: knows lists pages and secrets (D-61, REV-1), so such an entry says nothing. Secret or not, as reveal reads it.
+ * Nor does a page of the game system, which anyone may know (SYS-2).
+ */
+function publicKnowsProblems(world, pagesByName, page) {
+    return textsIn(page.fields.knows).flatMap((entry) => links(entry).flatMap((link) => {
+        const section = link.section;
+        const target = pagesByName.get(comparableText(link.page))?.[0] ?? systemPageNamed(world, link.page);
+        if (target?.system !== undefined) {
+            return [{
+                    path: page.path,
+                    message: `${page.name} knows ${written(link)}, ${systemLabel(target)}, ${systemKnowsReason(target)}: knows lists pages and secrets of the campaign.`,
+                    fix: `write ${page.name}, remove knows=${entry}`,
+                }];
+        }
+        const part = section === undefined || target === undefined ? undefined : shownPart(world, target, section);
+        return part !== undefined && !part.secret
+            ? [{ path: page.path, message: `${page.name} knows ${written(link)}, a section everyone can read: knows lists pages and secrets.`, fix: `write ${page.name}, remove knows=${entry}` }]
+            : [];
+    }));
+}
+function written(link) {
+    return link.section === undefined ? `[[${link.page}]]` : `[[${link.page}#${link.section}]]`;
+}
+/** How to fix a broken link: remove the list entry as it is written, set the field again, or correct the text. */
+/**
+ * How to fix a link in a field to a page that does not exist: what the world lacks gets its page, as a spell the system does not have (D-216); a wrong link goes. A
+ * campaign played in another language than its system's is told the system's.
+ */
+function missingFix(world, page, target, field, entry, inList) {
+    if (field === undefined || field === "effects") {
+        return linkFix(page, field, entry, inList);
+    }
+    const system = world.system;
+    const language = system !== undefined && world.language !== undefined && comparableText(world.language) !== comparableText(system.language)
+        ? ` (the system ${system.name} names its pages in ${system.language}: find looks them up)`
+        : "";
+    return `create ${target} with write if it belongs to this world, or ${linkFix(page, field, entry, inList)}${inList ? " if the link is wrong" : ""}${language}`;
+}
+function linkFix(page, field, entry, inList) {
+    if (field === undefined) {
+        return `correct the link in the text of ${page.name}, or create what it points to`;
+    }
+    if (field === "effects") {
+        return `end that effect with effect end, or create the page it links to`;
+    }
+    return inList ? `write ${page.name}, remove ${field}=${entry}` : `write ${page.name}, set ${field} to a page that exists`;
+}
+/**
+ * What is wrong with a page as a container or as a thing held (CON-10): listed by more than one container, listing itself, inside itself through others,
+ * listing what it cannot hold, or listing things in a field its type does not use.
+ */
+function containerProblems(world, pagesByName, listingsByName, page) {
+    const listings = (listingsByName.get(comparableText(page.name)) ?? []).filter((listing, index, all) => all.findIndex((other) => other.holder === listing.holder) === index);
+    const holders = listings.filter((listing) => listing.holder !== page && canHold(listing.holder.type, page.type));
+    const self = listings.find((listing) => listing.holder === page);
+    const problems = [];
+    if (holders.length > 1) {
+        const where = holders.map((listing) => listing.holder.name).join(" and in ");
+        problems.push({ path: page.path, message: `${page.name} is in ${where}; a thing is in one place only.`, fix: `move ${page.name}, to ${holders[0].holder.name} or wherever it is: it stays there only` });
+    }
+    if (self !== undefined) {
+        problems.push({ path: page.path, message: `${page.name} lists itself in ${self.field}: a thing is never inside itself.`, fix: `write ${page.name}, remove ${self.field}=${self.entry}` });
+    }
+    const ring = ringOf(world, page);
+    if (ring !== undefined) {
+        problems.push({
+            path: page.path,
+            message: `${page.name} is inside itself: ${[page, ...ring, page].map((holder) => holder.name).join(" › ")}.`,
+            fix: `move one of them out of the others, such as move ${page.name}, to a place outside`,
+        });
+    }
+    return [...problems, ...heldProblems(world, pagesByName, page), ...wrongFieldProblems(page)];
+}
+/** The containers above a page, nearest first, when climbing them leads back to it; undefined when it does not. */
+function ringOf(world, page) {
+    const chain = [];
+    for (let holder = validHoldersOf(world, page)[0]; holder !== undefined && !chain.includes(holder); holder = validHoldersOf(world, holder)[0]) {
+        if (holder === page) {
+            return chain;
+        }
+        chain.push(holder);
+    }
+    return undefined;
+}
+/** Entries of a container's field that point to pages it cannot hold (CON-1), or to pages of the game system, which are nowhere (SYS-6): they put nothing anywhere. */
+function heldProblems(world, pagesByName, holder) {
+    return listingsOf(holder).flatMap((listing) => linksIn(listing.entry).flatMap((name) => {
+        const held = pagesByName.get(comparableText(name));
+        const system = held === undefined ? systemPageNamed(world, name) : undefined;
+        if (system !== undefined && alwaysInList(world, system) !== undefined) {
+            return [{
+                    path: holder.path,
+                    message: `${holder.name} lists ${system.name} in ${listing.field}: ${alwaysInMessage(system, alwaysInList(world, system) ?? "")}`,
+                    fix: `write ${holder.name}, remove ${listing.field}=${listing.entry}`,
+                }];
+        }
+        if (system !== undefined) {
+            const instead = system.type === "item" ? `; one that ${holder.name} has is an item of the campaign with item=[[${system.name}]], or text` : "";
+            return [{
+                    path: holder.path,
+                    message: `${holder.name} lists ${system.name} in ${listing.field}, but ${system.name} is ${systemLabel(system)}, a kind, which is nowhere${instead}.`,
+                    fix: `write ${holder.name}, remove ${listing.field}=${listing.entry}${system.type === "item" ? `, then write "<name>", type item, set item=[[${system.name}]] and move it to ${holder.name}` : ""}`,
+                }];
+        }
+        const page = held?.length === 1 ? held[0] : undefined;
+        if (page === undefined || page === holder || canHold(holder.type, page.type)) {
+            return [];
+        }
+        const message = `${holder.name} lists ${page.name} in ${listing.field}, but ${withArticle(holder.type ?? "free page")} holds ${heldTypesText(holder.type)}, and ${page.name} is ${withArticle(page.type ?? "free page")}.`;
+        return [{ path: holder.path, message, fix: `move ${page.name}, to a container that holds it, such as a place; or write ${holder.name}, remove ${listing.field}=${listing.entry}` }];
+    }));
+}
+/** What a character has equipped and does not hold (CON-12), as write says it after a change of its inventory or of what it has equipped. */
+export function equippedNotes(world, character) {
+    return equippedProblems(world, groupBy(world.pages, (page) => [page.name]), character).map((problem) => `${problem.message} Fix: ${problem.fix}.`);
+}
+/** A road's stop that is a page but not a place of the campaign (ROA-4, ROA-7): its stretches lead nowhere. A stop that does not exist is a broken link, said above. */
+function stopProblems(world, pagesByName, road) {
+    const read = road.type === "place" ? readStops(road.fields.stops) : undefined;
+    if (read === undefined || "problem" in read) {
+        return [];
+    }
+    return [...new Set(read.stops)].flatMap((name) => {
+        const page = pagesByName.get(comparableText(name))?.[0] ?? systemPageNamed(world, name);
+        const what = page === undefined || (page.type === "place" && page.system === undefined) ? undefined : page.system === undefined ? withArticle(page.type ?? "free page") : systemLabel(page);
+        return what === undefined
+            ? []
+            : [{ path: road.path, message: `${road.name} has ${page?.name} among its stops, but it is ${what}, not a place of the campaign: the stretches to it lead nowhere.`, fix: `write ${road.name}, set stops again with places` }];
+    });
+}
+/**
+ * What a character has equipped and does not hold, directly or inside what it holds (CON-12): an item that went elsewhere, or a page of the game system, a kind,
+ * which is nowhere.
+ */
+function equippedProblems(world, pagesByName, character) {
+    const value = character.fields.equipped;
+    if (character.type !== "character" || isEmptyField(value)) {
+        return [];
+    }
+    return (Array.isArray(value) ? value : [value]).map(String).flatMap((entry) => linksIn(entry).flatMap((name) => {
+        const held = pagesByName.get(comparableText(name));
+        const system = held === undefined ? systemPageNamed(world, name) : undefined;
+        if (system !== undefined && alwaysInList(world, system) !== undefined) {
+            return [{ path: character.path, message: `${character.name} has ${system.name} in equipped: ${alwaysInMessage(system, alwaysInList(world, system) ?? "")}`, fix: `write ${character.name}, remove equipped=${entry}` }];
+        }
+        if (system !== undefined) {
+            return [{
+                    path: character.path,
+                    message: `${character.name} has ${system.name} in equipped, but it is ${systemLabel(system)}, a kind: what a character wears or wields is an item of the campaign with item=[[${system.name}]], in its inventory.`,
+                    fix: `write "<name>", type item, set item=[[${system.name}]], move it to ${character.name}, then write ${character.name}, remove equipped=${entry} and add the new one`,
+                }];
+        }
+        const page = held?.length === 1 ? held[0] : undefined;
+        return page === undefined || locate(world, page).chain.includes(character)
+            ? []
+            : [{
+                    path: character.path,
+                    message: `${character.name} has ${page.name} in equipped, but does not carry it: a character wears or wields only what it holds.`,
+                    fix: `move ${page.name}, to ${character.name}; or write ${character.name}, remove equipped=${entry}`,
+                }];
+    }));
+}
+/** Container fields on a page whose type does not list things there (CON-1): they put nothing anywhere. */
+function wrongFieldProblems(page) {
+    const own = containerFieldOf(page.type);
+    return containerFields.filter((field) => field !== own && !isEmptyField(page.fields[field])).map((field) => {
+        const message = own === undefined
+            ? `${page.name} is ${withArticle(page.type ?? "free page")}, which holds nothing, so its ${field} puts nothing anywhere.`
+            : `${page.name} lists things in ${field}, but ${withArticle(page.type ?? "free page")} holds them in ${own}.`;
+        return { path: page.path, message, fix: `move each thing it lists into ${own === undefined ? "a place, a character or an item" : page.name}, then write ${page.name}, unset ${field}` };
+    });
+}
+/** A place's environment that cannot be read, or an environment on a page that is not a place, where it holds for nothing (ENV-6). */
+function environmentProblems(page) {
+    const value = page.fields.environment;
+    if (isEmptyField(value)) {
+        return [];
+    }
+    // On other types, such as a creature, environment is a free field: a game may use it for where they live.
+    if (page.type === "character" || page.type === "item") {
+        return [{
+                path: page.path,
+                message: `${page.name} has an environment, but only a place's holds, for all it contains.`,
+                fix: `write ${page.name}, unset environment; what it does around itself, such as a lantern's light, is a field or an effect of its own`,
+            }];
+    }
+    if (page.type !== "place") {
+        return [];
+    }
+    // An environment that is not a list of lines is reported with the standard fields.
+    const read = standardFieldProblem(page.type, page.fields, "environment") === undefined ? readEnvironment(value) : { entries: [] };
+    return "problem" in read ? [{ path: page.path, message: `${page.name}: ${read.problem}`, fix: `write ${page.name}, set environment whole, such as ["light: dark"]` }] : [];
+}
+function inheritanceProblems(world, page) {
+    const problem = baseProblem(world, page);
+    const field = baseFieldOf(page.type) ?? "creature";
+    return problem === undefined ? [] : [{ path: page.path, message: problem, fix: `write ${page.name}, set ${field} to the ${field} it is a kind of, or unset it` }];
+}
+function sectionProblems(page) {
+    const repeated = repeatedNames(page.body).map((name) => ({ path: page.path, message: `${page.name} has two sections or secrets named "${name}".`, fix: `rename one of them by hand, so that ${page.name}#${name} finds one place` }));
+    // A secret the engine reads as public text would reach the player's view (VIEW-3).
+    const unread = unreadSecretLines(page.body).map((line) => ({
+        path: page.path,
+        message: `${page.name} marks a secret that is read as public text: "${page.body.split("\n")[line - 1].trim()}".`,
+        fix: "start its line with > [!secret] Name, at most three spaces in, by hand",
+    }));
+    return [...repeated, ...unread];
+}

package/dist/pages/containers.d.ts

@@ -0,0 +1,34 @@
+import type { PageType } from "./page-types.ts";
+import { type Page, type World } from "./world.ts";
+/** A planned move: the containers to write, in order, each with the entries it loses, as written, and those it gains; the destination comes last. */
+export interface MovePlan {
+    edits: {
+        holder: Page;
+        field: string;
+        remove: string[];
+        add: string[];
+    }[];
+    /** The pages that change place; the others were already only in the destination. */
+    moving: Page[];
+}
+/**
+ * Plans moving pages into a container (CON-4): after it, each is only there. Every entry that points to one of them goes, however it is written and from
+ * whichever container lists it; the destination keeps its one entry, or gains one at the end. Refused when the destination cannot hold one of them,
+ * or would be inside itself, or when a list to change is not a list of links.
+ */
+export declare function planMove(world: World, pages: Page[], destination: Page): MovePlan;
+/** Plans taking pages out of every container (TRV-12): in the open, between the places of the map, they are in none. What they carry goes with them. */
+export declare function planLeave(world: World, pages: Page[]): MovePlan;
+/**
+ * Writes a planned move, the destination last, so that a move stopped halfway is finished by doing it again (CON-4). Every file is worked out first, so that
+ * one that cannot be read stops the move before anything is written. Returns the world after it.
+ */
+export declare function applyMove(world: World, plan: MovePlan): World;
+/** Why a container cannot hold a page (CON-1), with the way out: where the page goes instead. */
+export declare function holdRefusal(holder: {
+    name: string;
+    type?: PageType;
+}, held: {
+    name: string;
+    type?: PageType;
+}): string;

package/dist/pages/containers.js

@@ -0,0 +1,181 @@
+// Moving pages from one container to another (D-151, CON-4): everything is checked before anything is written.
+import { join } from "node:path";
+import { files } from "../core/store.js";
+import { comparableText, withArticle } from "../core/text.js";
+import { links } from "./markdown.js";
+import { changeFields, joinPageFile, readFields, splitPageFile } from "./page-file.js";
+import { canHold, containerFieldOf, isEmptyField } from "./standard-fields.js";
+import { heldSystemPageMessage, systemLabel } from "./system-pages.js";
+import { linksIn, locate, readPage, withPage } from "./world.js";
+/**
+ * Plans moving pages into a container (CON-4): after it, each is only there. Every entry that points to one of them goes, however it is written and from
+ * whichever container lists it; the destination keeps its one entry, or gains one at the end. Refused when the destination cannot hold one of them,
+ * or would be inside itself, or when a list to change is not a list of links.
+ */
+export function planMove(world, pages, destination) {
+    for (const page of pages) {
+        checkMove(world, page, destination);
+    }
+    // checkMove refuses a destination that holds nothing, so it has its field.
+    const field = containerFieldOf(destination.type) ?? "contains";
+    const listedOnce = (page) => entriesOf(destination, field).filter((entry) => pointsTo(entry, page)).length === 1;
+    const edits = [];
+    for (const holder of world.pages.filter((page) => page !== destination)) {
+        const own = containerFieldOf(holder.type);
+        if (own === undefined) {
+            continue;
+        }
+        const remove = pages.flatMap((page) => checkedEntries(holder, own, page));
+        if (remove.length > 0) {
+            edits.push({ holder, field: own, remove: distinctLinks(remove), add: [] });
+        }
+    }
+    // A page only written twice in the destination does not move: its double goes in silence.
+    const inDestination = (page) => entriesOf(destination, field).some((entry) => pointsTo(entry, page));
+    const moving = pages.filter((page) => !inDestination(page) || edits.some((edit) => edit.remove.some((entry) => pointsTo(entry, page))));
+    // Who had one of them equipped, or something inside one of them, as a sword in a pack, and holds it no more after the move has it no more (CON-12); who
+    // moves keeps what goes with them, as a character their armor, or the passengers of a boat theirs.
+    const around = new Set([destination, ...locate(world, destination).chain]);
+    const carried = world.pages.filter((page) => moving.includes(page) || locate(world, page).chain.some((holder) => moving.includes(holder)));
+    const staysWith = (item, holder) => {
+        const chain = locate(world, item).chain;
+        const moved = chain.findIndex((container) => moving.includes(container));
+        return around.has(holder) || (!moving.includes(item) && moved !== -1 && chain.slice(0, moved + 1).includes(holder));
+    };
+    for (const holder of world.pages.filter((page) => page.type === "character")) {
+        const remove = entriesOf(holder, "equipped").filter((entry) => carried.some((page) => pointsTo(entry, page) && !staysWith(page, holder)));
+        if (remove.length > 0) {
+            edits.push({ holder, field: "equipped", remove: distinctLinks(remove), add: [] });
+        }
+    }
+    const renewed = pages.filter((page) => !listedOnce(page));
+    if (renewed.length > 0) {
+        checkList(destination, field);
+        // Written twice or more, it is written once again at the end; missing, it is added there.
+        const remove = renewed.flatMap((page) => checkedEntries(destination, field, page));
+        edits.push({ holder: destination, field, remove: distinctLinks(remove), add: renewed.map((page) => `[[${page.name}]]`) });
+    }
+    return { edits, moving };
+}
+/** Plans taking pages out of every container (TRV-12): in the open, between the places of the map, they are in none. What they carry goes with them. */
+export function planLeave(world, pages) {
+    const edits = [];
+    for (const holder of world.pages) {
+        const own = containerFieldOf(holder.type);
+        const remove = own === undefined ? [] : pages.flatMap((page) => checkedEntries(holder, own, page));
+        if (own !== undefined && remove.length > 0) {
+            edits.push({ holder, field: own, remove: distinctLinks(remove), add: [] });
+        }
+    }
+    return { edits, moving: pages.filter((page) => edits.some((edit) => edit.remove.some((entry) => pointsTo(entry, page)))) };
+}
+/**
+ * Writes a planned move, the destination last, so that a move stopped halfway is finished by doing it again (CON-4). Every file is worked out first, so that
+ * one that cannot be read stops the move before anything is written. Returns the world after it.
+ */
+export function applyMove(world, plan) {
+    // A page with more than one field to change, as a character's inventory and what it has equipped, is written once, with all of them.
+    const holders = plan.edits.map((edit) => edit.holder).filter((holder, index, all) => all.indexOf(holder) === index);
+    const changed = holders.map((holder) => {
+        const fullPath = join(world.root, holder.path);
+        const file = splitPageFile(files().fresh(fullPath) ?? "");
+        const frontmatter = plan.edits.filter((edit) => edit.holder === holder).reduce((text, { field, remove, add }) => {
+            const removed = remove.length === 0 ? text : changeFields(text, { remove: { [field]: remove } }, holder.path);
+            // A container left with nothing loses the field, as if it had never held anything.
+            const emptied = add.length === 0 && isEmptyList(readFields(removed, holder.path)[field]) ? changeFields(removed, { unset: [field] }, holder.path) : removed;
+            return add.length === 0 ? emptied : changeFields(emptied, { add: { [field]: add } }, holder.path);
+        }, file.frontmatter);
+        return { holder, fullPath, text: joinPageFile({ frontmatter, body: file.body }) };
+    });
+    let after = world;
+    for (const [index, { holder, fullPath, text }] of changed.entries()) {
+        try {
+            files().write(fullPath, text);
+        }
+        catch (error) {
+            const written = changed.slice(0, index).map((file) => file.holder.name);
+            const done = written.length === 0 ? "Nothing moved" : `Written already: ${written.join(", ")}`;
+            throw new Error(`${holder.path} could not be written (${error instanceof Error ? error.message : String(error)}). ${done}: fix it, then run the same move again, which finishes it.`);
+        }
+        after = withPage(after, after.pages.find((page) => page.path === holder.path), readPage(world.root, fullPath));
+    }
+    return after;
+}
+/** Why a container cannot hold a page (CON-1), with the way out: where the page goes instead. */
+export function holdRefusal(holder, held) {
+    if (held.type === "creature") {
+        return `${held.name} is a creature, a kind: its copies enter a scene with scene, creatures; one in particular is a character with creature [[${held.name}]].`;
+    }
+    if (held.type !== "place" && held.type !== "character" && held.type !== "item") {
+        return `${held.name} is ${withArticle(held.type ?? "free page")}, which is nowhere: only places, characters and items are inside something.`;
+    }
+    if (containerFieldOf(holder.type) === undefined) {
+        const where = held.type === "item" ? "a place, a character or an item" : held.type === "character" ? "a place or an item" : "a place";
+        return `${holder.name} is ${withArticle(holder.type ?? "free page")}, which holds nothing: ${held.name} goes into ${where}.`;
+    }
+    if (held.type === "place") {
+        const inside = holder.type === "item" ? ` For a world inside a thing, such as a lamp's, write a place with a link to ${holder.name}.` : "";
+        return `${holder.name} is ${withArticle(holder.type ?? "free page")}: a place goes only into a place.${inside}`;
+    }
+    return `${holder.name} is a character, who carries only items: to be with them, ${held.name} goes where ${holder.name} is.`;
+}
+/** A page goes only into a container that can hold it (CON-1), never into itself or into what it holds (CON-3); the pages of the game system go nowhere (SYS-6). */
+function checkMove(world, page, destination) {
+    if (page.system !== undefined) {
+        throw new Error(`${heldSystemPageMessage(page, destination, world)} Nothing moved.`);
+    }
+    if (destination.system !== undefined) {
+        throw new Error(`${destination.name} is ${systemLabel(destination)}, a kind, which holds nothing: ${page.name} goes into a page of the campaign. Nothing moved.`);
+    }
+    if (!canHold(destination.type, page.type)) {
+        throw new Error(`${holdRefusal(destination, page)} Nothing moved.`);
+    }
+    if (page === destination || locate(world, destination).chain.includes(page)) {
+        const why = page === destination ? "into itself" : `into ${destination.name}, which is inside it`;
+        throw new Error(`${page.name} cannot go ${why}: a thing is never inside itself. Nothing moved.`);
+    }
+}
+/** A container's list must be a list to change it: one written as text is refused, with how to write it. */
+function checkList(holder, field) {
+    const value = holder.fields[field];
+    if (!isEmptyField(value) && !Array.isArray(value)) {
+        throw new Error(`${field} on ${holder.name} is ${JSON.stringify(value)}, not a list: write it as one first, such as write ${holder.name}, set ${field}=[[A]], [[B]]. Nothing moved.`);
+    }
+}
+/**
+ * The entries of a container that point to a page, to take out. Refused when the container lists it in text, where no entry can be taken out alone,
+ * or in an entry that links to more than it, which would go too.
+ */
+function checkedEntries(holder, field, page) {
+    if (listsAsText(holder, field, page)) {
+        checkList(holder, field);
+    }
+    const entries = entriesOf(holder, field).filter((entry) => pointsTo(entry, page));
+    const shared = entries.find((entry) => links(entry).length > 1);
+    if (shared !== undefined) {
+        throw new Error(`${field} on ${holder.name} has an entry with more than one link, "${shared}": write one link for each entry first. Nothing moved.`);
+    }
+    return entries;
+}
+function isEmptyList(value) {
+    return Array.isArray(value) && value.length === 0;
+}
+/** The texts a container's list holds, as written. */
+function entriesOf(holder, field) {
+    const value = holder.fields[field];
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+/** Whether a container lists the page in a field that is not a list, where no entry can be taken out alone. */
+function listsAsText(holder, field, page) {
+    const value = holder.fields[field];
+    return !Array.isArray(value) && linksIn(value).some((name) => comparableText(name) === comparableText(page.name));
+}
+/** One entry for each link, the first written: removing it takes away every entry that is the same link, however written (CON-7). Other text stays as it is. */
+function distinctLinks(entries) {
+    const key = (entry) => (/^\[\[[^\]]+\]\]$/.test(entry.trim()) ? links(entry).map((link) => comparableText(`${link.page}#${link.section ?? ""}`)).join("|") : `text ${entry}`);
+    return entries.filter((entry, index) => entries.findIndex((other) => key(other) === key(entry)) === index);
+}
+/** Whether an entry is a link to the page, however written: [[bruna]], [[characters/Bruna.md|the ferry keeper]] (CON-2). */
+function pointsTo(entry, page) {
+    return links(entry).some((link) => comparableText(link.page) === comparableText(page.name));
+}

package/dist/pages/environment.d.ts

@@ -0,0 +1,26 @@
+import { type Page, type World } from "./world.ts";
+/** One entry of a place's environment, as light: dark. */
+export interface EnvironmentEntry {
+    name: string;
+    value: string;
+}
+/** What holds at a page, entry by entry, from the nearest place of its chain that has it, the page itself first when it is a place (ENV-2). */
+export declare function environmentAt(world: World, page: Page): {
+    entry: EnvironmentEntry;
+    place: Page;
+}[];
+/** The places whose environment holds at a page, nearest first: the page itself when it is a place, then the places of its chain (ENV-2). */
+export declare function placesAround(world: World, page: Page): Page[];
+/** The entries a place's environment holds (ENV-1); or why it cannot be read. A line written without quotes, which YAML reads as a map of one key, is the line it was. */
+export declare function readEnvironment(value: unknown): {
+    entries: EnvironmentEntry[];
+} | {
+    problem: string;
+};
+/** An entry as its line is written: light: dark. */
+export declare function formatEnvironmentEntry(entry: EnvironmentEntry): string;
+/**
+ * The lines of a place's environment after a write (ENV-4): `remove` takes entries out by name, `add` puts one in, or in place of the one with its name.
+ * `place` names the place in messages.
+ */
+export declare function changedEnvironment(current: unknown, add: unknown[], remove: unknown[], place: string): string[];