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

package/bin/neo-angband-mod-build.mjs

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+/**
+ * Build a mod's TypeScript into the `plugin.js` its folder ships.
+ *
+ *   neo-angband-mod-build [--root <dir>] [--mods a,b] [--out <dir>] [--check]
+ *
+ * WHY THIS EXISTS. A mod is distributed as a FOLDER: manifest.json plus plugin.js, an
+ * ES module the game imports from wherever that folder ended up - a loopback URL on
+ * desktop, a blob: from a browser directory picker, IndexedDB for one installed from a
+ * repository. The source is TypeScript, and TypeScript is not a thing a browser
+ * imports, so something has to do the transform.
+ *
+ * WHY IT LIVES IN THE SDK. It used to live in the engine repository, next to the mods
+ * that were bundled into the app - which meant the only way to build a plugin.js was
+ * to have the whole engine repository checked out. Now that every mod lives in its own
+ * repository, including the first-party ones, that is backwards: the rules below are
+ * the plugin ABI, the ABI belongs to the SDK, and the SDK is published. A mod repo
+ * installs @rpgm-tools/neo-angband-mod-sdk and runs this. Copying the script into each
+ * mod repo was the alternative, and it would have put three drifting copies of the
+ * same three guarantees in three places.
+ *
+ * WHAT IT MUST GUARANTEE, and why each is checked rather than assumed:
+ *
+ *  1. NO BARE IMPORTS, AND NO INLINED ENGINE. "@rpgm-tools/neo-angband-core" does not
+ *     resolve in a module fetched from a folder - it resolves against the document,
+ *     where nothing is published. The engine arrives as `ctx.core` instead. A mod's
+ *     source may import core for TYPES, which esbuild erases.
+ *
+ *     Every non-relative specifier is therefore marked EXTERNAL, and a surviving one
+ *     is fatal. That is not a detail. Without it, esbuild RESOLVES the import (a mod
+ *     repo has core as a devDependency, so it is right there in node_modules) and
+ *     inlines what it finds - and then this scan can never fire, because there is no
+ *     bare import left to see. Measured on the engine repo's own script, which did
+ *     not mark anything external: a plugin.ts doing `import { TMD } from
+ *     "@rpgm-tools/neo-angband-core"` built clean, exit 0, and shipped a private copy
+ *     of the timed-effect table inside plugin.js. For a frozen constant that is
+ *     merely wasteful; for anything with module state - a registry, a cache, the RNG -
+ *     it is a SECOND INSTANCE of the engine's state living inside the mod, which is
+ *     the exact failure the ABI's "the engine is passed in" rule exists to prevent.
+ *     A guard that cannot fail is worse than no guard: it reads as coverage.
+ *
+ *  2. ONE FILE. The ABI permits relative imports between a mod's own scripts, but
+ *     bundling them is strictly better for a distributed artefact: one request, one
+ *     digest, and no chance of a half-downloaded dependency graph.
+ *  3. A DEFAULT EXPORT THAT LOOKS LIKE A ModPlugin. The host validates this at load
+ *     (validateModPlugin), but a broken artefact should fail HERE, where there is a
+ *     build log, rather than as one line in a mod manager.
+ *  4. THE COMMITTED plugin.js IS CURRENT. In a mod repository plugin.js is a committed
+ *     artefact - it has to be, because that is the file the catalogue fetches at a tag
+ *     and hashes. Which means it can go stale against its own source, silently, and the
+ *     stale copy is the one players run. So `--check` compares byte for byte against
+ *     whatever plugin.js is already there and fails on a difference. Nothing else in
+ *     the chain would notice: the digest would match the stale file perfectly.
+ *
+ * `--check` builds and verifies without writing, for CI.
+ *
+ * TWO SHAPES OF --root, decided by what is in it:
+ *
+ *   a mod folder (has plugin.ts)       build it, writing beside its manifest.json
+ *   a folder OF mod folders            build each one that has a plugin.ts
+ *
+ * The first is what a mod repository wants: plugin.js is a committed artefact there,
+ * because that is the file the catalogue fetches and hashes. The second is what the
+ * engine repository wants for its demo mods, and writes to --out.
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+
+/* esbuild is not a dependency of this package. The SDK is imported at RUNTIME by the
+ * web build to validate manifests, and a native binary in that dependency tree is a
+ * cost every consumer pays for a tool only mod authors run. So it is resolved when the
+ * tool actually runs, and its absence names the remedy instead of stack-tracing. */
+let build;
+try {
+  ({ build } = await import("esbuild"));
+} catch {
+  console.error(
+    "[mod-build] esbuild is not installed. It is the transform this tool drives, and\n" +
+      "[mod-build] it is deliberately not a dependency of the SDK (a native binary in\n" +
+      "[mod-build] the runtime tree costs every consumer for a build-time tool).\n" +
+      "[mod-build] Add it:  npm i -D esbuild",
+  );
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+const flag = (name, fallback) => {
+  const at = args.indexOf(`--${name}`);
+  return at >= 0 && args[at + 1] !== undefined ? args[at + 1] : fallback;
+};
+const check = args.includes("--check");
+const root = resolve(process.cwd(), flag("root", "."));
+
+function note(message) {
+  console.log(`[mod-build] ${message}`);
+}
+let failed = false;
+function fail(message) {
+  console.error(`[mod-build] ${message}`);
+  failed = true;
+  process.exitCode = 1;
+}
+
+if (!existsSync(root) || !statSync(root).isDirectory()) {
+  fail(`FATAL - --root ${root} is not a directory`);
+  process.exit(1);
+}
+
+/**
+ * The mod folders to build, and where each one's output goes.
+ *
+ * `single` is the mod-repository case, and its default output is the folder itself:
+ * plugin.js is a committed artefact there, sitting next to the manifest.json it is
+ * distributed with. Writing it anywhere else would leave the repo's own copy stale,
+ * which is the one state nobody looks at.
+ */
+const single = existsSync(join(root, "plugin.ts"));
+const outFlag = flag("out", null);
+let targets;
+if (single) {
+  const id = readManifestId(root) ?? basename(root);
+  targets = [{ id, dir: root, out: outFlag === null ? root : resolve(process.cwd(), outFlag, id) }];
+} else {
+  const all = readdirSync(root)
+    .filter((id) => existsSync(join(root, id, "plugin.ts")))
+    .sort();
+  const requested = flag("mods", "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s !== "");
+  for (const id of requested) {
+    if (!all.includes(id)) {
+      /* A typo'd id is a caller bug, not a missing artefact: name what does exist
+       * rather than build nothing and exit 0. */
+      fail(`FATAL - no mod '${id}' with a plugin.ts under ${root} (have: ${all.join(", ") || "none"})`);
+      process.exit(1);
+    }
+  }
+  const selected = requested.length > 0 ? requested : all;
+  const outRoot = resolve(process.cwd(), outFlag ?? join(root, "..", "build", "mod-plugins"));
+  targets = selected.map((id) => ({ id, dir: join(root, id), out: join(outRoot, id) }));
+}
+
+if (targets.length === 0) {
+  /* Not an error - a repo may legitimately hold a content-only mod. But it is said out
+   * loud, because "nothing to build" and "built everything" are the same exit code and
+   * a CI step that quietly does nothing reads as a passing check. */
+  note(`no mod under ${root} ships a plugin.ts; nothing to build`);
+  process.exit(0);
+}
+
+note(`${check ? "checking" : "building"} ${targets.length}: ${targets.map((t) => t.id).join(", ")}`);
+
+/** The manifest's own id, or null when there is no readable manifest. */
+function readManifestId(dir) {
+  try {
+    const id = JSON.parse(readFileSync(join(dir, "manifest.json"), "utf8")).id;
+    return typeof id === "string" && id !== "" ? id : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A bare (package) specifier in the bundle.
+ *
+ * Matches the specifier position of a static import/export-from and of a dynamic
+ * `import("...")`, then keeps the ones that are not relative or absolute. Deliberately
+ * not a full parse: esbuild has produced one module of its own output, and the only
+ * imports left are the ones it was told to leave external - which is every bare one,
+ * on purpose. See guarantee 1.
+ */
+function bareImports(code) {
+  const specifiers = [
+    ...code.matchAll(/(?:^|[\s;}])(?:import|export)[\s\S]{0,200}?from\s*["']([^"']+)["']/g),
+    ...code.matchAll(/\bimport\s*\(\s*["']([^"']+)["']\s*\)/g),
+    ...code.matchAll(/(?:^|[\s;}])import\s*["']([^"']+)["']/g),
+  ].map((m) => m[1]);
+  return [...new Set(specifiers.filter((s) => !PATH_LIKE.test(s)))];
+}
+
+/** Relative, POSIX-absolute, or Windows drive-absolute. Anything else is a package. */
+const PATH_LIKE = /^(?:\.|\/|[A-Za-z]:[\\/])/;
+
+/**
+ * Leave every package specifier alone.
+ *
+ * `external: [...]` would need the names up front, and the point is to catch names
+ * nobody predicted - a mod that reaches for lodash cannot resolve it from a mod folder
+ * either. So the filter is "everything", narrowed here to specifiers that are not paths.
+ *
+ * The entry point is exempt explicitly. It arrives through onResolve like any other
+ * specifier, as an ABSOLUTE path - which on Windows begins with a drive letter and so
+ * is not relative by the naive test. Marking it external makes esbuild refuse the build
+ * outright ("the entry point cannot be marked as external"), which is how this was
+ * found: all three fixtures failed identically, including the one that must pass.
+ */
+const externalAll = {
+  name: "external-bare-specifiers",
+  setup(b) {
+    b.onResolve({ filter: /.*/ }, (a) => {
+      if (a.kind === "entry-point" || PATH_LIKE.test(a.path)) return null;
+      return { path: a.path, external: true };
+    });
+  },
+};
+
+for (const { id, dir, out } of targets) {
+  let js;
+  try {
+    const result = await build({
+      entryPoints: [join(dir, "plugin.ts")],
+      bundle: true,
+      format: "esm",
+      platform: "browser",
+      target: "es2022",
+      /* Readable output on purpose. A player can open plugin.js in the mod folder
+       * they installed, and a mod they cannot read is a mod they cannot trust; the
+       * few KB this costs are not worth the opacity. */
+      minify: false,
+      write: false,
+      legalComments: "inline",
+      plugins: [externalAll],
+      banner: {
+        js:
+          `// ${id} - generated from plugin.ts by neo-angband-mod-build\n` +
+          `// (@rpgm-tools/neo-angband-mod-sdk). Edit the TypeScript source, not this file.`,
+      },
+    });
+    js = result.outputFiles[0].text;
+  } catch (e) {
+    fail(`${id}: build failed - ${e.message}`);
+    continue;
+  }
+
+  const bare = bareImports(js);
+  if (bare.length > 0) {
+    /* The failure this catches is invisible in a dev bundle and total in a player's
+     * install, so it names the fix rather than just the problem. */
+    fail(
+      `${id}: plugin.js imports ${bare.map((s) => `"${s}"`).join(", ")} - a module ` +
+        `loaded from a mod folder cannot resolve a package by name, and bundling one ` +
+        `in would give the mod its own copy of that module's state. Take what you ` +
+        `need from ctx.core, and import @rpgm-tools/neo-angband-core for TYPES only ` +
+        `("import type { ... }").`,
+    );
+    continue;
+  }
+
+  /* Shape check. Importing the built module is the only way to see the default
+   * export, and it is safe here: this is the author's own code, just compiled. */
+  const dataUrl = `data:text/javascript;base64,${Buffer.from(js, "utf8").toString("base64")}`;
+  let plugin;
+  try {
+    plugin = (await import(dataUrl)).default;
+  } catch (e) {
+    fail(`${id}: plugin.js does not import cleanly - ${e.message}`);
+    continue;
+  }
+  const wrong = pluginProblem(plugin);
+  if (wrong) {
+    fail(`${id}: ${wrong}`);
+    continue;
+  }
+
+  if (check) {
+    const committed = join(out, "plugin.js");
+    if (existsSync(committed)) {
+      /* Guarantee 4. A stale committed artefact passes every other check in this file
+       * and every digest in the catalogue, because the digest is taken FROM it. */
+      const have = readFileSync(committed, "utf8");
+      if (have !== js) {
+        fail(
+          `${id}: the committed ${relative(process.cwd(), committed)} does not match its ` +
+            `source. It is what players actually run, and a digest taken from it would ` +
+            `match it perfectly. Rebuild it and commit the result.`,
+        );
+        continue;
+      }
+      note(`${id}: ok, and the committed plugin.js is current (${(js.length / 1024).toFixed(1)} KiB, api ${plugin.api})`);
+      continue;
+    }
+    note(`${id}: ok (${(js.length / 1024).toFixed(1)} KiB, api ${plugin.api})`);
+    continue;
+  }
+  mkdirSync(out, { recursive: true });
+  writeFileSync(join(out, "plugin.js"), js, "utf8");
+  if (resolve(out) !== resolve(dir)) {
+    /* The manifest travels with it: a mod folder without one is not a mod, and the
+     * shared validator (readModDir) requires a top-level manifest.json from every
+     * source alike. Copied verbatim - this tool is not in the business of editing what
+     * a mod declares, and a rewritten id would install under the wrong name. */
+    writeFileSync(
+      join(out, "manifest.json"),
+      readFileSync(join(dir, "manifest.json"), "utf8"),
+      "utf8",
+    );
+  }
+  note(
+    `${id}: wrote ${relative(process.cwd(), join(out, "plugin.js"))} ` +
+      `(${(js.length / 1024).toFixed(1)} KiB, api ${plugin.api})`,
+  );
+}
+
+if (failed) process.exitCode = 1;
+
+/**
+ * What is wrong with a built default export, or null.
+ *
+ * The same rules as the host's validateModPlugin, restated here rather than imported
+ * because that module lives in the web front end and this is a plain script the SDK
+ * ships. The duplication is two field checks; importing a compiled copy would tie the
+ * build step to whether the front end happens to have been built.
+ */
+function pluginProblem(plugin) {
+  if (plugin === null || plugin === undefined) return "plugin.js has no default export";
+  if (typeof plugin !== "object" && typeof plugin !== "function") {
+    return `plugin.js default-exports a ${typeof plugin}, not a plugin object`;
+  }
+  if (!Number.isInteger(plugin.api)) return 'plugin.js declares no integer "api" version';
+  if (plugin.hooks === undefined && plugin.register === undefined) {
+    return "plugin.js declares neither hooks nor register, so it would do nothing";
+  }
+  for (const name of ["hooks", "register", "uninstall"]) {
+    if (plugin[name] !== undefined && typeof plugin[name] !== "function") {
+      return `plugin.js: ${name} is not a function`;
+    }
+  }
+  return null;
+}

package/dist/engine.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The ENGINE gate: may a pack load on this build of the game?
+ *
+ * A manifest's `engine` is a semver RANGE over the engine's version
+ * (core's ENGINE_VERSION), declared by the pack author to say which builds their
+ * pack was written for. It has existed on PackManifest since the manifest was
+ * written, every discovery path in the host carefully carries it through
+ * normalisation - and until now NOTHING read it. `satisfies()` had exactly one
+ * caller, resolve.ts, for mod-to-mod `dependencies`.
+ *
+ * A range nothing evaluates is worse than no field at all, because authors fill it
+ * in and believe it. Two of the three first-party mods had drifted to
+ * `"engine": "4.2.x"` - the ANGBAND baseline (PARITY_BASELINE), not the port's
+ * version - and no test, no build and no boot could notice, because no code path
+ * ever compared it to anything.
+ *
+ * SEPARATE FROM `modApi`, and deliberately so; manifest.ts documents why at the
+ * field. The two answer different questions and must not be merged:
+ *
+ *   engine  a RANGE over the game's version, declared by any pack. "This content
+ *           was written for these builds." A patch release moves the game's
+ *           version and not the plugin ABI, so a range is the right shape.
+ *   modApi  an exact INTEGER, required of a pack shipping plugin.js, matched
+ *           exactly, because the ABI is unstable before 1.0 and a range would
+ *           promise a compatibility that does not exist.
+ *
+ * A pack can fail either, both, or neither, and the reasons a player must read are
+ * different in each case - so this returns a discriminated verdict rather than a
+ * boolean, and the caller keeps them apart.
+ */
+import type { PackManifest } from "./manifest.js";
+/**
+ * Why a pack may not load here - or that it may.
+ *
+ * `kind` rather than only prose, because the two failures have different AUDIENCES
+ * and a caller may want to route them differently: `out-of-range` is a message for
+ * the PLAYER (nothing is broken; the versions do not line up), and `bad-manifest`
+ * is a message for the pack's AUTHOR (the manifest does not say anything
+ * evaluable). Asserting on `kind` also keeps the tests off the wording.
+ */
+export type EngineVerdict = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly kind: "out-of-range" | "bad-manifest";
+    readonly why: string;
+};
+/**
+ * Does `engineVersion` satisfy the pack's declared `engine` range?
+ *
+ * An ABSENT range is allowed, and that is not laxity: `engine` is optional on
+ * PackManifest, most packs are pure data that no engine release breaks, and a pack
+ * that declines to guess at future compatibility is making a reasonable choice. An
+ * EMPTY OR MALFORMED range is not the same thing - the author meant to say
+ * something and said something unreadable - so it is refused as an author error
+ * rather than quietly treated as absent.
+ *
+ * Pure, and takes the version as an argument rather than importing it, so a test
+ * can drive any build and so mod-sdk stays independent of core.
+ */
+export declare function engineVerdict(manifest: Pick<PackManifest, "engine">, engineVersion: string): EngineVerdict;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACrB;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CAAC;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB,CAAC;AAIN;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,EACtC,aAAa,EAAE,MAAM,GACpB,aAAa,CAuCf"}

package/dist/engine.js

@@ -0,0 +1,88 @@
+/**
+ * The ENGINE gate: may a pack load on this build of the game?
+ *
+ * A manifest's `engine` is a semver RANGE over the engine's version
+ * (core's ENGINE_VERSION), declared by the pack author to say which builds their
+ * pack was written for. It has existed on PackManifest since the manifest was
+ * written, every discovery path in the host carefully carries it through
+ * normalisation - and until now NOTHING read it. `satisfies()` had exactly one
+ * caller, resolve.ts, for mod-to-mod `dependencies`.
+ *
+ * A range nothing evaluates is worse than no field at all, because authors fill it
+ * in and believe it. Two of the three first-party mods had drifted to
+ * `"engine": "4.2.x"` - the ANGBAND baseline (PARITY_BASELINE), not the port's
+ * version - and no test, no build and no boot could notice, because no code path
+ * ever compared it to anything.
+ *
+ * SEPARATE FROM `modApi`, and deliberately so; manifest.ts documents why at the
+ * field. The two answer different questions and must not be merged:
+ *
+ *   engine  a RANGE over the game's version, declared by any pack. "This content
+ *           was written for these builds." A patch release moves the game's
+ *           version and not the plugin ABI, so a range is the right shape.
+ *   modApi  an exact INTEGER, required of a pack shipping plugin.js, matched
+ *           exactly, because the ABI is unstable before 1.0 and a range would
+ *           promise a compatibility that does not exist.
+ *
+ * A pack can fail either, both, or neither, and the reasons a player must read are
+ * different in each case - so this returns a discriminated verdict rather than a
+ * boolean, and the caller keeps them apart.
+ */
+import { satisfies } from "./semver.js";
+const OK = { ok: true };
+/**
+ * Does `engineVersion` satisfy the pack's declared `engine` range?
+ *
+ * An ABSENT range is allowed, and that is not laxity: `engine` is optional on
+ * PackManifest, most packs are pure data that no engine release breaks, and a pack
+ * that declines to guess at future compatibility is making a reasonable choice. An
+ * EMPTY OR MALFORMED range is not the same thing - the author meant to say
+ * something and said something unreadable - so it is refused as an author error
+ * rather than quietly treated as absent.
+ *
+ * Pure, and takes the version as an argument rather than importing it, so a test
+ * can drive any build and so mod-sdk stays independent of core.
+ */
+export function engineVerdict(manifest, engineVersion) {
+    const range = manifest.engine;
+    if (range === undefined)
+        return OK;
+    let matched;
+    try {
+        matched = satisfies(engineVersion, range);
+    }
+    catch (e) {
+        /* satisfies() throws SemverError for an empty range and for any token it cannot
+         * parse. It also throws if `engineVersion` itself is unparseable, which would be
+         * the GAME's fault and not the pack's - but that is a build-time impossibility
+         * (core's ENGINE_VERSION is a literal) and pretending to distinguish it here
+         * would mean claiming to know which of the two strings was wrong. The range is
+         * the one an author can fix, and the message quotes it so they can see it. */
+        return {
+            ok: false,
+            kind: "bad-manifest",
+            why: `declares "engine": ${JSON.stringify(range)}, which is not a version range ` +
+                `this game can read (${message(e)}) - the manifest needs fixing`,
+        };
+    }
+    if (matched)
+        return OK;
+    /* BOTH versions, and no claim about which side is behind. The modApi gate above it
+     * does say which way round, and it can: it compares two integers and the larger one
+     * is the newer. A RANGE does not give that for free - a mod wanting `^0.20.0` on a
+     * 0.10.0 build needs a newer GAME, one wanting `<0.5.0` needs a newer MOD, and
+     * telling them apart means computing the range's bounds, which this matcher does not
+     * expose. Naming the pair says everything true and nothing invented; a confident
+     * "the mod needs updating" would be wrong half the time, on the one line the player
+     * acts on. */
+    return {
+        ok: false,
+        kind: "out-of-range",
+        why: `was written for engine ${range}, and this game is ${engineVersion} - ` +
+            `the two do not line up, so one of them needs an update before it can load`,
+    };
+}
+function message(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAmBxC,MAAM,EAAE,GAAkB,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AAEvC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAsC,EACtC,aAAqB;IAErB,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC;IAC9B,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAEnC,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,SAAS,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX;;;;;sFAK8E;QAC9E,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,cAAc;YACpB,GAAG,EACD,sBAAsB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,iCAAiC;gBAC5E,uBAAuB,OAAO,CAAC,CAAC,CAAC,+BAA+B;SACnE,CAAC;IACJ,CAAC;IACD,IAAI,OAAO;QAAE,OAAO,EAAE,CAAC;IAEvB;;;;;;;kBAOc;IACd,OAAO;QACL,EAAE,EAAE,KAAK;QACT,IAAI,EAAE,cAAc;QACpB,GAAG,EACD,0BAA0B,KAAK,sBAAsB,aAAa,KAAK;YACvE,2EAA2E;KAC9E,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,CAAU;IACzB,OAAO,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC"}

package/dist/index.d.ts

@@ -15,10 +15,12 @@
 export { hasFacet, ManifestError, PACK_SHAPES, packFacets, packRef, slugify, validateManifest, } from "./manifest.js";
 export type { Capability, PackManifest, PackRef, PackRule, PackShape, PackTilePack, } from "./manifest.js";
 export { ResolveError, resolveLoadOrder } from "./resolve.js";
-export { satisfies, SemverError } from "./semver.js";
+export { compareSemver, satisfies, SemverError } from "./semver.js";
+export { engineVerdict } from "./engine.js";
+export type { EngineVerdict } from "./engine.js";
 export { ComposeError, composePacks, mergePatch } from "./compose.js";
-export { composeContentPacks } from "./loader.js";
-export type { ComposedContent, LoadedPack } from "./loader.js";
+export { composeContentPacks, composeDroppingBroken } from "./loader.js";
+export type { ComposedContent, ComposeFault, DroppedPack, LoadedPack } from "./loader.js";
 export { KEYED_RECORD_FILES, keyDescription, keySpecFor, RECORD_KEY_SPECS, recordKey, } from "./record-key.js";
 export type { RecordKeySpec } from "./record-key.js";
 export type { ComposedRecord, FileContribution, JsonRecord, JsonValue, PackContent, } from "./compose.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,QAAQ,EACR,aAAa,EACb,WAAW,EACX,UAAU,EACV,OAAO,EACP,OAAO,EACP,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,UAAU,EACV,YAAY,EACZ,OAAO,EACP,QAAQ,EACR,SAAS,EACT,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,SAAS,GACV,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,SAAS,EACT,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,aAAa,EACb,aAAa,EACb,OAAO,EACP,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,YAAY,EACV,cAAc,EACd,UAAU,EACV,cAAc,EACd,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpF,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,QAAQ,EACR,aAAa,EACb,WAAW,EACX,UAAU,EACV,OAAO,EACP,OAAO,EACP,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,UAAU,EACV,YAAY,EACZ,OAAO,EACP,QAAQ,EACR,SAAS,EACT,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,SAAS,GACV,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,SAAS,EACT,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,aAAa,EACb,aAAa,EACb,OAAO,EACP,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,YAAY,EACV,cAAc,EACd,UAAU,EACV,cAAc,EACd,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpF,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -14,9 +14,10 @@
  */
 export { hasFacet, ManifestError, PACK_SHAPES, packFacets, packRef, slugify, validateManifest, } from "./manifest.js";
 export { ResolveError, resolveLoadOrder } from "./resolve.js";
-export { satisfies, SemverError } from "./semver.js";
+export { compareSemver, satisfies, SemverError } from "./semver.js";
+export { engineVerdict } from "./engine.js";
 export { ComposeError, composePacks, mergePatch } from "./compose.js";
-export { composeContentPacks } from "./loader.js";
+export { composeContentPacks, composeDroppingBroken } from "./loader.js";
 export { KEYED_RECORD_FILES, keyDescription, keySpecFor, RECORD_KEY_SPECS, recordKey, } from "./record-key.js";
 export { applyFieldPatch, composeFieldPatches, PatchError, touchedFields, } from "./patch.js";
 export { computeConflictReport } from "./conflicts.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,QAAQ,EACR,aAAa,EACb,WAAW,EACX,UAAU,EACV,OAAO,EACP,OAAO,EACP,gBAAgB,GACjB,MAAM,eAAe,CAAC;AASvB,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,SAAS,GACV,MAAM,iBAAiB,CAAC;AASzB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC;AAOpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAOvD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,QAAQ,EACR,aAAa,EACb,WAAW,EACX,UAAU,EACV,OAAO,EACP,OAAO,EACP,gBAAgB,GACjB,MAAM,eAAe,CAAC;AASvB,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzE,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,SAAS,GACV,MAAM,iBAAiB,CAAC;AASzB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC;AAOpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAOvD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/loader.d.ts

@@ -46,6 +46,22 @@
  * blank page rather than a message. It is the same shape of channel the pack
  * readers already use (`problems: readonly string[]`), so a host concatenates it
  * into the list it already shows.
+ *
+ * THAT PARAGRAPH WAS ONLY TRUE OF THIS FILE'S OWN REFUSALS, and it read as a
+ * property of composition (2026-07-31). `composePacks` throws ComposeError on a
+ * patch whose target does not exist, and `resolveLoadOrder` throws on a missing
+ * dependency or a cycle - both reached from composeContentPacks, both from a
+ * mod's manifest or contribution, and the host does compose at module scope with
+ * no try. So the one class of mod mistake that stayed loud took the whole game to
+ * a blank page with nothing on screen naming the mod. `composeDroppingBroken`
+ * below is the answer, and it is the rule the rest of the mod system already
+ * follows: one broken mod costs that mod.
+ *
+ * `faults` carries the same refusals as `problems` with the pack id kept SEPARATE
+ * rather than prefixed into the sentence. A host that wants to show a mod its own
+ * problems on its own row cannot get that back out of a formatted line without
+ * parsing this file's message format - which is how a UI comes to depend on
+ * punctuation.
  */
 import type { PackManifest } from "./manifest.js";
 import type { FileContribution } from "./compose.js";
@@ -58,6 +74,16 @@ export interface LoadedPack {
     /** fileName -> that file's contribution (records / patches / ...). */
     files: Record<string, FileContribution>;
 }
+/**
+ * One refused operation with the pack that asked for it kept separate from the
+ * sentence, so a host can put a mod's own problems on that mod's own row.
+ */
+export interface ComposeFault {
+    /** The pack whose operation was refused. */
+    packId: string;
+    /** What could not be honoured, with no id prefix. */
+    why: string;
+}
 /** The merged content: per-file record arrays, in deterministic order. */
 export interface ComposedContent {
     /** fileName -> composed record array. */
@@ -72,6 +98,12 @@ export interface ComposedContent {
      * A host shows these next to the pack-reading problems it already collects.
      */
     problems: string[];
+    /**
+     * The same refusals, attributed. One entry per line in `problems`, in the same
+     * order, with `packId` split out - so a mod manager can show a mod what IT got
+     * wrong without parsing a sentence.
+     */
+    faults: ComposeFault[];
 }
 /**
  * Compose a set of loaded packs into merged per-file record arrays. With a
@@ -80,4 +112,44 @@ export interface ComposedContent {
  * unchanged, so routing the base game through this path is a no-op.
  */
 export declare function composeContentPacks(packs: readonly LoadedPack[]): ComposedContent;
+/** One pack that was left out of a composition, and why. */
+export interface DroppedPack {
+    /** The pack's id. */
+    readonly id: string;
+    /** What it did that could not be composed, as the thrower said it. */
+    readonly why: string;
+}
+/**
+ * Compose, dropping any pack whose contribution or manifest makes composition
+ * IMPOSSIBLE, and reporting which ones went.
+ *
+ * WHY THIS EXISTS. Everything in this file reports rather than throws, and that
+ * made the throwing paths easy to forget: `composePacks` throws ComposeError on a
+ * patch whose target does not exist or a duplicate record name, and
+ * `resolveLoadOrder` throws ResolveError on a missing dependency or a cycle. Both
+ * are reachable from `composeContentPacks` and both are caused by a MOD - so on
+ * the web host, which composes at module scope with no try, one mod's typo was a
+ * blank page. Not a bad message: no page, and therefore no mod manager to open
+ * and no way to turn the offending mod off again. The only exit was clearing
+ * localStorage.
+ *
+ * ONE BROKEN MOD COSTS THAT MOD. That is already the rule everywhere else here -
+ * a bad record file loses one contribution, a plugin that throws at import loses
+ * one plugin, a register() that throws loses one mod - and it is what this
+ * restores for the throwing paths. Each thrown message names its pack
+ * (`<pid>/<file>: ...` from compose.ts, `pack <id> requires ...` from resolve.ts),
+ * so the offender is identified, removed, and composition retried.
+ *
+ * `packs[0]` is the BASE GAME and is never dropped: if it is the pack named, or if
+ * no pack can be identified from the message, everything but the base is dropped
+ * at once. A game with no content cannot start, so that is the floor - and it is
+ * the outcome a player recognises ("my mods are off") rather than a dead tab.
+ *
+ * The loop is bounded by the pack count: every pass either returns or removes one
+ * pack, so it cannot spin.
+ */
+export declare function composeDroppingBroken(packs: readonly LoadedPack[]): {
+    readonly composed: ComposedContent;
+    readonly dropped: readonly DroppedPack[];
+};
 //# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAIlD,OAAO,KAAK,EAAE,gBAAgB,EAA2B,MAAM,cAAc,CAAC;AAI9E;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,YAAY,CAAC;IACvB,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACzC;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACnC,uEAAuE;IACvE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,iFAAiF;IACjF,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAoND;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,UAAU,EAAE,GAC3B,eAAe,CA0FjB"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAIlD,OAAO,KAAK,EAAE,gBAAgB,EAA2B,MAAM,cAAc,CAAC;AAI9E;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,YAAY,CAAC;IACvB,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACzC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACnC,uEAAuE;IACvE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,iFAAiF;IACjF,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;;OAIG;IACH,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAyOD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,UAAU,EAAE,GAC3B,eAAe,CA6FjB;AAED,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,qBAAqB;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG;IACnE,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;CAC1C,CAgCA"}