@brass-lantern/mcp 0.0.1-stage → 2.3.0

package/dist/docs/pages/guide/how-it-works.md

@@ -0,0 +1,152 @@
+# How it works
+
+Three parts, kept deliberately apart, and shipped as three library packages ([Using the library](https://mrballistic.github.io/brass-lantern/guide/using-the-library)), plus an MCP server for coding agents ([Coding agents](https://mrballistic.github.io/brass-lantern/guide/coding-agents)): the engine and parser are `@brass-lantern/engine`, the terminal and stores are `@brass-lantern/vue`, and the intent server is `@brass-lantern/server`. The engine imports no Vue, Pinia or browser globals, so the same turn loop runs in a browser, in Node (`createGame`) and in tests.
+
+This page is a tour of the internals. File paths are in the [repo](https://github.com/mrballistic/brass-lantern), for readers of the source; nothing here is needed to use the packages.
+
+1. **The engine** (`packages/engine/src/engine/`) is a deterministic state machine. It never knows which game it’s running: everything specific to a world, including its rules, is data.
+2. **The parser** turns what the player typed into `{ action, target, indirect }`. A regex parser in the browser handles the canonical commands instantly. Anything it can’t parse, or parses into something the engine can’t act on, can go to the optional [intent server](https://mrballistic.github.io/brass-lantern/guide/intent-server), where an LLM reads it more loosely. The LLM only *classifies* input; it never writes story text.
+3. **The world** (`packages/engine/src/worlds/`) is one object. Swap it and you have a different game.
+
+```
+browser                                      intent server (optional)
+┌───────────────────────────────────┐        ┌────────────────────────┐
+│ terminal ─► store                 │  POST  │ /api/parse-intent       │
+│               │ splitCommands     │ ─────► │ rate limit, size caps   │──► Gemini
+│               ▼ regex parser      │        │ model chain, deadline   │
+│               ▼ engine ◄── world  │ ◄───── │ reply sanitizing        │
+│               │  (miss? ask LLM)  │        └────────────────────────┘
+│               ▼ output + save     │
+└───────────────────────────────────┘
+```
+
+## From keystroke to reply
+
+The store (`packages/vue/src/stores/game.ts`) runs every line through the same steps:
+
+1. **Meta commands** (SAVE, RESTORE, LOAD, UNDO, RESTART, SCRIPT, THEME, BLOOM, EFFECTS, EJECT, COOKIES) are handled by the store itself, and so is the answer to a SAVE or RESTORE prompt.
+2. **Split.** `splitCommands` (`packages/engine/src/engine/parser.ts`) breaks the line into commands:
+   - First the line is cleaned (`cleanInput`): trimmed, with every run of whitespace made one space. A line still longer than `MAX_INPUT_LENGTH` (1,000 characters) is refused whole: the parsers return nothing, and `createGame().send`, `interpret` and the Vue store answer “[That’s too long for me to follow. Nothing happened.]” (`TOO_LONG_REPLY`) before anything runs. Every pattern is written for the cleaned form, so no line costs more than linear time to read.
+   - Clauses always split on `then`, `;` and full stops, except after `dr.`, `mr.` and the like.
+   - Within a clause, `and` and commas split only when every piece is a recognized command, or an object after a list verb: `get key and wallet` becomes `get key` and `take wallet`.
+   - A clause that isn’t clearly a list (“could you grab my keys and wallet”) stays whole.
+   - Anything inside quotes is masked first, so a quoted “. ” or “, ” never splits a line (`answer “a well. yes”` is one command). A text verb (SAY, ANSWER) takes the rest of the line, and ends it.
+   - Names that contain “and” (`andNames(world)`: every item and character name and alias with the word in it, longest first) are masked too, so `take flair from lost and found and go north` is two commands. The store and `createGame` work the list out once per world.
+
+   Each command may be **captured** first: a room’s or the world’s `capture` (`captureLine` in `packages/engine/src/engine/engine.ts`) can take it before it’s parsed, which ends the line. Captured input never reaches the intent server.
+3. **The conversation.** `interpret` (`packages/engine/src/engine/conversation.ts`) looks at the command in the light of the last one:
+   - **an answer** to a question the engine just asked (“Which door do you mean?” → `trap`) fills in the waiting command and runs it, **without** asking the intent server;
+   - **AGAIN** (`g`) runs the last command again;
+   - **OOPS *word*** swaps the word nobody understood in the last line and runs that.
+
+   Anything else is a fresh command, and drops any waiting question.
+4. **Parse.** `fallbackParse` maps each command to an action, with synonyms, a second object (“give X to Y”, “put X in Y”), ALL and EXCEPT, and a bare word meaning GO. Besides `target` and `indirect`, an action can carry:
+   - **`number`**: a number in an object slot (`turn dial to 4`, `set year to 776`), the value alongside the digits typed (`parseNumber`: digits to 1000, or H:MM as minutes); rules see that slot as `number`;
+   - **`text`**: for a world verb with `target: 'text'`, the rest of the line, outer double quotes dropped;
+   - **`prep`**: `in`, `on`, `under`, `behind`, `off`, `over` or `through`, for the forms that take one (PUT X UNDER Y, THROW X OFF Y, READ X THROUGH Y);
+   - **`direction`**: for PUSH X NORTH (and CLIMB UP/DOWN a thing);
+   - **ME, MYSELF, SELF and YOURSELF** stay as typed: the engine decides they name the player (the reserved ID `player`, for rules), and never matches them, or `player` from the intent server, against things’ names.
+5. **Pronouns.** `it`, `them` and `that` become the last thing the engine acted on; `him` and `her`, the last person.
+6. **Execute.** `execute(action, { world, state })` returns the lines to print, whether anything changed, and `understood: false` if it couldn’t make sense of the command (no such exit, no such item, no rule that applies). When a noun matches more than one thing, or a verb is missing its object, it returns a **question** (`ask`) instead, before touching anything. Before running a command that changes the game, the store keeps a snapshot for UNDO (the last 50, for this session only).
+7. **Retry on a miss.** If the regex couldn’t parse the command, or the engine didn’t understand it, the store asks the intent server how to read it. If the LLM’s reading is different and the engine can act on it, that result is shown instead; otherwise the literal reply stands.
+8. **Time passes.** After a command the engine acted on (never after a misunderstood one, a question, or a command like VERBOSE that takes no time), the room’s end routines run (`onEnd`), then the move counter goes up, wounds heal, timers fire, daemons run, characters fight, and ambient lines print, in that order (`packages/engine/src/engine/time.ts`, after Zork’s CLOCKER). If the light changed, the reply says so.
+9. **Output.** Lines are styled by their prefix and typed out, and the game is saved if anything changed.
+
+**The one rule to keep**
+Step 7 runs the engine on the literal reading first, and possibly again on the LLM’s reading. That’s only safe because **a miss never changes the game**. When you add an engine handler, decide whether you can act before you touch any state. `packages/engine/tests/engine/engine-hooks.test.ts` checks this.
+
+The intent server sees the room by ID and name (`red_mug (red coffee mug)`), so its answer uses IDs the engine matches exactly. Everything still goes through the same fuzzy matcher (`packages/engine/src/engine/fuzzy.ts`), so a slightly-off answer still lands. Names match strongest first: the exact name, an alias or the ID; a whole word of a name or alias; a whole word of the ID, or part of a name; part of the ID; the starts of words (every typed word of three or more letters must match, so an extra word like “red ball” for a plain “ball” misses); and, in brass style, a close misspelling (a typed word of five or more letters at least 80% alike, comparing the start of a longer word too, so “lunberg” finds Lumbergh; among misspellings, a close match to a whole name word beats one found only through an ID word or a word’s start). Objects and people are compared together, so EXAMINE LUMBERGH finds Lumbergh rather than his mug; on a tie EXAMINE prefers objects, and ATTACK, FOLLOW and the person in GIVE/SHOW … TO prefer people. Equally good matches ask “Which do you mean?”. Infocom style never guesses misspellings.
+
+## Cartridges and sessions
+
+The terminal talks to whatever is running through one interface (`useSession()` in `packages/vue/src/stores/session.ts`):
+
+- **The cartridge menu**, when nothing is inserted.
+- **A native world**, run by the engine above.
+- **A Z-machine story**, run by ifvms. See [Playing story files](https://mrballistic.github.io/brass-lantern/guide/z-machine).
+
+Inserting or ejecting a cartridge clears the screen.
+
+## The engine
+
+`execute` (`packages/engine/src/engine/engine.ts`) dispatches on the action to one handler per verb (`packages/engine/src/engine/verbs/`), and each handler reads the world’s rules rather than knowing any particular game.
+
+**The object tree.** Every item has one parent: a room, the player, another item, or nowhere yet (`GameState.locations`, in `packages/engine/src/engine/model.ts`). Inventory, a room’s contents and a container’s contents are all read from that one map. Containers and surfaces nest. What the player can *see* (through glass) and *reach* (into open things) is computed from the tree, and the parser only matches what can be seen.
+
+| Concept | Where in the world | Notes |
+|---|---|---|
+| Conditions | anywhere | `flag:`, `has:`, `held:`, `in:`, `visited:`, `inside:`, `open:`, `locked:`, `on:`, `here:`, `var:`, `number:`, `said:`, `target:`, `indirect:`, `direction:`, `terrain:`, `water:`, `aboard`, `seen:`, `following:`, `carrying`, `lit:`, `alive:`, `awake:`, `fighting:`, `with:`, `!`, `&`. One parser, `packages/engine/src/engine/conditions.ts`. |
+| Rules | `instead`, `after` on items and rooms | Replace a verb’s default, or follow it. `packages/engine/src/engine/rules.ts`. |
+| Containers, doors | `item.container`, `item.surface`, `item.door` | Open, close, lock, put in, take from. |
+| Exits | `room.exits` | A room ID, or `{ to, if, denial, door, denials, then }`. GO runs through rules. |
+| Vehicles | `item.vehicle`, `room.terrain` / `water` / `air`, `world.onFoot` | BOARD, DISEMBARK, and Zork’s rules for water and land, generalized to named terrains: a vehicle `travels` on some, rests on others (`packages/engine/src/engine/verbs/vehicle.ts`, `movement.ts`). |
+| Effects | `events` | Lines and typed effects: flags, moves, variables, timers, chance, death, endings (`packages/engine/src/engine/effects.ts`). |
+| Darkness | `room.dark`, `item.light`, `world.darkness` | In an unlit dark room you can only find what you carry (`packages/engine/src/engine/model.ts` `isLit`). |
+| Death, endings | `world.death`, `world.endings` | `packages/engine/src/engine/death.ts`, `packages/engine/src/engine/endings.ts`. |
+| Characters | `npcs`, `room.npcs` | Places, held things, states, hiding and descriptions (`GameState.npcs`, read through `packages/engine/src/engine/model.ts`). |
+| Topics, orders | `npc.topics`, `npc.orders`, `npc.obeys`, `npc.refuseOrder`, `instead.order` | ASK *X* ABOUT *Y* and “*X*, do this” (`packages/engine/src/engine/verbs/talk.ts`; see [Orders](#orders) below). |
+| Followers | `npc.follows`, `{ follow }` | Characters who go where the player goes (`packages/engine/src/engine/verbs/movement.ts`). |
+| Combat, health | `npc.combat`, `world.combat` | Zork’s blows, tables, wounds and healing (`packages/engine/src/engine/combat.ts`). |
+| Weight | `world.carry`, `item.size` | `packages/engine/src/engine/weight.ts`. |
+| Scripts | `world.scripts` | The code hatch: functions that return steps (`packages/engine/src/engine/scripts.ts`). `descriptionScript` also builds descriptions from state; `{var:NAME}` and `{number}` fill in text (`packages/engine/src/engine/text.ts`). |
+| Events | `events` | Line lists. `[Flag set: …]`, `[Added to inventory: …]` and `[… consumed]` lines change state. Events from `onEnter`, `onTake`, `onWear`, `onSmash` and `bareHanded` fire once; use-rule and gift events run every time. |
+| Flags | `flagLabels` | The friendly label in an event line, mapped to a flag ID. |
+| Use rules | `item.onUse` | The older form of `instead.use`. |
+| Gifts | `npc.onGive`, `npc.refuse` | Giving takes the item; a refusal keeps it. |
+| Gated rooms | `room.requires`, `room.denial` | |
+| The ending | `finale` | Smash X in room Y holding Z: event, epilogue, score, footer. |
+| Timers | `ambient` | Lines every N turns while a condition holds. Turns count only commands the engine acted on. |
+| Score | `scoring`, `ranks`, `maxScore`, `scoreLine`, `rankLine` | Summed from flags, conditions that hold, and the `score` variable; the lines are templates. |
+| Status line | `style`, `statusLine` | Zork’s room, score and moves in Infocom style; `MOVES: n` (or score and moves) otherwise. |
+
+When a world needs behavior the schema can’t express, the engine gets a *generic* hook (in `packages/engine/src/types/world.ts` and the engine); it never branches on a world’s IDs. [CONTRIBUTING.md](https://github.com/mrballistic/brass-lantern/blob/main/CONTRIBUTING.md) has the details.
+
+### Orders
+
+“*X*, *command*” (and TELL *X* TO *command*) is its own verb, `order`, handled by `handleOrder` in `packages/engine/src/engine/verbs/talk.ts`. The pipeline, in order:
+
+1. **Address.** The character is matched in the player’s room, or among those whose `heardFrom` names it. No one matching is a miss.
+2. **`instead.order` rules** answer first, and the order’s words stay words (they aren’t resolved as things).
+3. **Parse the inner command** with `fallbackParse`, as the player would have typed it. A character with neither `orders` nor `obeys` stops here with `refuseOrder`.
+4. **Resolve its objects before anything changes**, among what the *character* can reach (its room’s things and what it holds), plus ME (the player), a typed number, and other characters present. A name that matches nothing is a miss; one that matches several is a question, and neither takes time or changes state.
+5. **`orders` rules**, keyed by the inner verb (or the first typed word when the parsed verb has no table, so the parsed verb wins a clash). Their conditions see the inner command through the same command record rules use: `target:`, `indirect:`, `number:`, `said:`, `direction:`.
+6. **`obeys`**: if no rule answered, the engine performs GO, TAKE, DROP or GIVE ME itself, moving the character or its things. A refusal here is understood and takes a turn.
+7. **Ends the line.** A result for a character with `orders` or `obeys` carries `stopLine`, and the store drops the rest of the typed line (Zork’s P-CONT). A miss never does, so the intent-server retry isn’t affected.
+
+**Adding a verb** is usually a world change: declare it in `world.verbs` and give things `instead` rules for it. The parser learns its words from the world, and the browser tells the intent server which world verbs to accept, so neither needs editing.
+
+A *built-in* verb, with default behavior in the engine, is a change to the engine itself (for contributors; see [CONTRIBUTING.md](https://github.com/mrballistic/brass-lantern/blob/main/CONTRIBUTING.md)), and takes three edits:
+- the regex in `packages/engine/src/engine/parser.ts`, plus its words in `BUILT_IN_WORDS`;
+- the dispatcher in `packages/engine/src/engine/engine.ts` (wrapped in `withRules`), plus its HELP text;
+- `ACTION_VOCAB` in `packages/server/src/llm.ts`. Without that last one, the server throws away the LLM’s answer as an unknown verb.
+
+**Saves** are format 2.0. A 1.0 save (from before the object tree) is converted on load by `packages/engine/src/engine/migrate.ts`, so players keep their games. A 2.0 save that has no place for an item (one a later version of the world added) gets that item’s starting place; an item recorded as `null` (used up) stays gone.
+
+## The terminal
+
+The CRT is hand-written CSS (`packages/vue/src/styles/crt.css`), with no canvas and no UI framework. Every rule is scoped to the game’s shell, which fills its container, so the effects stay inside the game’s box on any page:
+- a boot sequence, scanlines, phosphor bloom and a barrel vignette;
+- flicker at two rates, plus occasional glitches;
+- phosphor decay on older lines, and a block cursor with a square-wave blink.
+
+The default look, `crt-amber`, is deliberately period-accurate rather than WCAG-compliant. The colors are twelve `--bl-*` role variables set by a **theme**, so a game can ship `crt-green`, a plain `simple` look (light or dark, following the system) or a palette of its own, and the player can switch with THEME. Reduced motion turns off flicker, glitch and noise. [Using the library](https://mrballistic.github.io/brass-lantern/guide/using-the-library#themes) has the details.
+
+Each output line is classified by its first characters (`packages/engine/src/engine/output.ts`). The class sets both its style and its typewriter speed:
+
+| Prefix | Type | Speed |
+|---|---|---|
+| `> ` | your input | instant |
+| `📍` | room header | 10ms/char |
+| event emoji (`💼🌀👔💕💻💾🔨💥📎✨🪄🤜😖😴🐟🌺📬📞`) | scripted moment | 18ms/char |
+| `═`, `“` | banner, narration | 12ms/char |
+| `[` | system | instant |
+| anything else | prose | 10ms/char |
+
+A restored session renders instantly, with no typewriter replay, and its boot sequence is shortened. The header shows the game’s `terminalName` and `version` options, then the cartridge’s title (in builds with a menu); on the right, a native world’s status line (`MOVES: n`, or Zork’s “West of House  Score: 0  Moves: 0” in Infocom style) or the story’s own, and a COOKIES button when analytics are configured.
+
+## Saves and analytics
+
+- **Saves** live in `localStorage` only, one per cartridge, under `<storagePrefix>:save:<cartridge id>` (or the cartridge’s `saveKey`), with up to 500 lines of history. [Cartridges and storage](https://mrballistic.github.io/brass-lantern/reference/cartridges#browser-storage) lists every key. They’re written after every change. SAVE *name* keeps an extra copy under `<save key>:named:<name>`, and RESTORE *name* brings it back. If storage is unavailable (private browsing), play continues and SAVE says so.
+- **UNDO** history is memory only: up to 50 snapshots, gone on reload, RESTART or RESTORE.
+- **SCRIPT** downloads a transcript as a text file when it stops; nothing is stored.
+- **Analytics** are the app’s, not the library’s: the packages send nothing anywhere. A game tells `GameOptions.analytics.onEvent` about `game_start` and `session_resumed` (each with a `cartridge` parameter for story files) and, for native worlds, `game_completed` with the move count; what happens next, and whether the player has consented, is up to the app. Given `analytics.openConsent`, the header shows a COOKIES link and the COOKIES command calls it. The demo site, for example, sends those events to Google Analytics only when `VITE_GA_MEASUREMENT_ID` is set at build time, and only after the player accepts its `ConsentBanner`; it honors Do Not Track, and a build without an ID shows no banner.

package/dist/docs/pages/guide/intent-server.md

@@ -0,0 +1,92 @@
+# The intent server
+
+Players don’t type like parsers. The intent server hears what the regex parser couldn’t handle, such as “make that thing stop beeping” or “pocket my billfold”, and asks an LLM which of the engine’s verbs and IDs that means. It’s optional: without it the game is fully playable, and loose phrasing just gets a “didn’t understand” reply.
+
+It ships as `@brass-lantern/server`, with `parseIntent` (a function) and `intentRoute` (an Express router). The repo also has a small Express app around them for the demo, described under [Run the repo’s server](#run-the-repo-s-server).
+
+## Use it in your own backend
+
+The package reads no environment variables; you pass the key in. [Using the library](https://mrballistic.github.io/brass-lantern/guide/using-the-library#the-intent-server) has the full wiring:
+
+```ts
+import { intentRoute } from '@brass-lantern/server/express';
+
+app.set('trust proxy', 'loopback'); // behind a reverse proxy on the same machine
+app.use(express.json({ limit: '32kb' }));
+app.use('/api', intentRoute({ apiKey, models, timeoutMs, rateLimitPerMinute }));
+```
+
+Behind Apache or nginx, `trust proxy` lets the rate limit see each player’s address; without it every request seems to come from the proxy, and all your players share one bucket. Then set `intentEndpoint: '/api/parse-intent'` in the game’s options. Without it (or with `null` or an empty string) the game never asks.
+
+## Run the repo’s server
+
+```bash
+npm install                                  # at the repo root: installs every workspace
+cd packages/server
+cp .env.example .env        # then set GEMINI_KEY (get one at https://aistudio.google.com/apikey)
+npm run dev                 # http://127.0.0.1:3001
+```
+
+With `npm run dev` running at the repo root too, Vite proxies `/api/*` to it, so the browser just calls its own origin. This app reads its settings from the environment (below); the library does not.
+
+**Keep the key on the server**
+The browser never talks to Google; only this server does, with the key in a request header. **Never give the key a `VITE_` prefix.** Vite inlines `VITE_*` variables into the public bundle.
+
+## The API
+
+`POST /api/parse-intent`
+
+```json
+{
+  "input": "hand gary his mug",
+  "context": {
+    "roomName": "Hallway",
+    "exits": ["south", "cubicle", "north", "break_room"],
+    "items": ["mug"],
+    "npcs": ["gary (Gary)"],
+    "inventory": ["stapler"],
+    "verbs": []
+  }
+}
+```
+
+Response: `{ "action": "give", "target": "mug", "indirect": "gary" }`, or `{ "action": "unknown" }` when there’s no good reading or every model fails. Items whose name matches their ID are sent as the bare ID; others as `id (name)`.
+
+The reply can also carry a `prep` (`put … under`, `throw … off`, `read … through`), a `direction` (`push … north`), and a `number` (`turn dial to 4`, 0 to 1000; the client keeps it only when `target` or `indirect` is the word `number` or its digits). For an order (`tell robot to take lamp`), `indirect` is the command as a few plain lowercase words instead of an identifier; the engine parses it as it would typed text.
+
+`verbs` lists the world’s own verbs, which the server accepts alongside its built-in list. Bad requests and rate limiting get an error status instead: 400 with only an `error` field for a missing input or malformed context; 400 with `fallback` as well for input over 200 characters; 429 (with `Retry-After`) and 500, both with `fallback`. The `fallback` is always `{ "action": "unknown" }`. The bundled client treats any non-OK response as `unknown`, so the player just sees the literal reply.
+
+The repo’s server app also answers `GET /health` with `{"ok":true}`; `intentRoute` itself serves only `POST /parse-intent`.
+
+## How it decides
+
+The server calls Gemini’s REST API directly, with no SDK:
+
+- **Structured output.** `responseMimeType: application/json` with a schema whose verb field is an enum of the engine’s actions. Temperature 0, minimal thinking, 150 output tokens.
+- **A model chain inside one deadline.** It tries `gemini-3.5-flash-lite`, then `gemini-3.6-flash`, within 5 seconds in total. Every attempt but the last is capped at 2.5s, so a stalled model still leaves time for the fallback.
+- **Error handling.** A retired model (404), rate limiting (429) and server errors (5xx) move on to the next model. Bad requests and bad keys (400/401/403) stop, since every model would repeat them.
+- **Sanitizing.** The reply must name a known verb, and `target` / `indirect` must look like identifiers. Anything else is dropped, so model output can never carry prose to the player.
+- **The prompt** treats player input as data, and tells the model to answer with IDs from the context.
+
+## Configuration
+
+These apply to the repo’s own server app. All of them are read in `packages/server/src/config.ts`; the library entry points take the same settings as parameters instead.
+
+| Variable | Default | |
+|---|---|---|
+| `GEMINI_KEY` | (required) | The server refuses to start without it. |
+| `GEMINI_MODELS` | `gemini-3.5-flash-lite,gemini-3.6-flash` | Comma-separated, tried in order. `GEMINI_MODEL` (one model) also works. |
+| `PORT` | `3001` | |
+| `HOST` | `127.0.0.1` | Loopback by default; put a reverse proxy in front. |
+| `RATE_LIMIT_PER_MINUTE` | `30` | Per client, per process. |
+
+Google retires models regularly. A retired model just answers 404 and the chain moves on, so update the list when you notice, before the last one goes.
+
+## Abuse limits
+
+There’s no auth, by design: the endpoint only classifies short commands. Its cost is bounded instead:
+
+- **Input caps:** 200 characters of input, and context lists of at most 50 entries of 100 characters each.
+- **Rate limit:** per client, with IPv6 bucketed by /64 so one user can’t rotate addresses, plus a global ceiling.
+- **No CORS headers**, so other websites can’t spend your quota from their visitors’ browsers.
+- **Your provider’s quota** as the backstop. Keep a spending limit on the key.

package/dist/docs/pages/guide/porting-zork.md

@@ -0,0 +1,115 @@
+# Porting Zork
+
+Brass Lantern ships Zork I twice: the original story file, run by the Z-machine interpreter, and **ZORK I · NATIVE**, a rebuild as an ordinary Brass Lantern world (`packages/engine/src/worlds/zork1.ts`). The native version is how the engine proves it can carry an Infocom-class game. A test plays both side by side and fails if they disagree.
+
+## How ZIL maps to a world
+
+Zork was written in ZIL, Infocom’s language. Its source is MIT licensed ([historicalsource/zork1](https://github.com/historicalsource/zork1)), and most of it translates directly:
+
+| ZIL | Brass Lantern |
+|---|---|
+| `<ROOM …>` with `LDESC` | a room with `description` |
+| `<ROOM …>` with an `M-LOOK` routine | `descriptions: [{ if, text }]`, the first that holds |
+| `(NORTH TO X)` | `exits: { north: 'x' }` |
+| `(EAST "The door is boarded…")` | `exits: { east: { denial: '…' } }` |
+| `(WEST TO KITCHEN IF KITCHEN-WINDOW IS OPEN)` | `exits: { west: { to: 'kitchen', door: 'kitchen_window' } }` |
+| `<OBJECT …>` | an item |
+| `CONTBIT`, `OPENBIT`, `TRANSBIT` | `container: { openable, open, transparent }` |
+| `SURFACEBIT` | `surface: true` |
+| `NDESCBIT` | `scenery: true` |
+| `LOCAL-GLOBALS` and a room’s `GLOBAL` list | `room.scenery: [...]` |
+| `FDESC` / `LDESC` on an object | `initialDescription` / `roomDescription` |
+| `TEXT` | `text` (READ) |
+| `LIGHTBIT` | `switchable: true, light: true` |
+| an object’s `ACTION` routine | `instead` and `after` rules |
+| a room’s `VALUE` | an `onEnter` event that sets a scored flag |
+| a verb only some objects understand (MOVE, COUNT) | a [world verb](https://mrballistic.github.io/brass-lantern/reference/world-schema#world-verbs) |
+| a room without `ONBIT` | `dark: true` |
+| `LIT?` | the engine’s light check (a `light` item switched on, in sight) |
+| an interrupt (`QUEUE`, `ENABLE`) | a fuse (`schedule`) or a daemon. Zork’s clock counts a `QUEUE X n` from a command down that same turn and the engine’s from the next, so it becomes `in: n-1`; an interrupt requeuing itself stays `in: n` |
+| `I-LANTERN` and `LAMP-TABLE` | a `lamp_fuel` variable and daemons that warn at its thresholds |
+| `JIGS-UP` | the `die` effect and `world.death` |
+| `PROB` | the `chance` effect |
+| a room’s `M-ENTER` | `onEnter`, which Infocom style runs before the description |
+| a `PER` exit routine with several refusals (the chimney) | an exit’s `denials` |
+| the parser’s ORPHAN and WHICH-PRINT (“Which door do you mean, the wooden door or the trap door?”) | built in: a question, answered by the next line |
+| the parser’s OOPS and AGAIN | built in |
+| an object with no `TEXT` (EXAMINE lists a container’s contents) | `description: ''` |
+| `ACTORBIT` objects | characters (`npcs`), with places, things they hold (`holds`) and descriptions by state |
+| `VILLAINS`, `HERO-BLOW`, `VILLAIN-BLOW`, the melee tables | a character’s `combat` block and `world.combat` (the tables are the engine’s) |
+| a villain’s ACTION modes (`F-DEAD`, `F-UNCONSCIOUS`, `F-CONSCIOUS`, `F-BUSY?`, `F-FIRST?`) | `onDeath`, `onUnconscious`, `onWake`, `onBusy`, `firstStrike` |
+| `SIZE`, `CAPACITY`, `LOAD-ALLOWED`, `FUMBLE-NUMBER` | `size`, `container.weight`, `carry` |
+| `V-DIAGNOSE`, `I-CURE` | DIAGNOSE and healing, built in |
+| an `ACTION` routine data can’t express (`I-SWORD`, the troll catching what you throw) | a [script](https://mrballistic.github.io/brass-lantern/reference/world-schema#scripts) |
+| a `PER` exit routine with a side effect (`UP-CHIMNEY-FUNCTION`) | an exit’s `then` event |
+| the parser’s GWIM for ATTACK (“(with the sword)”) | built in, Infocom style |
+| `TVALUE` (points while a treasure is in the case) | a score entry with a condition: `{ if: 'inside:painting:trophy_case', points: 6 }` |
+| `TVALUE` as the thief reads it (what’s worth stealing) | `treasure: 6` on the item, read by `ctx.treasure` |
+| `INVISIBLE` on a character (the thief, lurking) | `hidden: true`, or `{ npcState, hidden }` to change it |
+| `INVISIBLE` on an object (the stiletto until the thief dies) | the `hide` and `reveal` effects |
+| `SACREDBIT`, `MAZEBIT` | room `tags: ['sacred']`, `tags: ['maze']`, read by `ctx.tags` |
+| `I-THIEF` and `ROBBER-FUNCTION` | a daemon running a script (`thief_turn`), with combat hooks and rules on the thief |
+| the cyclops’s daemon and `CYCLOWRATH` | a daemon script and a variable |
+| `ASK`/`TELL … ABOUT` and orders (“thief, give me the bag”) | `topics`, `refuseOrder` and `instead.order` on a character |
+| an object `ACTION` that prints and returns false, so the verb goes on | an `instead` rule with `continue: true` |
+| `JIGS-UP` resetting things (the trap door) | `death.then` |
+| a raw-input loop in a room’s M-ENTER (the Loud Room) | a room’s `capture`, with `{ free: true }` replies |
+| a room’s M-END | the room’s `onEnd` |
+| V-WAIT’s three turns of the clock | `world.wait: { turns: 3 }` |
+| `FCLEAR … TOUCHBIT` on a room | `{ unvisit: 'room' }` |
+| `FSET … NDESCBIT` in play (the tied rope) | `{ unlist }` and `{ relist }` |
+| `GOTO room <>` (no description: the mirror) | `{ go: 'room', quiet: true }` |
+| `PICK-ONE` (no repeats until all are used) | a script: `pickOne` in `packages/engine/src/worlds/zork1.ts` |
+| `PROB n m` (ZPROB: worse odds once LUCKY is false) | a script checking the `unlucky` flag |
+| PRSI’s routine before PRSO’s | the rule order in Infocom style |
+| `SACREDBIT` on an object (the platinum bar) | the item tag `sacred`, which the thief script respects |
+| JIGS-UP’s branches: Hades once you’ve seen the Altar, dying while dead, “Bad luck, huh?” | `death.variants`, `death.instead`, a conditional `death.message` line |
+| `ALWAYS-LIT` for a spirit | `darkness.litIf` |
+| DEAD-FUNCTION | a world `capture` while `flag:dead` |
+| BURN (LIGHT … WITH) and FLAMEBIT/BURNBIT | the BURN verb, `flaming` and `burnable` |
+| VEHBIT and VTYPE (the magic boat) | an item’s `vehicle: { travels: 'water' }`, BOARD and DISEMBARK |
+| NONLANDBIT on a room (the river, the reservoir at high tide) | the room’s `water` (a condition for the reservoir) |
+| a vehicle’s M-BEG and M-END | its rules (asked before the room’s) and its `onEnd`; Zork’s RBOAT M-BEG is in the world capture |
+| I-RIVER, RIVER-SPEEDS, RIVER-LAUNCH | a self-requeuing fuse and LAUNCH’s table, in scripts |
+| GOTO’s grue from one dark room into another | `darkness.stumble` |
+| PRINT-CONT’s “(outside the magic boat)” and first-seen-first order | built in, Infocom style |
+| EMPTY-HANDED and WEIGHT (the narrow passage: nothing heavier than 4) | an exit’s `if: 'heaviest<=4'` |
+| a room’s M-ENTER that acts before you look (the bat’s FLY-ME) | `onEnter` with `{ look: true }` first, then a script that picks a room |
+| a room’s M-END that checks the turn’s command (BOOM-ROOM) | the room’s `onEnd` running a script that reads `ctx.command` |
+| two objects standing for one thing at two places (the basket on its chain) | two items swapped by the RAISE and LOWER rules; things inside travel with the real one |
+| NO-OBJS’ LIGHT-SHAFT score on the first lit turn | the room’s `onEnd` setting a flag that `scoring` counts |
+| HACK-HACK’s random endings (V-WAVE, V-RAISE) | a world verb’s fixed `reply`, naming its object with `{target}` |
+| SCORE-UPD’s win at 350 (the whisper, the map, the secret path) | a daemon on `score>=350 & !flag:won` |
+| FINISH (the score, then RESTART/RESTORE/QUIT) | an `endings` entry with `score: true` and a footer |
+| GOTO’s “You have moved into a dark place.” | `darkness.arrive` |
+| TOUCHBIT set by OPEN, ROB and the like | built in for OPEN (Infocom style); the `{ touch }` step elsewhere |
+| the parser’s GWIM for a missing tool (“(with the shovel)”) | a script picking the one TOOLBIT thing held |
+| MOVE putting things first in a room (newest-first listings) | built in for things; a character who arrived this turn is listed first |
+
+`style: 'infocom'` makes the engine follow Zork’s conventions:
+- “There is a sword here.”;
+- brief descriptions of rooms you’ve seen;
+- newest-first listings;
+- Zork’s SCORE line and status line (“West of House  Score: 0  Moves: 0”);
+- Zork’s questions (“What do you want to take?”) and TAKE ALL (“lamp: Taken.”, including what can’t be taken, and why).
+
+## The differential test
+
+`packages/engine/tests/worlds/zork1-diff.test.ts` runs a walkthrough through both versions and compares every reply, ignoring case, spacing and quote style. A mismatch prints both sides:
+
+```
+> open sack
+  native:   Opening the brown sack reveals a lunch, and a clove of garlic.
+  original: Opening the brown sack reveals a clove of garlic, and a lunch.
+```
+
+- **The walkthrough** covers the early slices: the house and forest, the cellar and the gallery with the lamp lit, the parser (a bare TAKE and its answer, “Which door do you mean?”, AGAIN, OOPS, TAKE ALL and DROP ALL), the troll, the maze, and the cyclops (ULYSSES).
+- **Scripted sessions** (`packages/engine/tests/worlds/zork1-sessions.test.ts`) check every puzzle: each is a short command list played from the Round Room in both versions and compared reply by reply, its wrong orders and side branches included (the dam, the leak, the Loud Room, the mirrors, the rope, the exorcism, the candles, ghost mode). **Both sides are seeded**: a test-only option seeds the interpreter’s own generator (`new ZMachineSession(…, { seed })`), so each session plays the same way every time, with a seed pinned per side where the thief stays away.
+- **Fights are random,** and our dice aren’t Zork’s, so the walkthrough has **sync points**: walking into the Troll Room, each side retries until the troll doesn’t strike first, and at the fight each side attacks until its troll is dead. The original retries by starting its session again, the native port by trying another seed. The thief wanders at random from the first move, so either side starts over on the next seed whenever he shows up.
+- **`packages/engine/tests/worlds/zork1-fight.test.ts`** checks the fight itself: it fights the real troll 300 times, collects everything it prints, and requires every line of 200 native fights to be one the original prints. It found a difference between Zork’s source and its story file: the source gives a knocked-out player’s foes extra rounds, and Release 119 doesn’t. The story file wins.
+- **`packages/engine/tests/worlds/zork1-thief.test.ts`** does the same for the thief: 60 original sessions wait in the dark cellar with a treasure until he comes, and every line 100 native runs print must be one the original prints.
+- **The whole game** (`packages/engine/tests/worlds/zork1-full.ts`, adapted from the walkthrough Microsoft’s Jericho project ships for Zork I) runs natively from the first move to the barrow on a pinned seed, and must end with every treasure in the case, 350 points, the whisper, the map’s text and the closing text. **`packages/engine/tests/worlds/zork1-chapters.test.ts`** compares it with the original in nine chapters: for chapter *k* both sides replay chapters 1 to *k* and compare chapter *k* reply by reply, fights being sync points (`@fight <foe> with <weapon>`). Each chapter has a seed pair on which the two sides agree; none falls back to line sets.
+- **`packages/engine/tests/worlds/zork1-thief-timing.test.ts`** measures the thief: 40 seeds a side wait in the Round Room until he first shows, and the medians must agree within 25% (measured: 17 turns each).
+- **The room order is read from the story file.** `packages/engine/tests/helpers/zobjects.ts` decodes `zork1.z3`’s object tree, and the native world’s rooms must follow it, since the thief walks rooms in that order.
+- **Expected differences** go in `packages/engine/tests/worlds/zork1-allowlist.ts`, each with a reason, and the test fails if one stops being different. Two kinds: a misspelled word, where Zork says “I don’t know the word” and the native engine says it sees no such thing (and, in the app, asks the intent server; the OOPS that follows it matches); and replies after the fight that depend on how it went (DIAGNOSE, SCORE’s move count).
+- **Random lines** the original prints (the distant songbird) are filtered out: the engine’s generator is seeded and reproducible, but it can’t replay Zork’s own. Random outcomes (the grue, where things scatter when you die) are pinned by seeded unit tests instead, and the death texts are checked against a real death in the original.

package/dist/docs/pages/guide/testing.md

@@ -0,0 +1,100 @@
+# Testing a world
+
+A world is data, and data rots quietly: an exit points at a renamed room, a flag label gets a typo, the ending becomes unreachable. Two kinds of test catch nearly all of it, and both run in plain Node with any test runner. The examples here use [Vitest](https://vitest.dev/).
+
+## Play it
+
+`createGame` from `@brass-lantern/engine` runs a world with no browser: feed it the lines a player would type, and read the replies. A test reads like a transcript:
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { createGame } from '@brass-lantern/engine';
+import { tutorial } from '@brass-lantern/engine/worlds';
+
+describe('Snack Attack', () => {
+  it('plays to the best ending', () => {
+    const game = createGame(tutorial, { seed: 1 });
+    const text = [
+      'open drawer',
+      'take stapler',
+      'north',
+      'take mug and give mug to gary',
+      'talk to gary',
+      'north',
+      'smash machine with stapler',
+    ].flatMap((line) => game.send(line).lines).join('\n');
+
+    expect(game.state.gameOver).toBe(true);
+    expect(text).toContain('You share the pretzels');
+    expect(text).toContain('[Score: 50 of 50');
+  });
+});
+```
+
+Swap `tutorial` for your own world (`import { myWorld } from './my-world'`). `seed` makes the game’s randomness repeatable, so a world with chance effects or fights plays the same way on every run.
+
+Write at least two: the **shortest win**, and a run that **earns every point**. When either breaks, you’ve changed the critical path or the scoring, on purpose or not.
+
+To pin every word, compare the whole transcript: `expect(text).toMatchInlineSnapshot()` fills itself in on the first `npx vitest -u`, and from then on any change to the text fails the test until you look at it.
+
+`send` takes a whole line, as the player would type it: chained commands, pronouns, AGAIN, OOPS, UNDO and the answer to a question all work. When the game asks “Which door do you mean?”, the reply’s `awaiting` is true and the next `send` answers it. There’s no intent server in a test, so write commands the regex parser understands, and name things with words the world knows. Every word of three or more letters has to be in the thing’s name, an alias or its ID, so `take red ball` misses a thing called only “ball” (“You don’t see a “red ball” here.”). In brass style a close misspelling of a word in the name also matches. In the browser the intent server might rescue that; in a test it fails, which is how you find the alias players will need. Since 2.1.0 this is stricter than it was, so a test that passed on 2.0 can start failing here: add the alias (see [How names are matched](https://mrballistic.github.io/brass-lantern/guide/building-worlds/#how-names-are-matched)).
+
+## Check the data
+
+`auditWorld(world)` returns a list of problems, one string each, and an empty list when it finds none:
+
+```ts
+import { expect, it } from 'vitest';
+import { auditWorld } from '@brass-lantern/engine';
+import { myWorld } from './my-world';
+
+it('has no broken references', () => {
+  expect(auditWorld(myWorld)).toEqual([]);
+});
+```
+
+It finds the mistakes that fail silently in play:
+
+- effects naming items, rooms, events or endings that don’t exist, and unknown effects;
+- events named by rules, `onEnter`, `onTake`, `onWear`, `onSmash`, `onGive`, daemons and the finale that don’t exist;
+- conditions of unknown kinds, or naming items and rooms that don’t exist (in rules, triggers, exits, `requires`, daemons, hints and scoring); `direction:` takes any lowercase word, since an `orders.go` rule sees the place as typed (`direction:basement`);
+- exits to nowhere, doors that aren’t items, items listed in rooms or containers that don’t exist;
+- a world verb word that a built-in verb already owns, and the reserved IDs `player` and `number`.
+
+It doesn’t walk the map. A few more checks are worth writing for your own world. Every room reachable from the start:
+
+```ts
+it('every room is reachable from the start', () => {
+  const seen = new Set<string>();
+  const queue = [myWorld.startRoom];
+  while (queue.length) {
+    const id = queue.shift()!;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    for (const exit of Object.values(myWorld.rooms[id]?.exits ?? {})) {
+      const to = typeof exit === 'string' ? exit : exit.to;
+      if (to) queue.push(to);
+    }
+  }
+  expect(Object.keys(myWorld.rooms).filter((id) => !seen.has(id))).toEqual([]);
+});
+```
+
+More along the same lines: every `[Flag set: …]` label is in `flagLabels`; every flag in a `requires`, hint or scoring entry can actually be set by some event; every gated room has a `denial`; every `listExits` label is a real exit.
+
+**Copy style** is easy to test too. If you use curly quotes, fail on straight ones:
+
+```ts
+it('uses smart punctuation', () => {
+  const strings: string[] = [];
+  const walk = (v: unknown): void => {
+    if (typeof v === 'string') strings.push(v);
+    else if (Array.isArray(v)) v.forEach(walk);
+    else if (v && typeof v === 'object') Object.values(v).forEach(walk);
+  };
+  walk(myWorld);
+  expect(strings.filter((s) => /["']/.test(s))).toEqual([]);
+});
+```
+
+That walks every string in the world, IDs and conditions included, which is fine as long as those don’t use quotes either.