@rpgm-tools/neo-angband-mod-sdk 0.10.0

package/dist/record-key.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Per-record identity for the record files whose identity is NOT a unique
+ * string `name`.
+ *
+ * CURRENT STATE, FIRST, BECAUSE THIS COMMENT USED TO MISLEAD. Every record file
+ * but ONE is addressable per record today: 24 by a unique `name`, 19 by the
+ * explicit specs in this file, and `history` by nothing - and an op against
+ * `history` is REPORTED, never silently dropped. Two independent reviewers read
+ * the older wording, took the "the other 20 files do not fit it" paragraph below
+ * for the present tense, and filed the same non-existent P1 ("20 files silently
+ * discard patch/replace/remove, including object, ego_item, vault, trap, store,
+ * brand, slay, projection, constants"). Those nine are precisely the files this
+ * table fixes. If you are about to report that bug, run record-key.test.ts.
+ *
+ * WHY THIS EXISTS
+ *
+ * composePacks (compose.ts) keys every record by `packRef(pack, slugify(name))`.
+ * That is the right identity for the 24 upstream record files whose records
+ * carry a unique `name` - monster, object_property, terrain and so on - and it
+ * is what makes `patches` / `replaces` / `fieldPatches` / `removes` work there.
+ *
+ * The other 20 files did not fit it, for two measured reasons (counts taken over
+ * packages/content/pack on 2026-07-29). This is the problem statement, not the
+ * status:
+ *
+ *  - 14 files have no string `name` at all. Their identity lives somewhere else:
+ *    `code` (brand, slay, chest_trap, projection), the tval half of a composite
+ *    (`object_base`), the upstream `name:<name>:<desc>` line (trap), an index
+ *    (pain, names), a plain other field (store, ui_knowledge, body, world,
+ *    flavor, hints), or nowhere at all because the file is a single config
+ *    singleton (constants, visuals).
+ *  - 6 files DO have `name` but core's own data slugs two records to the same
+ *    ref, mostly because slugify drops `*` and `+`: object has 5 such pairs
+ *    ("Acquirement" / "*Acquirement*"), vault 1 ("Little eruption" /
+ *    "Little eruption+"), and brand / slay / chest_trap name several records
+ *    after the element rather than the variant. ego_item is the genuine case:
+ *    "of Acid" exists twice, distinguished only by which item types it applies
+ *    to - which are the very fields a mod would patch, so they cannot be part of
+ *    its identity.
+ *
+ * Before this file existed, a per-record op against any of those 20 was
+ * SILENTLY DROPPED (loader.ts stripped the whole contribution before compose saw
+ * it). This table is what makes 19 of them addressable, and it is deliberately
+ * an EXPLICIT declaration rather than a heuristic: guessing a key would trade a
+ * silent drop for a silent mis-merge, which is worse. Every entry below was
+ * verified unique over the shipped core pack (see record-key.test.ts, which
+ * reads the real pack and fails if a declared key stops being unique).
+ *
+ * `history` is deliberately absent: a history record is
+ * `{chart:{chart,next,roll}, phrase}` and every part of that is a value a mod
+ * would legitimately change, so it has no identity to key on. An op against it
+ * is REPORTED, not applied - see loader.ts.
+ *
+ * AMBIGUITY IS NAMED, NEVER GUESSED. A key that two records in the same file
+ * claim (object's 5 pairs, ego_item's 25) makes that one ref unaddressable; the
+ * records stay in the game and any op naming the ref becomes a reported problem.
+ * The rest of the file remains addressable per record.
+ */
+/**
+ * How to derive one record's identity within a file.
+ *
+ * - `fields`: slugify each dot-path in order and join with "--". Every path must
+ *   resolve to a string or a number; anything else (absent, object, array) means
+ *   the record has no derivable key and is simply not addressable.
+ * - `singleton`: the file holds exactly one config record, so the FILE is the
+ *   identity (ref `<pack>:<file>`). A second record in such a file collides with
+ *   the first and both become unaddressable, which is the correct answer - the
+ *   host binds one.
+ */
+export type RecordKeySpec = {
+    readonly kind: "fields";
+    readonly paths: readonly string[];
+} | {
+    readonly kind: "singleton";
+};
+/**
+ * The identity of every record file that is NOT keyed by a unique string `name`.
+ *
+ * A file absent from this table is keyed by `name`, which is what composePacks
+ * already does. Keys here are file stems, exactly as they appear in a pack
+ * folder (`brand.json` -> `brand`).
+ */
+export declare const RECORD_KEY_SPECS: Readonly<Record<string, RecordKeySpec>>;
+/**
+ * Files with a declared key spec, sorted. Exported so a test can assert the set
+ * in BOTH directions (a file wrongly added and a file wrongly removed).
+ */
+export declare const KEYED_RECORD_FILES: readonly string[];
+/** The key spec for a file: the declared one, or `name` by default. */
+export declare function keySpecFor(file: string): RecordKeySpec;
+/**
+ * The slug half of a record's ref within `file`, or null when this record has no
+ * derivable identity (a missing key field, or a key field that is not a scalar).
+ * Null means "not addressable"; it never means "drop the record".
+ */
+export declare function recordKey(file: string, record: unknown, spec?: RecordKeySpec): string | null;
+/** A human phrase for what a file's identity is, for problem messages. */
+export declare function keyDescription(file: string): string;
+//# sourceMappingURL=record-key.d.ts.map

package/dist/record-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-key.d.ts","sourceRoot":"","sources":["../src/record-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAKH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC;AAEnC;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAsCpE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EACV,CAAC;AAEvC,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAEtD;AAcD;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,EACf,IAAI,GAAE,aAAgC,GACrC,MAAM,GAAG,IAAI,CAcf;AAED,0EAA0E;AAC1E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKnD"}

package/dist/record-key.js

@@ -0,0 +1,157 @@
+/**
+ * Per-record identity for the record files whose identity is NOT a unique
+ * string `name`.
+ *
+ * CURRENT STATE, FIRST, BECAUSE THIS COMMENT USED TO MISLEAD. Every record file
+ * but ONE is addressable per record today: 24 by a unique `name`, 19 by the
+ * explicit specs in this file, and `history` by nothing - and an op against
+ * `history` is REPORTED, never silently dropped. Two independent reviewers read
+ * the older wording, took the "the other 20 files do not fit it" paragraph below
+ * for the present tense, and filed the same non-existent P1 ("20 files silently
+ * discard patch/replace/remove, including object, ego_item, vault, trap, store,
+ * brand, slay, projection, constants"). Those nine are precisely the files this
+ * table fixes. If you are about to report that bug, run record-key.test.ts.
+ *
+ * WHY THIS EXISTS
+ *
+ * composePacks (compose.ts) keys every record by `packRef(pack, slugify(name))`.
+ * That is the right identity for the 24 upstream record files whose records
+ * carry a unique `name` - monster, object_property, terrain and so on - and it
+ * is what makes `patches` / `replaces` / `fieldPatches` / `removes` work there.
+ *
+ * The other 20 files did not fit it, for two measured reasons (counts taken over
+ * packages/content/pack on 2026-07-29). This is the problem statement, not the
+ * status:
+ *
+ *  - 14 files have no string `name` at all. Their identity lives somewhere else:
+ *    `code` (brand, slay, chest_trap, projection), the tval half of a composite
+ *    (`object_base`), the upstream `name:<name>:<desc>` line (trap), an index
+ *    (pain, names), a plain other field (store, ui_knowledge, body, world,
+ *    flavor, hints), or nowhere at all because the file is a single config
+ *    singleton (constants, visuals).
+ *  - 6 files DO have `name` but core's own data slugs two records to the same
+ *    ref, mostly because slugify drops `*` and `+`: object has 5 such pairs
+ *    ("Acquirement" / "*Acquirement*"), vault 1 ("Little eruption" /
+ *    "Little eruption+"), and brand / slay / chest_trap name several records
+ *    after the element rather than the variant. ego_item is the genuine case:
+ *    "of Acid" exists twice, distinguished only by which item types it applies
+ *    to - which are the very fields a mod would patch, so they cannot be part of
+ *    its identity.
+ *
+ * Before this file existed, a per-record op against any of those 20 was
+ * SILENTLY DROPPED (loader.ts stripped the whole contribution before compose saw
+ * it). This table is what makes 19 of them addressable, and it is deliberately
+ * an EXPLICIT declaration rather than a heuristic: guessing a key would trade a
+ * silent drop for a silent mis-merge, which is worse. Every entry below was
+ * verified unique over the shipped core pack (see record-key.test.ts, which
+ * reads the real pack and fails if a declared key stops being unique).
+ *
+ * `history` is deliberately absent: a history record is
+ * `{chart:{chart,next,roll}, phrase}` and every part of that is a value a mod
+ * would legitimately change, so it has no identity to key on. An op against it
+ * is REPORTED, not applied - see loader.ts.
+ *
+ * AMBIGUITY IS NAMED, NEVER GUESSED. A key that two records in the same file
+ * claim (object's 5 pairs, ego_item's 25) makes that one ref unaddressable; the
+ * records stay in the game and any op naming the ref becomes a reported problem.
+ * The rest of the file remains addressable per record.
+ */
+import { slugify } from "./manifest.js";
+/**
+ * The identity of every record file that is NOT keyed by a unique string `name`.
+ *
+ * A file absent from this table is keyed by `name`, which is what composePacks
+ * already does. Keys here are file stems, exactly as they appear in a pack
+ * folder (`brand.json` -> `brand`).
+ */
+export const RECORD_KEY_SPECS = {
+    /* `code` is the upstream identity; `name` names the element, so ACID_2 and
+     * ACID_3 both slug to "acid". */
+    brand: { kind: "fields", paths: ["code"] },
+    slay: { kind: "fields", paths: ["code"] },
+    chest_trap: { kind: "fields", paths: ["code"] },
+    /* projection: `code` is on all 56 records, `name` is not. */
+    projection: { kind: "fields", paths: ["code"] },
+    /* object_base: `name` is the composite {tval, name}; tval is the key upstream
+     * looks bases up by. */
+    object_base: { kind: "fields", paths: ["name.tval"] },
+    /* trap: `name` is the composite {name, desc} - upstream's `name:<name>:<desc>`
+     * line. The display half repeats (6 records are "strange rune"); the pair is
+     * unique. */
+    trap: { kind: "fields", paths: ["name.name", "name.desc"] },
+    /* store: the STORE_* code. */
+    store: { kind: "fields", paths: ["store"] },
+    /* pain: the message-set index, which IS its identity (mon_pain_msg). */
+    pain: { kind: "fields", paths: ["type"] },
+    ui_knowledge: { kind: "fields", paths: ["monster-category"] },
+    /* names: the random-name section index. */
+    names: { kind: "fields", paths: ["section"] },
+    body: { kind: "fields", paths: ["body"] },
+    /* world: the level's name, which is what upstream's up/down links reference. */
+    world: { kind: "fields", paths: ["level.name"] },
+    /* flavor: one record per object base, keyed by that base's tval. */
+    flavor: { kind: "fields", paths: ["kind.tval"] },
+    /* hints: the hint text is the whole record, so it is also its identity. */
+    hints: { kind: "fields", paths: ["H"] },
+    /* Config singletons: one record for the whole file. */
+    constants: { kind: "singleton" },
+    visuals: { kind: "singleton" },
+    /* Files that DO have `name` but need more of the record to be unique. Each is
+     * still not fully unique (see the header) - the residual collisions are
+     * reported, never guessed. */
+    object: { kind: "fields", paths: ["type", "name"] },
+    vault: { kind: "fields", paths: ["type", "name"] },
+    ego_item: { kind: "fields", paths: ["name"] },
+};
+/**
+ * Files with a declared key spec, sorted. Exported so a test can assert the set
+ * in BOTH directions (a file wrongly added and a file wrongly removed).
+ */
+export const KEYED_RECORD_FILES = Object.keys(RECORD_KEY_SPECS).sort();
+/** The key spec for a file: the declared one, or `name` by default. */
+export function keySpecFor(file) {
+    return RECORD_KEY_SPECS[file] ?? { kind: "fields", paths: ["name"] };
+}
+function atPath(record, path) {
+    let cur = record;
+    for (const part of path.split(".")) {
+        if (typeof cur !== "object" || cur === null || Array.isArray(cur)) {
+            return undefined;
+        }
+        cur = cur[part];
+        if (cur === undefined)
+            return undefined;
+    }
+    return cur;
+}
+/**
+ * The slug half of a record's ref within `file`, or null when this record has no
+ * derivable identity (a missing key field, or a key field that is not a scalar).
+ * Null means "not addressable"; it never means "drop the record".
+ */
+export function recordKey(file, record, spec = keySpecFor(file)) {
+    if (typeof record !== "object" || record === null || Array.isArray(record)) {
+        return null;
+    }
+    if (spec.kind === "singleton")
+        return slugify(file);
+    const parts = [];
+    for (const path of spec.paths) {
+        const value = atPath(record, path);
+        if (typeof value !== "string" && typeof value !== "number")
+            return null;
+        const slug = slugify(String(value));
+        if (slug.length === 0)
+            return null;
+        parts.push(slug);
+    }
+    return parts.join("--");
+}
+/** A human phrase for what a file's identity is, for problem messages. */
+export function keyDescription(file) {
+    const spec = keySpecFor(file);
+    return spec.kind === "singleton"
+        ? `the whole file (one config record, ref "<pack>:${slugify(file)}")`
+        : spec.paths.join(" + ");
+}
+//# sourceMappingURL=record-key.js.map

package/dist/record-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-key.js","sourceRoot":"","sources":["../src/record-key.ts"],"names":[],"mappings":"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"}

package/dist/resolve.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Deterministic pack load-order resolution.
+ *
+ * Dependencies load before dependents (topological order); ties break by the
+ * caller's INPUT ORDER, so the order is reproducible on every machine given the
+ * same pack list. Cycles and missing dependencies are hard errors - a mod set
+ * either composes deterministically or fails loudly before play.
+ *
+ * TIES USED TO BREAK LEXICOGRAPHICALLY BY ID, and that was a defect, not a
+ * preference. Determinism was the goal and input order delivers it just as well:
+ * the caller's list is itself deterministic (the stored enabled array, an
+ * external manager's load-order.json, or `?mods=a,b`). Sorting by id instead
+ * DISCARDED the player's choice, while the mod manager went on offering "Move
+ * later (loads last, wins conflicts)" (web/src/mods.ts) - a reorder that changed
+ * nothing for any two packs with no dependency edge between them, which is most
+ * pairs. Vortex/MO2 semantics require the deployed order to decide, so the one
+ * thing the resolver must not do is invent an order of its own.
+ *
+ * Dependency edges still win outright: input order only decides among packs the
+ * graph leaves free, which is exactly what a load-order list is for.
+ *
+ * Beyond hard `dependencies`, MOD_LIFECYCLE.md section 3 defines two more
+ * ordering inputs, both soft (their absence is never an error):
+ *
+ *  - `optionalDependencies`: if the named pack is present, it loads first
+ *    and its version is checked against the declared range exactly like a
+ *    hard dependency; if it is absent, it is silently skipped.
+ *  - `loadAfter` / `loadBefore`: pure ordering hints among present packs,
+ *    with no version semantics. `loadBefore` is implemented as the mirror
+ *    of `loadAfter` (X.loadBefore = [Y] adds the same edge as Y.loadAfter
+ *    = [X]).
+ *
+ * All of these contribute edges to the same topological sort, so a cycle
+ * created by mixing dependencies with loadAfter/loadBefore is rejected
+ * exactly like a dependency cycle.
+ */
+import type { PackManifest } from "./manifest.js";
+export declare class ResolveError extends Error {
+}
+/** Order manifests so every pack follows all of its dependencies. */
+export declare function resolveLoadOrder(manifests: readonly PackManifest[]): PackManifest[];
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAIlD,qBAAa,YAAa,SAAQ,KAAK;CAAG;AA8B1C,qEAAqE;AACrE,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,SAAS,YAAY,EAAE,GACjC,YAAY,EAAE,CAoGhB"}

package/dist/resolve.js

@@ -0,0 +1,161 @@
+/**
+ * Deterministic pack load-order resolution.
+ *
+ * Dependencies load before dependents (topological order); ties break by the
+ * caller's INPUT ORDER, so the order is reproducible on every machine given the
+ * same pack list. Cycles and missing dependencies are hard errors - a mod set
+ * either composes deterministically or fails loudly before play.
+ *
+ * TIES USED TO BREAK LEXICOGRAPHICALLY BY ID, and that was a defect, not a
+ * preference. Determinism was the goal and input order delivers it just as well:
+ * the caller's list is itself deterministic (the stored enabled array, an
+ * external manager's load-order.json, or `?mods=a,b`). Sorting by id instead
+ * DISCARDED the player's choice, while the mod manager went on offering "Move
+ * later (loads last, wins conflicts)" (web/src/mods.ts) - a reorder that changed
+ * nothing for any two packs with no dependency edge between them, which is most
+ * pairs. Vortex/MO2 semantics require the deployed order to decide, so the one
+ * thing the resolver must not do is invent an order of its own.
+ *
+ * Dependency edges still win outright: input order only decides among packs the
+ * graph leaves free, which is exactly what a load-order list is for.
+ *
+ * Beyond hard `dependencies`, MOD_LIFECYCLE.md section 3 defines two more
+ * ordering inputs, both soft (their absence is never an error):
+ *
+ *  - `optionalDependencies`: if the named pack is present, it loads first
+ *    and its version is checked against the declared range exactly like a
+ *    hard dependency; if it is absent, it is silently skipped.
+ *  - `loadAfter` / `loadBefore`: pure ordering hints among present packs,
+ *    with no version semantics. `loadBefore` is implemented as the mirror
+ *    of `loadAfter` (X.loadBefore = [Y] adds the same edge as Y.loadAfter
+ *    = [X]).
+ *
+ * All of these contribute edges to the same topological sort, so a cycle
+ * created by mixing dependencies with loadAfter/loadBefore is rejected
+ * exactly like a dependency cycle.
+ */
+import { ManifestError } from "./manifest.js";
+import { satisfies, SemverError } from "./semver.js";
+export class ResolveError extends Error {
+}
+/**
+ * Verify a present dependency's version range, throwing ResolveError with a
+ * plain-language message naming the fix. Used for both hard `dependencies`
+ * and `optionalDependencies` that happen to be present.
+ */
+function checkVersionRange(dependentId, depId, range, byId) {
+    const dep = byId.get(depId);
+    let ok;
+    try {
+        ok = satisfies(dep.version, range);
+    }
+    catch (err) {
+        const reason = err instanceof SemverError ? err.message : String(err);
+        throw new ResolveError(`pack ${dependentId} declares an invalid version range "${range}" for ${depId}: ${reason}`);
+    }
+    if (!ok) {
+        throw new ResolveError(`pack ${dependentId} requires ${depId} ${range} but ${dep.version} is installed`);
+    }
+}
+/** Order manifests so every pack follows all of its dependencies. */
+export function resolveLoadOrder(manifests) {
+    const byId = new Map();
+    for (const m of manifests) {
+        if (byId.has(m.id)) {
+            throw new ManifestError(`duplicate pack id: ${m.id}`);
+        }
+        byId.set(m.id, m);
+    }
+    for (const m of manifests) {
+        for (const [dep, range] of Object.entries(m.dependencies ?? {})) {
+            if (!byId.has(dep)) {
+                throw new ResolveError(`pack ${m.id} requires missing pack ${dep}`);
+            }
+            checkVersionRange(m.id, dep, range, byId);
+        }
+        for (const [dep, range] of Object.entries(m.optionalDependencies ?? {})) {
+            if (!byId.has(dep))
+                continue; // absence of an optional dependency is not an error
+            checkVersionRange(m.id, dep, range, byId);
+        }
+    }
+    // Collect, per pack, the full set of ids that must load before it: hard
+    // deps, present optional deps, present loadAfter, and the reverse edge
+    // for every present pack's loadBefore. Built as per-id Sets so that the
+    // same edge declared twice (e.g. both a hard dependency and a loadAfter
+    // entry) collapses to one edge instead of a duplicate that would corrupt
+    // the Kahn in-degree bookkeeping below.
+    const prereqs = new Map();
+    for (const m of manifests) {
+        prereqs.set(m.id, new Set());
+    }
+    for (const m of manifests) {
+        const set = prereqs.get(m.id);
+        for (const dep of Object.keys(m.dependencies ?? {})) {
+            set.add(dep);
+        }
+        for (const dep of Object.keys(m.optionalDependencies ?? {})) {
+            if (byId.has(dep))
+                set.add(dep);
+        }
+        for (const after of m.loadAfter ?? []) {
+            if (byId.has(after))
+                set.add(after);
+        }
+    }
+    for (const m of manifests) {
+        for (const before of m.loadBefore ?? []) {
+            // m must load before `before`: that is the same edge as
+            // `before`.loadAfter including m, so add it to before's prereq set.
+            const set = prereqs.get(before);
+            if (set !== undefined)
+                set.add(m.id);
+        }
+    }
+    const remainingDeps = new Map();
+    const dependents = new Map();
+    for (const m of manifests) {
+        remainingDeps.set(m.id, new Set(prereqs.get(m.id)));
+        for (const dep of prereqs.get(m.id)) {
+            const list = dependents.get(dep) ?? [];
+            list.push(m.id);
+            dependents.set(dep, list);
+        }
+    }
+    /* The caller's position for each id, which is what ties break on. */
+    const inputAt = new Map();
+    manifests.forEach((m, i) => inputAt.set(m.id, i));
+    const at = (id) => inputAt.get(id) ?? 0;
+    // Kahn with a frontier kept in input order, so the result is deterministic
+    // without the resolver imposing an order the player did not choose.
+    const frontier = [...remainingDeps.entries()]
+        .filter(([, deps]) => deps.size === 0)
+        .map(([id]) => id)
+        .sort((a, b) => at(a) - at(b));
+    const order = [];
+    while (frontier.length > 0) {
+        const id = frontier.shift();
+        order.push(byId.get(id));
+        for (const dependent of dependents.get(id) ?? []) {
+            const deps = remainingDeps.get(dependent);
+            deps.delete(id);
+            if (deps.size === 0) {
+                // Insert keeping the frontier in input order.
+                const pos = frontier.findIndex((f) => at(f) > at(dependent));
+                if (pos === -1)
+                    frontier.push(dependent);
+                else
+                    frontier.splice(pos, 0, dependent);
+            }
+        }
+    }
+    if (order.length !== manifests.length) {
+        const stuck = [...remainingDeps.entries()]
+            .filter(([, deps]) => deps.size > 0)
+            .map(([id]) => id)
+            .sort();
+        throw new ResolveError(`dependency cycle among packs: ${stuck.join(", ")}`);
+    }
+    return order;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"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"}

package/dist/semver.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A small, dependency-free semver range matcher.
+ *
+ * This package bundles into a browser build, so it cannot pull in the
+ * `semver` npm package; this file implements just enough of the range
+ * grammar for pack manifests (MOD_LIFECYCLE.md section 3):
+ *
+ *  - `*` or `x` (any case): matches any version.
+ *  - an exact version, `1.2.3`: matches only that version.
+ *  - a partial version used bare, `1.2` or `1`: matches any version with
+ *    that prefix (`1.2` matches `1.2.0`..`1.2.x`; `1` matches `1.0.0`..`1.x.x`).
+ *  - caret ranges, `^1.2.3`: compatible-with, following npm's rule that the
+ *    leftmost nonzero component may not change (`^1.2.3` allows up to but
+ *    not including `2.0.0`; `^0.2.3` allows up to but not including `0.3.0`;
+ *    `^0.0.3` allows only `0.0.3`).
+ *  - tilde ranges, `~1.2.3`: patch-level allowed (up to but not including
+ *    `1.3.0`); `~1.2` is the same; `~1` allows up to but not including `2.0.0`.
+ *  - comparator sets: `>=`, `>`, `<=`, `<`, `=`, combined with spaces and
+ *    ANDed together, e.g. `>=1.0.0 <2.0.0`.
+ *
+ * Limitation (documented, not fixed): prerelease tags (`1.0.0-beta.2`) are
+ * compared naively as a single lexicographic string once the numeric
+ * major.minor.patch triple is equal, rather than the full dot-separated,
+ * numeric-vs-alphanumeric identifier comparison the semver spec defines.
+ * A version with no prerelease is always treated as newer than one with a
+ * prerelease at the same major.minor.patch, matching the spec; the ordering
+ * among different prerelease strings themselves does not. Pack authors who
+ * need exact prerelease ordering should not rely on it here.
+ */
+export declare class SemverError extends Error {
+}
+/**
+ * Does `version` satisfy `range`? Throws SemverError if either string is
+ * malformed (an unparseable version, or a range with an unparseable token).
+ */
+export declare function satisfies(version: string, range: string): boolean;
+//# sourceMappingURL=semver.d.ts.map

package/dist/semver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semver.d.ts","sourceRoot":"","sources":["../src/semver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,qBAAa,WAAY,SAAQ,KAAK;CAAG;AAyLzC;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAWjE"}