@heroiclands/package-build 23.0.0 → 23.1.1

package/engine/map-notes.mjs

@@ -1,1309 +0,0 @@
-/*
- * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
- * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
- *
- * This work is licensed under the GNU General Public License v3.0 (GPLv3).
- * You may copy, modify, and distribute it under the terms of that license.
- *
- * For full terms, see the LICENSE.md file in the project root or visit:
- * https://www.gnu.org/licenses/gpl-3.0.html
- *
- * SPDX-License-Identifier: GPL-3.0-or-later
- */
-
-/**
- * **Map notes** — the markdown → Foundry `Scene` translation.
- *
- * A map note carries an *essence*: a curated, hand-owned subset of what a Scene
- * record holds, exactly as a weapon note carries a weapon's essence rather than
- * an Item's schema. Everything a Scene needs and nobody should have to author —
- * the canvas defaults, the embedded `Level`, every derived region field — is
- * synthesised here.
- *
- * Three note types compile through this module and differ only in derived
- * defaults: `battlemap` (tactical), `localmap` (~1 km) and `regionalmap` (large
- * scale). An unknown type fails the build rather than silently defaulting.
- *
- * **Two unit conventions, deliberately.** Geometry — walls, doors, lights,
- * tiles, sounds, region shapes — is authored in **pixels**, Foundry's native
- * storage, because a traced battlemap's walls do not lie on grid intersections
- * (measured: 97.8% do not). Map pins (`locations:`) are authored in **grid
- * squares**, commonly half-integers, because that is how a human reads a
- * position off the map. The two are told apart by their key: `position:` and
- * segment/shape coordinates are pixels, `at:` is grid squares. Mixing them
- * fails silently and visually in Foundry — a grid-valued wall lands in a tiny
- * clump at the top-left — so both directions are linted here against the map's
- * own `dimensions` and `pxPerGrid`.
- *
- * **What this module refuses.** Foundry accepts several authoring mistakes
- * without complaint, producing a valid document that simply never does
- * anything: a region event outside SoHL's curated set, a region with no shapes,
- * a degenerate two-point polygon, `restrict:` with no level. Each is an error
- * here. So is any `executeScript` behaviour: its `source` is a
- * `JavaScriptField`, and a note carrying one would be data compiled into code —
- * the system's top security constraint. It is not representable in this schema
- * and there is no escape hatch.
- *
- * Plain ESM with no Foundry and no filesystem access, so it is unit-testable
- * and usable from the bare-`node` pack scripts. The compiler that walks the
- * content tree and drives it is `scenes.mjs`.
- */
-
-import crypto from "crypto";
-
-import { compendiumUuid, makeId, MAP_SUBTYPES, MAP_TYPES } from "./ids.mjs";
-// The curated region-event vocabulary is shared verbatim with the runtime
-// bridge (`SohlRegionTriggerBehavior`), so an event this build accepts is
-// exactly one the bridge forwards.
-import { CURATED_REGION_EVENTS, EXCLUDED_REGION_EVENTS } from "./region-events.mjs";
-// A map's background art is `img`, as every other note type's art is. `image`,
-// the spelling a map alone once used, is retired and gone.
-import { sohlField } from "./frontmatter.mjs";
-// `bgImage` is one of the four declared art slots, so its accepted set comes
-// from there rather than being restated: the overlay, a tile's texture and an
-// ambient sound's `audio` are map-specific address fields, not slots, and take
-// no set beyond their own type.
-import { artSlot } from "./art-fields.mjs";
-
-/* -------------------------------------------------------------------- */
-/*  Note types and their canvas profiles                                */
-/* -------------------------------------------------------------------- */
-
-// The set itself lives in `ids.mjs`, a leaf both this module and the
-// doc-carrying type set in `item-docs.mjs` can depend on without a cycle.
-export { MAP_SUBTYPES, MAP_TYPES };
-
-/**
- * Whether a content note's type compiles into a Scene.
- *
- * @param {string} [type] - The note's `type` frontmatter.
- * @returns {boolean} True for a map type.
- */
-export function isMapType(type) {
-    return MAP_TYPES.has(String(type));
-}
-
-/**
- * Per-subtype canvas defaults, emitted **explicitly** on every scene.
- *
- * This is not a convenience. `grid.type`, `grid.distance` and `grid.units` all
- * declare `initial: () => game.system.grid.*`, and there is no `game` at build
- * time — left to their initial they would throw or ship undefined. The numeric
- * values are `CONST.GRID_TYPES` and `CONST.FOG_EXPLORATION_MODES`, spelled out
- * here because the constants module is Foundry's, not ours.
- *
- * @type {Readonly<Record<string, object>>}
- */
-export const MAP_SUBTYPE_PROFILES = Object.freeze({
-    battlemap: Object.freeze({
-        grid: { type: 1 /* SQUARE */, distance: 5, units: "ft" },
-        tokenVision: true,
-        fog: { mode: 1 /* INDIVIDUAL */ },
-        padding: 0.25,
-    }),
-    localmap: Object.freeze({
-        grid: { type: 1 /* SQUARE */, distance: 10, units: "m" },
-        tokenVision: false,
-        fog: { mode: 0 /* DISABLED */ },
-        padding: 0.1,
-    }),
-    regionalmap: Object.freeze({
-        grid: { type: 0 /* GRIDLESS */, distance: 5, units: "km" },
-        tokenVision: false,
-        fog: { mode: 0 /* DISABLED */ },
-        padding: 0,
-    }),
-    totm: Object.freeze({
-        grid: { type: 0 /* GRIDLESS */, distance: 1, units: "" },
-        tokenVision: false,
-        fog: { mode: 0 /* DISABLED */ },
-        padding: 0,
-    }),
-});
-
-/**
- * The canvas profile for a map subType.
- *
- * Keyed on the subType rather than the type: every map note is
- * `type: map`, and which canvas it derives is the one thing the three
- * spellings ever decided.
- *
- * @param {string} subType - The note's `subType`.
- * @returns {object} The profile from {@link MAP_SUBTYPE_PROFILES}.
- * @throws {Error} When the subType is not a map subType — the build's
- *   fail-fast contract, so a typo never ships a scene with Foundry's own
- *   defaults.
- */
-export function mapProfile(subType) {
-    const profile = MAP_SUBTYPE_PROFILES[String(subType)];
-    if (!profile) {
-        throw new Error(
-            `unknown map subtype "${subType}" — expected one of ${MAP_SUBTYPES.join(", ")}`,
-        );
-    }
-    return profile;
-}
-
-/**
- * Foundry's own id for the level a scene is created with
- * (`Scene.metadata.defaultLevelId`). Adopting it makes every reference to the
- * synthesised level derivable, and matches what Foundry would have produced.
- */
-export const DEFAULT_LEVEL_ID = "defaultLevel0000";
-
-/* -------------------------------------------------------------------- */
-/*  Derived ids and colours                                             */
-/* -------------------------------------------------------------------- */
-
-/**
- * The id of one region within its scene.
- *
- * Derived rather than stored so a cross-reference (`teleportToken`,
- * `toggleBehavior`) can be resolved to a UUID before the target scene has been
- * compiled. An authored `_id` always wins — the converter pins ids on
- * write-back exactly as it does for items and actors.
- *
- * @param {string} sceneId - The owning scene's `_id`.
- * @param {string} key - The region's authored key.
- * @param {string} [pinned] - An authored `_id`, if any.
- * @returns {string} A 16-character Foundry id.
- */
-export function regionDocId(sceneId, key, pinned) {
-    return pinned || makeId("scene-region", `${sceneId}:${key}`);
-}
-
-/**
- * The id of one behaviour within its region.
- *
- * @param {string} regionId - The owning region's `_id`.
- * @param {string} key - The behaviour's authored key.
- * @param {string} [pinned] - An authored `_id`, if any.
- * @returns {string} A 16-character Foundry id.
- */
-export function behaviorDocId(regionId, key, pinned) {
-    return pinned || makeId("region-behavior", `${regionId}:${key}`);
-}
-
-/**
- * A region's highlight colour, derived from its key.
- *
- * Foundry's default is `Color.fromHSV([Math.random(), 0.8, 0.8])` — a different
- * value on every create, which would make each build's output differ from the
- * last for no reason anyone could see. Hashing the key keeps builds
- * reproducible and diffs quiet, in the same hue/saturation family Foundry
- * itself would have chosen, and keeps the value out of the note entirely.
- *
- * @param {string} key - The region's authored key.
- * @returns {string} A CSS hex colour.
- */
-export function regionColor(key) {
-    const digest = crypto.createHash("sha1").update(`region:${key}`).digest();
-    const hue = digest.readUInt32BE(0) / 0x100000000;
-    return hsvToHex(hue, 0.8, 0.8);
-}
-
-/**
- * HSV → `#rrggbb`, matching Foundry's `Color.fromHSV`.
- *
- * @param {number} h - Hue, 0–1.
- * @param {number} s - Saturation, 0–1.
- * @param {number} v - Value, 0–1.
- * @returns {string} A CSS hex colour.
- */
-function hsvToHex(h, s, v) {
-    const i = Math.floor(h * 6);
-    const f = h * 6 - i;
-    const p = v * (1 - s);
-    const q = v * (1 - f * s);
-    const t = v * (1 - (1 - f) * s);
-    const [r, g, b] = [
-        [v, t, p],
-        [q, v, p],
-        [p, v, t],
-        [p, q, v],
-        [t, p, v],
-        [v, p, q],
-    ][i % 6];
-    const byte = (c) =>
-        Math.round(c * 255)
-            .toString(16)
-            .padStart(2, "0");
-    return `#${byte(r)}${byte(g)}${byte(b)}`;
-}
-
-/* -------------------------------------------------------------------- */
-/*  Unit-mix lints                                                      */
-/* -------------------------------------------------------------------- */
-
-/**
- * The map's own measurements, from which both unit lints are derived.
- *
- * @typedef {object} MapGeometry
- * @property {string} label - The authored key, for error messages.
- * @property {number} pxPerGrid - Pixels per grid square.
- * @property {number[]} dimensions - `[width, height]` in pixels.
- */
-
-/**
- * Reject geometry authored in grid squares where pixels belong.
- *
- * A grid-valued wall or region is not rejected by Foundry: it becomes a
- * 12x11-pixel feature in the top-left corner, invisible on the map and
- * impossible to notice in a diff. The test is derived from the map itself
- * rather than a magic number — when every coordinate of one feature is smaller
- * than a single grid square, on a map several squares across, the author
- * counted squares.
- *
- * @param {number[]} coords - The feature's coordinates, in pixels.
- * @param {MapGeometry} geom - The map's measurements.
- * @throws {Error} When the coordinates read as grid units.
- */
-export function assertPixelGeometry(coords, geom) {
-    const values = coords.filter((c) => Number.isFinite(c)).map(Math.abs);
-    if (!values.length) return;
-    const gridSpan = Math.max(...geom.dimensions) / geom.pxPerGrid;
-    const largest = Math.max(...values);
-    if (gridSpan >= 4 && largest > 0 && largest < geom.pxPerGrid) {
-        throw new Error(
-            `${geom.label}: every coordinate is smaller than one grid square ` +
-                `(${geom.pxPerGrid}px) on a map ${Math.round(gridSpan)} squares ` +
-                `across — this geometry looks authored in grid units. Wall, door, ` +
-                `light, tile, sound and region-shape coordinates are pixels; only ` +
-                `\`locations:\` are grid squares.`,
-        );
-    }
-}
-
-/**
- * Reject a map pin authored in pixels where grid squares belong.
- *
- * @param {number[]} at - The pin's `[x, y]`, in grid squares.
- * @param {MapGeometry} geom - The map's measurements.
- * @throws {Error} When the coordinates read as pixels.
- */
-export function assertGridLocation(at, geom) {
-    const [gx, gy] = [geom.dimensions[0] / geom.pxPerGrid, geom.dimensions[1] / geom.pxPerGrid];
-    if (at[0] > gx || at[1] > gy) {
-        throw new Error(
-            `${geom.label}: [${at.join(", ")}] lies outside the map's ` +
-                `${Math.round(gx)}x${Math.round(gy)} grid — a location looks ` +
-                `authored in pixels. \`locations:\` are grid squares (commonly ` +
-                `half-integers, a pin centred in its square).`,
-        );
-    }
-}
-
-/* -------------------------------------------------------------------- */
-/*  Walls and doors                                                     */
-/* -------------------------------------------------------------------- */
-
-/** Authored sense names → the Wall field each restricts. */
-const SENSE_FIELDS = Object.freeze({
-    movement: "move",
-    sight: "sight",
-    light: "light",
-    sound: "sound",
-});
-
-/** `CONST.EDGE_SENSE_TYPES`. `WALL_SENSE_TYPES` is deprecated in v14. */
-const EDGE_SENSE = Object.freeze({ NONE: 0, LIMITED: 10, NORMAL: 20 });
-
-/**
- * Compile a wall's `blocks:` / `limits:` lists into Foundry's four numeric
- * restriction fields.
- *
- * The authored vocabulary is deliberately not Foundry's.
- * `WALL_MOVEMENT_TYPES.NONE` means movement does **not** collide — i.e.
- * passable — so `movement: none` reads as the exact opposite of what it does.
- * `blocks:` says what the wall stops and `limits:` what it merely attenuates;
- * anything unnamed is passable.
- *
- * @param {{blocks?: string[], limits?: string[]}} spec - The authored lists.
- * @param {string} label - The authored key, for error messages.
- * @returns {{move: number, sight: number, light: number, sound: number}} The
- *   Wall restriction fields.
- * @throws {Error} On an unknown sense, a sense in both lists, or a *limited*
- *   movement restriction (movement is binary — it has no LIMITED value).
- */
-export function wallRestrictions(spec, label) {
-    const out = { move: 0, sight: 0, light: 0, sound: 0 };
-    const blocks = toList(spec?.blocks);
-    const limits = toList(spec?.limits);
-
-    const check = (name, list) => {
-        if (!(name in SENSE_FIELDS)) {
-            throw new Error(
-                `${label}: unknown restriction "${name}" in ${list} — expected ` +
-                    `one of ${Object.keys(SENSE_FIELDS).join(", ")}`,
-            );
-        }
-    };
-    for (const name of blocks) check(name, "blocks");
-    for (const name of limits) check(name, "limits");
-
-    const both = blocks.filter((n) => limits.includes(n));
-    if (both.length) {
-        throw new Error(
-            `${label}: "${both[0]}" is named in both blocks and limits — a ` +
-                `restriction is one or the other`,
-        );
-    }
-    if (limits.includes("movement")) {
-        throw new Error(
-            `${label}: movement cannot be limited — a wall either blocks ` +
-                `movement or does not. Name it in blocks, or leave it out.`,
-        );
-    }
-
-    for (const name of blocks) out[SENSE_FIELDS[name]] = EDGE_SENSE.NORMAL;
-    for (const name of limits) out[SENSE_FIELDS[name]] = EDGE_SENSE.LIMITED;
-    return out;
-}
-
-/** `CONST.WALL_DOOR_TYPES` by authored name. */
-const DOOR_KINDS = Object.freeze({ door: 1, secret: 2 });
-
-/** `CONST.WALL_DOOR_STATES` by authored name. */
-const DOOR_STATES = Object.freeze({ closed: 0, open: 1, locked: 2 });
-
-/**
- * Compile one wall segment into a Wall document.
- *
- * @param {number[]} segment - `[x1, y1, x2, y2]` in pixels.
- * @param {object} spec - The authored wall or door entry.
- * @param {MapGeometry} geom - The map's measurements.
- * @param {{sceneId: string, id: string}} ids - The scene id and this wall's id.
- * @returns {object} The Wall document, keyed for the pack.
- */
-function buildWall(segment, spec, geom, { sceneId, id }) {
-    if (!Array.isArray(segment) || segment.length !== 4) {
-        throw new Error(
-            `${geom.label}: a wall segment is [x1, y1, x2, y2] in pixels; got ` +
-                `${JSON.stringify(segment)}`,
-        );
-    }
-    assertPixelGeometry(segment, geom);
-    const doc = {
-        _id: id,
-        c: segment.map((n) => Math.round(n)),
-        ...wallRestrictions(spec, geom.label),
-        dir: 0,
-        door: 0,
-        ds: 0,
-        _key: `!scenes.walls!${sceneId}.${id}`,
-    };
-    if (spec.kind) {
-        const door = DOOR_KINDS[spec.kind];
-        if (door === undefined) {
-            throw new Error(
-                `${geom.label}: unknown door kind "${spec.kind}" — expected ` +
-                    `${Object.keys(DOOR_KINDS).join(" or ")}`,
-            );
-        }
-        doc.door = door;
-        const state = DOOR_STATES[spec.state ?? "closed"];
-        if (state === undefined) {
-            throw new Error(
-                `${geom.label}: unknown door state "${spec.state}" — expected ` +
-                    `one of ${Object.keys(DOOR_STATES).join(", ")}`,
-            );
-        }
-        doc.ds = state;
-    }
-    return doc;
-}
-
-/* -------------------------------------------------------------------- */
-/*  Region shapes                                                       */
-/* -------------------------------------------------------------------- */
-
-/**
- * The shape forms a map note may author. `rect` is the short spelling of
- * `rectangle`, as the design's own examples use.
- */
-const SHAPE_FORMS = Object.freeze(new Set(["rect", "rectangle", "circle", "ellipse", "polygon"]));
-
-/**
- * Compile one authored shape into a Foundry shape record.
- *
- * Four forms only — `rectangle` (`rect` is accepted as its short spelling),
- * `circle`, `ellipse` and `polygon`. The remaining six Foundry shapes are
- * template and token-attached forms with no place in an authored map, and
- * `gridBased` is deliberately not exposed: it re-interprets a shape metrically,
- * and one unit convention per note is the whole point.
- *
- * @param {object} spec - The authored shape entry.
- * @param {MapGeometry} geom - The map's measurements.
- * @returns {object} The Foundry shape record.
- * @throws {Error} On an unknown form, a degenerate polygon, or grid-unit
- *   coordinates.
- */
-export function buildShape(spec, geom) {
-    if (!spec || typeof spec !== "object") {
-        throw new Error(`${geom.label}: a shape must be a mapping`);
-    }
-    const hole = Boolean(spec.hole);
-    const forms = Object.keys(spec).filter((k) => k !== "hole");
-    if (forms.length !== 1) {
-        throw new Error(
-            `${geom.label}: a shape names exactly one of rectangle, circle, ` +
-                `ellipse, polygon; got ${forms.length ? forms.join(" + ") : "none"}`,
-        );
-    }
-    const [form] = forms;
-    if (!SHAPE_FORMS.has(form)) {
-        throw new Error(
-            `${geom.label}: unsupported shape "${form}" — a map note may use ` +
-                `rectangle, circle, ellipse or polygon`,
-        );
-    }
-    const raw = spec[form];
-    if (!Array.isArray(raw) || raw.some((n) => !Number.isFinite(n))) {
-        throw new Error(`${geom.label}: ${form} takes a flat list of numbers in pixels`);
-    }
-    assertPixelGeometry(raw, geom);
-
-    switch (form) {
-        case "rect":
-        case "rectangle":
-            expectLength(raw, 4, `${geom.label}: rectangle is [x, y, width, height]`);
-            return {
-                type: "rectangle",
-                x: raw[0],
-                y: raw[1],
-                width: raw[2],
-                height: raw[3],
-                hole,
-            };
-        case "circle":
-            expectLength(raw, 3, `${geom.label}: circle is [x, y, radius]`);
-            return {
-                type: "circle",
-                x: raw[0],
-                y: raw[1],
-                radius: raw[2],
-                hole,
-            };
-        case "ellipse":
-            if (raw.length !== 4 && raw.length !== 5) {
-                throw new Error(
-                    `${geom.label}: ellipse is [x, y, radiusX, radiusY] with an ` +
-                        `optional rotation`,
-                );
-            }
-            return {
-                type: "ellipse",
-                x: raw[0],
-                y: raw[1],
-                radiusX: raw[2],
-                radiusY: raw[3],
-                rotation: raw[4] ?? 0,
-                hole,
-            };
-        case "polygon":
-            if (raw.length % 2 !== 0) {
-                throw new Error(
-                    `${geom.label}: a polygon takes x/y pairs, so an even count; ` +
-                        `got ${raw.length}`,
-                );
-            }
-            // The schema's floor of 4 numbers admits a two-point "polygon",
-            // which is a line segment and encloses nothing.
-            if (raw.length < 6) {
-                throw new Error(
-                    `${geom.label}: a polygon needs at least 3 points; got ` + `${raw.length / 2}`,
-                );
-            }
-            return { type: "polygon", points: [...raw], hole };
-        default:
-            throw new Error(
-                `${geom.label}: unsupported shape "${form}" — a map note may use ` +
-                    `rectangle, circle, ellipse or polygon`,
-            );
-    }
-}
-
-/* -------------------------------------------------------------------- */
-/*  Region behaviours                                                   */
-/* -------------------------------------------------------------------- */
-
-/**
- * The events `toggleBehavior` itself accepts — Foundry's own list, which is
- * wider than SoHL's curated set.
- */
-const TOGGLE_BEHAVIOR_EVENTS = Object.freeze([
-    "tokenEnter",
-    "tokenExit",
-    "tokenMoveIn",
-    "tokenMoveOut",
-    "tokenTurnStart",
-    "tokenTurnEnd",
-    "tokenRoundStart",
-    "tokenRoundEnd",
-]);
-
-/** `AdjustDarknessLevelRegionBehaviorType.MODES`, authored by name. */
-const DARKNESS_MODES = Object.freeze({ override: 0, brighten: 1, darken: 2 });
-
-/** The events `displayScrollingText` accepts. */
-const SCROLLING_TEXT_EVENTS = Object.freeze([
-    "tokenAnimateIn",
-    "tokenAnimateOut",
-    "tokenTurnStart",
-    "tokenTurnEnd",
-    "tokenRoundStart",
-    "tokenRoundEnd",
-]);
-
-/**
- * The region behaviours a map note may carry, and the fields each accepts.
- *
- * An allow-list rather than a pass-through: an unlisted field would be dropped
- * by Foundry without a word, and an unlisted *type* fails Foundry's own create
- * with an unrelated message (`Cannot read properties of undefined (reading
- * 'regions')`), so both are checked here where the note and the key can be
- * named.
- *
- * @type {Readonly<Record<string, {fields: string[], events?: readonly string[]}>>}
- */
-const BEHAVIOR_SPECS = Object.freeze({
-    // The SoHL bridge.
-    trigger: { fields: ["events", "action"], events: CURATED_REGION_EVENTS },
-    adjustDarknessLevel: { fields: ["mode", "modifier"] },
-    applyActiveEffect: { fields: ["effects"] },
-    changeLevel: { fields: ["movementActions"] },
-    defineSurface: {
-        fields: [
-            "placement",
-            "light",
-            "move",
-            "sight",
-            "sound",
-            "occlusion",
-            "exposure",
-            "culling",
-        ],
-    },
-    displayScrollingText: {
-        fields: ["events", "text", "color", "visibility", "once"],
-        events: SCROLLING_TEXT_EVENTS,
-    },
-    modifyMovementCost: { fields: ["difficulties"] },
-    pauseGame: { fields: ["once"] },
-    suppressWeather: { fields: [] },
-    teleportToken: {
-        fields: ["to", "placement", "snap", "choice", "revealed"],
-    },
-    toggleBehavior: {
-        fields: ["events", "enable", "disable"],
-        events: TOGGLE_BEHAVIOR_EVENTS,
-    },
-});
-
-/**
- * The behaviour types a map note may carry (v1).
- *
- * @type {ReadonlySet<string>}
- */
-export const REGION_BEHAVIOR_TYPES = Object.freeze(new Set(Object.keys(BEHAVIOR_SPECS)));
-
-/**
- * Behaviour types a map note may **never** carry, and why.
- *
- * `executeScript` is banned outright: its `source` is a `JavaScriptField`, so a
- * note carrying one would compile data into code — the system's top security
- * constraint (non-negotiable rule 10). There is no escape hatch and no
- * configuration that re-enables it. `executeMacro` is merely deferred: its
- * target Macro has to ship in the same Adventure to resolve, and
- * Adventure-bundled macros are not built yet.
- *
- * @type {ReadonlyMap<string, string>}
- */
-export const BANNED_REGION_BEHAVIOR_TYPES = Object.freeze(
-    new Map([
-        [
-            "executeScript",
-            "its `source` is a JavaScriptField, so a note carrying one would " +
-                "compile data into code (non-negotiable rule 10). It is not " +
-                "representable in a map note and has no escape hatch.",
-        ],
-        [
-            "executeMacro",
-            "its target Macro must ship in the same Adventure to resolve, and " +
-                "Adventure-bundled macros are not built yet.",
-        ],
-    ]),
-);
-
-/**
- * Compile one authored behaviour entry into a RegionBehavior document.
- *
- * @param {string} key - The behaviour's authored key.
- * @param {object} spec - The authored entry.
- * @param {object} ctx - The compile context (resolvers, warnings, ids).
- * @returns {object} The RegionBehavior document, keyed for the pack.
- */
-function buildBehavior(key, spec, ctx) {
-    const label = `${ctx.regionLabel}.behaviors.${key}`;
-    if (!spec || typeof spec !== "object") {
-        throw new Error(`${label}: a behaviour must be a mapping`);
-    }
-    const reserved = new Set(["_id", "name", "disabled"]);
-    const types = Object.keys(spec).filter((k) => !reserved.has(k));
-    if (types.length !== 1) {
-        throw new Error(
-            `${label}: a behaviour names exactly one behaviour type; got ` +
-                `${types.length ? types.join(" + ") : "none"}`,
-        );
-    }
-    const [type] = types;
-
-    const banned = BANNED_REGION_BEHAVIOR_TYPES.get(type);
-    if (banned) throw new Error(`${label}: "${type}" is not permitted — ${banned}`);
-    const behaviorSpec = BEHAVIOR_SPECS[type];
-    if (!behaviorSpec) {
-        throw new Error(
-            `${label}: unknown behaviour type "${type}" — a map note may carry ` +
-                `${[...REGION_BEHAVIOR_TYPES].sort().join(", ")}`,
-        );
-    }
-
-    const authored = spec[type] ?? {};
-    if (typeof authored !== "object" || Array.isArray(authored)) {
-        throw new Error(`${label}: ${type} takes a mapping of its fields`);
-    }
-    for (const field of Object.keys(authored)) {
-        if (!behaviorSpec.fields.includes(field)) {
-            throw new Error(
-                `${label}: ${type} has no field "${field}" — it accepts ` +
-                    `${behaviorSpec.fields.join(", ") || "no fields"}`,
-            );
-        }
-    }
-
-    const system = compileBehaviorSystem(type, authored, behaviorSpec, label, ctx);
-    const id = behaviorDocId(ctx.regionId, key, spec._id);
-    const doc = {
-        _id: id,
-        name: spec.name ?? "",
-        type,
-        system,
-        _key: `!scenes.regions.behaviors!${ctx.sceneId}.${ctx.regionId}.${id}`,
-    };
-    if (spec.disabled) doc.disabled = true;
-    return doc;
-}
-
-/**
- * Translate one behaviour's authored fields into its `system` data.
- *
- * @param {string} type - The behaviour type.
- * @param {object} authored - The authored fields.
- * @param {object} behaviorSpec - Its entry in {@link BEHAVIOR_SPECS}.
- * @param {string} label - The authored path, for error messages.
- * @param {object} ctx - The compile context.
- * @returns {object} The behaviour's `system` data.
- */
-function compileBehaviorSystem(type, authored, behaviorSpec, label, ctx) {
-    if (behaviorSpec.events) {
-        assertEvents(authored.events, behaviorSpec.events, label, type);
-    }
-    switch (type) {
-        case "trigger": {
-            if (authored.action && !ctx.knownActions?.has(authored.action)) {
-                ctx.warn(
-                    `${label}: action "${authored.action}" matches no known SoHL ` +
-                        `action — the region will forward the event but offer nothing`,
-                );
-            }
-            return {
-                events: [...authored.events],
-                actionName: authored.action ?? null,
-            };
-        }
-        case "teleportToken": {
-            const { to, ...rest } = authored;
-            return {
-                ...rest,
-                destinations: toList(to).map((addr) => ctx.resolveRegionRef(addr, label)),
-            };
-        }
-        case "toggleBehavior": {
-            const { enable, disable, ...rest } = authored;
-            const out = { ...rest, events: [...authored.events] };
-            if (enable) {
-                out.enable = toList(enable).map((a) => ctx.resolveBehaviorRef(a, label));
-            }
-            if (disable) {
-                out.disable = toList(disable).map((a) => ctx.resolveBehaviorRef(a, label));
-            }
-            return out;
-        }
-        case "adjustDarknessLevel": {
-            // Authored by name: `AdjustDarknessLevelRegionBehaviorType.MODES`
-            // is a numeric enum nobody should have to remember.
-            const mode = authored.mode ?? "override";
-            const value = DARKNESS_MODES[mode];
-            if (value === undefined) {
-                throw new Error(
-                    `${label}: unknown darkness mode "${mode}" — expected one of ` +
-                        `${Object.keys(DARKNESS_MODES).join(", ")}`,
-                );
-            }
-            return { mode: value, modifier: authored.modifier ?? 0 };
-        }
-        case "applyActiveEffect": {
-            return {
-                effects: toList(authored.effects).map((a) => ctx.resolveEffectRef(a, label)),
-            };
-        }
-        default:
-            return { ...authored };
-    }
-}
-
-/**
- * Reject a region event Foundry would store verbatim and never fire.
- *
- * The excluded names are listed in the error because reaching for one — most
- * plausibly `tokenMoveWithin` — is the mistake this lint exists for, and
- * Foundry gives no sign of it: a bogus name never matches a dispatched event,
- * and an excluded one is dispatched and then dropped by the bridge. No error,
- * no log, no automation.
- *
- * @param {string[]} events - The authored events.
- * @param {readonly string[]} allowed - The events this behaviour accepts.
- * @param {string} label - The authored path, for error messages.
- * @param {string} type - The behaviour type.
- * @throws {Error} When an event is not accepted.
- */
-function assertEvents(events, allowed, label, type) {
-    const list = toList(events);
-    if (!list.length) {
-        throw new Error(`${label}: ${type} needs at least one event`);
-    }
-    for (const event of list) {
-        if (allowed.includes(event)) continue;
-        const excluded = EXCLUDED_REGION_EVENTS.includes(event);
-        throw new Error(
-            `${label}: "${event}" is ${excluded ? "deliberately excluded" : "not a region event"} ` +
-                `for ${type}. Accepted: ${allowed.join(", ")}. Excluded (stored ` +
-                `verbatim by Foundry and never acted on): ` +
-                `${EXCLUDED_REGION_EVENTS.join(", ")}.`,
-        );
-    }
-}
-
-/* -------------------------------------------------------------------- */
-/*  Regions                                                             */
-/* -------------------------------------------------------------------- */
-
-/** `CONST.REGION_VISIBILITY`, authored by name because the order is arbitrary. */
-const REGION_VISIBILITY = Object.freeze({
-    layer: 0,
-    gamemaster: 1,
-    always: 2,
-    observer: 3,
-    layerUnlocked: 4,
-});
-
-/** `CONST.EDGE_RESTRICTION_TYPES`. */
-const RESTRICTION_TYPES = Object.freeze(["light", "darkness", "sight", "sound", "move"]);
-
-/**
- * Compile one authored region into a Region document with its behaviours.
- *
- * @param {string} key - The region's authored key.
- * @param {object} spec - The authored entry.
- * @param {MapGeometry} geom - The map's measurements.
- * @param {object} ctx - The compile context.
- * @returns {object} The Region document, keyed for the pack.
- */
-function buildRegion(key, spec, geom, ctx) {
-    const label = `regions.${key}`;
-    const shapeGeom = { ...geom, label };
-    const shapes = toList(spec.shapes).map((s) => buildShape(s, shapeGeom));
-    if (!shapes.length) {
-        throw new Error(
-            `${label}: a region needs at least one shape — Foundry accepts one ` +
-                `with none, and it simply never triggers`,
-        );
-    }
-
-    const id = regionDocId(ctx.sceneId, key, spec._id);
-    const visibilityName = spec.visibility ?? "layerUnlocked";
-    const visibility = REGION_VISIBILITY[visibilityName];
-    if (visibility === undefined) {
-        throw new Error(
-            `${label}: unknown visibility "${visibilityName}" — expected one of ` +
-                `${Object.keys(REGION_VISIBILITY).join(", ")}`,
-        );
-    }
-
-    const [bottom = null, top = null] = toList(spec.elevation);
-    const doc = {
-        _id: id,
-        name: spec.name ?? key,
-        color: regionColor(key),
-        shapes,
-        elevation: { bottom: bottom ?? null, top: top ?? null },
-        visibility,
-        behaviors: [],
-        _key: `!scenes.regions!${ctx.sceneId}.${id}`,
-    };
-
-    if (spec.restrict != null) {
-        if (!RESTRICTION_TYPES.includes(spec.restrict)) {
-            throw new Error(
-                `${label}: unknown restrict "${spec.restrict}" — expected one of ` +
-                    `${RESTRICTION_TYPES.join(", ")}`,
-            );
-        }
-        doc.restriction = { enabled: true, type: spec.restrict, priority: 0 };
-        // A restricted region must belong to exactly one level, or the shape
-        // constraint silently never computes. `levels` is otherwise never
-        // emitted: the empty set means "all levels", which is right for the
-        // one-scene-per-floor rule.
-        doc.levels = [DEFAULT_LEVEL_ID];
-    }
-
-    const behaviorCtx = { ...ctx, regionId: id, regionLabel: label };
-    for (const [bKey, bSpec] of Object.entries(spec.behaviors ?? {})) {
-        doc.behaviors.push(buildBehavior(bKey, bSpec, behaviorCtx));
-    }
-    return doc;
-}
-
-/* -------------------------------------------------------------------- */
-/*  The scene                                                           */
-/* -------------------------------------------------------------------- */
-
-/**
- * Compile a map note into a Scene document, embedded documents and all.
- *
- * Every embedded document carries its own `_key`. This is not decoration: the
- * compendium CLI writes each one straight to its sublevel by that key, and a
- * missing one fails the compile with `Key cannot be null or undefined`.
- *
- * @param {object} fm - The note's frontmatter.
- * @param {object} ctx - The compile context:
- *   `packageId`, `journalEntryId`, `journalPack` (the pack the note's derived
- *   JournalEntry landed in), `pageIds` (heading key → page id),
- *   `resolveRegionRef` / `resolveBehaviorRef` / `resolveEffectRef` (address →
- *   UUID), `art` (an art address → the path each surface serves),
- *   `knownActions`, `warnings`, and optionally `folder` and `stats`.
- * @returns {object} The Scene document, keyed for the pack.
- * @throws {Error} On any authoring mistake Foundry would accept silently.
- */
-export function buildScene(fm, ctx) {
-    const sohl = fm.sohl ?? {};
-    const sceneId = fm.id;
-    if (!sceneId) throw new Error("a map note needs an `id`");
-    const profile = mapProfile(fm.subType);
-    const scale = fm.data?.scale;
-    if (scale !== undefined) {
-        if (
-            fm.subType !== "regionalmap" ||
-            !scale ||
-            typeof scale !== "object" ||
-            Array.isArray(scale) ||
-            Object.keys(scale).some((key) => !["distance", "unit"].includes(key)) ||
-            !(Number.isFinite(scale.distance) && scale.distance > 0) ||
-            typeof scale.unit !== "string" ||
-            !scale.unit.trim()
-        ) {
-            throw new Error(
-                "`data.scale` on a regionalmap is {distance: positive number, unit: nonempty string}",
-            );
-        }
-    }
-
-    const dimensions = sohl.dimensions;
-    if (
-        !Array.isArray(dimensions) ||
-        dimensions.length !== 2 ||
-        !dimensions.every((n) => Number.isInteger(n) && n > 0)
-    ) {
-        throw new Error("`dimensions` is [width, height] in whole pixels — the map's own size");
-    }
-    const pxPerGrid = fm.subType === "totm" ? 100 : sohl.pxPerGrid;
-    if (!Number.isInteger(pxPerGrid) || pxPerGrid <= 0) {
-        throw new Error(
-            "`pxPerGrid` is the whole number of pixels per grid square, and must " +
-                "match the art",
-        );
-    }
-    // A Scene has no `img`, so a map's background is its own slot, authored
-    // under `data:` with the other art. It is an `image` address like every
-    // other art reference, and the record it resolves to carries the path.
-    const img = ctx.art(fm.data?.bgImage, "bgImage", "image", artSlot("bgImage")?.accepts);
-    if (!img) throw new Error("a map note needs a `bgImage`");
-
-    const warn = (message) => {
-        if (ctx.warnings) ctx.warnings.push(message);
-    };
-    const inner = { ...ctx, sceneId, warn };
-    const geom = { label: "", pxPerGrid, dimensions };
-
-    const scene = {
-        name: ctx.name ?? fm.name?.full ?? "Unnamed Map",
-        _id: sceneId,
-        navigation: true,
-        navOrder: 0,
-        width: dimensions[0],
-        height: dimensions[1],
-        padding: profile.padding,
-        grid: {
-            type: profile.grid.type,
-            size: pxPerGrid,
-            distance: scale?.distance ?? profile.grid.distance,
-            units: scale?.unit ?? profile.grid.units,
-        },
-        tokenVision: profile.tokenVision,
-        fog: { mode: profile.fog.mode },
-        initialLevel: DEFAULT_LEVEL_ID,
-        levels: [buildLevel(sohl, sceneId, img, ctx.art)],
-        drawings: [],
-        tokens: [],
-        lights: buildLights(sohl, geom, inner),
-        notes: buildLocations(sohl, geom, inner),
-        sounds: buildSounds(sohl, geom, inner),
-        tiles: buildTiles(sohl, geom, inner),
-        walls: buildWalls(sohl, geom, inner),
-        regions: buildRegions(sohl, geom, inner),
-        folder: ctx.folder ?? null,
-        sort: 0,
-        ownership: { default: 0 },
-        flags: {},
-        _key: `!scenes!${sceneId}`,
-    };
-    if (sohl.navName) scene.navName = sohl.navName;
-    if (ctx.stats) scene._stats = ctx.stats;
-
-    if (ctx.journalEntryId) {
-        if (!ctx.packageId) {
-            throw new Error("a map note with a journal needs `packageId` in its compile context");
-        }
-        // `Scene.journal` is a plain ForeignDocumentField, which
-        // `ForeignDocumentField#initialize` unconditionally nulls inside a
-        // compendium. The source id survives (and resolves after an Adventure
-        // import, which reads source data and keeps ids), but a bare `scenes`
-        // pack needs the flag to find the entry at all.
-        scene.journal = ctx.journalEntryId;
-        scene.flags[ctx.packageId] = {
-            docUuid: compendiumUuid(ctx.packageId, "doc", ctx.journalEntryId, ctx.journalPack),
-        };
-    }
-    return scene;
-}
-
-/**
- * Synthesise the scene's single embedded Level from `img:` / `overlay:`.
- *
- * Authors never write `levels:`. A scene must ship at least one Level — the
- * client-side `_preCreate` net that would create one does not run for offline
- * pack compilation, and the server-side migration shim is version-gated on
- * `_stats.coreVersion`, so a pack stamped 14.x+ skips it and ships a scene with
- * no Level and no map.
- *
- * @param {object} sohl - The note's `sohl:` block.
- * @param {string} sceneId - The owning scene's `_id`.
- * @param {string} img - The background art, already resolved from the note's
- *   `bgImage` address by {@link buildScene}. Passed rather than resolved here,
- *   because an address is answered by the compile's index and this function
- *   takes none.
- * @param {(value: unknown, key: string, type: string, accepts?: Iterable<string>) => string|null} [art] -
- *   The art resolver, for the foreground overlay. Omitted, a note naming one
- *   gets no overlay rather than a path nothing serves.
- * @returns {object} The Level document, keyed for the pack.
- */
-export function buildLevel(sohl, sceneId, img, art = () => null) {
-    const level = {
-        _id: DEFAULT_LEVEL_ID,
-        name: sohl.levelName ?? "Ground",
-        elevation: { bottom: 0, top: 20 },
-        background: {
-            color: sohl.backgroundColor ?? "#999999",
-            src: img,
-        },
-        // The overlay is an `image` address like the background, and resolves
-        // by the same rule — a scene draws the two from one statement each.
-        foreground: { src: art(sohl.overlay ?? null, "overlay", "image") },
-        sort: 0,
-        _key: `!scenes.levels!${sceneId}.${DEFAULT_LEVEL_ID}`,
-    };
-    return level;
-}
-
-/**
- * Compile the `walls:` and `doors:` blocks into Wall documents.
- *
- * Walls are keyed by **feature** rather than by restriction signature, so a
- * diff reads "the hayloft walls changed" instead of "line 143 changed", and a
- * human can find the one wall they meant to move.
- *
- * @param {object} sohl - The note's `sohl:` block.
- * @param {MapGeometry} geom - The map's measurements.
- * @param {object} ctx - The compile context.
- * @returns {object[]} The Wall documents.
- */
-export function buildWalls(sohl, geom, ctx) {
-    const out = [];
-    for (const [key, spec] of Object.entries(sohl.walls ?? {})) {
-        const label = `walls.${key}`;
-        const segments = toList(spec.segments);
-        if (!segments.length) {
-            throw new Error(`${label}: a wall group needs at least one segment`);
-        }
-        segments.forEach((segment, i) => {
-            const id = makeId("scene-wall", `${ctx.sceneId}:${key}:${i}`);
-            out.push(
-                buildWall(
-                    segment,
-                    spec,
-                    { ...geom, label },
-                    {
-                        sceneId: ctx.sceneId,
-                        id,
-                    },
-                ),
-            );
-        });
-    }
-    for (const [key, spec] of Object.entries(sohl.doors ?? {})) {
-        const label = `doors.${key}`;
-        const id = spec._id || makeId("scene-door", `${ctx.sceneId}:${key}`);
-        out.push(
-            buildWall(
-                spec.segment,
-                { kind: "door", ...spec },
-                { ...geom, label },
-                {
-                    sceneId: ctx.sceneId,
-                    id,
-                },
-            ),
-        );
-    }
-    return out;
-}
-
-/**
- * Compile the `lights:` block into AmbientLight documents.
- *
- * `dim` and `bright` are radii in the scene's **distance units** (Foundry's own
- * meaning), not pixels; only `position:` is pixels.
- *
- * @param {object} sohl - The note's `sohl:` block.
- * @param {MapGeometry} geom - The map's measurements.
- * @param {object} ctx - The compile context.
- * @returns {object[]} The AmbientLight documents.
- */
-export function buildLights(sohl, geom, ctx) {
-    return Object.entries(sohl.lights ?? {}).map(([key, spec]) => {
-        const label = `lights.${key}`;
-        const [x, y] = requirePosition(spec.position, { ...geom, label });
-        const id = spec._id || makeId("scene-light", `${ctx.sceneId}:${key}`);
-        const config = {
-            dim: spec.dim ?? 0,
-            bright: spec.bright ?? 0,
-            angle: spec.angle ?? 360,
-        };
-        if (spec.color) config.color = spec.color;
-        if (spec.animation) config.animation = spec.animation;
-        return {
-            _id: id,
-            x,
-            y,
-            rotation: spec.rotation ?? 0,
-            walls: spec.walls ?? true,
-            vision: spec.vision ?? false,
-            config,
-            _key: `!scenes.lights!${ctx.sceneId}.${id}`,
-        };
-    });
-}
-
-/**
- * Compile the `tiles:` block into Tile documents.
- *
- * @param {object} sohl - The note's `sohl:` block.
- * @param {MapGeometry} geom - The map's measurements.
- * @param {object} ctx - The compile context.
- * @returns {object[]} The Tile documents.
- */
-export function buildTiles(sohl, geom, ctx) {
-    return Object.entries(sohl.tiles ?? {}).map(([key, spec]) => {
-        const label = `tiles.${key}`;
-        const [x, y] = requirePosition(spec.position, { ...geom, label });
-        const size = toList(spec.size);
-        expectLength(size, 2, `${label}: size is [width, height] in pixels`);
-        assertPixelGeometry(size, { ...geom, label });
-        if (!spec.image) throw new Error(`${label}: a tile needs an image`);
-        const id = spec._id || makeId("scene-tile", `${ctx.sceneId}:${key}`);
-        return {
-            _id: id,
-            x,
-            y,
-            width: size[0],
-            height: size[1],
-            elevation: spec.elevation ?? 0,
-            rotation: spec.rotation ?? 0,
-            alpha: spec.alpha ?? 1,
-            sort: 0,
-            // A tile's texture is an address, resolved by the same rule the
-            // scene's own background is. Its key is named for the type it
-            // reaches, so a tile placing a glyph rather than artwork qualifies
-            // — `sohl-none-icon-chest` — and the default needs no memorising.
-            texture: { src: ctx.art(spec.image, "image", "image") },
-            _key: `!scenes.tiles!${ctx.sceneId}.${id}`,
-        };
-    });
-}
-
-/**
- * Compile the `sounds:` block into AmbientSound documents.
- *
- * Positional audio is the one audio mechanism that packages cleanly: `path` is
- * a plain `FilePathField` with no document reference behind it.
- *
- * @param {object} sohl - The note's `sohl:` block.
- * @param {MapGeometry} geom - The map's measurements.
- * @param {object} ctx - The compile context.
- * @returns {object[]} The AmbientSound documents.
- */
-export function buildSounds(sohl, geom, ctx) {
-    return Object.entries(sohl.sounds ?? {}).map(([key, spec]) => {
-        const label = `sounds.${key}`;
-        const [x, y] = requirePosition(spec.position, { ...geom, label });
-        if (!spec.audio) throw new Error(`${label}: an ambient sound needs an \`audio\` address`);
-        const id = spec._id || makeId("scene-sound", `${ctx.sceneId}:${key}`);
-        return {
-            _id: id,
-            name: spec.name ?? key,
-            x,
-            y,
-            radius: spec.radius ?? 0,
-            // An ambient sound is a file a package ships, like the pictures, so
-            // it is an address too. The emitted field stays Foundry's own
-            // `path`, which is what a Scene's AmbientSound calls it.
-            path: ctx.art(spec.audio, "audio", "audio"),
-            repeat: spec.repeat ?? true,
-            volume: spec.volume ?? 0.5,
-            walls: spec.walls ?? true,
-            easing: spec.easing ?? true,
-            _key: `!scenes.sounds!${ctx.sceneId}.${id}`,
-        };
-    });
-}
-
-/**
- * Compile the `locations:` block into Note documents — the map pins.
- *
- * A location's key names a heading in the note's body, and the pin points at
- * the journal page that heading compiled into. `Note.entryId` / `pageId` are
- * `{idOnly: true}` fields, which return before the compendium guard, so pin
- * targets survive packing intact — but `Note#entry` resolves by bare id against
- * the **world** collection, which is why a map with pins ships inside an
- * Adventure (`keepId: true`).
- *
- * @param {object} sohl - The note's `sohl:` block.
- * @param {MapGeometry} geom - The map's measurements.
- * @param {object} ctx - The compile context.
- * @returns {object[]} The Note documents.
- */
-export function buildLocations(sohl, geom, ctx) {
-    const locations = Object.entries(sohl.locations ?? {});
-    if (!locations.length) return [];
-    if (!ctx.journalEntryId) {
-        throw new Error(
-            "`locations:` need a journal to point at — give the note a body with " +
-                "a heading per location",
-        );
-    }
-    return locations.map(([key, spec]) => {
-        const label = `locations.${key}`;
-        const at = toList(spec.at);
-        expectLength(at, 2, `${label}: at is [x, y] in grid squares`);
-        if (!at.every((n) => Number.isFinite(n))) {
-            throw new Error(`${label}: at is [x, y] in grid squares`);
-        }
-        assertGridLocation(at, { ...geom, label });
-        const pageId = ctx.pageIds.get(key);
-        if (!pageId) {
-            throw new Error(
-                `${label}: no body heading matches "${key}" — a location pin points ` +
-                    `at the page its heading compiled into. Headings available: ` +
-                    `${[...ctx.pageIds.keys()].join(", ") || "(none)"}`,
-            );
-        }
-        const id = spec._id || makeId("scene-note", `${ctx.sceneId}:${key}`);
-        return {
-            _id: id,
-            entryId: ctx.journalEntryId,
-            pageId,
-            x: Math.round(at[0] * geom.pxPerGrid),
-            y: Math.round(at[1] * geom.pxPerGrid),
-            text: spec.label ?? "",
-            iconSize: spec.iconSize ?? 40,
-            _key: `!scenes.notes!${ctx.sceneId}.${id}`,
-        };
-    });
-}
-
-/**
- * Compile the `regions:` block into Region documents with their behaviours.
- *
- * @param {object} sohl - The note's `sohl:` block.
- * @param {MapGeometry} geom - The map's measurements.
- * @param {object} ctx - The compile context.
- * @returns {object[]} The Region documents.
- */
-export function buildRegions(sohl, geom, ctx) {
-    return Object.entries(sohl.regions ?? {}).map(([key, spec]) =>
-        buildRegion(key, spec, geom, ctx),
-    );
-}
-
-/* -------------------------------------------------------------------- */
-/*  Small shared helpers                                                */
-/* -------------------------------------------------------------------- */
-
-/**
- * A value as a list: absent → empty, scalar → single, list → itself.
- *
- * @param {*} value - The authored value.
- * @returns {Array} The list form.
- */
-function toList(value) {
-    if (value == null) return [];
-    return Array.isArray(value) ? value : [value];
-}
-
-/**
- * Assert a list's length, with the authored form named in the message.
- *
- * @param {Array} list - The list.
- * @param {number} length - The expected length.
- * @param {string} message - The error to throw.
- */
-function expectLength(list, length, message) {
-    if (list.length !== length) throw new Error(message);
-}
-
-/**
- * Read a `position:` (pixels) and lint its units.
- *
- * @param {*} position - The authored `[x, y]`.
- * @param {MapGeometry} geom - The map's measurements.
- * @returns {number[]} The rounded pixel coordinates.
- */
-function requirePosition(position, geom) {
-    const at = toList(position);
-    expectLength(at, 2, `${geom.label}: position is [x, y] in pixels`);
-    if (!at.every((n) => Number.isFinite(n))) {
-        throw new Error(`${geom.label}: position is [x, y] in pixels`);
-    }
-    assertPixelGeometry(at, geom);
-    return at.map((n) => Math.round(n));
-}