rpg-engine 0.0.0-stage → 0.1.0

package/dist/dice/evaluate.d.ts

@@ -0,0 +1,30 @@
+import { type Term } from "./notation.ts";
+export interface Die {
+    /** Final value; with compounding explosions, the sum of its faces. */
+    value: number;
+    /** Faces that make up the value: more than one only with compounding explosions. */
+    faces: number[];
+    /** The face this die showed before its reroll. */
+    rerolledFrom?: number;
+    dropped?: boolean;
+    success?: boolean;
+}
+export interface TermResult {
+    term: Term;
+    dice: Die[];
+    total: number;
+}
+export interface RollBreakdown {
+    total: number;
+    terms: TermResult[];
+}
+/** Returns the next face of a die with the given sides. */
+export type NextFace = (sides: number | "F") => number;
+export declare function evaluateTerms(terms: Term[], nextFace: NextFace): RollBreakdown;
+export declare function digitalFaces(random: (sides: number) => number): NextFace;
+/** Faces from the values the player rolled, used in order: impossible or missing values are errors. */
+export declare function physicalFaces(values: number[]): {
+    nextFace: NextFace;
+    unusedCount(): number;
+};
+export declare function dieName(sides: number | "F"): string;

package/dist/dice/evaluate.js

@@ -0,0 +1,90 @@
+import { DiceError, matches } from "./notation.js";
+const maxExplosions = 100;
+export function evaluateTerms(terms, nextFace) {
+    const results = terms.map((term) => {
+        return term.kind === "constant" ? { term, dice: [], total: term.sign * term.value } : rollDiceTerm(term, nextFace);
+    });
+    return { total: results.reduce((sum, result) => sum + result.total, 0), terms: results };
+}
+export function digitalFaces(random) {
+    return (sides) => (sides === "F" ? random(3) - 2 : random(sides));
+}
+/** Faces from the values the player rolled, used in order: impossible or missing values are errors. */
+export function physicalFaces(values) {
+    let usedCount = 0;
+    return {
+        nextFace(sides) {
+            if (usedCount >= values.length) {
+                throw new DiceError(`The roll needs one more ${dieName(sides)}, for a reroll or an explosion: ask the player to roll it.`);
+            }
+            const value = values[usedCount++];
+            const [lowest, highest] = sides === "F" ? [-1, 1] : [1, sides];
+            if (!Number.isInteger(value) || value < lowest || value > highest) {
+                throw new DiceError(`Impossible value ${value} on a ${dieName(sides)}: ask the player to roll it again.`);
+            }
+            return value;
+        },
+        unusedCount: () => values.length - usedCount,
+    };
+}
+export function dieName(sides) {
+    return sides === "F" ? "Fudge die" : `d${sides}`;
+}
+function rollDiceTerm(term, nextFace) {
+    const dice = [];
+    let explosionCount = 0;
+    for (let index = 0; index < term.count; index++) {
+        const firstFace = nextFace(term.sides);
+        const die = { value: firstFace, faces: [firstFace] };
+        if (term.rerollOnce && matches(term.rerollOnce, firstFace)) {
+            const rerolledFace = nextFace(term.sides);
+            die.value = rerolledFace;
+            die.faces = [rerolledFace];
+            die.rerolledFrom = firstFace;
+        }
+        dice.push(die);
+        if (!term.explode) {
+            continue;
+        }
+        let lastFace = die.value;
+        while (matches(term.explode.condition, lastFace)) {
+            if (++explosionCount > maxExplosions) {
+                throw new DiceError("Too many explosions in a single roll.");
+            }
+            lastFace = nextFace(term.sides);
+            if (term.explode.compound) {
+                die.faces.push(lastFace);
+                die.value += lastFace;
+            }
+            else {
+                dice.push({ value: lastFace, faces: [lastFace] });
+            }
+        }
+    }
+    if (term.keep || term.drop) {
+        markDropped(dice, term);
+    }
+    const keptDice = dice.filter((die) => !die.dropped);
+    if (term.success) {
+        for (const die of keptDice) {
+            die.success = matches(term.success, die.value);
+        }
+        return { term, dice, total: term.sign * keptDice.filter((die) => die.success).length };
+    }
+    return { term, dice, total: term.sign * keptDice.reduce((sum, die) => sum + die.value, 0) };
+}
+function markDropped(dice, term) {
+    const indexesByValue = dice.map((_, index) => index).sort((left, right) => dice[left].value - dice[right].value || left - right);
+    let droppedIndexes;
+    if (term.keep) {
+        const keepCount = Math.min(term.keep.count, dice.length);
+        droppedIndexes = term.keep.which === "highest" ? indexesByValue.slice(0, dice.length - keepCount) : indexesByValue.slice(keepCount);
+    }
+    else {
+        const dropCount = Math.min(term.drop.count, dice.length);
+        droppedIndexes = term.drop.which === "lowest" ? indexesByValue.slice(0, dropCount) : indexesByValue.slice(dice.length - dropCount);
+    }
+    for (const index of droppedIndexes) {
+        dice[index].dropped = true;
+    }
+}

package/dist/dice/format.d.ts

@@ -0,0 +1,3 @@
+import type { RollBreakdown } from "./evaluate.ts";
+/** One line such as `2d20kh1+5 = 19 [14, (7)] + 5`: dropped dice in parentheses, rerolls `1->6`, successes `8*`. */
+export declare function formatRoll(notation: string, breakdown: RollBreakdown): string;

package/dist/dice/format.js

@@ -0,0 +1,26 @@
+/** One line such as `2d20kh1+5 = 19 [14, (7)] + 5`: dropped dice in parentheses, rerolls `1->6`, successes `8*`. */
+export function formatRoll(notation, breakdown) {
+    const termTexts = breakdown.terms.map((termResult, index) => {
+        const sign = termResult.term.sign < 0 ? "- " : index === 0 ? "" : "+ ";
+        if (termResult.term.kind === "constant") {
+            return sign + termResult.term.value;
+        }
+        const isFudge = termResult.term.sides === "F";
+        return sign + "[" + termResult.dice.map((die) => formatDie(die, isFudge)).join(", ") + "]";
+    });
+    const countsSuccesses = breakdown.terms.some((termResult) => termResult.term.kind === "dice" && termResult.term.success);
+    return `${notation} = ${breakdown.total}${countsSuccesses ? " successes" : ""} ${termTexts.join(" ")}`;
+}
+function formatDie(die, isFudge) {
+    let dieText = isFudge ? fudgeSymbol(die.value) : die.faces.join("+");
+    if (die.rerolledFrom !== undefined) {
+        dieText = `${isFudge ? fudgeSymbol(die.rerolledFrom) : die.rerolledFrom}->${dieText}`;
+    }
+    if (die.success) {
+        dieText += "*";
+    }
+    return die.dropped ? `(${dieText})` : dieText;
+}
+function fudgeSymbol(value) {
+    return value > 0 ? "+" : value < 0 ? "-" : "0";
+}

package/dist/dice/index.d.ts

@@ -0,0 +1,4 @@
+export { DiceError, parseNotation } from "./notation.ts";
+export { createProof, fingerprint, sha256 } from "./proof.ts";
+export { type DiceRoll, type FaceSource, rollDice, type ThrownDie } from "./roll-dice.ts";
+export { type NotationPart, notationParts } from "./words.ts";

package/dist/dice/index.js

@@ -0,0 +1,5 @@
+// Dice for any game: notation, digital or physical faces, proofs for hidden rolls. Depends on nothing else in rpg-engine.
+export { DiceError, parseNotation } from "./notation.js";
+export { createProof, fingerprint, sha256 } from "./proof.js";
+export { rollDice } from "./roll-dice.js";
+export { notationParts } from "./words.js";

package/dist/dice/notation.d.ts

@@ -0,0 +1,43 @@
+/** A comparison against a die face, such as `>=8` or `=1`. */
+export interface Condition {
+    operator: "=" | "<" | "<=" | ">" | ">=";
+    value: number;
+}
+export interface DiceTerm {
+    kind: "dice";
+    sign: 1 | -1;
+    count: number;
+    /** Number of faces, or "F" for Fudge dice (-1, 0, +1). */
+    sides: number | "F";
+    /** Reroll a die once when it matches (`ro<=2`). */
+    rerollOnce?: Condition;
+    /** Roll an extra die when a die matches (`!`), or add it to the same die (`!!`). */
+    explode?: {
+        condition: Condition;
+        compound: boolean;
+    };
+    keep?: {
+        which: "highest" | "lowest";
+        count: number;
+    };
+    drop?: {
+        which: "highest" | "lowest";
+        count: number;
+    };
+    /** Count the dice that match instead of adding them up (`>=8`). */
+    success?: Condition;
+}
+export interface ConstantTerm {
+    kind: "constant";
+    sign: 1 | -1;
+    value: number;
+}
+export type Term = DiceTerm | ConstantTerm;
+/** A dice error the user or the AI can fix: its message says how. */
+export declare class DiceError extends Error {
+}
+/** Reads a notation valid for any game, such as `1d20+5`, `2d20kh1`, `4d6dl1`, `2d6ro<=2`, `1d6!`, `6d10>=8`, `4dF`, `d%`. */
+export declare function parseNotation(notation: string): Term[];
+/** How many dice the roll needs at least, before rerolls and explosions. */
+export declare function minimumDice(terms: Term[]): number;
+export declare function matches(condition: Condition, face: number): boolean;

package/dist/dice/notation.js

@@ -0,0 +1,132 @@
+/** A dice error the user or the AI can fix: its message says how. */
+export class DiceError extends Error {
+}
+const maxTerms = 20;
+const maxDice = 100;
+const maxSides = 1000;
+const conditionPattern = /^(<=|>=|<|>|=)(\d+)/;
+/** Reads a notation valid for any game, such as `1d20+5`, `2d20kh1`, `4d6dl1`, `2d6ro<=2`, `1d6!`, `6d10>=8`, `4dF`, `d%`. */
+export function parseNotation(notation) {
+    const compact = notation.replace(/\s+/g, "");
+    if (compact === "") {
+        throw new DiceError("The dice notation is empty.");
+    }
+    const signedTerms = compact.match(/[+-]?[^+-]+/g) ?? [];
+    if (signedTerms.join("") !== compact) {
+        throw new DiceError(`Cannot read "${notation}".`);
+    }
+    if (signedTerms.length > maxTerms) {
+        throw new DiceError(`Too many terms in "${notation}" (at most ${maxTerms}).`);
+    }
+    return signedTerms.map((signedTerm) => parseTerm(signedTerm, notation));
+}
+/** How many dice the roll needs at least, before rerolls and explosions. */
+export function minimumDice(terms) {
+    return terms.reduce((sum, term) => sum + (term.kind === "dice" ? term.count : 0), 0);
+}
+export function matches(condition, face) {
+    switch (condition.operator) {
+        case "=":
+            return face === condition.value;
+        case "<":
+            return face < condition.value;
+        case "<=":
+            return face <= condition.value;
+        case ">":
+            return face > condition.value;
+        case ">=":
+            return face >= condition.value;
+    }
+}
+function parseTerm(signedTerm, notation) {
+    const sign = signedTerm.startsWith("-") ? -1 : 1;
+    const termText = signedTerm.replace(/^[+-]/, "");
+    if (/^\d+$/.test(termText)) {
+        return { kind: "constant", sign, value: Number(termText) };
+    }
+    const match = /^(\d*)d(\d+|%|F)(.*)$/i.exec(termText);
+    if (!match) {
+        throw new DiceError(`Cannot read "${termText}" in "${notation}".`);
+    }
+    const [, countText, sidesText, modifiers] = match;
+    const count = countText === "" ? 1 : Number(countText);
+    const sides = sidesText.toUpperCase() === "F" ? "F" : sidesText === "%" ? 100 : Number(sidesText);
+    if (count < 1 || count > maxDice) {
+        throw new DiceError(`"${termText}": roll between 1 and ${maxDice} dice.`);
+    }
+    if (sides !== "F" && (sides < 2 || sides > maxSides)) {
+        throw new DiceError(`"${termText}": a die has between 2 and ${maxSides} faces.`);
+    }
+    const term = { kind: "dice", sign, count, sides };
+    if (modifiers !== "") {
+        if (sides === "F") {
+            throw new DiceError(`"${termText}": Fudge dice take no modifiers.`);
+        }
+        parseModifiers(modifiers, term, termText);
+    }
+    return term;
+}
+function parseModifiers(modifiers, term, termText) {
+    let remaining = modifiers;
+    while (remaining !== "") {
+        let match;
+        if ((match = /^ro(<=|>=|<|>|=)?(\d+)/i.exec(remaining))) {
+            if (term.rerollOnce) {
+                throw duplicateModifier(termText, "reroll");
+            }
+            term.rerollOnce = toCondition(match[1] ?? "=", match[2]);
+        }
+        else if ((match = /^(!!?)(?:(<=|>=|<|>|=)(\d+))?/.exec(remaining))) {
+            if (term.explode) {
+                throw duplicateModifier(termText, "explosion");
+            }
+            const explodeOn = match[2] ? toCondition(match[2], match[3]) : { operator: "=", value: term.sides };
+            if (everyFaceMatches(explodeOn, term.sides)) {
+                throw new DiceError(`"${termText}": the dice would explode forever.`);
+            }
+            term.explode = { condition: explodeOn, compound: match[1] === "!!" };
+        }
+        else if ((match = /^k([hl]?)(\d*)/i.exec(remaining))) {
+            if (term.keep || term.drop) {
+                throw duplicateModifier(termText, "keep or drop");
+            }
+            term.keep = { which: match[1].toLowerCase() === "l" ? "lowest" : "highest", count: match[2] === "" ? 1 : Number(match[2]) };
+            if (term.keep.count < 1 || term.keep.count > term.count) {
+                throw new DiceError(`"${termText}": keep between 1 and ${term.count} dice.`);
+            }
+        }
+        else if ((match = /^d([hl])(\d*)/i.exec(remaining))) {
+            if (term.keep || term.drop) {
+                throw duplicateModifier(termText, "keep or drop");
+            }
+            term.drop = { which: match[1].toLowerCase() === "l" ? "lowest" : "highest", count: match[2] === "" ? 1 : Number(match[2]) };
+            if (term.drop.count < 1 || term.drop.count >= term.count) {
+                throw new DiceError(`"${termText}": drop between 1 and ${term.count - 1} dice.`);
+            }
+        }
+        else if ((match = conditionPattern.exec(remaining))) {
+            if (term.success) {
+                throw duplicateModifier(termText, "success");
+            }
+            term.success = toCondition(match[1], match[2]);
+        }
+        else {
+            throw new DiceError(`"${termText}": unknown modifier "${remaining}".`);
+        }
+        remaining = remaining.slice(match[0].length);
+    }
+}
+function toCondition(operator, value) {
+    return { operator: operator, value: Number(value) };
+}
+function everyFaceMatches(condition, sides) {
+    for (let face = 1; face <= sides; face++) {
+        if (!matches(condition, face)) {
+            return false;
+        }
+    }
+    return true;
+}
+function duplicateModifier(termText, modifier) {
+    return new DiceError(`"${termText}": only one ${modifier} modifier per die.`);
+}

package/dist/dice/proof.d.ts

@@ -0,0 +1,4 @@
+/** The text a hidden roll commits to: once revealed, its SHA-256 must start with the fingerprint shown before. */
+export declare function createProof(rollId: string, rollText: string, salt: string): string;
+export declare function sha256(text: string): string;
+export declare function fingerprint(proof: string): string;

package/dist/dice/proof.js

@@ -0,0 +1,12 @@
+import { createHash } from "node:crypto";
+const fingerprintLength = 16;
+/** The text a hidden roll commits to: once revealed, its SHA-256 must start with the fingerprint shown before. */
+export function createProof(rollId, rollText, salt) {
+    return `${rollId}|${rollText}|${salt}`;
+}
+export function sha256(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+export function fingerprint(proof) {
+    return sha256(proof).slice(0, fingerprintLength);
+}

package/dist/dice/roll-dice.d.ts

@@ -0,0 +1,29 @@
+/** Where the faces come from: the digital generator, or the faces the player rolled with physical dice. */
+export type FaceSource = {
+    random(sides: number): number;
+} | {
+    values: number[];
+};
+export interface DiceRoll {
+    notation: string;
+    total: number;
+    /** One line such as `2d20kh1+5 = 19 [14, (7)] + 5`. */
+    text: string;
+    /** The value of each die, in order, dropped ones included: what a roll kept for later holds (KEP-2). */
+    faces: number[];
+    /** Each die as it was thrown, for who shows the throw (D-279). */
+    dice: ThrownDie[];
+}
+/**
+ * A die as it was thrown: its sides, the face it shows, the faces that add up on it with explosions, the face it showed before a reroll, and whether it was
+ * dropped or is a success.
+ */
+export interface ThrownDie {
+    sides: number | "F";
+    value: number;
+    faces?: number[];
+    rerolledFrom?: number;
+    dropped?: boolean;
+    success?: boolean;
+}
+export declare function rollDice(notation: string, source: FaceSource): DiceRoll;

package/dist/dice/roll-dice.js

@@ -0,0 +1,43 @@
+import { dieName, digitalFaces, evaluateTerms, physicalFaces } from "./evaluate.js";
+import { formatRoll } from "./format.js";
+import { DiceError, minimumDice, parseNotation } from "./notation.js";
+export function rollDice(notation, source) {
+    const terms = parseNotation(notation);
+    const breakdown = "values" in source ? rollPhysical(terms, source.values) : evaluateTerms(terms, digitalFaces(source.random));
+    return {
+        notation,
+        total: breakdown.total,
+        text: formatRoll(notation, breakdown),
+        faces: breakdown.terms.flatMap((term) => term.dice.map((die) => die.value)),
+        dice: breakdown.terms.flatMap((result) => {
+            const term = result.term;
+            return term.kind === "dice" ? result.dice.map((die) => thrownDie(term.sides, die)) : [];
+        }),
+    };
+}
+function rollPhysical(terms, values) {
+    const neededCount = minimumDice(terms);
+    if (values.length < neededCount) {
+        throw new DiceError(`This roll needs at least ${neededCount} values (${describeDice(terms)}), but ${values.length} were given.`);
+    }
+    const faces = physicalFaces(values);
+    const breakdown = evaluateTerms(terms, faces.nextFace);
+    const unusedCount = faces.unusedCount();
+    if (unusedCount > 0) {
+        throw new DiceError(`Too many values: ${values.length} given, but the roll used ${values.length - unusedCount}.`);
+    }
+    return breakdown;
+}
+function describeDice(terms) {
+    return terms.flatMap((term) => (term.kind === "dice" ? [`${term.count} ${dieName(term.sides)}`] : [])).join(", ");
+}
+function thrownDie(sides, die) {
+    return {
+        sides,
+        value: die.value,
+        ...(die.faces.length > 1 ? { faces: die.faces } : {}),
+        ...(die.rerolledFrom === undefined ? {} : { rerolledFrom: die.rerolledFrom }),
+        ...(die.dropped === true ? { dropped: true } : {}),
+        ...(die.success === undefined ? {} : { success: die.success }),
+    };
+}

package/dist/dice/words.d.ts

@@ -0,0 +1,12 @@
+import { type DiceTerm } from "./notation.ts";
+/** A part of a notation as the dashboard writes it in words: dice with what they do past rolling, as 2d20 keeping the highest, or a number added, as +5. */
+export type NotationPart = ({
+    dice: string;
+} & Pick<DiceTerm, "keep" | "drop" | "rerollOnce" | "explode" | "success">) | {
+    add: string;
+};
+/**
+ * A notation in parts, for the dashboard to say in words to a player who does not read it (D-292): 2d20kh1+5 is 2d20 keeping the highest, and +5; undefined for
+ * a notation that says nothing more than its dice and numbers, as 1d20+2, or that cannot be read.
+ */
+export declare function notationParts(notation: string): NotationPart[] | undefined;

package/dist/dice/words.js

@@ -0,0 +1,21 @@
+import { parseNotation } from "./notation.js";
+/**
+ * A notation in parts, for the dashboard to say in words to a player who does not read it (D-292): 2d20kh1+5 is 2d20 keeping the highest, and +5; undefined for
+ * a notation that says nothing more than its dice and numbers, as 1d20+2, or that cannot be read.
+ */
+export function notationParts(notation) {
+    try {
+        const terms = parseNotation(notation);
+        const ruled = terms.some((term) => term.kind === "dice" && rules(term).length > 0);
+        return ruled
+            ? terms.map((term) => (term.kind === "constant" ? { add: `${term.sign < 0 ? "−" : "+"}${term.value}` } : { dice: `${term.sign < 0 ? "−" : ""}${term.count}d${term.sides}`, ...Object.fromEntries(rules(term)) }))
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** What a term of dice does past rolling them: keep, drop, reroll, explode, count successes. */
+function rules(term) {
+    return ["keep", "drop", "rerollOnce", "explode", "success"].flatMap((rule) => (term[rule] === undefined ? [] : [[rule, term[rule]]]));
+}

package/dist/effects/effect.d.ts

@@ -0,0 +1,57 @@
+/**
+ * When an effect ends (EFF-2): at a game date, written as the time module reads it; at the start of someone's turn in a round of the scene;
+ * when the scene ends; or at an occasion of the game system, such as long rest, which only its recipe brings (DAT-5).
+ */
+export type EffectEnd = {
+    date: string;
+} | {
+    round: number;
+    turn: string;
+} | {
+    scene: true;
+} | {
+    occasion: string;
+};
+/** An effect on whoever has it (D-123, D-132): its name, who keeps it alive (D-138), the values it gives for a while, and when it ends, if it does. */
+export interface Effect {
+    name: string;
+    /** Who keeps it alive, such as a character concentrating on it, as written: a link to a page, or the name of a copy. */
+    by?: string;
+    /** Temporary values, by field, as written: [["ac", "15"]]. */
+    values: [string, string][];
+    end?: EffectEnd;
+}
+/** The effect a line of the effects field writes (EFF-1); or why it is not one. */
+export declare function readEffect(line: string): {
+    effect: Effect;
+} | {
+    problem: string;
+};
+/**
+ * The effects a field holds: one line, or a list of lines; an empty field holds none. Names are unique on a page (EFF-1).
+ * A line written in Obsidian without quotes, which YAML reads as "name (field": "value) until …", is read as the line it was.
+ */
+export declare function readEffects(value: unknown): {
+    effects: Effect[];
+} | {
+    problem: string;
+};
+/** An effect as its line is written (EFF-1), with who keeps it first among its values. */
+export declare function formatEffect(effect: Effect): string;
+/** An end as written: day 2, 14:20, round 12, Ennio, scene end, or long rest. */
+export declare function formatEnd(end: EffectEnd): string;
+/** How many rounds a duration such as 3 rounds or 1 round gives; undefined for anything else. */
+export declare function readRounds(text: string): number | undefined;
+/** Whether a duration is the scene itself: the effect ends when the scene does. */
+export declare function isSceneDuration(text: string): boolean;
+/** The effects with one added, as the newest: an effect with the same name is replaced (EFF-3, EFF-4). */
+export declare function withEffect(effects: Effect[], effect: Effect): Effect[];
+/** Who keeps an effect alive, by name: [[Lena]] and Lena are the same; undefined when no one does. */
+export declare function keeperOf(effect: Effect): string | undefined;
+/** The effect with this name, ignoring case and how accents are written. */
+export declare function effectNamed(effects: Effect[], name: string): Effect | undefined;
+/** Whether an effect counted in rounds has ended when the turn passes to `turn` in `round` (EFF-9): at its turn in its round, at the start of its round when that one is no longer in the order, a round later anyway. */
+export declare function endsAtTurn(end: {
+    round: number;
+    turn: string;
+}, round: number, turn: string, order: string[]): boolean;

package/dist/effects/effect.js

@@ -0,0 +1,123 @@
+import { comparableText } from "../core/text.js";
+// "Scudo della fede (by: [[Lena]], ac: 15) until day 2, 14:20": a name, values in brackets, an end; the brackets and the end may be missing.
+const linePattern = /^(.+?)(?:\s+\(([^()]*)\))?(?:\s+until\s+(.+))?$/i;
+const roundPattern = /^round\s+(\d{1,9})\s*,\s*(.+)$/i;
+const roundsPattern = /^(\d{1,4})\s*rounds?$/i;
+const sceneEnd = "scene end";
+/** The effect a line of the effects field writes (EFF-1); or why it is not one. */
+export function readEffect(line) {
+    const match = linePattern.exec(line.trim());
+    if (match === null) {
+        return { problem: `"${line}" is not an effect: write its name, then its values in brackets and its end, such as Scudo della fede (ac: 15) until day 2, 14:20.` };
+    }
+    const [, written, valuesText, endText] = match;
+    const values = valuesText === undefined ? [] : readValues(valuesText);
+    // Brackets without values belong to the name, as in Forma (orso).
+    const name = values === undefined ? `${written} (${valuesText})` : written;
+    if (/\buntil\b/i.test(name)) {
+        return { problem: `"${line}" has "until" in its name: write the end after the name and the values, such as ${name.replace(/\s*\(?\s*\buntil\b.*$/i, "")} until day 2, 14:20.` };
+    }
+    const pairs = values ?? [];
+    const keeper = pairs.find(([field]) => comparableText(field) === "by");
+    const effect = { name, ...(keeper === undefined ? {} : { by: keeper[1] }), values: pairs.filter((pair) => pair !== keeper) };
+    return endText === undefined ? { effect } : withEnd(effect, endText);
+}
+/**
+ * The effects a field holds: one line, or a list of lines; an empty field holds none. Names are unique on a page (EFF-1).
+ * A line written in Obsidian without quotes, which YAML reads as "name (field": "value) until …", is read as the line it was.
+ */
+export function readEffects(value) {
+    if (value === undefined || value === null || (typeof value === "string" && value.trim() === "")) {
+        return { effects: [] };
+    }
+    const lines = (Array.isArray(value) ? value : [value]).map(asLine);
+    if (lines.some((line) => line === undefined)) {
+        return { problem: "effects must be a list of lines of text, such as Scudo della fede (ac: 15) until day 2, 14:20." };
+    }
+    const effects = [];
+    for (const line of lines.filter((text) => text.trim() !== "")) {
+        const read = readEffect(line);
+        if ("problem" in read) {
+            return read;
+        }
+        if (effects.some((effect) => sameName(effect.name, read.effect.name))) {
+            return { problem: `The effect ${read.effect.name} is written twice: keep one.` };
+        }
+        effects.push(read.effect);
+    }
+    return { effects };
+}
+/** An effect as its line is written (EFF-1), with who keeps it first among its values. */
+export function formatEffect(effect) {
+    const pairs = [...(effect.by === undefined ? [] : [["by", effect.by]]), ...effect.values];
+    const values = pairs.length === 0 ? "" : ` (${pairs.map(([field, value]) => `${field}: ${value}`).join(", ")})`;
+    return `${effect.name}${values}${effect.end === undefined ? "" : ` until ${formatEnd(effect.end)}`}`;
+}
+/** An end as written: day 2, 14:20, round 12, Ennio, scene end, or long rest. */
+export function formatEnd(end) {
+    return "date" in end ? end.date : "round" in end ? `round ${end.round}, ${end.turn}` : "occasion" in end ? end.occasion : sceneEnd;
+}
+/** How many rounds a duration such as 3 rounds or 1 round gives; undefined for anything else. */
+export function readRounds(text) {
+    const match = roundsPattern.exec(text.trim());
+    const rounds = match === null ? 0 : Number(match[1]);
+    return rounds > 0 ? rounds : undefined;
+}
+/** Whether a duration is the scene itself: the effect ends when the scene does. */
+export function isSceneDuration(text) {
+    return comparableText(text.trim()) === "scene";
+}
+/** The effects with one added, as the newest: an effect with the same name is replaced (EFF-3, EFF-4). */
+export function withEffect(effects, effect) {
+    return [...effects.filter((other) => !sameName(other.name, effect.name)), effect];
+}
+/** Who keeps an effect alive, by name: [[Lena]] and Lena are the same; undefined when no one does. */
+export function keeperOf(effect) {
+    return effect.by === undefined ? undefined : pageName(effect.by);
+}
+/** The effect with this name, ignoring case and how accents are written. */
+export function effectNamed(effects, name) {
+    return effects.find((effect) => sameName(effect.name, name));
+}
+/** Whether an effect counted in rounds has ended when the turn passes to `turn` in `round` (EFF-9): at its turn in its round, at the start of its round when that one is no longer in the order, a round later anyway. */
+export function endsAtTurn(end, round, turn, order) {
+    if (round !== end.round) {
+        return round > end.round;
+    }
+    return sameName(turn, end.turn) || !order.some((name) => sameName(name, end.turn));
+}
+function withEnd(effect, endText) {
+    const text = endText.trim();
+    if (comparableText(text) === sceneEnd) {
+        return { effect: { ...effect, end: { scene: true } } };
+    }
+    const round = roundPattern.exec(text);
+    if (round === null) {
+        // A date always has a number in it; an end without one is an occasion, such as long rest (DAT-5).
+        return { effect: { ...effect, end: /\d/.test(text) ? { date: text } : { occasion: text } } };
+    }
+    return Number(round[1]) < 1 ? { problem: `"${endText}" is not an end: rounds start from 1.` } : { effect: { ...effect, end: { round: Number(round[1]), turn: pageName(round[2]) } } };
+}
+/** "ac: 15, speed: 40 ft" as pairs; undefined when the text is not written as values. */
+function readValues(text) {
+    const pairs = text.split(/\s*,\s*(?=[^,:]+:)/).map((part) => {
+        const separator = part.indexOf(":");
+        return separator <= 0 ? undefined : [part.slice(0, separator).trim(), part.slice(separator + 1).trim()];
+    });
+    return pairs.length === 0 || pairs.some((pair) => pair === undefined || pair[0] === "" || pair[1] === "") ? undefined : pairs;
+}
+/** An item of the effects field as a line: text, or the map YAML makes of a line written without quotes. */
+function asLine(item) {
+    if (typeof item === "string") {
+        return item;
+    }
+    const entries = item !== null && typeof item === "object" && !Array.isArray(item) ? Object.entries(item) : [];
+    return entries.length === 1 && typeof entries[0][1] !== "object" ? `${entries[0][0]}: ${String(entries[0][1])}` : undefined;
+}
+/** A name as a link or a turn writes it: [[Annegato 1]] and Annegato 1 are the same. */
+function pageName(text) {
+    return text.trim().replace(/^\[\[(.*?)(?:\|.*)?\]\]$/, "$1").trim();
+}
+function sameName(first, second) {
+    return comparableText(first.trim()) === comparableText(second.trim());
+}

package/dist/effects/index.d.ts

@@ -0,0 +1 @@
+export { type Effect, type EffectEnd, effectNamed, endsAtTurn, formatEffect, formatEnd, isSceneDuration, keeperOf, readEffect, readEffects, readRounds, withEffect } from "./effect.ts";

package/dist/effects/index.js

@@ -0,0 +1,2 @@
+// Conditions and effects on whoever has them (D-123, D-132): a line of text each, with temporary values and an end in game time or in rounds. It knows no game.
+export { effectNamed, endsAtTurn, formatEffect, formatEnd, isSceneDuration, keeperOf, readEffect, readEffects, readRounds, withEffect } from "./effect.js";