@rpgm-tools/neo-angband-mod-sdk 1.3.0 → 1.9.0

package/docs/MOD_COMPATIBILITY.md

@@ -7,11 +7,13 @@ The short answer, and the target the rest of this document explains:
 
 > A mod that is pure data should survive engine releases without being
 > republished. A mod that ships code should survive patch and minor releases,
-> and get a release's warning before an ABI change strands it.
+> and get a release's warning before an ABI change strands it. That ABI includes
+> a named subset of `ctx.core`; the rest of that namespace is an escape hatch.
 
 Written down on 2026-08-02, after measuring how the four gates actually behaved.
 Three of the four were stricter than they needed to be, and the fourth did not
-exist.
+exist. The fourth is `ctx.core`. A named subset of that namespace is part of the
+promise; the rest of it is an escape hatch.
 
 ## The four things that can strand a mod
 
@@ -20,7 +22,7 @@ exist.
 | 1 | `engine` | a semver range over `ENGINE_VERSION` | **warns** for data, **refuses** code |
 | 2 | `modApi` | the plugin ABI, an integer | refuses outside the accepted window |
 | 3 | a patch target | one `patches` / `fieldPatches` / `removes` ref | **skips that op**, keeps the mod |
-| 4 | `ctx.core` | any of the engine's ~1950 exports | nothing. See below. |
+| 4 | `ctx.core` | a guaranteed name disappearing; any other export a plugin actually calls | the loader still does nothing at load time; a guaranteed name cannot be removed from the engine without an alias or a two-release ABI bump. See below. |
 
 ### 1. `engine` is a label on data and a gate on code
 
@@ -231,10 +233,10 @@ instead of `values`, say) took down the whole pack, or every installed mod when
 the raw error named none of them; it is now refused the same way a missing
 patch target already was.
 
-### 4. The handed-in namespaces are not covered by any of the above, and that is the honest gap
+### 4. `ctx.core` is handed over whole; a named subset of it is guaranteed
 
 `ModPluginContext.core` is the **live core module namespace** - the whole engine,
-around 1,950 runtime exports, deliberately not a curated slice (decision 18, and
+1,974 runtime exports, deliberately not a curated slice (decision 18, and
 because a curated list is the thing that drifts). The count is not maintained by
 hand: `packages/core/mod-api-surface.json` is the recorded surface and
 `mod-core-surface.test.ts` fails in BOTH directions against it, so a removal and
@@ -247,12 +249,60 @@ A core function can be renamed without touching any of that, so the one number a
 mod author checks says nothing about the surface they spend all their time
 calling.
 
-What exists now is not a fence but a **ratchet**:
+That width is why the whole namespace cannot carry the compatibility promise: a
+ban on removing any of 1,974 names would freeze the port. First-party plugins
+call 23 of those names at runtime, and those 23 are the part of `ctx.core` the
+promise covers.
+
+| Export | `typeof` | Called by |
+|---|---|---|
+| `DDGRID` | object | feature-restoration |
+| `FEAT` | object | bug-fixes, borg |
+| `MON_RACE_FLAG_ENTRIES` | object | borg |
+| `MON_SPELL_ENTRIES` | object | borg |
+| `OptionState` | function | qol |
+| `REST_COMPLETE` | number | borg |
+| `RSF` | object | borg |
+| `Rng` | function | borg |
+| `TV` | object | borg |
+| `describeLookGrid` | function | qol |
+| `gearObjectForUse` | function | feature-restoration |
+| `knownPile` | function | qol |
+| `loc` | function | bug-fixes |
+| `movementTunnelTest` | function | qol |
+| `parseTilePrefs` | function | upstream-catchup |
+| `placeStairs` | function | bug-fixes |
+| `playerConfuseDir` | function | feature-restoration |
+| `setPrefErrorPolicy` | function | qol |
+| `squareIsEmpty` | function | bug-fixes |
+| `squareIsNoStairs` | function | bug-fixes |
+| `squareIsVisibleTrap` | function | qol |
+| `squareNumWallsAdjacent` | function | bug-fixes |
+| `tunnelAux` | function | qol |
+
+qol 7, bug-fixes 6, borg 7, feature-restoration 3, upstream-catchup 1. linoleum
+and forge call none: linoleum reaches the game through `host.tiles` and
+`ctx.registries`; forge holds `ctx.core` and does not read a name from it.
+
+`packages/core/mod-core-guaranteed.json` is the list, and
+`mod-core-guaranteed.test.ts` fails if any of those names is missing from the
+live namespace a plugin receives, or if its `typeof` has changed. Removing one
+is a compatibility break: keep the old name as an alias, or take the two-release
+`modApi` path. Updating `mod-api-surface.json` is not enough.
+
+**Everything else on `ctx.core` is the escape hatch.** A plugin may call it. A
+rename or removal of an unguaranteed name is recorded in the table below and can
+ship in the same release. Prefer a seam (`ModHooks`, `ctx.registries`, a
+capability-gated facade) when one exists. Reaching past those into an
+unguaranteed name is coupling to that engine release.
+
+What exists for the rest of the namespace is not a fence but a **ratchet**:
 `packages/core/mod-api-surface.json` records every runtime export, and
 `mod-core-surface.test.ts` fails when the set changes in either direction.
 
-- A **removal or rename** fails CI with the names, and the fix is either to keep
-  the old name as an alias or to record the break here and take it knowingly.
+- A **removal or rename** of an unguaranteed name fails CI with the names, and
+  the fix is either to keep the old name as an alias or to record the break here
+  and take it knowingly. A guaranteed name cannot take that second path.
 - An **addition** also fails, with a one-line fix
   (`node tools/api-surface.mjs --update`). That is not pedantry: a baseline that
   tolerated additions would go stale, an export added in one release and removed
@@ -262,9 +312,10 @@ What exists now is not a fence but a **ratchet**:
 #### There are two such namespaces now, watched the same way
 
 `ctx.authoring` is the mod SDK's public barrel, 94 runtime exports, handed over
-whole on exactly the terms `ctx.core` is and for exactly the same reason: a
-curated subset of an authoring API is a second list to maintain, and the first
-thing that happens to a curated list is that it lags the function somebody needs.
+whole for the same reason `ctx.core` is: a curated subset of an authoring API is
+a second list to maintain, and the first thing that happens to a curated list is
+that it lags the function somebody needs. It is ratchet-only. It is not part of
+the named `ctx.core` subset above.
 
 Until it was handed to a plugin, a rename inside the SDK was caught by `tsc -b`
 over this repository, because every consumer of it was in the repository. That
@@ -293,6 +344,9 @@ here for discoverability rather than as a warning.
 | unreleased (2026-08-22) | `ctx.composedRecords` | Every content record the running game was composed from, as JSON, keyed by pack-file stem with no extension. The UNBOUND twin of `ctx.registries`, and the shape the authoring functions above accept: `registries.monsters.races` is bound and carries neither the JSON key names nor the fields that bound to nothing, so a peer table cannot be built from it. Mod-added records are in it on the same terms as core's, each carrying its provenance. Absent during content composition, for the same reason `registries` is. |
 | unreleased (2026-08-22) | `ctx.reloadGame` | The game's own mod-change reload, so a mod that installed something can apply it: every plugin's `uninstall()` runs, the autoplayer hands the keyboard back, the live character is written down, and the session resumes that character instead of landing on the title screen. Behind `mod:install` rather than a capability of its own, because content composes at load and an install a mod cannot follow with a reload leaves the player holding something the process will never load. Not a permission to reload - a plugin reaches `location` with no grant - it is the four steps a mod cannot take for itself. |
 | unreleased (2026-08-22) | `ctx.installMod(...).lines` | A field on both arms of the existing install outcome: the wording the Mods screen itself prints for that same outcome, including one row per unmet requirement and the author's advice under them. Added because a mod built in the game must fail a requirement in the same words a downloaded mod fails in; `problem` is unchanged and remains one whole sentence. |
+| unreleased (2026-09-01) | `ModRegistryHost.menus.addAction` | A capability-gated additive companion to `menus.register`: a plugin declaring `registry:menu` can add one labelled, namespaced callback row to `core:game-menu`. Existing menu transformers keep their behaviour, and an existing plugin neither calls nor observes the new method, so this is a backward-compatible API addition and does not move `MOD_API_VERSION`. |
+| unreleased (2026-09-05) | `ctx.keymaps.entries`, `.rebind`, and `.remove` | The existing `keymap:write` facade now records an owner for each binding it creates. A mod can enumerate, replace, and remove only its own bindings in the active keyset; it cannot learn, overwrite, or remove player bindings or another mod's. Player keymap edits clear a claim, and the mod-change teardown removes claims that remain, so a disabled mod has no surviving keyboard binding. Existing `bind` remains free-trigger-only, so this is a backward-compatible API addition and does not move `MOD_API_VERSION`. |
+| unreleased (2026-09-02) | API-2 Worker ABI | `modApi: 2` plus `runtime: "worker"` and a mod-relative `workerEntry` selects a dedicated module Worker booted by host code rather than importing `plugin.js` into the renderer. Its independently versioned protocol starts with immutable init data, logs, async preferences, own-asset bytes, bag migration, semantic commands, render-coalesced state and display snapshots, and host-rendered declarative panels. The intended final surface also adds versioned read snapshots, host-cached policies for synchronous paths, async hook decisions with validated patches, declarative registry/content and tile declarations, cached frontend/HUD/region display lists, semantic keymap/debug/wizard/storage operations, and mediated mod lifecycle actions. API-1 is temporarily trusted compatibility code, not a permanent dual-API arrangement; the planned end state is full API-2 cutover for every shipped mod. |
 
 #### Removals taken knowingly
 
@@ -428,12 +482,15 @@ Nothing else about `UiEntryConfig` moved, and a plugin that only calls
 unaffected: every one of those gained an OPTIONAL trailing registry argument and
 behaves exactly as before when it is omitted.
 
-**This does not make `ctx.core` stable.** It makes breaking it visible to the
-person breaking it, in the repository where it happens, before it reaches a
-player's browser. The remaining pressure valve is `ModHooks`, which is a closed
-interface of eight members that the bug-fixes mod alone needed six of - if
-authors keep reaching past it into `ctx.core`, that is the signal to grow the
-seam, not to fence the namespace.
+**The rest of `ctx.core` is not frozen.** The ratchet makes a break visible in
+this repository before it reaches a player's browser. Nested keys on a
+guaranteed object (`FEAT.MORE`, `TV.SWORD`, `RSF.BR_FIRE`) follow the same
+shape-change recording as the rest of the engine: the promise is the top-level
+name and its `typeof`, not every property behind it. The remaining pressure
+valve is `ModHooks`, which is a closed interface of eight members that the
+bug-fixes mod alone needed six of - if authors keep reaching past it into
+unguaranteed `ctx.core` names, that is the signal to grow the seam or to add a
+name to the guaranteed subset, not to fence the namespace.
 
 ## What is *not* a compatibility mechanism
 

package/docs/MOD_LIFECYCLE.md

@@ -92,6 +92,15 @@ deletion - even of cosmetics - violates the "nothing a player earned vanishes
 without a trace" guarantee. The prompt is per-save and one-time so it never
 nags; declining leaves everything quarantined and reversible.
 
+BUILT. The prompt is put once the game screen is live, keeps first, and
+counts what a purge would destroy; dismissing it keeps, because the question
+has been asked and keeping is the only answer that destroys nothing. The
+answer is recorded in `SavedGame.orphansAcknowledged` and forced to disk
+immediately, so neither answer is re-asked and a purge cannot be undone by a
+crash. `orphanPromptDue` and `purgeOrphans`
+(`packages/core/src/mod/orphan-stash.ts`) are the whole of the engine side;
+purging is the only write in the orphan path.
+
 ### When a mod's content leaves the game (RATIFIED, decision 19)
 
 Quarantine is the storage mechanism; these are the player-facing
@@ -108,19 +117,35 @@ uninstalled but SHADOWED - a later mod in the load order `removes` or
   content as normal on the next descent; no half-loaded mod geometry is
   ever walked.
 - Stranded items. Items whose definition came from the missing mod are
-  not dropped and not deleted. They are moved into the player's HOME
-  (the game's existing persistent stash) as inert entries - visible,
-  labelled with their origin mod, but not equippable, usable, or
-  sellable while the mod is absent. Reinstalling the mod (same major
-  version) reactivates them in place. This uses the same
-  `orphans:<id>@<version>` store; the home is just where the player sees
-  and reclaims them.
+  not dropped and not deleted. They are frozen in the
+  `orphans:<id>@<version>` store as inert entries - listed, labelled with
+  their origin mod, and not equippable, usable or sellable while the mod
+  is absent. Reinstalling the mod puts each one back in the slot it came
+  out of: an item that was worn returns to that equipment slot when the
+  slot is still free, and one that was carried returns to the pack.
+  BUILT, and built AS THE STORE rather than as home stock: the frozen
+  entry records the gear handle and the equipment slots it was
+  quarantined out of (`packages/core/src/mod/save-blocks.ts`), which is
+  what makes the exact restore possible. It occupies no home slot, no
+  pack slot and no weight while it waits, so it costs the player nothing
+  that a home slot would have cost, and the stash view below is where it
+  is seen and reclaimed.
 - The stash view. A dedicated, always-reachable screen lists everything
   currently quarantined - by uninstall OR by another mod's override -
   grouped by the mod that owns it, showing what it is, why it is inert
-  ("frost uninstalled" / "shadowed by bigmonsters"), and what would
-  restore it ("reinstall frost >=1.0" / "move bigmonsters below frost").
+  ("frost is not installed" / "frost is installed but switched off"), and
+  what would restore it ("install frost again" / "turn frost back on").
   Nothing a player earned ever vanishes without a trace they can find.
+  BUILT: Mods -> "Set aside by a missing mod", screen id
+  `core:mod-orphans` (`packages/web/src/mod-orphans.ts`), over the
+  read-only model in `packages/core/src/mod/orphan-stash.ts`. The row
+  carries the count, and a load that newly freezes something says so on
+  the message line naming what it was. Quarantine is keyed on namespace
+  PRESENCE, so the screen derives the reason from what the host can see
+  now rather than from a reason the store records; the shadowed case
+  reaches the same screen through the same route as soon as quarantine
+  produces it, because a shadowed entity's own namespace is present and
+  the screen already words that state.
 
 These recoveries are graceful degradation, not gameplay rollback: they
 preserve what the player has against a tooling change, and do not let the
@@ -270,17 +295,20 @@ documented, not hidden. The desktop build could clone directly, since it has a
 real filesystem and a real process to run git in. Either way the installer
 consumes the same pack format.
 
-### From a marketplace (future release)
-
-The marketplace is a delivery layer over the same pipeline, not a
-separate system. It serves pre-validated, pre-packaged `.ngpack` bundles
-(the pack directory, zipped, with the manifest and a signed content
-hash) from its own host, and adds browse / search / screenshots /
-ratings in-app. Building it later is cheap because the bundle
-format and the installer are built now, with "git" and "marketplace" as two
-sources feeding one installer. [PROPOSED] The in-app browser is a view
-onto that source; actually building the marketplace backend is a future
-release, as noted.
+### From a marketplace - DECLINED
+
+This section previously proposed a from-scratch, self-hosted marketplace
+serving pre-validated, pre-packaged `.ngpack` bundles (the pack directory,
+zipped, with the manifest and a signed content hash), with browse / search /
+screenshots / ratings in-app. It was never built past this design. Nexus
+Mods integration (tracked separately - see the mod-distribution issues)
+supersedes it: Nexus already provides hosting, browse/search, screenshots
+and ratings at a scale a self-hosted marketplace would take years to reach,
+and building a second, competing one afterward would be duplicate
+infrastructure with a much smaller audience. The manifest fields this
+proposal anticipated (`description`, `screenshots`, `changelog`, `author`,
+`license`, and a hash-based integrity record) were not wasted - they are
+exactly what a Nexus-origin install preview reuses.
 
 ### Updating and uninstalling
 
@@ -639,8 +667,8 @@ pointing at the fix, not a silent divergence.
 Save determinism mode (core-governed ratchet). The label is not just cosmetic:
 every save carries a determinism mode that CORE owns and enforces regardless
 of which mods are loaded. A save starts DETERMINISTIC; the first time a
-determinism-affecting mod is enabled on it, core flips it to NONDETERMINISTIC
-seamlessly and IRREVERSIBLY. Removing the mod later does not restore
+determinism-affecting mod is enabled on it, core flips it to NONDETERMINISTIC.
+The change is IRREVERSIBLE. Removing the mod later does not restore
 deterministic mode - it is a one-way ratchet, so a deterministic (unmodded)
 save cannot be tainted by a mod and then "cleansed" to reclaim its
 reproducibility/anti-scum guarantees. Mods can trigger the flip but can never
@@ -743,13 +771,15 @@ UI next, marketplace last:
    capability consent, profiles), plus the one auto-sort button the
    2026-08-01 amendment above adds. Bulk reordering, staging, collections
    and update watching stay the external manager's job.
-3. Future release: the marketplace backend and in-app browser, plus the
-   externally-authored enabled-set/order file and a Vortex/MO2 extension
-   over the shared on-disk format.
+3. Future release: Nexus Mods integration (a real second pinned origin,
+   not the from-scratch marketplace this item once named - see "From a
+   marketplace" above), the externally-authored enabled-set/order file, and
+   a Vortex/MO2 extension over the shared on-disk format.
 
-A `neo-pack` CLI (validate + bundle, a sibling of `neo-linoleum`) ships
-alongside so authors can check a pack in CI before publishing, and the
-repo carries sample mods that CI installs and runs.
+Authors check a pack in CI with `neo-angband-mod-check` (the same rules
+the game enforces at install) and produce a distributable `plugin.js`
+with `neo-angband-mod-build`. Both ship in `@rpgm-tools/neo-angband-mod-sdk`.
+The repo carries sample mods that CI installs and runs.
 
 ---
 
@@ -766,10 +796,17 @@ repo carries sample mods that CI installs and runs.
 6. Pre-migration snapshot as operational safety, reconciled with the
    no-save-scum rule. [DECIDED]
 7. Uninstall recovery: stranded characters return to town, mod items are
-   quarantined to the player's home and reactivate on reinstall, and a
-   stash view surfaces everything quarantined or shadowed. [DECIDED]
+   quarantined and reactivate in the slot they came out of on reinstall,
+   and a stash view surfaces everything quarantined or shadowed. [DECIDED;
+   the stash view and the item surfacing are BUILT, see "When a mod's
+   content leaves the game" above. The item half is the orphans store
+   rather than home stock, because the store records the gear handle and
+   equipment slots an item was taken from and the home has no way to carry
+   those; the effect a home entry was for - visible, labelled, inert,
+   costing no slot - is what the stash view provides. The stranded-location
+   half is not built.]
 8. Orphan policy: quarantine by default with a one-time per-save keep/purge
-   prompt (keep default); no auto-purge. [DECIDED 2026-07-14]
+   prompt (keep default); no auto-purge. [DECIDED 2026-07-14; BUILT]
 9. Integrate with Vortex and the other popular mod managers, and split the
    labour with them: the game keeps rudimentary management (enable/disable,
    per-patch opt-out, a one-step order nudge, conflict report, profiles)

package/docs/MOD_REACH.md

@@ -1318,7 +1318,7 @@ pack was already surfaced in the mod manager by `discoverContentModManifests`
 (`pack.ts`). The bytes were reachable; only the registration was not.
 
 The non-mod escape hatch is `?tiles=<base-url>` + `?graf=<id>`
-(`tiles.ts:178-187`, `packages/web/src/main.ts:1005-1006`), which also unlocks the full catalog
+(`tiles.ts:178-187`, `packages/web/src/main.ts:1005-1006`), which also exposes the full catalog
 (`tile-catalog.ts:109`). That is a user/URL affordance, not a mod path, and it
 cannot add a grafID.
 
@@ -1453,7 +1453,7 @@ used, and what a failed check costs.
 
 ## (d) The gap list
 
-Ranked by how much of "the whole game can be made over" each one unlocks.
+Ranked by how much of "the whole game can be made over" each one makes moddable.
 
 | # | Capability | Today | What would have to exist |
 | --- | --- | --- | --- |
@@ -1481,6 +1481,23 @@ Ranked by how much of "the whole game can be made over" each one unlocks.
 
 ---
 
+### Gap 21 current correction, 2026-09-06
+
+The row above contains historical measurements. The current code-derived record
+is docs/design/PRESENTATION_OWNER_SEAM.md. Its counts replace the old estimates:
+the HUD has 3 separately replaceable regions, the terminal has 33 full-screen
+erase paths plus its 1 compositor repaint, and 40 semantic ScreenView ids are
+modelled. The full-screen erase ratchet derives 31 region-declared paths, 2
+pending prompt paths, and 34 including the compositor in
+packages/web/src/main-regions.test.ts:430 through
+packages/web/src/main-regions.test.ts:433.
+
+The presentation owner seam is live for the HUD, menus, and ScreenView paths.
+Registry:menu still changes rows and now composes with menu presentation rather
+than replacing it. The two pending prompt paths and screens sharing the
+core:text fallback remain incomplete. The design records the exact surface list,
+the host guarantees, and the compatibility fallback rule.
+
 ## The goal: every dispatch point in this document becomes moddable
 
 **A correction, recorded 2026-08-08.** An earlier revision of this page argued

package/docs/MOD_SEAMS.md

@@ -610,6 +610,13 @@ Six things about it, and the first two are the ones that will surprise you:
   action bar does with its buttons. `modal: true` takes the pointer, takes the
   focus on mount, and gets `role="dialog"`; a plain panel takes neither and gets
   `role="group"`.
+- **The host fits the container to the visual viewport.** On a phone, opening
+  the virtual keyboard can leave the layout viewport at its former height while
+  shrinking the visible rectangle. The host follows `visualViewport` for the
+  panel and the canvas, including its offset, so a modal panel does not extend
+  behind the keyboard. A panel that puts fields near its lower edge should still
+  call `element.scrollIntoView({ block: "center" })` when a field receives focus:
+  a browser may reserve more of the visible rectangle for its own input chrome.
 - **The keyboard is decided per keystroke, by where the caret is.** The game's
   front end has ONE keydown registration - `window`, capture phase, installed at
   import - and every modal handler behind it calls `stopImmediatePropagation`. So

package/docs/PLUGINS.md

@@ -161,7 +161,7 @@ What `ctx` carries:
 | `api` | the ABI version the **host** implements |
 | `engine` | the engine version, if you want to adapt rather than refuse |
 | `flags` | **your** resolved rule toggles: `choices[flag] ?? rule.default`, sliced to the rules your own manifest declares |
-| `core` | the live engine namespace: core's entire public API |
+| `core` | the live engine namespace: core's entire public API. A named subset is guaranteed; the rest is an escape hatch. See [MOD_COMPATIBILITY.md](MOD_COMPATIBILITY.md) |
 | `state` | the live `GameState`. Handed to `register`, `migrateBag`, `controller` and every display seam; **never** to `hooks`, because the host composes hooks before a game exists |
 | `assetUrl` | `(path) => Promise<string \| null>`, a URL for one of *your* files |
 | `data` | your own record files, parsed, keyed without `.json` |
@@ -1392,8 +1392,13 @@ absent paths leave the exact glyph sink active.
 
 The same is true of `UiInput` in `packages/web/src/input-door.ts`. It is the
 single device-neutral route by which keyboard and keymap input reaches screens;
-its direction carries an analog vector and angle. It does not grant a plugin a
-binding registry in this phase. Stored player keymaps are evaluated first when
+its direction carries an analog vector and angle. A plugin that declares and is
+granted `keymap:write` receives `ctx.keymaps` during a live game. `bind()` claims
+only a free trigger; `entries()` lists only bindings the calling mod owns; and
+`rebind()` and `remove()` can change only those owned bindings. A plugin cannot
+read, overwrite, or remove the player's bindings or another mod's bindings. A
+player change clears the mod claim, and bindings still owned by a departing mod
+are removed during host teardown. Stored player keymaps are evaluated first when
 the root owns input; score pages, modals, and run interruption retain their
 existing literal-key gates, so a mod must not use injected input to outrank the
 player's chosen mapping or an active screen.
@@ -1421,7 +1426,7 @@ written down, and the table below is a reading of it:
 | `registry:rune` | what a RUNE is: the unit of object knowledge. `rune.desc` (the recall line), `.name` (the display decoration), `.knows` / `.learn` (the knowledge pair, handed the player so YOUR mod keeps the store, since core never grew a slot for it), `.objectHas` (whether an item carries it) and `.modMessage` (the "You feel stronger!" line, keyed on the modifier). Plus `.contribute`, which is how your rune gets into the list every consumer enumerates, and without it the six tables above are handlers nothing ever calls |
 | `registry:vocab` | declare genuinely new vocabulary (flags, stats, mod-coined kinds) and store per-entity values |
 | `registry:message` | message TYPES: `messages.define(name, sound?)` coins one and returns its number, `.lookup(name)` finds an existing one, `.types()` lists what has been added, `.addSounds(...)` attaches sounds. Adding a `message_type.json` RECORD needs no capability, the same way adding an item does; this is the code half, for a type your own plugin raises |
-| `registry:menu` | rewrite one stable menu id's semantic rows. `menus.handlerFor(id)` returns the earlier transformer, so a later mod wraps it before calling `menus.register(id, ...)`; a throw or a non-row-array result is reported against that mod and leaves the original menu usable |
+| `registry:menu` | rewrite one stable menu id's semantic rows. `menus.handlerFor(id)` returns the earlier transformer, so a later mod wraps it before calling `menus.register(id, ...)`; a throw or a non-row-array result is reported against that mod and leaves the original menu usable. `menus.addAction("core:game-menu", action, label, handler)` adds a namespaced, runnable row to the Escape Game menu; it is the door for a mod-owned callback rather than a rewrite of a core action |
 | `registry:tiles` | supply tiles for content the loaded tile pack does not draw, which in practice means content a mod added. `tiles.register(filler)` installs one filler per mod; every registered filler runs, in load order, after the pack's own prefs and every mod's. It can only write where NOTHING is assigned, so it cannot repaint the tile set even by mistake and two mods cannot fight over an index. The same seam also grew a repaint-in-place door (`fill.transform`, mirror and/or a palette remap over an existing tile) and a player-cell door (`tiles.player`, asked once per frame what the character's own cell should show). See [Filling tiles](#filling-tiles) and [Repainting a tile, and drawing the player's own cell](#repainting-a-tile-and-drawing-the-players-own-cell) |
 
 A facade you did not declare throws when you touch it, even if the player
@@ -1547,6 +1552,31 @@ register(host) {
 }
 ```
 
+That transformer changes presentation only: a row it invents has no core action
+behind it. To add a **runnable** row of your own, declare `registry:menu` and
+use `addAction` instead. The host namespaces `action` by your mod id, appends
+the row to the Escape Game menu, and calls only your handler when the player
+selects it. The handler begins in the selection gesture, so it may open a
+browser folder picker.
+
+```js
+register(host, ctx) {
+  host.menus.addAction(
+    "core:game-menu",
+    "choose-backup-folder",
+    "Choose backup folder...",
+    async () => {
+      const name = await ctx.backupFolder?.choose();
+      ctx.log(name ? `Using backup folder: ${name}` : "Backup folder unchanged.");
+    },
+  );
+}
+```
+
+`core:game-menu` is the only action location in this API version. A callback
+that throws is reported against its mod and returns the player to the Game menu;
+it never falls through to a similarly positioned core row.
+
 Plugin code runs **in process, synchronously**, with the same access to the rng,
 the chunk, the player and the monster that core has, because a deep override
 cannot cross an async, isolated Worker boundary. So it is trusted code, exactly as

package/docs/README.md

@@ -72,9 +72,9 @@ write down at all.
 | **Replace the front end**: draw the world yourself, any way you like | **Complete** | gap 9 |
 | Know **where you may draw**: named regions, in grid cells and CSS pixels, on every frame | **Complete** | gap 9 |
 | Drive the game programmatically: an autoplayer, a bot, a test harness | **Complete** | `BORG.md`, `ModPlugin.controller` |
-| Menus: add, reorder, retitle and re-tag **rows** (`registry:menu`). How a menu is **presented** is not reachable | **WIP** | gap 21 |
-| **Replace the UI**: the HUD, the status line, the message area, menu presentation, the ~50 full screens | **Not yet** | gap 21 |
-| Own a HUD region (messages, vitals, status) with core drawing the ones you do not claim, or **create a region of your own**: ordered, overlapping, transparent, composited, and owning pointer input on the cells it paints | **WIP** | gap 21 |
+| Menus: add, reorder, retitle and re-tag **rows** (registry:menu), then replace the presentation of a supported question | **WIP** | gap 21, PRESENTATION_OWNER_SEAM.md |
+| **Replace the UI**: the HUD, status line, message area, menu presentation, and full screens | **WIP** | gap 21, PRESENTATION_OWNER_SEAM.md |
+| Own a HUD region (messages, vitals, status) with core drawing the ones you do not claim, or **create a region of your own**: ordered, overlapping, transparent, composited, and owning pointer input on the cells it paints | **WIP** | gap 21, PRESENTATION_OWNER_SEAM.md |
 | Retitle, regroup, reorder, re-tag or rebind an existing web keypress command (`registry:menu`); the command's closure stays shell-private | **Complete** | `MOD_REACH.md` row 23 |
 | Rename one of your own rule flags or sections without losing the player's saved choice (`renamedRuleFlags`, `renamedSectionFlags`) | **Complete** | `AUTHORING.md` |
 | Rebind keys, or add a gamepad: `input-door.ts` is host infrastructure, not a seam | **Not yet** | `MOD_SEAMS.md` |
@@ -157,15 +157,17 @@ that has not been settled.
   Scope of record; no repository or code exists yet.
 - Coming as the engine lands them (P7 deliverables): handler registry
   catalog (effects, commands, room builders), the sandbox capability
-  reference for scripted plugins, dialog/quest/shop cookbooks, the
-  `neo-pack` validator/bundler, and publishing guidance.
+  reference for scripted plugins, dialog/quest/shop cookbooks, and
+  publishing guidance. Validate and bundle are not in that list:
+  `neo-angband-mod-check` and `neo-angband-mod-build` already ship in
+  `@rpgm-tools/neo-angband-mod-sdk`.
 
 ## The first-party mods
 
 Seven, **none of them bundled**, all OFF until enabled (see
 `DEFAULT_ENABLED_MODS` - an untouched install is the faithful base game with no mod
 loaded). Each lives in its own repository and arrives through the mod manager's
-*Install a mod...* row:
+*Recommended mods...* row:
 
 | id | shape | where it lives | what it adds |
 | --- | --- | --- | --- |
@@ -446,8 +448,9 @@ version and are called out in release notes.
 **`MOD_COMPATIBILITY.md` is the page that answers "will my mod still work".**
 In one line: a data-only mod should survive engine releases without being
 republished, and a mod that ships code gets a release's warning before an ABI
-change strands it. That page has the mechanisms, the measurements behind them,
-and the one place the promise does not yet hold (`ctx.core`).
+change strands it. That ABI includes a named subset of `ctx.core`; the rest of
+that namespace is an escape hatch. That page has the mechanisms, the
+measurements behind them, and the list of guaranteed names.
 
 ## Licensing for mod authors
 

package/docs/REQUIREMENTS.md

@@ -55,6 +55,12 @@ The game shows it beside the mod's name, so a player can tell two mods of the sa
 
 Without it the mod is offered to every version of the game forever, including the one that changes the thing it depends on. With it, a player is told the mod is too old instead of watching it misbehave. This was advice until it was measured: every mod that had shipped declared one, and the mods that did not were the ones nothing had checked.
 
+### Request only capabilities the game knows
+
+`capabilities-recognized`
+
+A capability string is the consent surface a player reads and the gate the runtime actually opens. An unrecognized string, or a capability on a pack that cannot execute, is refused when the game loads the plugin - after the player has already installed it. This check is CapabilitySet.fromManifest, the same function the loader calls, so a typo that used to pass here and fail there cannot.
+
 ### Declare modApi if the mod ships plugin.js
 
 `plugin-declares-modapi`

package/docs/tutorials/01-tweak-a-value.md

@@ -9,7 +9,7 @@ toolchain, no account, and no copy of the game's source code.
 
 ---
 
-## The whole mod
+## Mod files
 
 A mod is a folder. Make one anywhere you like, call it `my-first-mod`, and put
 two files in it:
@@ -98,7 +98,7 @@ folder...**, and point it at the folder *containing* `my-first-mod`. Then turn i
 on and reload as above. The game remembers the folder, so editing a file and
 reloading the page is your whole edit-and-test loop.
 
-## What you should see
+## Check the result
 
 Buy a dagger in the **Weapon Smiths** (the `3` on the town map) - that is the
 shop that stocks daggers, not the General Store. It now costs around 300 gold
@@ -110,7 +110,7 @@ ordinary again. That is the part worth pausing on: your change is a layer over
 the base game, not an edit to it. Nothing on your machine was modified, and the
 game underneath is still the vanilla one.
 
-## Try changing this
+## Variations to try
 
 - Make the dagger **lighter**: add `{ "op": "set", "path": "weight", "value": 4 }`.
 - Change a **monster** instead. Add a `monster.json` with
@@ -120,7 +120,7 @@ game underneath is still the vanilla one.
   reload. Read the error: that message is your main debugging tool, and it is
   worth seeing once while you already know what is wrong.
 
-## The finished version
+## Sample mod
 
 `samples/tutorials/tutorial-01-tweak-a-value/` in this repository is exactly this mod.
 It is not a copy of the tutorial. It is a mod that gets loaded and checked