@datamoc/mw_games 0.7.6 → 0.7.8

package/dist/mwl/runtime.js

@@ -1,9 +1,21 @@
 import { decodeSave, encodeSave } from './persistence.js';
 import { evaluateCondition } from './conditions.js';
 import { evaluateExpression } from './expression.js';
-import { integerAttribute, requiredAttribute } from './utils.js';
+import { booleanAttribute, booleanValue, integerAttribute, numberAttribute, requiredAttribute } from './utils.js';
+import { endLevelCarryover } from './carryover.js';
 const required = requiredAttribute;
 const integer = (node, attribute, fallback) => integerAttribute(node, attribute, fallback) ?? fallback;
+/**
+ * A fresh, empty world: no sides, units, maps or variables, at turn 1 and `playing`.
+ *
+ * @example
+ * ```ts
+ * import { createWorld } from '@datamoc/mw_games/mwl';
+ *
+ * const world = createWorld();
+ * console.log(world.turn, world.status); // 1 'playing'
+ * ```
+ */
 export function createWorld() {
     return {
         variables: {},
@@ -13,6 +25,7 @@ export function createWorld() {
         gold: {},
         turn: 1,
         status: 'playing',
+        sideStatus: {},
         map: null,
         timeOfDay: '',
         scheduleIndex: 0,
@@ -22,6 +35,14 @@ export function createWorld() {
  * Parse map text: one row per line, comma-separated codes. A token may be
  * `<side> <code>` to mark that side's keep/start, which is how a leader knows
  * where to appear.
+ *
+ * @example
+ * ```ts
+ * import { parseTerrain } from '@datamoc/mw_games/mwl';
+ *
+ * const map = parseTerrain('Gg,Gg\nGg,1 Kh');
+ * console.log(map.width, map.starts['1']); // 2 [{ x: 1, y: 1 }]
+ * ```
  */
 export function parseTerrain(text) {
     const rows = text
@@ -35,10 +56,11 @@ export function parseTerrain(text) {
     for (let y = 0; y < height; y++) {
         for (let x = 0; x < width; x++) {
             const token = rows[y]?.[x] ?? '_off^_usr';
-            const keep = /^([0-9]+)\s+(.+)$/.exec(token);
+            //`<side> <code>`: the side is the id `[side]` declares, so a named side works here too
+            const keep = /^([A-Za-z0-9_][\w.-]*)\s+(\S.*)$/.exec(token);
             if (keep) {
                 codes.push(keep[2]);
-                (starts[Number(keep[1])] ??= []).push({ x, y });
+                (starts[keep[1]] ??= []).push({ x, y });
             }
             else
                 codes.push(token);
@@ -54,6 +76,16 @@ export function parseTerrain(text) {
  * real data (pathfinding costs, combat formulas) stay in the engine adapter;
  * this runtime's `move` is a bounds and occupancy check, and `attack` applies
  * the amount the content asks for.
+ *
+ * @example
+ * ```ts
+ * import { compile, MwlRuntime } from '@datamoc/mw_games/mwl';
+ *
+ * const runtime = new MwlRuntime(compile('[game]\nschema=0.1\n[/game]'), {
+ *   resolveMap: () => 'Gg,Gg\nGg,Gg',
+ * });
+ * console.log(runtime.world.turn); // 1
+ * ```
  */
 export class MwlRuntime {
     constructor(game, options = {}) {
@@ -73,6 +105,8 @@ export class MwlRuntime {
         this.loadInitialContent();
         this.loadInitialUnits();
         this.loadLeaders();
+        //roles filter over the units, so this runs once they and the leaders are in the world
+        this.loadScenarioExtras();
     }
     run(trigger) {
         for (const event of this.nodes('event')) {
@@ -118,7 +152,7 @@ export class MwlRuntime {
                 continue;
             if (event.attributes.unit !== undefined && event.attributes.unit !== id)
                 continue;
-            if (event.attributes.side !== undefined && integer(event, 'side', Number.NaN) !== unit.side)
+            if (event.attributes.side !== undefined && event.attributes.side !== unit.side)
                 continue;
             if (!this.eventFiltersMatch(event))
                 continue;
@@ -150,18 +184,39 @@ export class MwlRuntime {
         return !filter || this.filterMatches(filter);
     }
     executeEvent(event) {
-        for (const command of event.children.filter((child) => child.tag !== 'condition' && child.tag !== 'filter' && child.tag !== 'filter_condition')) {
-            if (command.tag === 'say') {
-                this.showSay(command);
+        this.runBlock(this.commandChildren(event));
+    }
+    /**
+     * Runs a sequence of commands, with `say` and `dialogue` taking the message path rather
+     * than `executeNode`. Shared by an event's top level, an `[if]`/`[else]` body and a
+     * dialogue branch, so all three treat a nested pair the same way.
+     */
+    runBlock(children) {
+        for (let index = 0; index < children.length; index++) {
+            const child = children[index];
+            if (this.isConsumedElse(children, index))
+                continue;
+            if (child.tag === 'say') {
+                this.showSay(child);
                 continue;
             }
-            if (command.tag === 'dialogue') {
-                this.showDialogue(command);
+            if (child.tag === 'dialogue') {
+                this.showDialogue(child);
                 continue;
             }
-            this.executeNode(command);
+            this.executeNode(child);
         }
     }
+    /**
+     * Whether an `[else]` at `index` is the branch its immediately preceding `[if]` already ran.
+     * A taken `[if]` runs its own body and owns the `[else]`, so the loop skips that `[else]`;
+     * a false `[if]` ran nothing, so the `[else]` is left for the loop to run as its fallback.
+     * A free-standing `[else]` with no `[if]` before it is never consumed.
+     */
+    isConsumedElse(children, index) {
+        const previous = children[index - 1];
+        return children[index]?.tag === 'else' && previous?.tag === 'if' && this.nodeConditionMatches(previous);
+    }
     executeTracedEvent(event, trigger) {
         const id = event.attributes.id ??
             `${event.attributes.on ?? event.attributes.trigger ?? 'event'}@${event.location?.line ?? 0}`;
@@ -188,12 +243,13 @@ export class MwlRuntime {
         for (const child of node.children) {
             if (child.tag === 'message') {
                 this.showMessage(child.attributes);
-                const side = Number.parseInt(child.attributes.side ?? '', 10);
                 last = {
                     text: child.attributes.text ?? child.attributes.value ?? '',
                     ...(child.attributes.speaker === undefined ? {} : { speaker: child.attributes.speaker }),
                     ...(child.attributes.portrait === undefined ? {} : { portrait: child.attributes.portrait }),
-                    ...(Number.isFinite(side) ? { side } : {}),
+                    ...(child.attributes.side === undefined || child.attributes.side === ''
+                        ? {}
+                        : { side: child.attributes.side }),
                 };
             }
             else if (child.tag === 'say') {
@@ -206,7 +262,7 @@ export class MwlRuntime {
             if (child.tag !== 'choice' || !child.attributes.text)
                 continue;
             if (child.attributes.variable !== undefined &&
-                !sameValue(this.world.variables[child.attributes.variable], child.attributes.equals))
+                !sameValue(this.variableAt(child.attributes.variable), child.attributes.equals))
                 continue;
             const branches = child.children.filter((branch) => branch.tag === 'branch');
             if (branches.length) {
@@ -264,8 +320,7 @@ export class MwlRuntime {
             this.executeEvent(event);
         }
         else {
-            for (const command of choice.branch ?? [])
-                this.executeNode(command);
+            this.runBlock(choice.branch ?? []);
         }
         this.checkObjectives();
         return true;
@@ -294,11 +349,19 @@ export class MwlRuntime {
         Object.assign(this.world.gold, restored.gold ?? {});
         this.world.turn = restored.turn;
         this.world.status = restored.status;
+        this.world.sideStatus = { ...(restored.sideStatus ?? {}) };
         this.world.map = restored.map ?? null;
         this.world.timeOfDay = restored.timeOfDay ?? this.schedule[0] ?? '';
         this.world.scheduleIndex = restored.scheduleIndex ?? 0;
         // One-shot events stay spent across a load.
         this.world.firedEvents = [...(restored.firedEvents ?? [])];
+        // Scenario data a command may have changed, restored wholesale rather than merged: a load
+        // is that save's world, not this scenario's with a few fields over it.
+        this.world.villages = restored.villages ? structuredClone(restored.villages) : undefined;
+        this.world.clearedShroud = restored.clearedShroud ? structuredClone(restored.clearedShroud) : undefined;
+        this.world.roles = restored.roles ? structuredClone(restored.roles) : undefined;
+        this.world.objects = restored.objects ? structuredClone(restored.objects) : undefined;
+        this.world.story = restored.story ? structuredClone(restored.story) : undefined;
         this.world.pendingDialogue = restored.pendingDialogue;
         this.pendingDialogue = restored.pendingDialogue
             ? { id: restored.pendingDialogue.id, choices: [...restored.pendingDialogue.choices] }
@@ -337,6 +400,22 @@ export class MwlRuntime {
                 entry.controller = side.attributes.controller;
             if (side.attributes.recruit !== undefined)
                 entry.recruit = side.attributes.recruit;
+            //only what was written, so a world stays as small as the content that made it
+            if (side.attributes.team_name !== undefined)
+                entry.teamName = side.attributes.team_name;
+            if (side.attributes.user_team_name !== undefined)
+                entry.userTeamName = side.attributes.user_team_name;
+            if (side.attributes.share_vision !== undefined)
+                entry.shareVision = side.attributes.share_vision;
+            if (side.attributes.flag !== undefined)
+                entry.flag = side.attributes.flag;
+            if (side.attributes.village_gold !== undefined)
+                entry.villageGold = integer(side, 'village_gold', 0);
+            for (const key of ['heal', 'fog', 'shroud', 'hidden']) {
+                const written = side.attributes[key];
+                if (written !== undefined)
+                    entry[key] = written === 'yes' || written === 'true';
+            }
             this.world.sides[required(side, 'id')] = entry;
         }
         for (const map of this.nodes('map')) {
@@ -346,6 +425,60 @@ export class MwlRuntime {
                 this.world.map = this.buildMap(id, map);
         }
     }
+    /** Direct children of `[game]` with a tag, as opposed to `nodes` which searches the whole tree. */
+    topLevelNodes(tag) {
+        const game = this.game.roots.find((root) => root.tag === 'game');
+        return (game?.children ?? this.game.roots).filter((root) => root.tag === tag);
+    }
+    /**
+     * Scenario-level data that is not a side, a map or a unit: `[object]` placements, the `[story]`
+     * beats, and the `[role]` table. Kept as plain data on the world - the framework sequences and
+     * serialises it, and the game decides what an object does, what a story beat looks like, and
+     * what a role is for.
+     */
+    loadScenarioExtras() {
+        for (const object of this.topLevelNodes('object')) {
+            const x = integer(object, 'x', 0);
+            const y = integer(object, 'y', 0);
+            const entry = { x, y };
+            if (object.attributes.id !== undefined)
+                entry.id = object.attributes.id;
+            if (object.attributes.name !== undefined)
+                entry.name = object.attributes.name;
+            if (object.attributes.image !== undefined)
+                entry.image = object.attributes.image;
+            if (object.attributes.side !== undefined)
+                entry.side = object.attributes.side;
+            (this.world.objects ??= []).push(entry);
+        }
+        for (const story of this.topLevelNodes('story')) {
+            const text = story.attributes.text ?? story.attributes.value;
+            if (text === undefined)
+                continue;
+            const entry = { text };
+            if (story.attributes.title !== undefined)
+                entry.title = story.attributes.title;
+            if (story.attributes.image !== undefined)
+                entry.image = story.attributes.image;
+            if (story.attributes.music !== undefined)
+                entry.music = story.attributes.music;
+            (this.world.story ??= []).push(entry);
+        }
+        for (const role of this.topLevelNodes('role')) {
+            const name = role.attributes.role ?? role.attributes.name;
+            if (name === undefined)
+                continue;
+            //`role`/`name` on this tag name the role being assigned, not a unit to match, so the
+            //filter must not read either back as one - the same double duty `[store_unit]`'s
+            //`variable`/`name` has
+            const filter = withoutAttributes(role.attributes, 'role', 'name');
+            const matched = Object.entries(this.world.units).filter(([id, unit]) => unit.alive && unitMatchesFilter(unit, id, filter));
+            //a unit learns the role it was assigned, so a later `[filter] role=courier` finds it
+            for (const [, unit] of matched)
+                unit.role = name;
+            (this.world.roles ??= {})[name] = matched.map(([id]) => id);
+        }
+    }
     buildMap(id, node) {
         let text = node.attributes.terrain;
         if (!text && node.attributes.file && this.resolveMap)
@@ -356,7 +489,7 @@ export class MwlRuntime {
         for (const start of node.children) {
             if (start.tag !== 'start')
                 continue;
-            const side = optionalInteger(start, 'side');
+            const side = start.attributes.side;
             const x = optionalInteger(start, 'x');
             const y = optionalInteger(start, 'y');
             if (side !== undefined && x !== undefined && y !== undefined)
@@ -380,7 +513,14 @@ export class MwlRuntime {
                     entry.moves = stats.movement;
             }
             if (unit.attributes.side !== undefined)
-                entry.side = integer(unit, 'side', 0);
+                entry.side = unit.attributes.side;
+            if (unit.attributes.name !== undefined)
+                entry.name = unit.attributes.name;
+            if (unit.attributes.role !== undefined)
+                entry.role = unit.attributes.role;
+            const can_recruit = booleanAttribute(unit, 'can_recruit');
+            if (can_recruit !== undefined)
+                entry.can_recruit = can_recruit;
             this.world.units[id] = entry;
         }
     }
@@ -389,25 +529,27 @@ export class MwlRuntime {
             const leader = side.attributes.leader;
             if (!leader)
                 continue;
-            const sideNumber = optionalInteger(side, 'id');
-            if (sideNumber === undefined)
+            const sideId = side.attributes.id;
+            if (!sideId)
                 continue;
-            const starts = this.world.map?.starts[sideNumber];
+            const starts = this.world.map?.starts[sideId];
             if (!starts?.length)
                 continue;
             const stats = this.unitTypes.get(leader);
             for (const start of starts) {
                 if (this.unitAt(start.x, start.y))
                     continue;
-                const id = `${leader} ${sideNumber} (${start.x},${start.y})`;
+                const id = `${leader} ${sideId} (${start.x},${start.y})`;
                 this.world.units[id] = {
                     hp: stats?.hitpoints ?? 1,
                     x: start.x,
                     y: start.y,
                     alive: true,
                     type: leader,
-                    side: sideNumber,
+                    side: sideId,
                     moves: stats?.movement ?? 0,
+                    can_recruit: true,
+                    leader: true,
                 };
             }
         }
@@ -425,14 +567,109 @@ export class MwlRuntime {
                 break;
             }
             case 'spawn':
-                this.spawnUnit(node.attributes.type ?? '', node.attributes.side === undefined ? undefined : integer(node, 'side', 0), integer(node, 'x', 0), integer(node, 'y', 0), node.attributes.id ?? node.attributes.target, node.attributes.hp === undefined ? undefined : integer(node, 'hp', 1));
+                this.spawnUnit(node.attributes.type ?? '', node.attributes.side, integer(node, 'x', 0), integer(node, 'y', 0), node.attributes.id ?? node.attributes.target, node.attributes.hp === undefined ? undefined : integer(node, 'hp', 1));
                 break;
             case 'move':
                 this.applyMove(node.attributes.unit ?? required(node, 'target'), integer(node, 'x', 0), integer(node, 'y', 0));
                 break;
-            case 'kill':
-                this.killUnit(node.attributes.unit ?? required(node, 'target'));
+            case 'kill': {
+                //a named unit that is not there is a content error; a filter that matches nobody is not,
+                //which is what WML's own `[kill]` does. An empty filter matches every unit, there as
+                //here, which is worth knowing before writing one.
+                const named = node.attributes.unit ?? node.attributes.target;
+                if (named === undefined)
+                    killMatching(this.world, node.attributes);
+                else
+                    this.killUnit(named);
+                break;
+            }
+            case 'fire_event': {
+                const id = node.attributes.id ?? node.attributes.name;
+                if (!id)
+                    throw new Error('[fire_event] requires id');
+                this.fireEvent(id);
+                break;
+            }
+            case 'store_unit': {
+                const variable = node.attributes.variable ?? node.attributes.name ?? required(node, 'variable');
+                this.setVariableAt(variable, this.matchingUnits(node, ['variable', 'name']).map(([id, unit]) => ({ id, ...unitSnapshot(unit) })));
+                break;
+            }
+            case 'unstore_unit': {
+                const variable = required(node, 'variable');
+                for (const entry of this.storedUnits(variable))
+                    this.restoreUnit(entry, {});
+                break;
+            }
+            case 'recall': {
+                const stored = this.storedUnits(required(node, 'variable'));
+                const wanted = node.attributes.id ?? node.attributes.unit;
+                const entry = wanted === undefined ? stored[0] : stored.find((candidate) => candidate.id === wanted);
+                if (!entry)
+                    throw new Error(`[recall] found no stored unit${wanted === undefined ? '' : ` named ${wanted}`}`);
+                const placement = {};
+                if (node.attributes.x !== undefined)
+                    placement.x = integer(node, 'x', 0);
+                if (node.attributes.y !== undefined)
+                    placement.y = integer(node, 'y', 0);
+                if (node.attributes.side !== undefined)
+                    placement.side = node.attributes.side;
+                this.restoreUnit(entry, placement);
+                break;
+            }
+            case 'modify_unit': {
+                //WML separates which units (`[filter]`) from what changes (`[set]`); a bare
+                //`[modify_unit] hp=5` with no `[set]` changes every unit it matches
+                const changes = node.children.find((child) => child.tag === 'set')?.attributes ?? node.attributes;
+                for (const [, unit] of this.matchingUnits(node))
+                    applyUnitChanges(unit, changes);
+                break;
+            }
+            case 'heal_unit': {
+                const amount = optionalInteger(node, 'amount');
+                const absolute = optionalInteger(node, 'hp');
+                if (amount === undefined && absolute === undefined)
+                    throw new Error('[heal_unit] requires amount or hp');
+                for (const [, unit] of this.matchingUnits(node))
+                    unit.hp = absolute ?? unit.hp + (amount ?? 0);
+                break;
+            }
+            case 'set_terrain':
+                this.setTerrain(integer(node, 'x', 0), integer(node, 'y', 0), required(node, 'terrain'));
+                break;
+            case 'capture_village': {
+                const x = integer(node, 'x', 0);
+                const y = integer(node, 'y', 0);
+                const entry = { x, y, side: required(node, 'side') };
+                if (node.attributes.name !== undefined)
+                    entry.name = node.attributes.name;
+                (this.world.villages ??= {})[`${x},${y}`] = entry;
+                break;
+            }
+            case 'clear_shroud': {
+                const side = required(node, 'side');
+                const x = integer(node, 'x', 0);
+                const y = integer(node, 'y', 0);
+                const radius = integer(node, 'radius', 1);
+                const cleared = new Set(this.world.clearedShroud?.[side] ?? []);
+                for (let dy = -radius; dy <= radius; dy++)
+                    for (let dx = -radius; dx <= radius; dx++)
+                        cleared.add(`${x + dx},${y + dy}`);
+                (this.world.clearedShroud ??= {})[side] = [...cleared];
+                break;
+            }
+            case 'role': {
+                const name = node.attributes.role ?? node.attributes.name;
+                if (!name)
+                    throw new Error('[role] requires role');
+                //`role`/`name` here name the role being assigned, not a unit to match, so the filter
+                //must not read either back as one - the same exclusion the scenario-level role uses
+                const matched = this.matchingUnits(node, ['role', 'name']);
+                for (const [, unit] of matched)
+                    unit.role = name;
+                (this.world.roles ??= {})[name] = matched.map(([id]) => id);
                 break;
+            }
             case 'attack':
                 this.attack(node.attributes.defender ?? node.attributes.target ?? required(node, 'target'), integer(node, 'amount', 0));
                 break;
@@ -450,8 +687,7 @@ export class MwlRuntime {
                 if (limit < 1 || limit > 100_000)
                     throw new Error('MWL while max_iterations must be between 1 and 100000');
                 for (let iteration = 0; iteration < limit && this.nodeConditionMatches(node); iteration++)
-                    for (const child of node.children)
-                        this.executeNode(child);
+                    this.runBlock(this.commandChildren(node));
                 break;
             }
             case 'foreach': {
@@ -471,8 +707,7 @@ export class MwlRuntime {
                 for (let index = 0; index < entries.length; index++) {
                     this.setVariableAt(item, entries[index][1]);
                     this.setVariableAt(indexName, index);
-                    for (const child of node.children)
-                        this.executeNode(child);
+                    this.runBlock(this.commandChildren(node));
                 }
                 break;
             }
@@ -482,28 +717,43 @@ export class MwlRuntime {
                     child.attributes.equals !== undefined &&
                     sameValue(value, child.attributes.equals));
                 const fallback = node.children.find((child) => child.tag === 'default');
-                for (const child of (selected ?? fallback)?.children ?? [])
-                    this.executeNode(child);
+                this.runBlock((selected ?? fallback)?.children ?? []);
                 break;
             }
             case 'end_turn':
                 this.endTurn();
                 break;
             case 'win':
+                this.markSideResult(node.attributes.side, 'won');
                 this.world.status = 'won';
                 break;
             case 'lose':
+                this.markSideResult(node.attributes.side, 'lost');
                 this.world.status = 'lost';
                 break;
-            case 'if':
-                if (!this.nodeConditionMatches(node))
-                    break;
-                for (const child of node.children)
-                    this.executeNode(child);
+            case 'endlevel': {
+                const result = node.attributes.result === 'defeat' ? 'defeat' : 'victory';
+                this.world.status = result === 'defeat' ? 'lost' : 'won';
+                this.world.carryover = endLevelCarryover(this.world, endLevelSide(this.world, node.attributes.side), {
+                    result,
+                    bonus: integerAttribute(node, 'bonus'),
+                    carryoverPercentage: numberAttribute(node, 'carryover_percentage'),
+                    carryoverAdd: booleanAttribute(node, 'carryover_add'),
+                    nextScenario: node.attributes.next_scenario ?? null,
+                });
+                break;
+            }
+            case 'if': {
+                //an immediately following [else] is this branch's other half, not a separate
+                //command: the condition picks one body, and runBlock skips the [else] itself
+                const fallback = node.children.find((child) => child.tag === 'else');
+                const taken = this.nodeConditionMatches(node) ? node : fallback;
+                this.runBlock(taken ? this.commandChildren(taken) : []);
                 break;
+            }
             case 'else':
-                for (const child of node.children)
-                    this.executeNode(child);
+                //reachable at top level for a free-standing [else]; a paired one is run by its [if]
+                this.runBlock(this.commandChildren(node));
                 break;
             case 'hook':
                 this.runHook(node);
@@ -512,6 +762,15 @@ export class MwlRuntime {
                 throw new Error(`unknown MWL command: ${name}`);
         }
     }
+    /**
+     * A node's children that are commands to run, dropping the condition children the schema
+     * allows a branch to carry. A `[condition]` is read by the branch itself, never executed:
+     * `[if]`/`[while]` evaluate one through `nodeConditionMatches`, where running it as a command
+     * would be an unknown tag.
+     */
+    commandChildren(node) {
+        return node.children.filter((child) => child.tag !== 'condition' && child.tag !== 'filter' && child.tag !== 'filter_condition');
+    }
     runHook(node) {
         const reference = node.attributes.name ?? '';
         const hook = this.hooks?.command?.[reference];
@@ -545,12 +804,11 @@ export class MwlRuntime {
     showMessage(attributes) {
         if (!this.onMessage)
             return;
-        const side = Number.parseInt(attributes.side ?? '', 10);
         const message = {
             text: this.interpolate(attributes.text ?? attributes.value ?? ''),
             ...(attributes.speaker === undefined ? {} : { speaker: attributes.speaker }),
             ...(attributes.portrait === undefined ? {} : { portrait: attributes.portrait }),
-            ...(Number.isFinite(side) ? { side } : {}),
+            ...(attributes.side === undefined || attributes.side === '' ? {} : { side: attributes.side }),
         };
         this.onMessage(message);
     }
@@ -560,8 +818,7 @@ export class MwlRuntime {
      * same interpolation WML authors expect in story and dialogue strings.
      */
     interpolate(text) {
-        const variables = this.world.variables;
-        const numeric = Object.fromEntries(Object.entries(variables).filter((entry) => typeof entry[1] === 'number'));
+        const numeric = Object.fromEntries(Object.entries(this.world.variables).filter((entry) => typeof entry[1] === 'number'));
         const expanded = text.replace(/\$\(([^)]*)\)/g, (_whole, expression) => {
             try {
                 return String(evaluateExpression(expression, numeric));
@@ -571,7 +828,7 @@ export class MwlRuntime {
             }
         });
         return expanded.replace(/\$([A-Za-z_][A-Za-z0-9_.]*)/g, (_whole, name) => {
-            const value = variables[name];
+            const value = this.variableAt(name);
             return value === undefined || typeof value === 'boolean' ? '' : String(value);
         });
     }
@@ -585,7 +842,7 @@ export class MwlRuntime {
         // so content can alias changing values without arithmetic.
         const reference = /^\$([A-Za-z_][A-Za-z0-9_.]*)$/.exec(raw.trim());
         if (reference) {
-            const value = this.world.variables[reference[1]];
+            const value = this.variableAt(reference[1]);
             this.setVariableAt(name, value === undefined ? '' : value);
             return;
         }
@@ -597,35 +854,16 @@ export class MwlRuntime {
         this.setVariableAt(name, raw);
     }
     variableAt(path) {
-        let value = this.world.variables;
-        for (const part of path.split('.')) {
-            if (!value || typeof value !== 'object' || Array.isArray(value))
-                return undefined;
-            value = value[part];
-        }
-        return value;
+        return variableAtPath(this.world.variables, path);
     }
     setVariableAt(path, value) {
         const previous = this.variableAt(path);
-        const parts = path.split('.');
-        if (parts.length === 1) {
-            this.world.variables[path] = value;
-            this.onTrace?.({ type: 'variable', name: path, ...(previous === undefined ? {} : { previous }), value });
-            return;
-        }
-        let current = this.world.variables;
-        for (const part of parts.slice(0, -1)) {
-            const child = current[part];
-            if (!child || typeof child !== 'object' || Array.isArray(child))
-                current[part] = {};
-            current = current[part];
-        }
-        current[parts.at(-1)] = value;
+        setVariableAtPath(this.world.variables, path, value);
         this.onTrace?.({ type: 'variable', name: path, ...(previous === undefined ? {} : { previous }), value });
     }
     spawnUnit(type, side, x, y, id, hp) {
         const stats = type ? this.unitTypes.get(type) : undefined;
-        const key = id ?? `${type || 'unit'}#${side ?? 0}@${x},${y}`;
+        const key = id ?? `${type || 'unit'}#${side ?? ''}@${x},${y}`;
         this.world.units[key] = {
             hp: hp ?? stats?.hitpoints ?? 1,
             x,
@@ -642,6 +880,64 @@ export class MwlRuntime {
             throw new Error(`MWL unit is not alive: ${id}`);
         unit.alive = false;
     }
+    /**
+     * Live units a command's filter selects: its `[filter]` child when it has one, otherwise its
+     * own attributes, read by the same `unitMatchesFilter` an event filter and `[kill]` use. An
+     * empty filter matches every live unit, the rule `[kill]` already documents.
+     */
+    matchingUnits(node, exclude = []) {
+        const filter = node.children.find((child) => child.tag === 'filter');
+        //a `[filter]` child is a real unit filter and keeps every attribute; the node's own
+        //attributes are the fallback, minus whatever they mean to this command instead of a unit
+        const attributes = filter ? filter.attributes : withoutAttributes(node.attributes, ...exclude);
+        return Object.entries(this.world.units).filter(([id, unit]) => unit.alive && unitMatchesFilter(unit, id, attributes));
+    }
+    /** The unit snapshots `[store_unit]` wrote into a world variable, or a named content error. */
+    storedUnits(variable) {
+        const stored = this.variableAt(variable);
+        if (!Array.isArray(stored))
+            throw new Error(`MWL variable ${variable} is not a stored unit list; store one first`);
+        return stored.filter((entry) => !!entry && typeof entry === 'object' && !Array.isArray(entry));
+    }
+    /** Writes a stored snapshot back into the world, applying any placement overrides. */
+    restoreUnit(entry, placement) {
+        const id = typeof entry.id === 'string' ? entry.id : undefined;
+        if (!id)
+            throw new Error('a stored unit snapshot is missing its id');
+        const unit = {
+            hp: typeof entry.hp === 'number' ? entry.hp : 1,
+            x: placement.x ?? (typeof entry.x === 'number' ? entry.x : 0),
+            y: placement.y ?? (typeof entry.y === 'number' ? entry.y : 0),
+            alive: entry.alive !== false,
+        };
+        if (typeof entry.type === 'string')
+            unit.type = entry.type;
+        const side = placement.side ?? (typeof entry.side === 'string' ? entry.side : undefined);
+        if (side !== undefined)
+            unit.side = side;
+        if (typeof entry.moves === 'number')
+            unit.moves = entry.moves;
+        if (typeof entry.name === 'string')
+            unit.name = entry.name;
+        if (typeof entry.role === 'string')
+            unit.role = entry.role;
+        if (typeof entry.can_recruit === 'boolean')
+            unit.can_recruit = entry.can_recruit;
+        if (typeof entry.leader === 'boolean')
+            unit.leader = entry.leader;
+        this.world.units[id] = unit;
+    }
+    /** Changes one cell of the primary map, keeping the parsed grid and its size in step. */
+    setTerrain(x, y, terrain) {
+        const map = this.world.map;
+        if (!map)
+            throw new Error('[set_terrain] needs a loaded map');
+        if (x < 0 || y < 0 || x >= map.width || y >= map.height)
+            throw new Error(`[set_terrain] is outside the map: ${x},${y}`);
+        const codes = [...map.codes];
+        codes[y * map.width + x] = terrain;
+        this.world.map = { ...map, codes };
+    }
     addGold(side, delta) {
         this.world.gold[side] = (this.world.gold[side] ?? 0) + delta;
     }
@@ -650,6 +946,22 @@ export class MwlRuntime {
         this.advanceSchedule();
         this.resetMoves();
         this.run('turn');
+        this.checkTimeOver();
+    }
+    /**
+     * Wesnoth's "time over", as a framework native: once the scenario's `turn_limit` has passed,
+     * `time_over` becomes a variable content can test and an event trigger it can answer. The
+     * framework reports it rather than ending anything, because a turn limit is usually a defeat and
+     * occasionally the whole point of the scenario ("hold out until then"), so what it means is
+     * content's business - `[endlevel]` is right there for it. Fired once, and derived from the turn
+     * counter rather than kept in step with it.
+     */
+    checkTimeOver() {
+        const limit = integerAttribute(this.game.roots[0], 'turn_limit');
+        if (limit === undefined || this.world.turn <= limit || this.world.variables.time_over === 'yes')
+            return;
+        this.world.variables.time_over = 'yes';
+        this.run('time_over');
     }
     advanceSchedule() {
         if (!this.schedule.length)
@@ -680,7 +992,20 @@ export class MwlRuntime {
     conditionMatches(node) {
         return node.children
             .filter((child) => child.tag === 'condition')
-            .every((condition) => variableMatches(this.world.variables[condition.attributes.variable], condition.attributes, primitiveVariables(this.world.variables)));
+            .every((condition) => {
+            if (condition.attributes.condition === 'hook') {
+                const hookName = condition.attributes.hook;
+                const predicateName = hookName?.startsWith('predicate:')
+                    ? hookName.slice('predicate:'.length)
+                    : undefined;
+                const predicate = predicateName ? this.hooks?.predicate?.[predicateName] : undefined;
+                if (!predicate)
+                    throw new Error(`MWL predicate ${predicateName ?? '<missing>'} is not implemented`);
+                const { condition: _condition, hook: _hook, ...context } = condition.attributes;
+                return Boolean(predicate(this.worldView(), context));
+            }
+            return variableMatches(this.variableAt(condition.attributes.variable), condition.attributes, resolveVariable(this.world.variables));
+        });
     }
     nodeConditionMatches(node) {
         if (node.attributes.test !== undefined)
@@ -702,7 +1027,7 @@ export class MwlRuntime {
                 const name = child.attributes.name;
                 if (name === undefined)
                     return false;
-                return variableMatches(this.world.variables[name], child.attributes, primitiveVariables(this.world.variables));
+                return variableMatches(this.variableAt(name), child.attributes, resolveVariable(this.world.variables));
             }
             if (child.tag === 'predicate') {
                 const name = child.attributes.name;
@@ -721,12 +1046,17 @@ export class MwlRuntime {
             return true;
         });
     }
-    conditionMet(node) {
+    /**
+     * Whether one objective's condition holds. `defaultSide` is the side whose own
+     * `[victory]`/`[defeat]` node this is, so a condition that names no side (a side losing
+     * when its own units are gone) reads as that side rather than as nobody.
+     */
+    conditionMet(node, defaultSide) {
         const condition = node.attributes.condition ?? '';
-        const side = optionalInteger(node, 'side');
+        const side = node.attributes.side ?? defaultSide;
         switch (condition) {
             case 'units_dead': {
-                const target = optionalInteger(node, 'side_filter') ?? side;
+                const target = node.attributes.side_filter ?? side;
                 if (target === undefined)
                     return false;
                 return !Object.values(this.world.units).some((unit) => unit.alive && unit.side === target);
@@ -737,14 +1067,13 @@ export class MwlRuntime {
             }
             case 'gold_at_least': {
                 const gold = optionalInteger(node, 'gold');
-                return (gold !== undefined &&
-                    node.attributes.side !== undefined &&
-                    (this.world.gold[node.attributes.side] ?? 0) >= gold);
+                const goldSide = node.attributes.side ?? defaultSide;
+                return gold !== undefined && goldSide !== undefined && (this.world.gold[goldSide] ?? 0) >= gold;
             }
             case 'unit_at': {
                 const x = optionalInteger(node, 'x');
                 const y = optionalInteger(node, 'y');
-                const targetSide = optionalInteger(node, 'side_filter') ?? side;
+                const targetSide = node.attributes.side_filter ?? side;
                 return Object.values(this.world.units).some((unit) => unit.alive &&
                     (targetSide === undefined || unit.side === targetSide) &&
                     (node.attributes.type === undefined || unit.type === node.attributes.type) &&
@@ -765,15 +1094,60 @@ export class MwlRuntime {
                 return false;
         }
     }
+    /**
+     * Evaluates the scenario-wide `[objectives]` conditions first, exactly as before, then each
+     * side's own `[victory]`/`[defeat]` children. The scenario ends on the first side whose own
+     * condition fires, recording that side in `world.sideStatus`; a side's victory outranks
+     * another side's defeat when both fire in the same evaluation, which is the same precedence
+     * the scenario-wide pair has always had. A side condition with no `side`/`side_filter` reads
+     * as that side's own, so "this side loses when it has no units left" is written without
+     * repeating the id.
+     */
     checkObjectives() {
         if (this.world.status !== 'playing')
             return;
-        if (this.nodes('victory').some((node) => this.conditionMet(node))) {
+        // a `[victory]`/`[defeat]` under a `[side]` is that side's own, never the scenario's
+        const sideConditions = new Set();
+        const sides = this.nodes('side');
+        for (const side of sides) {
+            for (const child of side.children) {
+                if (child.tag === 'victory' || child.tag === 'defeat')
+                    sideConditions.add(child);
+            }
+        }
+        if (this.nodes('victory').some((node) => !sideConditions.has(node) && this.conditionMet(node))) {
             this.world.status = 'won';
             return;
         }
-        if (this.nodes('defeat').some((node) => this.conditionMet(node)))
+        if (this.nodes('defeat').some((node) => !sideConditions.has(node) && this.conditionMet(node))) {
             this.world.status = 'lost';
+            return;
+        }
+        let sideWon = false;
+        let sideLost = false;
+        for (const side of sides) {
+            const id = side.attributes.id;
+            if (!id || (this.world.sideStatus?.[id] ?? 'playing') !== 'playing')
+                continue;
+            if (side.children.some((child) => child.tag === 'victory' && this.conditionMet(child, id))) {
+                this.markSideResult(id, 'won');
+                sideWon = true;
+            }
+            else if (side.children.some((child) => child.tag === 'defeat' && this.conditionMet(child, id))) {
+                this.markSideResult(id, 'lost');
+                sideLost = true;
+            }
+        }
+        if (sideWon)
+            this.world.status = 'won';
+        else if (sideLost)
+            this.world.status = 'lost';
+    }
+    /** Records one side's own result; the scenario status is set by whichever side fired first. */
+    markSideResult(side, result) {
+        if (side === undefined || side === '')
+            return;
+        (this.world.sideStatus ??= {})[side] = result;
     }
     worldView() {
         return {
@@ -791,16 +1165,18 @@ export class MwlRuntime {
             },
             spawn: (type, side, x, y) => this.spawnUnit(type, side, x, y),
             kill: (unit) => this.killUnit(unit),
-            gold: (side, delta) => this.addGold(String(side), delta),
+            gold: (side, delta) => this.addGold(side, delta),
             setVariable: (name, value) => {
-                this.world.variables[name] = value;
+                setVariableAtPath(this.world.variables, name, value);
             },
             message: (speaker, text) => this.onMessage?.({ text, ...(speaker ? { speaker } : {}) }),
             endTurn: () => this.endTurn(),
-            win: (_side) => {
+            win: (side) => {
+                this.markSideResult(side, 'won');
                 this.world.status = 'won';
             },
-            lose: (_side) => {
+            lose: (side) => {
+                this.markSideResult(side, 'lost');
                 this.world.status = 'lost';
             },
         };
@@ -824,12 +1200,24 @@ export class MwlRuntime {
         return result;
     }
 }
+/**
+ * Applies one already-validated `MwlCommand` to a world, without a runtime around it.
+ *
+ * @example
+ * ```ts
+ * import { createWorld, execute } from '@datamoc/mw_games/mwl';
+ *
+ * const world = createWorld();
+ * execute(world, { name: 'set_variable', target: 'gold', value: 50 });
+ * console.log(world.variables.gold); // 50
+ * ```
+ */
 export function execute(world, command) {
     if (world.status !== 'playing' && command.name !== 'win' && command.name !== 'lose')
         return;
     switch (command.name) {
         case 'set_variable':
-            world.variables[command.target] = command.value;
+            setVariableAtPath(world.variables, command.target, command.value);
             break;
         case 'modify_gold':
             world.gold[command.target] = (world.gold[command.target] ?? 0) + command.amount;
@@ -844,25 +1232,139 @@ export function execute(world, command) {
             world.units[command.target] = { hp: command.hp, x: command.x, y: command.y, alive: true };
             break;
         case 'kill':
-            requireUnit(world, command.target).alive = false;
+            if (command.target !== undefined)
+                requireUnit(world, command.target).alive = false;
+            else
+                killMatching(world, command.filter ?? {});
             break;
         case 'end_turn':
             world.turn++;
             break;
         case 'win':
+            if (command.side !== undefined && command.side !== '')
+                (world.sideStatus ??= {})[command.side] = 'won';
             world.status = 'won';
             break;
         case 'lose':
+            if (command.side !== undefined && command.side !== '')
+                (world.sideStatus ??= {})[command.side] = 'lost';
             world.status = 'lost';
             break;
+        case 'endlevel':
+            world.status = command.result === 'defeat' ? 'lost' : 'won';
+            world.carryover = endLevelCarryover(world, command.side ?? null, command);
+            break;
     }
 }
+/**
+ * Which side an `[endlevel]` carries: the one it names, or the human-controlled side when it names
+ * none. `null` when there is no such side, which is not an error - a scenario can end with nobody
+ * to carry.
+ */
+function endLevelSide(world, named) {
+    const id = named ?? Object.entries(world.sides).find(([, side]) => side.controller === 'human')?.[0];
+    if (!id || !(id in world.sides))
+        return null;
+    return { id };
+}
+/**
+ * The sides a scenario's content says see together, as groups ready for `FactionFog.share`.
+ *
+ * Wesnoth groups sides into teams with `[side] team_name`, and `share_vision` says whether a side
+ * shares what it sees with its team. `none` does not; `all` and `shroud` are treated alike here
+ * because `FactionFog` shares sight and memory as one thing rather than keeping them apart, and a
+ * fog that separated them would be the place to tell the two apart. A side with no `team_name`
+ * shares with nobody, and a team of one is not returned, since sharing with nobody is what it
+ * already does.
+ *
+ * @example
+ * ```ts
+ * import { sideVisionGroups, type MwlWorld } from '@datamoc/mw_games/mwl';
+ *
+ * declare const world: MwlWorld;
+ *
+ * // sides 1 and 2 both wrote team_name=north, and side 3 asked for share_vision=none
+ * console.log(sideVisionGroups(world)); // [['1', '2']]
+ * ```
+ */
+export function sideVisionGroups(world) {
+    const teams = new Map();
+    for (const [id, side] of Object.entries(world.sides)) {
+        if (!side.teamName || side.shareVision === 'none')
+            continue;
+        const group = teams.get(side.teamName);
+        if (group)
+            group.push(id);
+        else
+            teams.set(side.teamName, [id]);
+    }
+    return [...teams.values()].filter((group) => group.length > 1);
+}
 function requireUnit(world, id) {
     const unit = world.units[id];
     if (!unit || !unit.alive)
         throw new Error(`MWL unit is not alive: ${id}`);
     return unit;
 }
+/** Kills every alive unit a `[kill]` filter matches, and says how many it killed. */
+function killMatching(world, attributes) {
+    let killed = 0;
+    for (const [id, unit] of Object.entries(world.units)) {
+        if (!unit.alive || !unitMatchesFilter(unit, id, attributes))
+            continue;
+        unit.alive = false;
+        killed++;
+    }
+    return killed;
+}
+/** One unit as `[store_unit]` writes it: only the fields it has, so a variable stays small. */
+function unitSnapshot(unit) {
+    const snapshot = { hp: unit.hp, x: unit.x, y: unit.y, alive: unit.alive };
+    if (unit.type !== undefined)
+        snapshot.type = unit.type;
+    if (unit.side !== undefined)
+        snapshot.side = unit.side;
+    if (unit.moves !== undefined)
+        snapshot.moves = unit.moves;
+    if (unit.name !== undefined)
+        snapshot.name = unit.name;
+    if (unit.role !== undefined)
+        snapshot.role = unit.role;
+    if (unit.can_recruit !== undefined)
+        snapshot.can_recruit = unit.can_recruit;
+    if (unit.leader !== undefined)
+        snapshot.leader = unit.leader;
+    return snapshot;
+}
+/** Applies `[modify_unit]`'s chosen attributes to one unit, ignoring anything it did not name. */
+function applyUnitChanges(unit, changes) {
+    const hp = finiteNumber(changes.hp);
+    if (hp !== undefined)
+        unit.hp = hp;
+    const moves = finiteNumber(changes.moves);
+    if (moves !== undefined)
+        unit.moves = moves;
+    if (changes.type !== undefined)
+        unit.type = changes.type;
+    if (changes.side !== undefined)
+        unit.side = changes.side;
+    const alive = booleanValue(changes.alive);
+    if (alive !== undefined)
+        unit.alive = alive;
+    if (changes.name !== undefined)
+        unit.name = changes.name;
+    if (changes.role !== undefined)
+        unit.role = changes.role;
+    const canRecruit = booleanValue(changes.can_recruit);
+    if (canRecruit !== undefined)
+        unit.can_recruit = canRecruit;
+}
+function finiteNumber(value) {
+    if (value === undefined || value === '')
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
 function optionalInteger(node, attribute) {
     const value = node.attributes[attribute];
     if (value === undefined || value === '')
@@ -876,12 +1378,19 @@ function optionalInteger(node, attribute) {
  * lists split on commas, comparisons coerce both sides with `Number` and
  * fail on anything non-numeric.
  */
-function variableMatches(value, attributes, variables = {}) {
-    const resolve = (expected) => expected.startsWith('$') ? variables[expected.slice(1)] : expected;
+function variableMatches(value, attributes, resolve) {
+    const expected = (text) => {
+        if (!text.startsWith('$'))
+            return text;
+        const resolved = resolve(text.slice(1));
+        return typeof resolved === 'string' || typeof resolved === 'number' || typeof resolved === 'boolean'
+            ? resolved
+            : undefined;
+    };
     if (attributes.equals !== undefined)
-        return sameValue(value, resolve(attributes.equals));
+        return sameValue(value, expected(attributes.equals));
     if (attributes.not_equals !== undefined)
-        return !sameValue(value, resolve(attributes.not_equals));
+        return !sameValue(value, expected(attributes.not_equals));
     if (attributes.in !== undefined) {
         const options = attributes.in.split(',').map((entry) => entry.trim());
         return options.some((option) => sameValue(value, option));
@@ -912,22 +1421,38 @@ function variableMatches(value, attributes, variables = {}) {
 }
 /**
  * One alive unit against `filter`/`have_unit` attributes: side, type (with
- * comma-list `not_type` exclusion), world key (`unit`, or `id` on
- * `have_unit`), and coordinates all have to match when present.
+ * comma-list `not_type` exclusion), the unit's own name and role, whether it
+ * can recruit, whether it is its side's leader, world key (`unit`, or `id`
+ * on `have_unit`), and coordinates all have to match when present.
  */
 function unitMatchesFilter(unit, id, attributes) {
     const excluded = (attributes.not_type ?? '')
         .split(',')
         .map((entry) => entry.trim())
         .filter(Boolean);
+    const wantedCanRecruit = booleanValue(attributes.can_recruit);
+    const wantedLeader = booleanValue(attributes.leader);
     const key = attributes.unit ?? attributes.id;
     return ((key === undefined || id === key) &&
-        (attributes.side === undefined || unit.side === Number(attributes.side)) &&
+        (attributes.side === undefined || unit.side === attributes.side) &&
         (attributes.type === undefined || unit.type === attributes.type) &&
         (excluded.length === 0 || !excluded.includes(unit.type ?? '')) &&
+        (attributes.name === undefined || unit.name === attributes.name) &&
+        (attributes.role === undefined || unit.role === attributes.role) &&
+        (wantedCanRecruit === undefined || (unit.can_recruit ?? false) === wantedCanRecruit) &&
+        (wantedLeader === undefined || (unit.leader ?? false) === wantedLeader) &&
         (attributes.x === undefined || unit.x === Number(attributes.x)) &&
         (attributes.y === undefined || unit.y === Number(attributes.y)));
 }
+/** a copy of `attributes` without the given keys, for a command whose own attribute names are not a unit filter */
+function withoutAttributes(attributes, ...excluded) {
+    if (excluded.length === 0)
+        return { ...attributes };
+    const copy = { ...attributes };
+    for (const key of excluded)
+        delete copy[key];
+    return copy;
+}
 function sameValue(value, expected) {
     if (value === undefined || expected === undefined)
         return value === expected;
@@ -941,6 +1466,73 @@ function sameValue(value, expected) {
 function primitiveVariables(variables) {
     return Object.fromEntries(Object.entries(variables).filter((entry) => typeof entry[1] === 'string' || typeof entry[1] === 'number' || typeof entry[1] === 'boolean'));
 }
+/** `a.b[0].c` -> `['a', 'b', { index: 0 }, 'c']`. */
+function variablePathParts(path) {
+    return path
+        .split('.')
+        .flatMap((segment) => {
+        const name = /^([^[\]]*)((?:\[[^\]]*\])*)$/.exec(segment);
+        if (!name)
+            return [segment];
+        const parts = name[1] === '' ? [] : [name[1]];
+        for (const bracket of name[2].matchAll(/\[([^\]]*)\]/g)) {
+            const index = Number(bracket[1]);
+            parts.push({ index: /^\d+$/.test(bracket[1].trim()) ? index : undefined });
+        }
+        return parts;
+    })
+        .filter((part) => typeof part !== 'string' || part !== '');
+}
+/** The path parts of a write, with any bracketed index that is not a whole number refused by name. */
+function validVariablePathParts(path) {
+    const parts = variablePathParts(path);
+    if (parts.some((part) => typeof part !== 'string' && part.index === undefined))
+        throw new Error(`invalid variable path: ${path}`);
+    return parts;
+}
+function isIndexedStep(step) {
+    return typeof step !== 'string';
+}
+/**
+ * The one write of a variable path, so `execute()`, the hook host and the runtime's own
+ * `set_variable` all place a value at the same node a read walks to. A step after an index
+ * grows an array, so `a[0]`/`a[1]` build a real list rather than an object with numbered keys.
+ */
+function setVariableAtPath(variables, path, value) {
+    const parts = validVariablePathParts(path);
+    const key = (step) => (typeof step === 'string' ? step : step.index);
+    let current = variables;
+    for (let index = 0; index < parts.length - 1; index++) {
+        const step = key(parts[index]);
+        const child = current[step];
+        if (!child || typeof child !== 'object') {
+            current[step] = isIndexedStep(parts[index + 1]) ? [] : {};
+        }
+        current = current[step];
+    }
+    current[key(parts[parts.length - 1])] = value;
+}
+/** The one read of a variable path, used by every reader that takes a name. */
+function variableAtPath(variables, path) {
+    let value = variables;
+    for (const part of variablePathParts(path)) {
+        if (typeof part === 'string') {
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                return undefined;
+            value = value[part];
+        }
+        else {
+            if (!Array.isArray(value) || part.index === undefined)
+                return undefined;
+            value = value[part.index];
+        }
+    }
+    return value;
+}
+/** Resolves a `$name` reference (a path, not only a top-level key) from a variable tree. */
+function resolveVariable(variables) {
+    return (reference) => variableAtPath(variables, reference);
+}
 function coordinateMatches(specification, coordinate) {
     return specification.split(',').some((part) => {
         const value = part.trim();