rpg-engine 0.0.0-stage → 0.1.1

package/dist/commands/progression.js

@@ -0,0 +1,206 @@
+// What the classes of a character give (D-201, D-219, PRO-1–PRO-4): the row of each class's table at its level, and the features gained so far, with those its
+// subclasses add. The tables are the pages' own; this is where the system's progression meets the pages of a world.
+import { listItems } from "../core/formula.js";
+import { comparableText, valueNamed } from "../core/text.js";
+import { pagesWithName, sectionTitles, systemPageNamed } from "../pages/index.js";
+import { featureParts, fieldName, gainedFeatures, levelledFeatures, levelTable, mergedFeatures, rowFields } from "../progression/index.js";
+/** What the classes in these fields give, by the system's progression; undefined when the system has none or the fields name no class (PRO-1). */
+export function progressionOf(world, fields) {
+    const rule = world.system?.progression;
+    const written = rule === undefined ? undefined : valueNamed(fields, rule.list);
+    if (rule === undefined || written === undefined || written === null) {
+        return undefined;
+    }
+    const entries = listItems(written).flatMap((item, order) => {
+        const page = pageNamed(world, item.name);
+        return item.number === undefined || item.number < 1 || page === undefined ? [] : [{ name: item.name, level: item.number, page, order }];
+    });
+    const values = new Map();
+    const features = [];
+    for (const entry of entries) {
+        const { table, title } = readTable(entry.page, rule.features);
+        if (table === undefined) {
+            continue;
+        }
+        for (const [field, cell] of rowFields(table, entry.level, [...rule.skip, rule.features])) {
+            addValue(values, field, cell, { name: entry.page.name, level: entry.level });
+        }
+        features.push(...gainedFeatures(table, rule.features, entry.level, title).map((gained) => ({ ...gained, order: entry.order, part: 0, page: entry.page })));
+    }
+    const featuresField = fieldName(rule.features);
+    const parts = partsOf(world, fields, rule.parts, entries);
+    const given = [];
+    for (const part of parts) {
+        const levelled = levelledFeatures(listItemsOf(valueNamed(part.page.fields, featuresField)));
+        features.push(...levelled.flatMap((gained) => (gained === undefined || gained.level > part.level ? [] : [{ ...gained, order: part.order, part: 1, page: part.page }])));
+        // What it adds to the character's lists up to its item's level, as a domain's spells, always prepared (PRO-7).
+        for (const list of rule.parts?.lists ?? []) {
+            const items = levelledFeatures(listItemsOf(valueNamed(part.page.fields, list)));
+            given.push(...items.flatMap((item) => (item === undefined || item.level > part.level ? [] : [{ list, name: item.name, page: part.page }])));
+        }
+    }
+    // Item by item, then level by level; at the same level, a class's own features before its subclass's.
+    features.sort((first, second) => first.order - second.order || first.level - second.level || first.part - second.part);
+    return {
+        lists: rule.parts === undefined ? [rule.list] : [rule.list, rule.parts.list],
+        values: [...values.values()],
+        featuresField,
+        features: mergedFeatures(features).map(({ name }) => ({ name, pages: pagesGiving(features, name) })),
+        gains: features.map(({ name, level, page }) => ({ name, level, page })),
+        given,
+        from: [...entries.map((entry) => ({ list: rule.list, name: entry.page.name, level: entry.level })), ...parts.map((part) => ({ list: rule.parts?.list ?? "", name: part.page.name }))],
+    };
+}
+/** What the parts add to a list of the character, each with the page that adds it, as Bless from Life Domain in prepared (PRO-7). */
+export function givenItems(progression, list) {
+    return (progression?.given ?? []).filter((item) => comparableText(item.list) === comparableText(list));
+}
+/** The value the progression gives a field, or the features for its features field; undefined for any other field (PRO-2, PRO-3). */
+export function progressionValue(progression, field) {
+    if (progression === undefined) {
+        return undefined;
+    }
+    if (comparableText(field) === comparableText(progression.featuresField)) {
+        return progression.features.map((feature) => feature.name);
+    }
+    return progression.values.find((value) => comparableText(value.field) === comparableText(field))?.value;
+}
+/**
+ * The pages that tell a feature a character has, in the order of the classes, and its section's title, found by the name with or without its value in
+ * parentheses (PRO-4); undefined when the character has no such feature.
+ */
+export function featureSource(progression, name) {
+    const wanted = comparableText(featureParts(name).name);
+    const feature = progression?.features.find((candidate) => comparableText(featureParts(candidate.name).name) === wanted);
+    return feature === undefined ? undefined : { pages: feature.pages, title: featureParts(feature.name).name };
+}
+/**
+ * What validate says of the progression on a page (PRO-1, PRO-4): an item whose page has no table of levels, or no row at its level; a part whose page names no
+ * item, names one the list lacks, or lists features without a level.
+ */
+export function progressionProblems(world, page, fields) {
+    const rule = world.system?.progression;
+    const written = rule === undefined ? undefined : valueNamed(fields, rule.list);
+    if (rule === undefined || written === undefined || written === null) {
+        return [];
+    }
+    const items = listItems(written).map((item, order) => ({ ...item, order, page: pageNamed(world, item.name) }));
+    const entries = items.flatMap((item) => (item.number === undefined || item.page === undefined ? [] : [{ name: item.name, level: item.number, page: item.page, order: item.order }]));
+    // An item without a level or without a page gives nothing (PRO-1).
+    const unread = items.filter((item) => item.number === undefined || item.page === undefined).map((item) => ({
+        path: page.path,
+        message: item.page === undefined
+            ? `${rule.list} on ${page.name} names ${item.name}, which has no page, so it gives nothing.`
+            : `${item.name} in ${rule.list} on ${page.name} has no level, so it gives nothing.`,
+        fix: item.page === undefined
+            ? `write ${item.name} with its table of levels, or link one of the system's, such as [[${systemExample(world, rule.list)}]] ${item.number ?? 1}`
+            : `write ${page.name}, set ${rule.list} with each level, such as [[${item.page.name}]] 1`,
+    }));
+    const rows = entries.flatMap((entry) => {
+        const { table } = readTable(entry.page, rule.features);
+        const message = table === undefined
+            ? `${entry.page.name} has no table with a ${rule.features} column whose first column counts levels, so ${rule.list} on ${page.name} gives nothing from it.`
+            : !table.rows.has(entry.level)
+                ? `${entry.page.name} has no row for level ${entry.level} in its table, so ${rule.list} on ${page.name} gives nothing from it.`
+                : undefined;
+        return message === undefined ? [] : [{ path: page.path, message, fix: table === undefined ? `write ${entry.page.name} with its table of levels, as the system's do` : `check the level of ${entry.page.name} in ${rule.list}` }];
+    });
+    return [...unread, ...rows, ...partProblems(world, page, fields, rule, entries)];
+}
+/** The name of a page of the system that an item of the list may link to, for an example: the first one that has a table of levels. */
+function systemExample(world, list) {
+    const rule = world.system?.progression;
+    const page = rule === undefined ? undefined : world.system?.pages.find((candidate) => readTable(candidate, rule.features).table !== undefined);
+    return page?.name ?? list;
+}
+/** The pages that give a feature by this name, with or without its value in parentheses, each once, in the order they come (D-224). */
+function pagesGiving(features, name) {
+    const wanted = comparableText(featureParts(name).name);
+    return [...new Set(features.filter((feature) => comparableText(featureParts(feature.name).name) === wanted).map((feature) => feature.page))];
+}
+const tables = new WeakMap();
+/** The table of levels of a page, read once for each page, and how a name of its features column is a title of the page: as it is, or as the singular of one. */
+function readTable(page, column) {
+    const known = tables.get(page);
+    if (known !== undefined) {
+        return known;
+    }
+    const titles = sectionTitles(page.body);
+    const title = (name) => titles.find((candidate) => [comparableText(name), `${comparableText(name)}s`].includes(comparableText(candidate)));
+    const read = { table: levelTable(page.body, column), title };
+    tables.set(page, read);
+    return read;
+}
+/**
+ * A cell as a value: a whole number as a number, anything else as written. Two items with the same column give a value each, as the cantrips a bard and a
+ * sorcerer know, each from their class (PRO-2): "Bard 3, Sorcerer 4", which no formula reads.
+ */
+function addValue(values, field, cell, from) {
+    const value = /^\d+$/.test(cell) ? Number(cell) : cell;
+    const known = values.get(comparableText(field));
+    if (known === undefined) {
+        values.set(comparableText(field), { field, value, from: [from], cells: [value] });
+        return;
+    }
+    const cells = [...known.cells, value];
+    const every = [...known.from, from];
+    values.set(comparableText(field), { ...known, value: every.map((item, index) => `${item.name} ${String(cells[index])}`).join(", "), from: every, cells });
+}
+/** The parts the fields name whose page names an item of the list, each with the level of that item (PRO-3). */
+function partsOf(world, fields, parts, entries) {
+    if (parts === undefined) {
+        return [];
+    }
+    return listItems(valueNamed(fields, parts.list)).flatMap((item) => {
+        const page = pageNamed(world, item.name);
+        const owner = page === undefined ? undefined : ownerName(page, parts.field);
+        const entry = owner === undefined ? undefined : entries.find((candidate) => [comparableText(candidate.name), comparableText(candidate.page.name)].includes(comparableText(owner)));
+        return page === undefined || entry === undefined ? [] : [{ page, level: entry.level, order: entry.order }];
+    });
+}
+function partProblems(world, page, fields, rule, entries) {
+    if (rule.parts === undefined) {
+        return [];
+    }
+    const { list, field } = rule.parts;
+    const featuresField = fieldName(rule.features);
+    return listItems(valueNamed(fields, list)).flatMap((item) => {
+        const part = pageNamed(world, item.name);
+        if (part === undefined) {
+            return [];
+        }
+        const owner = ownerName(part, field);
+        const unlevelled = levelledFeatures(listItemsOf(valueNamed(part.fields, featuresField))).some((gained) => gained === undefined);
+        const message = owner === undefined
+            ? `${part.name} names no ${field}, so it adds no ${featuresField} to ${page.name}.`
+            : !entries.some((entry) => [comparableText(entry.name), comparableText(entry.page.name)].includes(comparableText(owner)))
+                ? `${part.name} is a part of ${owner}, which is not in ${rule.list} on ${page.name}: it adds nothing.`
+                : unlevelled
+                    ? `${part.name} lists ${featuresField} without the level at which each comes, such as "Improved Critical 3": those are left out.`
+                    : undefined;
+        return message === undefined
+            ? []
+            : [{
+                    path: page.path,
+                    message,
+                    fix: owner === undefined
+                        ? `write ${part.name}, set ${field}=[[...]] and ${featuresField} with their levels`
+                        : unlevelled
+                            ? `write ${part.name}, set ${featuresField} with the level of each, such as [Improved Critical 3]`
+                            : `add ${owner} to ${rule.list} on ${page.name}, or remove ${part.name} from ${list}`,
+                }];
+    });
+}
+/** The name of the item a part names in its field, such as Fighter for class: [[Fighter]]. */
+function ownerName(page, field) {
+    return listItems(valueNamed(page.fields, field))[0]?.name;
+}
+/** The items of a list as text, a single value as a list of one. */
+function listItemsOf(value) {
+    return (value === undefined || value === null ? [] : Array.isArray(value) ? value : [value]).map((item) => String(item));
+}
+/** The page with this name, the campaign's first, then the system's (SYS-3). */
+function pageNamed(world, name) {
+    const [named] = pagesWithName(world, name);
+    return named ?? systemPageNamed(world, name);
+}

package/dist/commands/rename.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+interface RenameResult {
+    from: string;
+    to: string;
+    path: string;
+    /** How many links now name it, and in which pages. */
+    links: number;
+    pages: string[];
+    /** The other page that keeps the old name, whose links are left as they are. */
+    kept?: string;
+}
+export declare const rename: import("../core/registry.ts").Command<z.ZodObject<{
+    page: z.ZodString;
+    to: z.ZodString;
+}, z.core.$strip>, RenameResult>;
+export {};

package/dist/commands/rename.js

@@ -0,0 +1,116 @@
+import { join } from "node:path";
+import { parseDocument } from "yaml";
+import { z } from "zod";
+import { requireCampaign } from "../campaign/index.js";
+import { appendLogEntry } from "../core/log.js";
+import { defineCommand } from "../core/registry.js";
+import { files } from "../core/store.js";
+import { comparableText } from "../core/text.js";
+import { applyRename, pageNamed, pageWithPath, planRename, renamedLinks } from "../pages/index.js";
+import { readOpenScene, updateScene } from "./game-scene.js";
+import { newDatedLogEntry } from "./game-time.js";
+import { campaignWorld } from "./game-world.js";
+export const rename = defineCommand({
+    name: "rename",
+    description: "Give a page of the campaign a new name, as when the player names their wolf or the character learns a place's true name. "
+        + "Every link to it follows, in the pages and the open scene; the old name stays among its aliases. "
+        + "Of two pages with the same name, give the one to rename by its path, as validate shows it: the links to that name stay with the other. "
+        + "Example: page Lupa, to Neve.",
+    group: "game",
+    positionals: ["page", "to"],
+    input: z.object({
+        page: z.string().describe("the page to rename: its name, or its path, as world/characters/Varro.md"),
+        to: z.string().describe("its new name"),
+    }),
+    run(input, context) {
+        const root = requireCampaign(context.folder);
+        const world = campaignWorld(root, context);
+        const page = pageAtPath(world, input.page) ?? pageNamed(world, input.page);
+        const to = input.to.trim().normalize("NFC");
+        if (page === undefined) {
+            throw new Error(`There is no page ${input.page}: look for its name with find. Nothing changed.`);
+        }
+        if (to === page.name) {
+            throw new Error(`${page.name} is already its name. Nothing changed.`);
+        }
+        const { scene } = readOpenScene(root);
+        const copy = Object.keys(scene?.copies ?? {}).find((name) => comparableText(name) === comparableText(to));
+        if (copy !== undefined) {
+            throw new Error(`${copy} is a copy in the open scene: give ${page.name} another name, or close the scene first. Nothing changed.`);
+        }
+        const from = page.name;
+        // Everything is checked before anything is written: the open scene first, then the page's new file, the links, and the old file last.
+        const plan = planRename(world, page, to);
+        if (plan.kept === undefined) {
+            renameInState(root, from, to);
+        }
+        try {
+            applyRename(plan);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(`${from} was renamed only in part (${reason}). Fix what stopped it, such as a file read-only or open in another program, then call rename ${from} ${to} again to finish.`);
+        }
+        appendLogEntry(root, newDatedLogEntry(root, context, "page-renamed", "public", { from, to, path: plan.path }));
+        return { from, to, path: plan.path, links: plan.links, pages: plan.pages, ...(plan.kept === undefined ? {} : { kept: plan.kept }) };
+    },
+    format(result) {
+        const links = result.pages.length === 0 ? "" : ` Links renamed in ${result.pages.join(", ")}.`;
+        const alias = comparableText(result.from) === comparableText(result.to) ? "" : ` ${result.from} stays among its aliases, so that what keeps the old name still finds it.`;
+        const kept = result.kept === undefined
+            ? ""
+            : ` The links to ${result.from}, in the pages and in the open scene, stay as they are and lead to ${result.kept}, which keeps that name: write [[${result.to}]] by hand in those meant for this page.`;
+        return `Renamed ${result.from} to ${result.to} (${result.path}).${links}${alias}${kept}`;
+    },
+});
+/** The page at a path of the campaign, as world/characters/Varro.md, with or without .md; undefined for a name. */
+function pageAtPath(world, given) {
+    const path = given.trim().split("\\").join("/").replace(/^\.\//, "");
+    if (!path.includes("/")) {
+        return undefined;
+    }
+    const page = pageWithPath(world, path.toLowerCase().endsWith(".md") ? path : `${path}.md`);
+    if (page === undefined) {
+        throw new Error(`There is no page at ${given}: give the path as validate shows it, such as world/characters/Varro.md, or the page's name. Nothing changed.`);
+    }
+    return page;
+}
+/**
+ * The present follows the new name: its links, and the open scene's names, as its order, its turn and who is hostile (D-415, D-416). Refused, changing
+ * nothing, when the links renamed would leave state.yaml unreadable.
+ */
+function renameInState(root, from, to) {
+    const path = join(root, "state.yaml");
+    const text = files().fresh(path);
+    const { renamed, count } = renamedLinks(text ?? "", from, to);
+    if (count > 0 && parseDocument(text ?? "").errors.length === 0 && parseDocument(renamed).errors.length > 0) {
+        throw new Error(`Renaming ${from} to ${to} would leave state.yaml unreadable, as a ' in a link written between '…' quotes: choose a name without ', or rewrite that line of state.yaml by hand between "…" quotes, then rename again. Nothing changed.`);
+    }
+    if (count > 0) {
+        files().write(path, renamed);
+    }
+    const { scene } = readOpenScene(root);
+    if (scene === undefined) {
+        return;
+    }
+    const named = (name) => (comparableText(name) === comparableText(from) ? to : name);
+    const list = (names) => names?.map(named);
+    const changes = [];
+    for (const [key, names] of [["order", scene.order], ["left", scene.left], ["hostile", scene.hostile]]) {
+        if (names !== undefined && names.some((name) => named(name) !== name)) {
+            changes.push([[key], list(names)]);
+        }
+    }
+    if (scene.turn !== undefined && named(scene.turn) !== scene.turn) {
+        changes.push([["turn"], to]);
+    }
+    if (scene.seen !== undefined && Object.keys(scene.seen).some((name) => named(name) !== name)) {
+        changes.push([["seen"], Object.fromEntries(Object.entries(scene.seen).map(([name, said]) => [named(name), said]))]);
+    }
+    if (scene.moved !== undefined && named(scene.moved.turn) !== scene.moved.turn) {
+        changes.push([["moved", "turn"], to]);
+    }
+    if (changes.length > 0) {
+        updateScene(root, changes);
+    }
+}

package/dist/commands/reveal.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+/** What reveal recorded, as its output tells it (REV-3): and the places the player's character now knows that have no point on the map, with one that has (D-319). */
+interface RevealResult {
+    learned: {
+        who: string;
+        what: string[];
+    }[];
+    known: {
+        who: string;
+        what: string[];
+    }[];
+    notSecret: {
+        what: string;
+        page: string;
+    }[];
+    unplaced?: {
+        places: string[];
+        from?: string;
+    };
+}
+export declare const reveal: import("../core/registry.ts").Command<z.ZodObject<{
+    page: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    to: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+}, z.core.$strip>, RevealResult>;
+export {};

package/dist/commands/reveal.js

@@ -0,0 +1,193 @@
+import { z } from "zod";
+import { requireCampaign } from "../campaign/index.js";
+import { appendLogEntry, readLog } from "../core/log.js";
+import { defineCommand } from "../core/registry.js";
+import { comparableText, withArticle } from "../core/text.js";
+import { baseChain, isEmptyField, isPartyMember, links, locate, pageNamed, parsePageReference, secretNames, shownPart, systemLabel, withPage, writePage } from "../pages/index.js";
+import { placedPosition } from "./game-positions.js";
+import { copyName, readOpenScene } from "./game-scene.js";
+import { newDatedLogEntry } from "./game-time.js";
+import { campaignWorld } from "./game-world.js";
+// A list, or one text, as an MCP client may send it.
+const textList = z.union([z.string(), z.array(z.string())]);
+export const reveal = defineCommand({
+    name: "reveal",
+    description: "Record what characters learn: a secret, as Page#Secret, or a whole page they did not know. "
+        + "Use it as soon as a character learns it. It adds the links to their knows and answers without the text: read a secret with show before you tell it. "
+        + "Example: page [Coppa#Veleno, Varro], to [Ettore, Bruna].",
+    group: "game",
+    positionals: ["page"],
+    input: z.object({
+        page: textList.describe("what they learn: Page#Secret, or a whole Page; one or a list"),
+        to: textList.optional().describe("who learns it: one or more characters, companions too when they learn it; the player's character alone if left out"),
+    }),
+    run(input, context) {
+        const root = requireCampaign(context.folder);
+        let world = campaignWorld(root, context);
+        const { scene } = readOpenScene(root);
+        const asked = listOf(input.page);
+        if (asked.length === 0) {
+            throw new Error("Give what they learn, such as page Coppa#Veleno, or a whole page such as Varro.");
+        }
+        // An empty to, as an MCP client may send it, is left out.
+        const to = input.to === undefined ? [] : listOf(input.to);
+        const learners = to.length === 0 ? [playerCharacter(world)] : [...new Set(to.map((name) => learnerOf(world, scene, name)))];
+        const found = asked.map((item) => learnableOf(root, world, item));
+        const known = found.filter((item) => item.kind === "known").filter((item, index, all) => all.findIndex((other) => sameLink(other.link, item.link)) === index);
+        learners.forEach(checkKnows);
+        const result = { learned: [], known: [], notSecret: found.filter((item) => item.kind === "public").map((item) => ({ what: item.shown, page: item.page })) };
+        const lines = [];
+        for (const learner of learners) {
+            const already = known.filter((item) => knowsLink(learner, item.link));
+            const learned = known.filter((item) => !already.includes(item));
+            if (already.length > 0) {
+                result.known.push({ who: learner.name, what: already.map((item) => item.shown) });
+            }
+            if (learned.length === 0) {
+                continue;
+            }
+            const written = writePage(world, learner.name, undefined, { add: { knows: learned.map((item) => item.link) } });
+            world = withPage(world, learner, written.page);
+            lines.push({ learner, links: learned.map((item) => item.link) });
+            result.learned.push({ who: learner.name, what: learned.map((item) => (item.asked === undefined ? item.shown : `${item.shown} (as ${item.asked} shows it)`)) });
+        }
+        logLearned(root, context, world, lines);
+        const unplaced = unplacedPlaces(world, lines);
+        return unplaced === undefined ? result : { ...result, unplaced };
+    },
+    format(result) {
+        const learned = result.learned.map((entry) => `${entry.who} now knows ${entry.what.join(", ")}.`);
+        const known = result.known.length === 0 ? "" : `Already known: ${result.known.map((entry) => `${entry.who}: ${entry.what.join(", ")}`).join("; ")}.`;
+        const notSecret = result.notSecret.length === 0 ? "" : `Not secrets, nothing to record: ${result.notSecret.map((entry) => `${entry.what} (whoever knows ${entry.page} knows it)`).join(", ")}.`;
+        const unplaced = result.unplaced === undefined ? "" : placesNote(result.unplaced.places, result.unplaced.from);
+        return [...(learned.length === 0 ? ["Nothing new to record."] : learned), known, notSecret, unplaced].filter((line) => line !== "").join(" ");
+    },
+});
+/**
+ * One line in the log for each who learned something (REV-3, D-158): public only for what the player's character knows, theirs and a companion's who learned it
+ * with them; what someone else learned alone stays hidden, since a secret's name may tell too much.
+ */
+function logLearned(root, context, world, lines) {
+    const players = world.pages.filter((page) => page.type === "character" && page.fields.role === "pc");
+    const playerKnows = (link) => players.some((player) => knowsLink(player, link));
+    for (const { learner, links: learned } of lines) {
+        const visible = learner.fields.role === "pc" || (isPartyMember(learner) && learned.every(playerKnows));
+        appendLogEntry(root, newDatedLogEntry(root, context, "learned", visible ? "public" : "hidden", { page: learner.name, knows: learned }));
+    }
+}
+/**
+ * The places the player's character just learned of that have no point on the map, neither their own nor from a place that holds them (D-319), as a found map
+ * may bring; and a place with a position to give theirs from. Undefined when there is none.
+ */
+function unplacedPlaces(world, lines) {
+    const player = lines.find((line) => line.learner.fields.role === "pc");
+    const places = (player?.links ?? []).flatMap((link) => links(link)).filter((link) => link.section === undefined).flatMap((link) => {
+        const page = pageNamed(world, link.page);
+        return page?.type === "place" && page.fields.stops === undefined && [page, ...locate(world, page).chain].every((holder) => placedPosition(world, holder) === undefined) ? [page.name] : [];
+    });
+    if (player === undefined || places.length === 0) {
+        return undefined;
+    }
+    const from = [...locate(world, player.learner).chain, ...world.pages].find((page) => placedPosition(world, page) !== undefined)?.name;
+    return { places, ...(from === undefined ? {} : { from }) };
+}
+/** What reveal says of places with no point on the map: they are not on it until they have a position, given from a place that has one (POS-2). */
+function placesNote(places, from) {
+    const example = `write ${places[0]}, set position="12 km NE of [[${from ?? "a place with a position"}]]"`;
+    return `${places.join(", ")} ${places.length === 1 ? "has" : "have"} no position, so the map does not show ${places.length === 1 ? "it" : "them"} yet: give one from a place that has one, such as ${example}.`;
+}
+/** What a name gives to learn (REV-2): a page, a secret where it is written, or a public section to skip. Anything that does not exist stops the command. */
+function learnableOf(root, world, item) {
+    const reference = parsePageReference(item);
+    if (reference.section === "") {
+        throw new Error(`Give the secret's name after #, such as ${reference.name}#Name: a secret without a name cannot be revealed until it has one. Nothing recorded.`);
+    }
+    const page = pageNamed(world, reference.name);
+    if (page === undefined) {
+        const roll = readLog(root).some((entry) => entry.type === "roll" && entry.visibility === "hidden" && entry.id === reference.name);
+        const why = roll ? `${reference.name} is a hidden roll: show its result with roll, reveal ${reference.name}.` : `There is no page named ${reference.name}: ${listHint(reference.name, "page") ?? "look for it with find."}`;
+        throw new Error(`${why} Nothing recorded.`);
+    }
+    if (page.system !== undefined) {
+        throw new Error(`${page.name} is ${systemLabel(page)}: it holds no secrets, and anyone may know what it says. Nothing recorded.`);
+    }
+    if (reference.section === undefined) {
+        return { kind: "known", link: `[[${page.name}]]`, shown: page.name };
+    }
+    const part = shownPart(world, page, reference.section);
+    if (part === undefined) {
+        throw new Error(`${missingSecret(world, page, reference.section)} Nothing recorded.`);
+    }
+    const shown = `${part.holder.name}#${part.title}`;
+    return part.secret ? { kind: "known", link: `[[${shown}]]`, shown, asked: part.holder === page ? undefined : page.name } : { kind: "public", shown: `${page.name}#${part.title}`, page: page.name };
+}
+/** What a page that lacks a secret has instead, and how to give it one: its secrets and those of its bases, and those without a name. */
+function missingSecret(world, page, name) {
+    const holders = [page, ...baseChain(world, page)];
+    const named = holders.flatMap((holder) => secretNames(holder.body).filter((title) => title !== "").map((title) => (holder === page ? title : `${title} (from ${holder.name})`)));
+    const listed = named.length === 0 ? "It has no secrets." : `Its secrets: ${named.join(", ")}.`;
+    const nameless = holders.some((holder) => secretNames(holder.body).includes("")) ? " It has a secret without a name: give it one, as > [!secret] Name, to reveal it." : "";
+    return `${page.name} has no section or secret "${name}". ${listed}${nameless} To write a new one, write ${page.name}#Name with secret and its text.`;
+}
+/** Who learns, when not said: the player's character, when there is one only (REV-2). */
+function playerCharacter(world) {
+    const players = world.pages.filter((page) => page.type === "character" && page.fields.role === "pc");
+    if (players.length !== 1) {
+        throw new Error(players.length === 0 ? "There is no player's character: give who learns it with to." : `There are ${players.length} player's characters, ${players.map((page) => page.name).join(" and ")}: give who learns it with to.`);
+    }
+    return players[0];
+}
+/** A character who learns: only characters know things (REV-1); a copy in the open scene keeps nothing of its own. */
+function learnerOf(world, scene, name) {
+    const reference = parsePageReference(name).name;
+    const copy = copyName(world, scene, reference);
+    if (copy !== undefined) {
+        throw new Error(`${copy} is a copy in the open scene, which keeps nothing of its own: only characters know things. Nothing recorded.`);
+    }
+    const page = pageNamed(world, reference);
+    if (page?.type !== "character") {
+        throw new Error(page === undefined
+            ? `There is no character named ${reference}: ${listHint(reference, "to") ?? "look for them with find."} Nothing recorded.`
+            : `${page.name} is ${withArticle(page.type ?? "free page")}: only characters know things. Nothing recorded.`);
+    }
+    return page;
+}
+/** knows takes items only as a list of links: one written otherwise stops the command before anything is written, for everyone. */
+function checkKnows(learner) {
+    const knows = learner.fields.knows;
+    if (!isEmptyField(knows) && !Array.isArray(knows)) {
+        throw new Error(`knows on ${learner.name} is ${JSON.stringify(knows)}, not a list: write it as one first, such as write ${learner.name}, set knows=[[A]], [[B]]. Nothing recorded.`);
+    }
+    const entries = Array.isArray(knows) ? knows : [];
+    const wrong = entries.find((entry) => typeof entry !== "string" || !/^\[\[[^\]]+\]\]$/.test(entry.trim()));
+    if (wrong !== undefined) {
+        const rewritten = entries.flatMap(linksOfEntry);
+        const fix = rewritten.length === 0 ? `write ${learner.name}, unset knows` : `write ${learner.name}, set knows=${rewritten.join(", ")}`;
+        throw new Error(`knows on ${learner.name} holds ${JSON.stringify(wrong)}, which is not a link: write the list again first, such as ${fix}. Nothing recorded.`);
+    }
+}
+/** The links an entry of knows holds, as links: those in a text, or the one YAML reads as a list in a list from [[Page]] written without quotes. */
+function linksOfEntry(entry) {
+    if (typeof entry === "string") {
+        return links(entry).map((link) => `[[${link.page}${link.section === undefined ? "" : `#${link.section}`}]]`);
+    }
+    const inner = Array.isArray(entry) && entry.length === 1 ? entry[0] : undefined;
+    return Array.isArray(inner) && inner.length === 1 && typeof inner[0] === "string" ? [`[[${inner[0]}]]`] : [];
+}
+/** How to give more than one name, when a name with commas names no page: a list sent as one text, as some clients do; undefined for any other name. */
+function listHint(name, field) {
+    return name.includes(",") ? `for more than one, give a list, such as ${field} [${name.split(",").map((part) => part.trim()).join(", ")}].` : undefined;
+}
+/** Whether a character's knows holds a link, however written. */
+function knowsLink(learner, link) {
+    const knows = learner.fields.knows;
+    return (Array.isArray(knows) ? knows : []).some((entry) => typeof entry === "string" && sameLink(entry, link));
+}
+/** Whether two texts are the same link: [[coppa#veleno]] and [[Coppa#Veleno]]. */
+function sameLink(first, second) {
+    const key = (text) => links(text).map((link) => comparableText(`${link.page}#${link.section ?? ""}`)).join("|");
+    return key(first) !== "" && key(first) === key(second);
+}
+function listOf(value) {
+    return (typeof value === "string" ? [value] : value).filter((item) => item.trim() !== "");
+}

package/dist/commands/roll.d.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import type { Context } from "../core/context.ts";
+import { type Page, type World } from "../pages/index.ts";
+import type { GameSystem } from "../systems/index.ts";
+export declare const roll: import("../core/registry.ts").Command<z.ZodObject<{
+    notation: z.ZodOptional<z.ZodString>;
+    why: z.ZodOptional<z.ZodString>;
+    check: z.ZodOptional<z.ZodString>;
+    who: z.ZodOptional<z.ZodString>;
+    values: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodNumber>, unknown>>;
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    reveal: z.ZodOptional<z.ZodString>;
+    keep: z.ZodOptional<z.ZodString>;
+    use: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, {
+    kind: "roll";
+    id: string;
+    text: string;
+    total: number;
+    why?: string;
+    who?: string;
+    check?: string;
+    physical: boolean;
+    hidden: boolean;
+    fingerprint?: string;
+    note?: string;
+    kept?: string;
+} | {
+    kind: "reveal";
+    id: string;
+    text: string;
+    proof: string;
+    sha256: string;
+    fingerprint: string;
+}>;
+/**
+ * The page of who rolls, a character or a copy in the open scene, with its world; undefined when who names neither, as a free label does. Without names to
+ * read, a name two pages share is a label too: the roll needs no sheet.
+ */
+export declare function rollerOf(root: string, context: Context, who: string | undefined, readsSheet: boolean): {
+    world: World;
+    page: Page;
+} | undefined;
+/** Whether a notation names a field, such as athletics in 1d20+athletics (DAT-8). */
+export declare function hasNames(notation: string): boolean;
+/** The notation with each name of a field as 0, to tell whether it is dice before a sheet is read: 1d20+athletics as 1d20+0. */
+export declare function namesAsZero(notation: string): string;
+/** The notation with each name of a field replaced by its value on the sheet of who rolls, effects and formulas included, and the values taken (DAT-8). */
+export declare function withSheetValues(notation: string, roller: {
+    world: World;
+    page: Page;
+} | undefined, who: string | undefined, system: GameSystem | undefined): {
+    notation: string;
+    taken: Record<string, number>;
+};