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

package/LICENSE.md

@@ -0,0 +1,43 @@
+# License
+
+Neo Angband is a derivative work of Angband and retains upstream's dual
+license, as the Angband project asks of its variants (see
+`reference/docs/copying.rst`, which remains the authoritative statement for
+the original code and its assets).
+
+Copyright (c) 1997 Ben Harrison, James E. Wilson, Robert A. Koeneke, and the
+Angband contributors; port code copyright (c) 2026 the Neo Angband
+contributors.
+
+This work is free software; you can redistribute it and/or modify it under
+the terms of either:
+
+a) the GNU General Public License as published by the Free Software
+   Foundation, version 2, or
+
+b) the "Angband licence":
+   This software may be copied and distributed for educational, research,
+   and not for profit purposes provided that this copyright and statement
+   are included in all such copies. Other copyrights may also apply.
+
+## Assets
+
+Asset licenses under `reference/` vary and are NOT all dual-licensed as
+above; see `reference/docs/copying.rst` for the full statements, and
+`packages/web/public/tiles/CREDITS.md` for the four tile packs this port
+actually bundles and the terms each one is bundled under.
+
+The Adam Bolt tiles (any purpose, with or without modification) and David
+Gervais tiles (CC BY 3.0, attribution given in that CREDITS.md) are available
+to tile packs under their own terms. The Shockbolt tile set is a distinct
+case and is **not** bundled: its license grants fee-free distribution *with*
+Angband but withholds modification without the author's permission, and
+withholds use with "other games or projects" absent explicit permission —
+so whether this port may carry it turns on a question only the author can
+settle. CREDITS.md states the grants and the prohibitions in full.
+
+## Mods
+
+Declarative content packs and tile packs are independent works and may be
+licensed as their authors choose. Distributed scripted plugins are safest
+treated as GPLv2 derivatives. See `docs/MODS.md`.

package/README.md

@@ -0,0 +1,72 @@
+# @rpgm-tools/neo-angband-mod-sdk
+
+The mod machinery for [Neo Angband](https://github.com/neostryder/neo-angband):
+manifest schema and validation, the deterministic load-order resolver, and the
+record-composition engine that merges packs.
+
+```bash
+npm install @rpgm-tools/neo-angband-mod-sdk
+```
+
+## Why it is a separate package
+
+The base game loads its own content **through this pipeline, as pack zero**. That
+is the point: there is no privileged path a mod cannot take, because the game
+itself does not have one. This package is that pipeline, with no engine attached —
+so a mod's build script or test can validate a manifest, resolve a load order or
+compose records without pulling in a game.
+
+## What is in it
+
+| Area | Exports |
+| --- | --- |
+| Manifests | `validateManifest`, `PackManifest`, `PackShape`, `packFacets`, `hasFacet`, `packRef`, `slugify` |
+| Load order | `resolveLoadOrder`, `satisfies` (the semver subset the manifests use) |
+| Composition | `composePacks`, `composeContentPacks`, `mergePatch`, `applyFieldPatch`, `composeFieldPatches` |
+| Conflicts | `computeConflictReport`, `RecordConflict`, `FieldTouch`, `RecordOverride` |
+| Record identity | `recordKey`, `keySpecFor`, `KEYED_RECORD_FILES`, `RECORD_KEY_SPECS` |
+| Capabilities | `CapabilitySet`, `parseCapability` — what a scripted plugin is allowed to reach |
+
+```ts
+import { validateManifest, ManifestError } from "@rpgm-tools/neo-angband-mod-sdk";
+
+try {
+  const manifest = validateManifest(JSON.parse(text));
+  console.log(manifest.id, manifest.shape, manifest.modApi);
+} catch (e) {
+  if (e instanceof ManifestError) console.error(`bad manifest: ${e.message}`);
+}
+```
+
+## The three pack shapes
+
+- **content** — declarative JSON validated against the record schemas. Safe by
+  construction: it cannot execute anything.
+- **tiles** — a tile pack, either a tilesheet re-skin or a loose Linoleum pack.
+- **plugin** — a scripted mod. It default-exports a `ModPlugin` and receives the
+  running engine as `ctx.core`, because a module loaded out of a mod folder cannot
+  resolve a bare specifier and a bundled copy of the engine would give the plugin
+  its own registries while the game ran on another set.
+
+A single mod may declare several of these as **facets**; `packFacets` is what
+reads them.
+
+## Related
+
+- [`@rpgm-tools/neo-angband-core`](https://www.npmjs.com/package/@rpgm-tools/neo-angband-core) — the engine itself
+- [docs/MODS.md](https://github.com/neostryder/neo-angband/blob/master/docs/MODS.md) — the full modding guide
+- First-party mods: [qol](https://github.com/neostryder/neo-angband-mod-qol) ·
+  [bug-fixes](https://github.com/neostryder/neo-angband-mod-bug-fixes) ·
+  [neo-linoleum](https://github.com/neostryder/neo-angband-mod-linoleum) ·
+  [borg](https://github.com/neostryder/neo-angband-mod-borg)
+
+## Versioning
+
+`0.9.x` is the pre-release line and the API can change inside it; `1.0.0` is
+reserved for the game's public release.
+
+## Licence
+
+GNU GPL v2, or the Angband licence, at your option — Angband's dual licence, kept
+as the Angband project asks of its variants. npm carries one SPDX identifier so the
+manifest says `GPL-2.0-only`; both texts are in [LICENSE.md](LICENSE.md).

package/dist/capabilities.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Capability model for scripted plugins (MOD_LIFECYCLE.md section 4, P7
+ * phase 5).
+ *
+ * Only `shape: plugin` packs may request capabilities; content and tile
+ * packs are validated data that cannot execute, so they request none
+ * (docs/MODS.md trust tiers). A plugin's `capabilities` list in its
+ * manifest is the consent surface: the installer shows each one in plain
+ * language, the user approves, and the runtime grants exactly that set -
+ * nothing a plugin did not ask for and the user did not see. The
+ * perceive/act facades (a later P7 phase) call `CapabilitySet.check()`
+ * before honoring a request; an ungranted capability throws a clear
+ * author-facing error rather than silently doing nothing or diverging.
+ *
+ * Vocabulary (four forms, MOD_LIFECYCLE section 4 / the frost example in
+ * section 2):
+ *  - "command:add"          - register commands on the act facade.
+ *  - "event:<name>"         - subscribe to an engine event, e.g.
+ *                             "event:turn-start".
+ *  - "state:<domain>.read"  - read one perceive-facade domain, e.g.
+ *                             "state:party.read"; or the wildcard
+ *                             "state:*.read" for any domain.
+ *  - "network:<host>"       - outbound network to one host; or "network:*"
+ *                             for any host. Not in the section-4 examples
+ *                             verbatim, but named there ("network access to
+ *                             api.example.com"); "*" is this module's
+ *                             extension for a plugin that genuinely needs
+ *                             unrestricted egress, and reads the same way
+ *                             the other wildcards do.
+ *  - "registry:<domain>"    - override a game SYSTEM registry from a TRUSTED
+ *                             in-process plugin (W2.2, core/mod/registry-host.ts):
+ *                             "registry:effect" | "registry:room" |
+ *                             "registry:command" | "registry:monster" |
+ *                             "registry:vocab"; or the wildcard "registry:*"
+ *                             for all of them. "registry:vocab" (W2.3) declares
+ *                             NEW vocabulary (flags/stats/any kind). Distinct
+ *                             from "command:add": that adds a command via the
+ *                             act facade, this replaces what a command DOES (and
+ *                             the effect/room/AI logic behind the game).
+ *                             (The named-core-rule flags the bundled qol /
+ *                             bug-fixes mods use, GameState.modRules, are a
+ *                             DECLARATIVE manifest field - PackManifest.rules -
+ *                             applied by the host, so they need no capability.)
+ *
+ * This module only surfaces `nondeterministic` from the manifest. The
+ * save's determinism ratchet itself - flipping a save from DETERMINISTIC to
+ * NONDETERMINISTIC the first time such a mod is enabled, once and
+ * irreversibly - lives in core/save (decisions 4/18/22), not here.
+ */
+import { type PackManifest } from "./manifest.js";
+export declare class CapabilityError extends Error {
+}
+/** A capability string parsed into its structured form. */
+export type ParsedCapability = {
+    kind: "command";
+    action: "add";
+} | {
+    kind: "event";
+    name: string;
+} | {
+    kind: "state";
+    domain: string;
+    access: "read";
+} | {
+    kind: "network";
+    host: string;
+} | {
+    kind: "registry";
+    domain: string;
+};
+/**
+ * Parse and validate a capability string against the vocabulary above,
+ * returning its structured form. Throws CapabilityError on anything
+ * malformed or outside the recognized patterns - an unknown capability is
+ * a hard error, not a silent no-op, since a typo'd request should fail
+ * loudly at install rather than quietly never matching a grant.
+ */
+export declare function parseCapability(cap: string): ParsedCapability;
+/**
+ * The capabilities a plugin was granted, built from its manifest. Facades
+ * hold one of these per loaded plugin and call `check()` before honoring
+ * any request that touches commands, events, state reads, or the network.
+ */
+export declare class CapabilitySet {
+    private readonly grants;
+    private readonly nondeterministic;
+    private readonly affectsGameplay;
+    private constructor();
+    /**
+     * Build a CapabilitySet from a pack manifest. Only `shape: plugin` packs
+     * may request capabilities (MOD_LIFECYCLE section 4): a content or tile
+     * pack with a non-empty `capabilities` list throws CapabilityError, since
+     * that shape cannot execute and so has nothing to grant capabilities to -
+     * the request signals author confusion or an upstream validation bug,
+     * not something to silently ignore.
+     */
+    static fromManifest(manifest: PackManifest): CapabilitySet;
+    /**
+     * True if `cap` is covered by a grant in this set, honoring the
+     * "state:*.read" and "network:*" wildcards. Throws CapabilityError if
+     * `cap` itself is not a recognized capability string.
+     */
+    has(cap: string): boolean;
+    /**
+     * Throws CapabilityError, naming the missing capability and how to fix
+     * it, unless `cap` is granted. This is the guard the perceive/act facades
+     * call before honoring a plugin's request - an author-facing error, not
+     * a silent divergence.
+     */
+    check(cap: string): void;
+    /** True if the manifest declared `nondeterministic: true` (section 4). */
+    isNondeterministic(): boolean;
+    /** True if the manifest declared `affectsGameplay: true`. */
+    isAffectsGameplay(): boolean;
+}
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAY,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAE5D,qBAAa,eAAgB,SAAQ,KAAK;CAAG;AAE7C,2DAA2D;AAC3D,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,KAAK,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAQzC;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAqB7D;AAgCD;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAC3C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAE1C,OAAO;IAUP;;;;;;;OAOG;IACH,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,aAAa;IAgB1D;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKzB;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAOxB,0EAA0E;IAC1E,kBAAkB,IAAI,OAAO;IAI7B,6DAA6D;IAC7D,iBAAiB,IAAI,OAAO;CAG7B"}

package/dist/capabilities.js

@@ -0,0 +1,170 @@
+/**
+ * Capability model for scripted plugins (MOD_LIFECYCLE.md section 4, P7
+ * phase 5).
+ *
+ * Only `shape: plugin` packs may request capabilities; content and tile
+ * packs are validated data that cannot execute, so they request none
+ * (docs/MODS.md trust tiers). A plugin's `capabilities` list in its
+ * manifest is the consent surface: the installer shows each one in plain
+ * language, the user approves, and the runtime grants exactly that set -
+ * nothing a plugin did not ask for and the user did not see. The
+ * perceive/act facades (a later P7 phase) call `CapabilitySet.check()`
+ * before honoring a request; an ungranted capability throws a clear
+ * author-facing error rather than silently doing nothing or diverging.
+ *
+ * Vocabulary (four forms, MOD_LIFECYCLE section 4 / the frost example in
+ * section 2):
+ *  - "command:add"          - register commands on the act facade.
+ *  - "event:<name>"         - subscribe to an engine event, e.g.
+ *                             "event:turn-start".
+ *  - "state:<domain>.read"  - read one perceive-facade domain, e.g.
+ *                             "state:party.read"; or the wildcard
+ *                             "state:*.read" for any domain.
+ *  - "network:<host>"       - outbound network to one host; or "network:*"
+ *                             for any host. Not in the section-4 examples
+ *                             verbatim, but named there ("network access to
+ *                             api.example.com"); "*" is this module's
+ *                             extension for a plugin that genuinely needs
+ *                             unrestricted egress, and reads the same way
+ *                             the other wildcards do.
+ *  - "registry:<domain>"    - override a game SYSTEM registry from a TRUSTED
+ *                             in-process plugin (W2.2, core/mod/registry-host.ts):
+ *                             "registry:effect" | "registry:room" |
+ *                             "registry:command" | "registry:monster" |
+ *                             "registry:vocab"; or the wildcard "registry:*"
+ *                             for all of them. "registry:vocab" (W2.3) declares
+ *                             NEW vocabulary (flags/stats/any kind). Distinct
+ *                             from "command:add": that adds a command via the
+ *                             act facade, this replaces what a command DOES (and
+ *                             the effect/room/AI logic behind the game).
+ *                             (The named-core-rule flags the bundled qol /
+ *                             bug-fixes mods use, GameState.modRules, are a
+ *                             DECLARATIVE manifest field - PackManifest.rules -
+ *                             applied by the host, so they need no capability.)
+ *
+ * This module only surfaces `nondeterministic` from the manifest. The
+ * save's determinism ratchet itself - flipping a save from DETERMINISTIC to
+ * NONDETERMINISTIC the first time such a mod is enabled, once and
+ * irreversibly - lives in core/save (decisions 4/18/22), not here.
+ */
+import { hasFacet } from "./manifest.js";
+export class CapabilityError extends Error {
+}
+const EVENT_RE = /^event:([a-z][a-z0-9-]*)$/;
+const STATE_RE = /^state:(\*|[a-z][a-z0-9-]*)\.read$/;
+const NETWORK_RE = /^network:(\*|[a-zA-Z0-9.-]+)$/;
+/** The override domains ModRegistryHost gates, plus the "*" wildcard. */
+const REGISTRY_RE = /^registry:(\*|effect|room|command|monster|vocab)$/;
+/**
+ * Parse and validate a capability string against the vocabulary above,
+ * returning its structured form. Throws CapabilityError on anything
+ * malformed or outside the recognized patterns - an unknown capability is
+ * a hard error, not a silent no-op, since a typo'd request should fail
+ * loudly at install rather than quietly never matching a grant.
+ */
+export function parseCapability(cap) {
+    if (cap === "command:add") {
+        return { kind: "command", action: "add" };
+    }
+    const event = EVENT_RE.exec(cap);
+    if (event) {
+        return { kind: "event", name: event[1] };
+    }
+    const state = STATE_RE.exec(cap);
+    if (state) {
+        return { kind: "state", domain: state[1], access: "read" };
+    }
+    const network = NETWORK_RE.exec(cap);
+    if (network) {
+        return { kind: "network", host: network[1] };
+    }
+    const registry = REGISTRY_RE.exec(cap);
+    if (registry) {
+        return { kind: "registry", domain: registry[1] };
+    }
+    throw new CapabilityError(`unrecognized capability: "${cap}"`);
+}
+/**
+ * True if `grant` covers `request`. Exact match for command/event, plus the
+ * two documented wildcards: a "state:*.read" grant covers a read of any
+ * domain, and a "network:*" grant covers egress to any host.
+ */
+function grantCovers(grant, request) {
+    switch (request.kind) {
+        case "command":
+            return grant.kind === "command";
+        case "event":
+            return grant.kind === "event" && grant.name === request.name;
+        case "state":
+            return (grant.kind === "state" &&
+                grant.access === request.access &&
+                (grant.domain === "*" || grant.domain === request.domain));
+        case "network":
+            return (grant.kind === "network" &&
+                (grant.host === "*" || grant.host === request.host));
+        case "registry":
+            return (grant.kind === "registry" &&
+                (grant.domain === "*" || grant.domain === request.domain));
+    }
+}
+/**
+ * The capabilities a plugin was granted, built from its manifest. Facades
+ * hold one of these per loaded plugin and call `check()` before honoring
+ * any request that touches commands, events, state reads, or the network.
+ */
+export class CapabilitySet {
+    grants;
+    nondeterministic;
+    affectsGameplay;
+    constructor(grants, nondeterministic, affectsGameplay) {
+        this.grants = grants;
+        this.nondeterministic = nondeterministic;
+        this.affectsGameplay = affectsGameplay;
+    }
+    /**
+     * Build a CapabilitySet from a pack manifest. Only `shape: plugin` packs
+     * may request capabilities (MOD_LIFECYCLE section 4): a content or tile
+     * pack with a non-empty `capabilities` list throws CapabilityError, since
+     * that shape cannot execute and so has nothing to grant capabilities to -
+     * the request signals author confusion or an upstream validation bug,
+     * not something to silently ignore.
+     */
+    static fromManifest(manifest) {
+        const requested = manifest.capabilities ?? [];
+        if (!hasFacet(manifest, "plugin") && requested.length > 0) {
+            throw new CapabilityError(`pack ${manifest.id}: only shape "plugin" packs may request capabilities ` +
+                `(this pack is shape "${manifest.shape}")`);
+        }
+        const grants = requested.map((cap) => parseCapability(cap));
+        return new CapabilitySet(grants, manifest.nondeterministic ?? false, manifest.affectsGameplay ?? false);
+    }
+    /**
+     * True if `cap` is covered by a grant in this set, honoring the
+     * "state:*.read" and "network:*" wildcards. Throws CapabilityError if
+     * `cap` itself is not a recognized capability string.
+     */
+    has(cap) {
+        const request = parseCapability(cap);
+        return this.grants.some((grant) => grantCovers(grant, request));
+    }
+    /**
+     * Throws CapabilityError, naming the missing capability and how to fix
+     * it, unless `cap` is granted. This is the guard the perceive/act facades
+     * call before honoring a plugin's request - an author-facing error, not
+     * a silent divergence.
+     */
+    check(cap) {
+        if (this.has(cap))
+            return;
+        throw new CapabilityError(`this plugin needs capability "${cap}"; add it to pack.json capabilities`);
+    }
+    /** True if the manifest declared `nondeterministic: true` (section 4). */
+    isNondeterministic() {
+        return this.nondeterministic;
+    }
+    /** True if the manifest declared `affectsGameplay: true`. */
+    isAffectsGameplay() {
+        return this.affectsGameplay;
+    }
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

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

package/dist/compose.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Record composition: how a stack of packs becomes one game.
+ *
+ * Every record in the composed game is identified by a PackRef
+ * ("<owner-pack>:<slug>"). Packs may:
+ *  - add records (they become the owner),
+ *  - patch records owned by packs they declare as dependencies
+ *    (deep merge: objects merge per key, arrays and scalars replace,
+ *    an explicit null deletes the key),
+ *  - replace such records wholesale, or
+ *  - remove them.
+ *
+ * The base game is pack zero ("core") and gets no special treatment:
+ * a total conversion is just a pack that replaces or removes core
+ * records. Composition is deterministic given the resolved load order,
+ * and every record carries provenance (owner plus every pack that
+ * modified it) for savefiles and debugging.
+ */
+import type { PackManifest, PackRef } from "./manifest.js";
+import type { FieldPatch } from "./patch.js";
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonRecord = {
+    [key: string]: JsonValue;
+};
+/** One pack's contribution to one record file (e.g. "monster"). */
+export interface FileContribution {
+    /** New records; this pack becomes their owner. Each needs a name. */
+    records?: JsonRecord[];
+    /** Deep-merge patches onto records owned by declared dependencies. */
+    patches?: Record<string, JsonRecord>;
+    /** Wholesale replacements (owner and ref are preserved). */
+    replaces?: Record<string, JsonRecord>;
+    /** Refs to delete from the composed game. */
+    removes?: string[];
+    /**
+     * Field-level patches (see patch.ts): ordered field ops per target ref.
+     * composePacks applies these in load order after the coarse `patches`/
+     * `replaces` for the same pack (each pack's ops fold onto the running
+     * value, which is identical to composeFieldPatches over the ordered
+     * list). The pre-launch conflict report (P7 phase 6) reads the same data
+     * to find same-field collisions without the false-positive whole-record
+     * conflicts `patches` produces.
+     */
+    fieldPatches?: Record<string, FieldPatch>;
+}
+export interface PackContent {
+    manifest: PackManifest;
+    /** Contributions keyed by record file: "monster", "object", ... */
+    files: Record<string, FileContribution>;
+}
+export interface ComposedRecord {
+    ref: PackRef;
+    /** The pack that added the record. */
+    owner: string;
+    /** Every pack that patched or replaced it, in load order. */
+    modifiedBy: string[];
+    value: JsonRecord;
+}
+export declare class ComposeError extends Error {
+}
+/** Deep merge per the pack patch rules. Returns a new object. */
+export declare function mergePatch(base: JsonRecord, patch: JsonRecord): JsonRecord;
+/**
+ * Compose packs (already in resolved load order) into per-file record
+ * maps. Iteration order of each map is deterministic: records appear
+ * in the order their owning packs added them.
+ */
+export declare function composePacks(packs: readonly PackContent[]): Map<string, Map<PackRef, ComposedRecord>>;
+//# sourceMappingURL=compose.d.ts.map

package/dist/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,MAAM,SAAS,GACjB,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AACjC,MAAM,MAAM,UAAU,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEtD,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;IACvB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACtC,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,YAAY,CAAC;IACvB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,OAAO,CAAC;IACb,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,qBAAa,YAAa,SAAQ,KAAK;CAAG;AAE1C,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,GAAG,UAAU,CAkB1E;AAWD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,WAAW,EAAE,GAC5B,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CA4E3C"}

package/dist/compose.js

@@ -0,0 +1,118 @@
+/**
+ * Record composition: how a stack of packs becomes one game.
+ *
+ * Every record in the composed game is identified by a PackRef
+ * ("<owner-pack>:<slug>"). Packs may:
+ *  - add records (they become the owner),
+ *  - patch records owned by packs they declare as dependencies
+ *    (deep merge: objects merge per key, arrays and scalars replace,
+ *    an explicit null deletes the key),
+ *  - replace such records wholesale, or
+ *  - remove them.
+ *
+ * The base game is pack zero ("core") and gets no special treatment:
+ * a total conversion is just a pack that replaces or removes core
+ * records. Composition is deterministic given the resolved load order,
+ * and every record carries provenance (owner plus every pack that
+ * modified it) for savefiles and debugging.
+ */
+import { packRef } from "./manifest.js";
+import { applyFieldPatch } from "./patch.js";
+export class ComposeError extends Error {
+}
+/** Deep merge per the pack patch rules. Returns a new object. */
+export function mergePatch(base, patch) {
+    const out = { ...base };
+    for (const [key, val] of Object.entries(patch)) {
+        if (val === null) {
+            delete out[key];
+        }
+        else if (typeof val === "object" &&
+            !Array.isArray(val) &&
+            typeof out[key] === "object" &&
+            out[key] !== null &&
+            !Array.isArray(out[key])) {
+            out[key] = mergePatch(out[key], val);
+        }
+        else {
+            out[key] = val;
+        }
+    }
+    return out;
+}
+function mayModify(m, ownerPack) {
+    return ownerPack === m.id || (m.dependencies ?? {})[ownerPack] !== undefined;
+}
+function ownerOf(ref) {
+    const at = ref.indexOf(":");
+    return at === -1 ? "" : ref.slice(0, at);
+}
+/**
+ * Compose packs (already in resolved load order) into per-file record
+ * maps. Iteration order of each map is deterministic: records appear
+ * in the order their owning packs added them.
+ */
+export function composePacks(packs) {
+    const game = new Map();
+    for (const pack of packs) {
+        const pid = pack.manifest.id;
+        for (const [file, contrib] of Object.entries(pack.files)) {
+            let table = game.get(file);
+            if (!table) {
+                table = new Map();
+                game.set(file, table);
+            }
+            for (const rec of contrib.records ?? []) {
+                const name = rec["name"];
+                if (typeof name !== "string" || name.length === 0) {
+                    throw new ComposeError(`${pid}/${file}: record without a name`);
+                }
+                const ref = packRef(pid, name);
+                if (table.has(ref)) {
+                    throw new ComposeError(`${pid}/${file}: duplicate record ${ref}`);
+                }
+                table.set(ref, { ref, owner: pid, modifiedBy: [], value: rec });
+            }
+            for (const kind of ["patches", "replaces"]) {
+                for (const [refStr, body] of Object.entries(contrib[kind] ?? {})) {
+                    const ref = refStr;
+                    const existing = table.get(ref);
+                    if (!existing) {
+                        const verb = kind === "patches" ? "patch" : "replace";
+                        throw new ComposeError(`${pid}/${file}: ${verb} target ${ref} does not exist`);
+                    }
+                    if (!mayModify(pack.manifest, ownerOf(ref))) {
+                        throw new ComposeError(`${pid}/${file}: cannot modify ${ref} without declaring ${ownerOf(ref)} as a dependency`);
+                    }
+                    existing.value =
+                        kind === "patches" ? mergePatch(existing.value, body) : body;
+                    existing.modifiedBy.push(pid);
+                }
+            }
+            for (const [refStr, ops] of Object.entries(contrib.fieldPatches ?? {})) {
+                const ref = refStr;
+                const existing = table.get(ref);
+                if (!existing) {
+                    throw new ComposeError(`${pid}/${file}: fieldPatch target ${ref} does not exist`);
+                }
+                if (!mayModify(pack.manifest, ownerOf(ref))) {
+                    throw new ComposeError(`${pid}/${file}: cannot modify ${ref} without declaring ${ownerOf(ref)} as a dependency`);
+                }
+                existing.value = applyFieldPatch(existing.value, ops);
+                existing.modifiedBy.push(pid);
+            }
+            for (const refStr of contrib.removes ?? []) {
+                const ref = refStr;
+                if (!table.has(ref)) {
+                    throw new ComposeError(`${pid}/${file}: remove target ${ref} does not exist`);
+                }
+                if (!mayModify(pack.manifest, ownerOf(ref))) {
+                    throw new ComposeError(`${pid}/${file}: cannot remove ${ref} without declaring ${ownerOf(ref)} as a dependency`);
+                }
+                table.delete(ref);
+            }
+        }
+    }
+    return game;
+}
+//# sourceMappingURL=compose.js.map

package/dist/compose.js.map

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