@rpgm-tools/neo-angband-core 1.3.0 → 1.9.0

package/src/game/player-turn.ts

@@ -116,6 +116,11 @@ export class ActionRegistry {
     this.actions.set(code, action);
   }
 
+  /** Remove an API-2 declaration during its host-owned teardown. */
+  unregister(code: string): void {
+    this.actions.delete(code);
+  }
+
   has(code: string): boolean {
     return this.actions.has(code);
   }

package/src/game/spell-cmd.ts

@@ -431,6 +431,16 @@ export function installSpellCommands(
     }
 
     spellLearn(player, spellIndex, env.msg);
+    const learned = spellByIndex(player.cls, spellIndex);
+    if (learned) {
+      state.modHooks?.abilityGained?.({
+        kind: "spell",
+        spellIndex,
+        name: learned.name,
+        realm: learned.realm.name,
+        command: "cast",
+      });
+    }
     calcSpells(player, deps.statInd, env.msg);
     return state.z.moveEnergy;
   });

package/src/index.ts

@@ -129,6 +129,10 @@ export * from "./session/save-migrate.js";
  * the fold, so both are part of the published API - see mod/hooks.ts. */
 export * from "./mod/hooks.js";
 export * from "./mod/save-blocks.js";
+/* The player-facing half of the same store: what is quarantined, which pack
+ * owned it, and whether that pack can be found now. Read-only over
+ * save-blocks.ts's storage - see mod/orphan-stash.ts. */
+export * from "./mod/orphan-stash.js";
 export * from "./mod/ids.js";
 export * from "./mod/registry-host.js";
 export * from "./mod/vocabulary.js";

package/src/mod/hooks.ts

@@ -114,6 +114,24 @@ export interface HistoryDisplayEntry {
   readonly expandUserInput?: true;
 }
 
+/** A newly available player ability, named without exposing a mutable game object. */
+export type AbilityGained =
+  | {
+      readonly kind: "spell";
+      readonly spellIndex: number;
+      readonly name: string;
+      readonly realm: string;
+      /** The host command that opens this spell's casting picker. */
+      readonly command: "cast";
+    }
+  | {
+      readonly kind: "activation";
+      readonly kindIndex: number;
+      readonly name: string;
+      /** The host command that opens the activation picker. */
+      readonly command: "activate";
+    };
+
 /**
  * A mod's behaviour contributions. Every member is optional; an absent member
  * means "this mod does not touch that point" and core takes its faithful path.
@@ -387,6 +405,16 @@ export interface ModHooks {
    * choices past the character they were made on).
    */
   optionsChanged?: (options: OptionStateData) => void;
+
+  /**
+   * The player learned a spell or gained a known activatable item
+   * (spell-cmd.ts, pickup.ts, and obj-cmd.ts). This is a notification: core has already
+   * committed the knowledge and does not read a return value. `command` is the
+   * semantic command a host turns into its current keyset's activation input;
+   * a mod may use it when offering a keymap without guessing which command the
+   * player uses.
+   */
+  abilityGained?: (ability: AbilityGained) => void;
 }
 
 /**
@@ -415,7 +443,7 @@ export interface ModHooks {
  *  - ANY hooks (saveNoiseScent, shapeLearnObviousFlagsDirectly) are disjunctive:
  *    one mod asking for the data is enough, because the data is additive and a
  *    second mod cannot object.
- *  - NOTIFICATION hooks (optionsChanged, levelRevisited) call every contributor
+ *  - NOTIFICATION hooks (optionsChanged, levelRevisited, abilityGained) call every contributor
  *    in load order.  There is no answer for a later mod to override.
  *
  * WHY THE LAST TWO ARE NOT EXCEPTIONS. "Later wins" answers the question "two
@@ -478,6 +506,7 @@ export const MOD_HOOK_FOLDS: Readonly<Record<keyof ModHooks, ModHookFold>> = {
   levelRevisited: "all-observe",
   messageText: "chained",
   optionsChanged: "all-observe",
+  abilityGained: "all-observe",
 };
 
 /**
@@ -658,6 +687,13 @@ export function guardModHooks(
     };
   }
 
+  const ability = hooks.abilityGained;
+  if (ability) {
+    out.abilityGained = (gained): void => {
+      guard("abilityGained", () => ability({ ...gained }), undefined);
+    };
+  }
+
   return out;
 }
 
@@ -814,6 +850,13 @@ export function composeModHooks(
     };
   }
 
+  const abilityGained = list.map((c) => c.abilityGained).filter(isFn);
+  if (abilityGained.length > 0) {
+    out.abilityGained = (gained): void => {
+      for (const fn of abilityGained) fn({ ...gained });
+    };
+  }
+
   return out;
 }
 

package/src/mod/orphan-stash.ts

@@ -0,0 +1,285 @@
+/**
+ * The stash MODEL: what the orphans store looks like to a player
+ * (MOD_LIFECYCLE.md decisions 7 and 8).
+ *
+ * `save-blocks.ts` owns the storage half. An entity whose defining pack is
+ * absent is frozen verbatim into `orphans:<id>@<version>` with its content id
+ * and its group / equipment-slot relationships intact, and reinstalling the
+ * pack rehydrates it exactly where it was. That half is complete, tested, and
+ * invisible: a player who uninstalls a mod watches their items disappear from
+ * the pack with nothing anywhere saying where they went.
+ *
+ * This module is the other half's DATA. It reads the store and answers the
+ * three questions decision 7's stash view asks - what is set aside, which mod
+ * owned it, and what would bring it back - as a structure a front end renders.
+ * The wording is deliberately NOT here: a screen owns its own sentences, the
+ * same split `screens.ts` keeps against the core's UI models.
+ *
+ * READ-ONLY, AND THAT IS THE DESIGN. Nothing in this file writes to a store or
+ * to a save. `purgeOrphans` is the single exception decision 8 requires, and it
+ * is a pure function that returns an empty store rather than editing one, so
+ * the caller's own assignment is the only mutation and it happens in one place.
+ *
+ * WHAT IT CANNOT SAY. Quarantine is keyed on namespace PRESENCE, so the store
+ * records that `frost` was missing and never why. This module therefore derives
+ * the reason from what the host can see NOW - the pack is not installed, or it
+ * is installed and switched off - rather than reading a reason the store does
+ * not carry. A caller that knows neither gets `"unknown"`, which is honest,
+ * where guessing "uninstalled" would not be. The SHADOWED case (a later mod's
+ * `removes`/`replaces` overriding a record the save depends on) reaches the same
+ * store by the same route the moment quarantine learns to produce it; it needs
+ * nothing here, because a shadowed entity's namespace is present and this
+ * already has a state for that.
+ */
+
+import { namespaceOf, orphanCount } from "./save-blocks.js";
+import type { OrphanEntry, OrphanKind, OrphanStore } from "./save-blocks.js";
+
+/* ------------------------------------------------------------------ *
+ * Categories: what a quarantined entity WAS, in the player's terms.
+ * ------------------------------------------------------------------ */
+
+/**
+ * What one quarantined entity is, as a player would name it.
+ *
+ * A category rather than a re-spelling of `OrphanKind`, because two kinds can
+ * be the same thing to a player (`gearObject` in an equipment slot and one in
+ * the pack differ only in where they were) and one kind can be two things
+ * (`gearObject` is exactly that case). `link` is the one that is NOT a thing
+ * the player owns: it is the group bookkeeping quarantine keeps so a mod's
+ * monster pack returns as a pack, and a screen that listed those as items would
+ * be showing a player a row per internal relationship.
+ */
+export type OrphanCategory =
+  | "worn"
+  | "carried"
+  | "floor"
+  | "held"
+  | "monster"
+  | "trap"
+  | "lore"
+  | "artifact"
+  | "cached"
+  | "link";
+
+/** Whether a `gearObject` orphan was quarantined out of an equipment slot. */
+function wasWorn(entry: OrphanEntry): boolean {
+  const locus = entry.locus;
+  if (typeof locus !== "object" || locus === null || Array.isArray(locus)) return false;
+  const slots = (locus as { equipSlots?: unknown }).equipSlots;
+  return Array.isArray(slots) && slots.length > 0;
+}
+
+/** The player-facing category of one quarantined entity. */
+export function orphanCategory(entry: OrphanEntry): OrphanCategory {
+  switch (entry.kind) {
+    case "gearObject":
+      return wasWorn(entry) ? "worn" : "carried";
+    case "heldObject":
+      return "held";
+    case "floorObject":
+      return "floor";
+    case "monster":
+      return "monster";
+    case "trap":
+      return "trap";
+    case "lore":
+      return "lore";
+    case "artifactCreated":
+      return "artifact";
+    /* The frozen-level cache (birth_levels_persist): a level the player has
+     * been to and can return to, which is one fact rather than four. */
+    case "cacheMonster":
+    case "cacheHeldObject":
+    case "cacheFloorObject":
+    case "cacheTrap":
+      return "cached";
+    case "group":
+    case "groupMembership":
+    case "cacheGroup":
+    case "cacheGroupMembership":
+      return "link";
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * The model.
+ * ------------------------------------------------------------------ */
+
+/** One quarantined entity, as the stash view lists it. */
+export interface OrphanStashItem {
+  /** The storage kind, for a presenter that wants the exact collection. */
+  readonly kind: OrphanKind;
+  /** What it is to a player. See `OrphanCategory`. */
+  readonly category: OrphanCategory;
+  /** The content id that could not resolve, e.g. `frost:ice-brand`. */
+  readonly ref: string;
+  /**
+   * The id with its namespace stripped, e.g. `ice-brand`.
+   *
+   * The BEST NAME THERE IS, and worth saying why it is not a real one. A frozen
+   * object carries its `kindId` and nothing else - the record that would give it
+   * a printable name came from the mod, which is the thing that is missing - so
+   * `describeObject` has nothing to work from. The id is what the player has,
+   * and it is what `OrphanEntry.ref` was documented to be for.
+   */
+  readonly name: string;
+}
+
+/**
+ * Whether the mod that owns a group of orphans can be found on this machine.
+ *
+ * `absent` and `disabled` are different sentences to a player: one needs a
+ * download and the other needs a switch. `present` means the pack composed and
+ * the entity still could not be put back, which `rehydrateSave` reports by
+ * leaving the entry in the store rather than by throwing.
+ */
+export type OrphanAvailability = "absent" | "disabled" | "present" | "unknown";
+
+/** Everything quarantined under one pack, at the version the save used. */
+export interface OrphanStashGroup {
+  /** The store's own key, `<namespace>@<version>`. */
+  readonly key: string;
+  /** The pack that owned this content, e.g. `frost`. */
+  readonly namespace: string;
+  /** The version that pack was at when the save was written. */
+  readonly version: string;
+  /** What the host can see of that pack right now. */
+  readonly availability: OrphanAvailability;
+  /** The entities, in store order (which is quarantine order). */
+  readonly items: readonly OrphanStashItem[];
+  /**
+   * How many `link` entries this group carries, counted rather than listed.
+   *
+   * Counted BECAUSE the count is the honest number and the rows are not: these
+   * are monster-group relationships, one per member of every quarantined pack,
+   * so a mod with a dozen monsters in groups would fill the screen with rows a
+   * player cannot act on. `total` below is what decision 8's prompt counts, and
+   * it includes these, so the screen and the prompt cannot disagree.
+   */
+  readonly links: number;
+  /** `items.length + links` - every entry under this key. */
+  readonly total: number;
+}
+
+/** The whole stash: every pack with something quarantined under it. */
+export interface OrphanStash {
+  /** Groups sorted by namespace then version, so the screen is stable. */
+  readonly groups: readonly OrphanStashGroup[];
+  /** Every entry in the store, matching `orphanCount`. */
+  readonly total: number;
+}
+
+/** What the host knows about the packs it can see. All optional. */
+export interface OrphanStashDeps {
+  /** Namespaces whose content composed into the running game. */
+  readonly present?: ReadonlySet<string>;
+  /** Namespaces installed on this machine, whether or not they are enabled. */
+  readonly installed?: ReadonlySet<string>;
+}
+
+/**
+ * Split a store key back into the namespace and version that made it.
+ *
+ * The FIRST `@` is the separator, which is what `rehydrateSave` already treats
+ * as the separator when it decides whether a key's pack is present. A namespace
+ * cannot contain one, so the two can only disagree on a version that does, and
+ * disagreeing there would mean this screen naming a pack that rehydrate would
+ * never match.
+ */
+export function parseOrphanKey(key: string): { namespace: string; version: string } {
+  const at = key.indexOf("@");
+  if (at <= 0) return { namespace: key, version: "" };
+  return { namespace: key.slice(0, at), version: key.slice(at + 1) };
+}
+
+function availabilityOf(namespace: string, deps: OrphanStashDeps): OrphanAvailability {
+  const { present, installed } = deps;
+  if (present?.has(namespace)) return "present";
+  if (installed?.has(namespace)) return "disabled";
+  /* Absent is a claim, so it needs evidence: a caller that supplied neither set
+   * knows nothing about this pack and must not be reported as having looked. */
+  if (present === undefined && installed === undefined) return "unknown";
+  return "absent";
+}
+
+function itemOf(entry: OrphanEntry): OrphanStashItem {
+  const namespace = namespaceOf(entry.ref);
+  return {
+    kind: entry.kind,
+    category: orphanCategory(entry),
+    ref: entry.ref,
+    name:
+      namespace !== null && entry.ref.startsWith(`${namespace}:`)
+        ? entry.ref.slice(namespace.length + 1)
+        : entry.ref,
+  };
+}
+
+/**
+ * The stash view's model: every quarantined entity, grouped by the pack that
+ * owned it, with what the host can currently see of that pack.
+ *
+ * Pure and total. An empty or absent store gives an empty stash rather than
+ * null, so a caller renders "nothing is set aside" from the same value it
+ * renders a full list from.
+ */
+export function orphanStash(
+  store: OrphanStore | undefined,
+  deps: OrphanStashDeps = {},
+): OrphanStash {
+  const groups: OrphanStashGroup[] = [];
+  for (const [key, entries] of Object.entries(store ?? {})) {
+    const { namespace, version } = parseOrphanKey(key);
+    const items: OrphanStashItem[] = [];
+    let links = 0;
+    for (const entry of entries) {
+      if (orphanCategory(entry) === "link") links++;
+      else items.push(itemOf(entry));
+    }
+    groups.push({
+      key,
+      namespace,
+      version,
+      availability: availabilityOf(namespace, deps),
+      items,
+      links,
+      total: items.length + links,
+    });
+  }
+  groups.sort((a, b) => a.namespace.localeCompare(b.namespace) || a.version.localeCompare(b.version));
+  return { groups, total: orphanCount(store) };
+}
+
+/* ------------------------------------------------------------------ *
+ * Decision 8: the one-time keep/purge question.
+ * ------------------------------------------------------------------ */
+
+/**
+ * Whether the one-time per-save keep/purge prompt is due (decision 8).
+ *
+ * Due exactly once: something is quarantined and this save has not been asked
+ * yet. Keeping is the default and answering either way sets `acknowledged`, so
+ * a player who declines is never nagged and a save that later quarantines more
+ * content is not re-asked - which is what "one-time per-save" means.
+ */
+export function orphanPromptDue(
+  store: OrphanStore | undefined,
+  acknowledged: boolean,
+): boolean {
+  return !acknowledged && orphanCount(store) > 0;
+}
+
+/**
+ * Decision 8's purge: every quarantined entity, gone permanently.
+ *
+ * A pure function returning the EMPTY store rather than one that empties the
+ * caller's, so the only write is the caller's own assignment. That matters more
+ * than it looks: this is the one destructive act in the whole orphan path, and
+ * the guarantee it breaks - nothing a player earned vanishes without a trace -
+ * is only allowed to break behind an explicit, counted, one-time confirmation.
+ * Quarantine remains the default; nothing calls this without an answer.
+ */
+export function purgeOrphans(): OrphanStore {
+  return {};
+}

package/src/mod/registry-host.ts

@@ -328,10 +328,15 @@ export type MenuTransformer = (
   rows: readonly MenuTransformRow[],
 ) => readonly MenuTransformRow[];
 
+/** Code to run after the player selects a mod-owned menu action. */
+export type MenuActionHandler = () => void | Promise<void>;
+
 /** Structural target implemented by the web front end, not by headless core. */
 export interface MenuRegistryTarget {
   register(id: string, transformer: MenuTransformer, owner?: string): void;
   handlerFor(id: string): MenuTransformer | null;
+  /** Add one owned, runnable row to an existing menu. */
+  addAction?(id: string, action: string, label: string, handler: MenuActionHandler, owner?: string): void;
 }
 
 /**
@@ -680,6 +685,16 @@ export interface MenuFacade {
   register(id: string, transformer: MenuTransformer): void;
   /** The currently installed transformer, for layering/wrapping an earlier mod. */
   handlerFor(id: string): MenuTransformer | null;
+  /**
+   * Add a row the host can actually run, rather than merely transforming the
+   * presentation of a row whose action core already knows. `action` is scoped
+   * to this mod, so two mods may both call theirs "backup" without colliding.
+   *
+   * The first supported location is `core:game-menu`, the Escape game menu.
+   * The callback starts directly from the selection gesture, so a browser-only
+   * action such as `ctx.backupFolder.choose()` may still open its folder picker.
+   */
+  addAction(id: "core:game-menu", action: string, label: string, handler: MenuActionHandler): void;
 }
 
 /**
@@ -1608,6 +1623,14 @@ export function createModRegistryHost(
         requireCap(capabilities, "menu");
         return requireTarget(targets.menus, "menu").handlerFor(id);
       },
+      addAction(id, action, label, handler): void {
+        requireCap(capabilities, "menu");
+        const menus = requireTarget(targets.menus, "menu");
+        if (!menus.addAction) {
+          throw new Error("mod registry: menu actions are not available in this game (host did not wire them)");
+        }
+        menus.addAction(id, action, label, handler);
+      },
     },
     tiles: {
       register(filler): void {

package/src/mod/save-blocks.ts

@@ -52,9 +52,14 @@
  * separate hard-incompatibility concern, not a quarantine case. Finer
  * sub-property granularity (a mod ego or brand on an otherwise-core object, a
  * mod origin-race on a core object) degrades to the base entity and is a
- * documented follow-up. The player-facing recoveries built ON TOP of this store
- * (stranded characters returning to town, mod items surfaced in the home, the
- * stash view) are P-UI work per MOD_LIFECYCLE section 6 step 2.
+ * documented follow-up. Of the player-facing recoveries built ON TOP of this
+ * store (MOD_LIFECYCLE decision 7), the stash view and the one-time keep/purge
+ * question are built - `mod/orphan-stash.ts` is the read-only model and
+ * `packages/web/src/mod-orphans.ts` the screen - and a quarantined item is
+ * surfaced there rather than as home stock, because the exact restore this file
+ * performs needs the gear handle and equipment slots that only the store
+ * carries. Returning a stranded character to town is still P-UI work per
+ * MOD_LIFECYCLE section 6 step 2.
  */
 
 import { parseId } from "./ids.js";

package/src/session/game.ts

@@ -525,6 +525,20 @@ export interface StartedGame {
   orphans: OrphanStore;
   /** decision-8: whether the one-time orphan keep/purge prompt has been shown. */
   orphansAcknowledged: boolean;
+  /**
+   * How many entities THIS load newly quarantined, as opposed to how many the
+   * store holds (`orphanCount(orphans)` answers that).
+   *
+   * The difference is the whole value of the number. A save reloaded with the
+   * same mod still missing quarantines nothing new - the entities were pruned
+   * out of the live collections on the first load and written into the store -
+   * so this is non-zero exactly on the load where the loss actually happened.
+   * That is the load a host should say something on (MOD_LIFECYCLE decision 7's
+   * "nothing a player earned vanishes without a trace"); saying it on every
+   * subsequent boot would be a nag, and saying it on none of them is the silence
+   * the stash view exists to end. 0 on a new game and on a clean reload.
+   */
+  quarantined: number;
   /**
    * Namespaces present now whose recorded content hash no longer matches
    * their current one (issue #20, save-blocks.ts mismatchedNamespaces): a
@@ -3856,6 +3870,7 @@ export function startGame(pack: GamePack, opts: StartGameOptions = {}): StartedG
     mods: {},
     orphans: {},
     orphansAcknowledged: false,
+    quarantined: 0,
     mismatchedPacks: [],
     options,
     randartSeed,
@@ -4778,6 +4793,7 @@ export function loadGame(
     mods: save.mods ?? {},
     orphans: quarantine.orphans,
     orphansAcknowledged: save.orphansAcknowledged ?? false,
+    quarantined: quarantine.quarantined,
     mismatchedPacks,
     ...(migration.applied.length > 0 || migration.notes.length > 0
       ? { saveMigration: { applied: migration.applied, notes: migration.notes } }

package/src/version.ts

@@ -24,4 +24,4 @@ export const PARITY_BASELINE = "4.2.6";
  * warrants, because a published tag is pinned by digest in a catalogue and
  * must never be moved.
  */
-export const ENGINE_VERSION = "1.3.0";
+export const ENGINE_VERSION = "1.9.0";