chore: obsidian docs

feat(ui): add bug reporting integrations
docs: implementation plan for bug reporting
2026-05-17 23:35:13 -05:00 · 2026-05-17 23:34:17 -05:00 · 2026-05-17 23:02:46 -05:00 · 2026-05-17 22:57:34 -05:00 · 2026-05-13 17:59:13 -05:00 · 2026-05-12 20:52:35 -05:00
153 changed files with 8144 additions and 570 deletions
@@ -22,11 +22,49 @@ npm run dev       # local dev server
 npm run build     # type-check + production build
 ```
 ## Make Your Own Game
 Halfstreet is currently meant to be forked as a complete Astro app, not consumed
 as a separate engine package. To make a new story, replace the markdown vault in
 `src/world/` and keep the TypeScript runtime in place.
 Start with:
 - `src/world/game.md` for the title, starting room, starting inventory, ending
  priority, opening art, help text, and end text.
 - `src/world/parser.md` for command vocabulary and aliases.
 - `src/world/rooms/`, `src/world/items/`, `src/world/encounters/`, and
  `src/world/endings/` for story content.
 - `src/world/mechanics/` and `src/world/actions/` for configurable rules and
  interactions.
 - `src/world/ui.md` for page metadata, footer links, and UI feature switches.
 - `src/world/templates/` for starter files.
 Run `npm test` after changing world files. The loader validates wikilinks,
 required sections, frontmatter shape, and references between rooms, items,
 encounters, endings, mechanics, and actions.
 ## Releases
 The footer build number comes from Woodpecker's pipeline number and increments on each CI build.
 The package version is an intentional release label.
 Use one of these from a clean worktree when you are ready to cut a release:
 ```sh
 npm run release:patch  # fixes, typo corrections, small polish
 npm run release:minor  # meaningful playable additions or mechanics
 npm run release:major  # disruptive changes after 1.0.0
 git push --follow-tags
 ```
 Each release script updates `package.json` and `package-lock.json`, creates a release commit, and tags it.
 ## Layout
 - `src/engine/` — parser, dispatcher, encounter logic
 - `src/ui/` — terminal renderer, theme, chips
- `src/world/` — markdown content (rooms, items, encounters, endings)
+- `src/world/` — Obsidian-friendly authoring vault
 - `src/pages/index.astro` — entry page
 ## Design docs
@@ -0,0 +1,653 @@
 # Bug Reporting Implementation Plan
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 **Goal:** Add a "Report a Bug" footer link that opens the Bugpin screenshot widget (forwards to GitHub Issues), plus auto error capture via Bugsink (Sentry-compatible) on every page.
 **Architecture:** Two independent flows. Bugpin = user-initiated, lazy-loaded `<script>` widget from `bugpin.half.st`, triggered by a footer `<button>`. Bugsink = background, `@sentry/browser` SDK initialised on page load against a DSN at `bugsink.half.st`. Both credentials are public project tokens and live in `src/world/ui.md`. Both flows are no-ops when not configured.
 **Tech Stack:** Astro 6, TypeScript, Zod 4, Vitest 4 (node env, no jsdom), `@sentry/browser` (new dep), Bugpin widget script.
 **Spec:** `docs/superpowers/specs/2026-05-17-bug-reporting-design.md`
 ---
 ## File map
 - `src/world/schema.ts` — **modify**: extend `uiFrontmatterSchema` with optional `bugReport` block.
 - `src/world/schema.test.ts` — **modify**: add accept/reject cases for `bugReport`.
 - `src/world/types.ts` — **modify**: extend `UiConfig` to expose `bugReport`.
 - `src/world/ui.md` — **modify**: add `bugReport` frontmatter.
 - `src/ui/error-tracking.ts` — **create**: reads body data attrs, calls `Sentry.init`. No-op when DSN missing.
 - `src/ui/bug-report.ts` — **create**: wires footer button click to lazy-load Bugpin widget, then call `BugPin.open()`. No-op when config missing.
 - `src/pages/index.astro` — **modify**: render the footer button conditionally, attach data attrs to `<body>`, import the two new modules.
 - `package.json` / `package-lock.json` — **modify**: add `@sentry/browser`.
 - `src/world/TODOs.md:45` — **modify**: rewrite to reflect actual approach.
 No DOM tests for the two new UI modules: the project's Vitest config runs in node with no jsdom. Coverage for those modules is `astro check` (type safety) + a manual smoke step at the end of the plan. Schema changes get full unit test coverage via the existing test file.
 ---
 ## Task 1: Extend `uiFrontmatterSchema` with `bugReport` (TDD)
 **Files:**
 - Modify: `src/world/schema.ts`
 - Modify: `src/world/schema.test.ts`
 - [ ] **Step 1: Add the failing tests**
 Append these inside the existing `describe('uiFrontmatterSchema', ...)` block in `src/world/schema.test.ts` (just before the closing `})` on line 120):
 ```ts
  it('accepts a bugReport block with bugpin and bugsink subconfigs', () => {
    const data = {
      pageTitle: 'Halfstreet',
      description: 'A gothic mystery.',
      footer: {
        copyright: '© 2026 Ethan J Lewis',
        links: [],
      },
      bugReport: {
        enabled: true,
        label: 'Report a Bug',
        bugpin: {
          serverUrl: 'https://bugpin.half.st',
          apiKey: 'proj_07df4bf91f12445b8ef8c723e865ed7b',
        },
        bugsink: {
          enabled: true,
          dsn: 'https://231ef18b6b4f426ca249778cfddf821c@bugsink.half.st/1',
        },
      },
    }
    expect(() => uiFrontmatterSchema.parse(data)).not.toThrow()
  })
  it('accepts ui config with no bugReport block at all', () => {
    const data = {
      pageTitle: 'Halfstreet',
      description: 'A gothic mystery.',
      footer: { copyright: '© 2026 Ethan J Lewis', links: [] },
    }
    expect(() => uiFrontmatterSchema.parse(data)).not.toThrow()
  })
  it('rejects a bugpin block with a non-url serverUrl', () => {
    const data = {
      pageTitle: 'Halfstreet',
      description: 'A gothic mystery.',
      footer: { copyright: '© 2026 Ethan J Lewis', links: [] },
      bugReport: {
        enabled: true,
        bugpin: { serverUrl: 'not-a-url', apiKey: 'proj_x' },
      },
    }
    expect(() => uiFrontmatterSchema.parse(data)).toThrow()
  })
  it('rejects a bugsink block with a non-url dsn', () => {
    const data = {
      pageTitle: 'Halfstreet',
      description: 'A gothic mystery.',
      footer: { copyright: '© 2026 Ethan J Lewis', links: [] },
      bugReport: {
        enabled: true,
        bugsink: { dsn: 'whatever' },
      },
    }
    expect(() => uiFrontmatterSchema.parse(data)).toThrow()
  })
 ```
 - [ ] **Step 2: Run tests, confirm they fail**
 ```
 npm test -- src/world/schema.test.ts
 ```
 Expected: the four new tests fail because `bugReport` is currently unknown (zod by default strips extras, so the "accepts" cases probably pass — but the "rejects" cases will fail because zod will accept anything for unknown fields). Either way, confirm the test runner reports at least the two "rejects" cases as failing.
 - [ ] **Step 3: Add the schema fields**
 In `src/world/schema.ts`, find `uiFrontmatterSchema` (starts at line 48). Add a `bugReport` field at the end of the object (after `features`, before the closing `})`). Final block:
 ```ts
 export const uiFrontmatterSchema = z.object({
  pageTitle: z.string().trim().min(1),
  description: z.string().trim().min(1),
  robots: z.string().trim().min(1).default('noindex'),
  themeColor: z.string().trim().min(1).default('#1a0d00'),
  footer: z.object({
    copyright: z.string().trim().min(1),
    copyrightHref: z.url().optional(),
    buildLabel: z.string().trim().min(1).default('Build #'),
    showBuild: z.boolean().default(true),
    links: z.array(z.object({
      label: z.string().trim().min(1),
      href: z.url(),
    })).default([]),
  }),
  features: z.object({
    chips: z.boolean().default(true),
    lightMeter: z.boolean().default(true),
    typedEffect: z.boolean().default(true),
    roomScroll: z.boolean().default(true),
  }).default({
    chips: true,
    lightMeter: true,
    typedEffect: true,
    roomScroll: true,
  }),
  bugReport: z.object({
    enabled: z.boolean().default(false),
    label: z.string().trim().min(1).default('Report a Bug'),
    bugpin: z.object({
      serverUrl: z.url(),
      apiKey: z.string().trim().min(1),
    }).optional(),
    bugsink: z.object({
      enabled: z.boolean().default(true),
      dsn: z.url(),
    }).optional(),
  }).optional(),
 })
 ```
 - [ ] **Step 4: Run tests, confirm pass**
 ```
 npm test -- src/world/schema.test.ts
 ```
 Expected: all `uiFrontmatterSchema` tests pass (the original two + the four new ones).
 - [ ] **Step 5: Commit**
 ```
 git add src/world/schema.ts src/world/schema.test.ts
 git commit -m "feat(world): add bugReport block to ui schema"
 ```
 ---
 ## Task 2: Surface `bugReport` on the `UiConfig` type
 **Files:**
 - Modify: `src/world/types.ts:64-85`
 - [ ] **Step 1: Extend the interface**
 In `src/world/types.ts`, replace the existing `UiConfig` interface (currently lines 64–85) with:
 ```ts
 export interface UiConfig {
  pageTitle: string
  description: string
  robots: string
  themeColor: string
  footer: {
    copyright: string
    copyrightHref?: string
    buildLabel: string
    showBuild: boolean
    links: Array<{
      label: string
      href: string
    }>
  }
  features: {
    chips: boolean
    lightMeter: boolean
    typedEffect: boolean
    roomScroll: boolean
  }
  bugReport?: {
    enabled: boolean
    label: string
    bugpin?: {
      serverUrl: string
      apiKey: string
    }
    bugsink?: {
      enabled: boolean
      dsn: string
    }
  }
 }
 ```
 - [ ] **Step 2: Verify type check passes**
 ```
 npx astro check
 ```
 Expected: 0 errors, 0 warnings (or at least no new errors introduced by this change).
 - [ ] **Step 3: Commit**
 ```
 git add src/world/types.ts
 git commit -m "feat(world): expose bugReport on UiConfig"
 ```
 ---
 ## Task 3: Add real config to `ui.md`
 **Files:**
 - Modify: `src/world/ui.md`
 - [ ] **Step 1: Edit frontmatter**
 Insert this block in `src/world/ui.md` between the `features:` block and the closing `---`, so the frontmatter ends like:
 ```yaml
 features:
  chips: true
  lightMeter: true
  typedEffect: true
  roomScroll: true
 bugReport:
  enabled: true
  label: "Report a Bug"
  bugpin:
    serverUrl: "https://bugpin.half.st"
    apiKey: "proj_07df4bf91f12445b8ef8c723e865ed7b"
  bugsink:
    enabled: true
    dsn: "https://231ef18b6b4f426ca249778cfddf821c@bugsink.half.st/1"
 ---
 ```
 - [ ] **Step 2: Verify the world loads**
 ```
 npm test -- src/world/buildWorld.test.ts
 npm test -- src/world/loader.test.ts
 ```
 Expected: all tests pass — the new frontmatter is valid.
 - [ ] **Step 3: Commit**
 ```
 git add src/world/ui.md
 git commit -m "feat(world): wire bugpin + bugsink credentials in ui.md"
 ```
 ---
 ## Task 4: Install `@sentry/browser`
 **Files:**
 - Modify: `package.json`, `package-lock.json`
 - [ ] **Step 1: Install**
 ```
 npm install @sentry/browser
 ```
 Expected: a single new dependency added under `"dependencies"` in `package.json`; lockfile updates.
 - [ ] **Step 2: Verify**
 ```
 node -e "require('@sentry/browser')"
 ```
 Expected: no output and exit code 0.
 - [ ] **Step 3: Commit**
 ```
 git add package.json package-lock.json
 git commit -m "chore: add @sentry/browser for bugsink integration"
 ```
 ---
 ## Task 5: Create the Bugsink init module
 **Files:**
 - Create: `src/ui/error-tracking.ts`
 No unit test — Vitest runs in node with no jsdom, and this module only does work in a browser. Coverage is `astro check` (types) + the manual smoke at the end.
 - [ ] **Step 1: Write the module**
 ```ts
 // src/ui/error-tracking.ts
 import * as Sentry from '@sentry/browser'
 const dsn = document.body?.dataset.bugsinkDsn ?? ''
 if (dsn) {
  Sentry.init({
    dsn,
    tracesSampleRate: 0,
    replaysSessionSampleRate: 0,
    replaysOnErrorSampleRate: 0,
    integrations: [],
  })
 }
 ```
 - [ ] **Step 2: Type-check**
 ```
 npx astro check
 ```
 Expected: 0 new errors.
 - [ ] **Step 3: Commit**
 ```
 git add src/ui/error-tracking.ts
 git commit -m "feat(ui): initialise sentry browser sdk against bugsink dsn"
 ```
 ---
 ## Task 6: Create the Bugpin trigger module
 **Files:**
 - Create: `src/ui/bug-report.ts`
 Module reads config from the footer button's `data-*` attributes, lazy-loads the Bugpin widget on first click, then calls `BugPin.open()`. Subsequent clicks just call `open()` again.
 - [ ] **Step 1: Write the module**
 ```ts
 // src/ui/bug-report.ts
 interface BugPinAPI {
  open: () => void
  close: () => void
 }
 declare global {
  interface Window {
    BugPin?: BugPinAPI
  }
 }
 const button = document.querySelector<HTMLButtonElement>('[data-bug-report-trigger]')
 if (button) {
  const serverUrl = button.dataset.bugpinServer
  const apiKey = button.dataset.bugpinKey
  if (serverUrl && apiKey) {
    let loadPromise: Promise<void> | null = null
    const ensureLoaded = (): Promise<void> => {
      if (window.BugPin) return Promise.resolve()
      if (loadPromise) return loadPromise
      loadPromise = new Promise<void>((resolve, reject) => {
        const script = document.createElement('script')
        script.src = `${serverUrl.replace(/\/$/, '')}/widget.js`
        script.async = true
        script.dataset.apiKey = apiKey
        script.addEventListener('load', () => resolve())
        script.addEventListener('error', () => {
          loadPromise = null
          reject(new Error(`Failed to load Bugpin widget from ${script.src}`))
        })
        document.head.appendChild(script)
      })
      return loadPromise
    }
    button.addEventListener('click', async (event) => {
      event.preventDefault()
      button.disabled = true
      try {
        await ensureLoaded()
        window.BugPin?.open()
      } catch (err) {
        console.error('[bug-report]', err)
      } finally {
        button.disabled = false
      }
    })
  }
 }
 ```
 - [ ] **Step 2: Type-check**
 ```
 npx astro check
 ```
 Expected: 0 new errors.
 - [ ] **Step 3: Commit**
 ```
 git add src/ui/bug-report.ts
 git commit -m "feat(ui): lazy-load bugpin widget on footer click"
 ```
 ---
 ## Task 7: Wire footer button and module imports in `index.astro`
 **Files:**
 - Modify: `src/pages/index.astro`
 - [ ] **Step 1: Add config bindings to the frontmatter script**
 In the `---` block at the top of `src/pages/index.astro`, after `const remainingFooterLinks = footerLinks.slice(1)`, add:
 ```ts
 const bugReport = ui?.bugReport
 const bugpinConfig = bugReport?.enabled ? bugReport.bugpin : undefined
 const bugsinkDsn =
  bugReport?.enabled && bugReport.bugsink?.enabled ? bugReport.bugsink.dsn : ''
 ```
 - [ ] **Step 2: Add the `data-bugsink-dsn` attribute to `<body>`**
 Replace the existing `<body>` opening tag with:
 ```astro
 <body data-bugsink-dsn={bugsinkDsn}>
 ```
 - [ ] **Step 3: Add the footer button**
 In the `<footer class="mystery-footer">` block (currently lines 89–109), append this AFTER the existing `{remainingFooterLinks.map(...)}` block, before the closing `</footer>`:
 ```astro
 {bugpinConfig && (
  <>
    <span aria-hidden="true">|</span>
    <button
      type="button"
      class="mystery-footer-bug-report"
      data-bug-report-trigger
      data-bugpin-server={bugpinConfig.serverUrl}
      data-bugpin-key={bugpinConfig.apiKey}
    >{bugReport?.label ?? 'Report a Bug'}</button>
  </>
 )}
 ```
 - [ ] **Step 4: Import the two new modules**
 Replace the existing module-import script block (currently lines 130–133):
 ```astro
 <script>
  import '../ui/terminal.ts'
  import '../ui/theme.ts'
 </script>
 ```
 with:
 ```astro
 <script>
  import '../ui/terminal.ts'
  import '../ui/theme.ts'
  import '../ui/error-tracking.ts'
  import '../ui/bug-report.ts'
 </script>
 ```
 - [ ] **Step 5: Add CSS so the button matches the surrounding links**
 Open `src/ui/crt.css` and grep for `.mystery-footer` to find the existing footer styles. Add a rule that makes the button look identical to the footer anchors. Append this block at the end of the existing `.mystery-footer` rules (search for `.mystery-footer a` and add directly after that selector's rule):
 ```css
 .mystery-footer-bug-report {
  background: none;
  border: none;
  padding: 0;
  margin: 0;
  font: inherit;
  color: inherit;
  text-decoration: underline;
  cursor: pointer;
 }
 .mystery-footer-bug-report:hover,
 .mystery-footer-bug-report:focus-visible {
  text-decoration: none;
 }
 .mystery-footer-bug-report:disabled {
  opacity: 0.5;
  cursor: progress;
 }
 ```
 If `.mystery-footer a` styles its anchors differently (e.g. specific color, no underline by default), match those properties instead. Look at the actual `a` rule and copy its `color`/`text-decoration` declarations into `.mystery-footer-bug-report` so the two render visually identically.
 - [ ] **Step 6: Run the full type check and build**
 ```
 npx astro check
 npm run build
 ```
 Expected: 0 errors, build succeeds.
 - [ ] **Step 7: Commit**
 ```
 git add src/pages/index.astro src/ui/crt.css
 git commit -m "feat(ui): add Report a Bug footer button and wire bug tracking modules"
 ```
 ---
 ## Task 8: Update TODOs
 **Files:**
 - Modify: `src/world/TODOs.md:45`
 - [ ] **Step 1: Rewrite the TODO line**
 Replace line 45 of `src/world/TODOs.md`:
 ```
 - [ ] Set up BugPin as a self-hosted visual bug reporter for the site, then have incoming reports create markdown files under `src/world/bugs/` via a webhook or API bridge so bugs can be tracked in git alongside the game content. Include screenshot/annotation metadata in the markdown and decide whether these bug docs stay outside the world loader or get their own loader later.
 ```
 with:
 ```
 - [ ] Add a "Report a Bug" footer link backed by Bugpin (widget at bugpin.half.st → forwards to GitHub Issues). Add Bugsink (@sentry/browser → bugsink.half.st) for automatic JS error capture. Mark complete after manual verification: a test report appears in the Bugpin portal AND a GitHub issue is created AND a thrown error appears in the Bugsink portal.
 ```
 - [ ] **Step 2: Commit**
 ```
 git add src/world/TODOs.md
 git commit -m "docs: rewrite TODO 45 to reflect Bugpin/Bugsink approach"
 ```
 ---
 ## Task 9: Manual smoke test
 **Pre-req:** the Bugpin GitHub integration must be configured server-side before user reports will create issues. See spec §5. Steps below test the widget plumbing regardless.
 - [ ] **Step 1: Start dev server**
 ```
 npm run dev
 ```
 Open the URL it prints (default `http://localhost:4321`).
 - [ ] **Step 2: Verify the footer button renders**
 In the rendered footer at the bottom of the page, confirm "Report a Bug" appears after "Source Code", styled like the surrounding links.
 - [ ] **Step 3: Verify the widget lazy-loads**
 Open DevTools → Network. Filter for `widget.js`. Confirm NO request to `bugpin.half.st/widget.js` on cold page load.
 Click "Report a Bug". Confirm:
 - A single GET to `https://bugpin.half.st/widget.js` (status 200).
 - The Bugpin dialog opens.
 - Take a screenshot, write "smoke test" in the note, submit.
 - The dialog closes / shows a success state.
 Re-click "Report a Bug". Confirm NO second `widget.js` request — only the dialog re-opens.
 - [ ] **Step 4: Verify Bugpin received the report**
 Open `https://bugpin.half.st/portal`. Confirm the "smoke test" report appears with the screenshot attached.
 If the GitHub integration is configured: confirm a matching issue appears in the halfstreet GitHub repo.
 - [ ] **Step 5: Verify Bugsink captures an uncaught error**
 In the dev server's running page, open DevTools console and run:
 ```js
 setTimeout(() => { throw new Error('bugsink smoke test') }, 0)
 ```
 Open `https://bugsink.half.st`. Confirm a "bugsink smoke test" event appears within ~30 seconds.
 - [ ] **Step 6: Verify the launcher styling is acceptable**
 After step 3, the Bugpin widget's built-in floating launcher may now also be visible on the page. If its presence is visually objectionable, add a CSS rule to `src/ui/crt.css` targeting the Bugpin host element (inspect the DOM to find the selector — Bugpin uses Shadow DOM with a custom-element host like `<bugpin-widget>` or similar). Example:
 ```css
 bugpin-widget,
 [data-bugpin-launcher] {
  display: none !important;
 }
 ```
 If this turns out to be needed, commit the CSS as `style(ui): hide bugpin built-in launcher (we have our own trigger)`. If the launcher's appearance is fine as-is, skip this step.
 - [ ] **Step 7: Mark TODO #45 complete**
 Once steps 1–5 all pass, edit `src/world/TODOs.md` line 45, change `- [ ]` to `- [x]`, and commit:
 ```
 git add src/world/TODOs.md
 git commit -m "chore: mark TODO 45 complete"
 ```
 ---
 ## Done criteria
 All of the following are true:
 - `npm test` passes.
 - `npx astro check` reports 0 errors.
 - `npm run build` succeeds.
 - Manual smoke (Task 9 steps 1–5) all pass.
 - TODO #45 is `[x]`.
@@ -0,0 +1,152 @@
 # Bug reporting: Bugpin (user) + Bugsink (auto)
 **Status:** Approved design, ready for implementation plan.
 **Date:** 2026-05-17
 ## Goal
 Let visitors report bugs in the Halfstreet site with a screenshot, and capture uncaught JavaScript errors automatically. Reports should flow to systems already running on the `half.st` host so there is no new infrastructure to manage.
 ## Two distinct flows
 | | Bugpin | Bugsink |
 |---|---|---|
 | Trigger | Visitor clicks "Report a Bug" in footer | Uncaught JS error |
 | Capture | Screenshot, annotations, free-text note, console/network metadata | Stack trace, breadcrumbs |
 | Destination | Bugpin portal → auto-creates a GitHub Issue in the halfstreet repo | Bugsink portal only |
 | Library | `bugpin.half.st/widget.js` (lazy-loaded on click) | `@sentry/browser` npm package (loads on every page) |
 The two are intentionally separate. Bugpin owns user-facing reports; Bugsink owns automatic exception capture. Sentry's user-feedback widget is **not** used — that would overlap Bugpin and muddle the responsibilities.
 ## Components
 ### 1. Footer link
 `src/pages/index.astro`
 Add "Report a Bug" to the footer chain after the existing links. Render as a `<button>` styled to match the surrounding `<a>` elements so it can dispatch JS without a hash-link navigation.
 Final order:
 `© 2026 Ethan J Lewis | GNU 3.0 | Build #<n> | Source Code | Report a Bug`
 The button only renders when `world.ui.bugReport?.enabled` is true and a Bugpin server URL is configured. If either is missing, the button is omitted (local dev stays clean).
 ### 2. Config
 `src/world/ui.md` — add a `bugReport` frontmatter block:
 ```yaml
 bugReport:
  enabled: true
  label: "Report a Bug"
  bugpin:
    serverUrl: "https://bugpin.half.st"
    apiKey: "proj_07df4bf91f12445b8ef8c723e865ed7b"
  bugsink:
    enabled: true
    dsn: "https://231ef18b6b4f426ca249778cfddf821c@bugsink.half.st/1"
 ```
 The Bugpin project API key and the Bugsink DSN are both designed to ship to clients (they are public credentials that authenticate the project, not the operator), so checking them into the repo is acceptable.
 `src/world/schema.ts` — extend `uiFrontmatterSchema` with an optional `bugReport` object:
 ```ts
 bugReport: z.object({
  enabled: z.boolean().default(false),
  label: z.string().trim().min(1).default('Report a Bug'),
  bugpin: z.object({
    serverUrl: z.url(),
    apiKey: z.string().trim().min(1),
  }).optional(),
  bugsink: z.object({
    enabled: z.boolean().default(true),
    dsn: z.url(),
  }).optional(),
 }).optional(),
 ```
 `src/world/types.ts` — extend `UiConfig` with the matching TypeScript shape.
 ### 3. Bugpin lazy loader
 New module: `src/ui/bug-report.ts`
 Responsibilities:
 - Read Bugpin config from a `data-*` attribute on the footer button (so the module stays free of Astro imports).
 - On first click, inject `<script src="${serverUrl}/widget.js" data-api-key="${apiKey}" async>` into `<head>`. Hide Bugpin's built-in floating button using whatever option the widget exposes (likely `data-hidden="true"` or a CSS rule scoped via the widget's Shadow DOM hook — confirm against the install guide during implementation).
 - Once the script resolves, call `window.BugPin.open()`.
 - Cache the loaded state on a module-level flag; subsequent clicks just call `open()` again.
 - If the script fails to load (offline, server down), log to the console and surface a minimal inline message ("Couldn't open bug reporter — try refreshing"). Do not break the page.
 Wire-up in `src/pages/index.astro`:
 - The footer button gets `data-bug-report-trigger`, `data-bugpin-server`, `data-bugpin-key` attributes.
 - A new `<script>` block imports `../ui/bug-report.ts` alongside the existing terminal/theme imports.
 The lazy-load is deliberate: ~150 KB of widget code stays off the cold load for visitors who never click.
 ### 4. Bugsink init
 New module: `src/ui/error-tracking.ts`
 Responsibilities:
 - Add `@sentry/browser` as a dependency.
 - Read the DSN from a `data-bugsink-dsn` attribute set on `<body>` (or a meta tag) so the module is server-render-agnostic.
 - On import, call:
  ```ts
  Sentry.init({
    dsn,
    tracesSampleRate: 0,
    replaysSessionSampleRate: 0,
    replaysOnErrorSampleRate: 0,
    integrations: [],
  })
  ```
 - If `dsn` is missing or `bugsink.enabled` is false, no-op.
 Error-capture only — no performance tracing, no session replay. Keeps the bundle small and avoids accidentally shipping a replay tool we didn't design for.
 Wire-up in `src/pages/index.astro`:
 - A new `<script>` block imports `../ui/error-tracking.ts` near the existing imports.
 ### 5. Bugpin GitHub wiring
 Out of scope for the code change, but recorded here so it isn't lost during implementation:
 1. In the halfstreet GitHub repo, create a classic personal access token (or fine-grained equivalent) with `repo` scope.
 2. In Bugpin admin (https://bugpin.half.st/portal): Projects → halfstreet → Integrations → GitHub. Paste the token, select the halfstreet repo, set default labels (e.g., `bug`, `user-report`).
 3. Verify by submitting a test report from the footer link and confirming an issue appears in GitHub.
 ## Out of scope
 - **Markdown files under `src/world/bugs/`.** Original TODO #45 proposed this; explicitly dropped — Bugpin's portal + GitHub Issues replace that storage path.
 - **Gitea mirroring.** Bugpin does not natively support Gitea. Deferred until there's clear value in a Bugpin → Gitea bridge. The front-end design does not preclude this; it would be a server-side addition on the Bugpin host.
 - **Sentry user-feedback widget.** Bugpin owns user reports; Bugsink stays auto-only.
 - **PII redaction policy.** Bugpin's widget includes a built-in blur tool; Bugsink only captures stack traces, not request bodies. No additional scrubbing layer.
 ## Risks / things to verify during implementation
 - **Bugpin "hide default button" mechanism.** Docs mention a floating launcher; the exact opt-out attribute needs to be confirmed against the install guide or the widget source. If no opt-out exists, fall back to CSS that hides the widget's launcher selector inside its Shadow DOM root (or wrap with a custom-element rule).
 - **Bugsink Sentry SDK compatibility.** Bugsink claims Sentry-SDK compatibility but tested feature surface varies. Verify with `@sentry/browser` v9 (current stable as of 2026-05) — if a specific minor version is needed, pin it.
 - **Cold-start cost.** Bugsink adds ~30–40 KB gzipped to the page. Acceptable for an authored, low-traffic site; flag if budget gets tight.
 ## TODOs.md update
 Replace line 45 with:
 ```
 - [ ] Add a "Report a Bug" footer link backed by Bugpin (widget at bugpin.half.st → forwards to GitHub Issues). Add Bugsink (@sentry/browser → bugsink.half.st) for automatic JS error capture.
 ```
 Mark complete once the implementation lands and a test report has appeared in both Bugpin's portal and GitHub.
 ## Files touched (preview)
 - `src/world/ui.md` — add `bugReport` block.
 - `src/world/schema.ts` — extend `uiFrontmatterSchema`.
 - `src/world/types.ts` — extend `UiConfig`.
 - `src/pages/index.astro` — render the button conditionally, wire data attributes, import the two new UI modules.
 - `src/ui/bug-report.ts` — **new**, lazy loads the Bugpin widget on click.
 - `src/ui/error-tracking.ts` — **new**, initializes Sentry SDK against Bugsink DSN.
 - `package.json` / `package-lock.json` — add `@sentry/browser`.
 - `src/world/TODOs.md` — rewrite line 45.
@@ -1,14 +1,15 @@
 {
  "name": "halfstreet",
-  "version": "0.0.1",
+  "version": "0.1.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "halfstreet",
-      "version": "0.0.1",
+      "version": "0.1.0",
      "license": "GPL-3.0-or-later",
      "dependencies": {
        "@sentry/browser": "^10.53.1",
        "astro": "^6.1.9",
        "yaml": "^2.8.4",
        "zod": "^4.4.3"
@@ -1766,6 +1767,81 @@
        "win32"
      ]
    },
    "node_modules/@sentry-internal/browser-utils": {
      "version": "10.53.1",
      "resolved": "https://registry.npmjs.org/@sentry-internal/browser-utils/-/browser-utils-10.53.1.tgz",
      "integrity": "sha512-X4d6y8sBMjmNhcDW4eMBU3ASsNIMz8dqaFkhyIMN/dkYr/yZKnbRZPaVuVUGvHKjnlficPpIH0/HK9KBjrYxPw==",
      "license": "MIT",
      "dependencies": {
        "@sentry/core": "10.53.1"
      },
      "engines": {
        "node": ">=18"
      }
    },
    "node_modules/@sentry-internal/feedback": {
      "version": "10.53.1",
      "resolved": "https://registry.npmjs.org/@sentry-internal/feedback/-/feedback-10.53.1.tgz",
      "integrity": "sha512-vVpTI/aEYN5d9IgZeYJWMqVaN0+iFgidSrYNAsZTh1US5sJUzF/wrl+68KdpmCtFROrN3jiAn1oPSwL5CKvEJA==",
      "license": "MIT",
      "dependencies": {
        "@sentry/core": "10.53.1"
      },
      "engines": {
        "node": ">=18"
      }
    },
    "node_modules/@sentry-internal/replay": {
      "version": "10.53.1",
      "resolved": "https://registry.npmjs.org/@sentry-internal/replay/-/replay-10.53.1.tgz",
      "integrity": "sha512-wZNzTBYkgGUPWMuUQv7L64+OJmoCnz7GQNiTrTFK6EVAjJXFBCSsPp/nhif0bLhbk8+0g4xz633uOhpXuQbFdw==",
      "license": "MIT",
      "dependencies": {
        "@sentry-internal/browser-utils": "10.53.1",
        "@sentry/core": "10.53.1"
      },
      "engines": {
        "node": ">=18"
      }
    },
    "node_modules/@sentry-internal/replay-canvas": {
      "version": "10.53.1",
      "resolved": "https://registry.npmjs.org/@sentry-internal/replay-canvas/-/replay-canvas-10.53.1.tgz",
      "integrity": "sha512-aueLaf/2prExwA76BGU5/bOXCKWqtt6jQXWA6WJQNrmKpPEtZJB4ypnpsou0McXQCF8tur2Y8U0TEkwQP13yJQ==",
      "license": "MIT",
      "dependencies": {
        "@sentry-internal/replay": "10.53.1",
        "@sentry/core": "10.53.1"
      },
      "engines": {
        "node": ">=18"
      }
    },
    "node_modules/@sentry/browser": {
      "version": "10.53.1",
      "resolved": "https://registry.npmjs.org/@sentry/browser/-/browser-10.53.1.tgz",
      "integrity": "sha512-zXF373hzUOGzUOrqd8xb1U3LQi5uYC3mwv+z5OMKUUinQlu30tTWBs7ypy6YTchtix9QlYaHWlayUF8vBZ5UjA==",
      "license": "MIT",
      "dependencies": {
        "@sentry-internal/browser-utils": "10.53.1",
        "@sentry-internal/feedback": "10.53.1",
        "@sentry-internal/replay": "10.53.1",
        "@sentry-internal/replay-canvas": "10.53.1",
        "@sentry/core": "10.53.1"
      },
      "engines": {
        "node": ">=18"
      }
    },
    "node_modules/@sentry/core": {
      "version": "10.53.1",
      "resolved": "https://registry.npmjs.org/@sentry/core/-/core-10.53.1.tgz",
      "integrity": "sha512-XG4ezlkyuAPjBC5+9kXC94rXXuqYTw9NRhfaDHssbTFaGnqBR8vQX2UUgZfY7ucbeelRDGfBu1sywoU+mB04uA==",
      "license": "MIT",
      "engines": {
        "node": ">=18"
      }
    },
    "node_modules/@shikijs/core": {
      "version": "4.0.2",
      "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-4.0.2.tgz",
@@ -1,7 +1,7 @@
 {
  "name": "halfstreet",
  "type": "module",
-  "version": "0.0.1",
+  "version": "0.1.0",
  "license": "GPL-3.0-or-later",
  "engines": {
    "node": ">=22.12.0"
@@ -11,10 +11,14 @@
    "build": "astro check && astro build",
    "preview": "astro preview",
    "astro": "astro",
    "release:patch": "npm version patch -m \"chore(release): %s\"",
    "release:minor": "npm version minor -m \"chore(release): %s\"",
    "release:major": "npm version major -m \"chore(release): %s\"",
    "test": "vitest run",
    "test:watch": "vitest"
  },
  "dependencies": {
    "@sentry/browser": "^10.53.1",
    "astro": "^6.1.9",
    "yaml": "^2.8.4",
    "zod": "^4.4.3"
@@ -0,0 +1,4 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m1065.9 452.47v-64.941h66.352v-304.94h67.766v-62.824h-78.352v54.352h-96v75.531h-105.88v105.18h-118.59v62.824h-60.707v64.941h-57.883v56.469h-76.234v108.71h-59.293v172.94h-53.648v-241.41h-52.941v-92.469h-49.41v-53.648h49.41v-67.059h97.41v-112.23h-67.059v45.176h-94.59v55.059h-48v62.824l-194.82-0.003906v-62.824h-66.352v-100.23h-67.059v112.23h54.352v67.059h51.531v53.648h-66.352v153.18h50.117v63.531h-50.117v127.77h53.648v56.469h166.59v-56.469h60.707v-60h107.29v146.12h-156v276h-17.648v86.824h280.23v-164.47h149.65v49.41h56.469v39.531h-59.293v75.531h139.77v-71.293h59.293v-93.176h45.176v93.176h67.059v71.293h176.47v-83.293h-113.65v-117.88h-62.824v-52.234h-59.293v-67.059h-60v-42.352h-121.41v-41.648h182.12v-67.059h-182.12v-45.176h280.23v-67.059h-230.12v-45.176h230.12v-50.117h-153.88v-48.707h188.47zm-750.35 151.06h-113.65v-63.531h113.65zm106.59 496.94h-40.234v-97.41h40.234z"/>
 </svg>
@@ -0,0 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m1200 431.4v-157.8h-77.398v49.199h-750v-49.199h-106.8v49.199h53.398v24.602h53.398v39.602h-54v13.801h-60.602v52.801h-81v60h-61.199v52.801h-57.602v85.199h-57.602v274.8h265.8v-254.4h57.602v-45h67.199v105.6h54v-105.6h43.199v67.801h54v-70.199h43.199v108h54v-64.801h54v-72h114.6v-70.199h237v-49.199h-234v-45.602h390.6zm-502.8-1.8008v96.602h-237v-121.8h237z"/>
 <path d="m506.4 443.4h147v49.199h-147z"/>
 <path d="m444.6 732.6h139.8v48.602h-139.8z"/>
 </svg>
@@ -0,0 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m770.13 1200v-116.11h-69.797v-100.67h-67.785v100.67h-72.484v-100.67h-67.785v100.67h-69.797v116.11z"/>
 <path d="m284.9 903.36h137.58v180.54h-137.58z"/>
 <path d="m770.13 903.36h137.58v180.54h-137.58z"/>
 <path d="m667.45 910.74v-132.89h206.04v-176.51h-226.17v176.51h-95.973v-176.51h-226.18v176.51h204.7v132.89z"/>
 <path d="m915.1 232.21v-116.11h-144.97v-116.11h-340.27v116.11h-144.97v116.11h-116.11v671.14h116.11v-555.04h116.11v-116.11h397.98v116.11h116.11v555.04h116.11v-671.14z"/>
 </svg>
@@ -0,0 +1,17 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m473.64 170.52h50.52v50.52h-50.52z"/>
 <path d="m574.68 170.52h50.52v50.52h-50.52z"/>
 <path d="m473.64 221.04h-50.52v101.04h50.52z"/>
 <path d="m625.2 322.08h50.641v-101.04h-50.641z"/>
 <path d="m524.16 473.64h151.68v-50.52h-101.04v-50.52h50.398v-50.523h-151.56v50.523h50.52v50.52h-101.04v50.52z"/>
 <path d="m524.16 120h50.52v50.52h-50.52z"/>
 <path d="m574.8 625.2v50.641h50.398v-101.04h-50.398z"/>
 <path d="m877.92 928.44h-151.56v-454.8h-50.52v50.52h-50.641v50.641h50.641v353.64h-252.72v-353.64h50.52v-50.641h-50.52v-50.52h-50.52v454.8h-151.56v50.52h50.52v50.52h50.52v-50.52h505.32v50.52h50.523z"/>
 <path d="m524.16 524.16h50.52v50.52h-50.52z"/>
 <path d="m473.64 574.68h50.52v50.52h-50.52z"/>
 <path d="m877.92 827.4h-50.523v50.523h101.04v-50.523z"/>
 <path d="m928.44 928.44v101.04h50.52v-151.56h-50.52z"/>
 <path d="m726.36 1029.5h-404.28v50.52h505.32v-50.52z"/>
 <path d="m877.92 1029.5h50.52v50.52h-50.52z"/>
 </svg>
@@ -0,0 +1,13 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m536.04 152.04h63.961v63.961h-63.961z"/>
 <path d="m792 152.04h63.961v63.961h-63.961z"/>
 <path d="m663.96 279.96v-63.961h-63.961v128.04h63.961z"/>
 <path d="m600 408v-63.961h-128.04v63.961z"/>
 <path d="m855.96 408v-63.961h-127.92v63.961z"/>
 <path d="m408 408h63.961v63.961h-63.961z"/>
 <path d="m663.96 408h63.961v63.961h-63.961z"/>
 <path d="m920.04 279.96v-63.961h-64.078v128.04h64.078z"/>
 <path d="m152.04 600h127.92v128.04h-127.92v63.961h192v63.961h63.961v64.078h-63.961v63.961h639.96v-63.961h-63.961v-64.078h63.961v-63.961h63.961v-255.96h-895.92zm639.96 192h63.961v-128.04h64.078v128.04h-64.078v63.961h-63.961z"/>
 <path d="m87.961 663.96v64.078h64.078v-128.04h-64.078z"/>
 </svg>
@@ -0,0 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m684.72 854.16h-282.36v56.398h395.28v-56.398z"/>
 <path d="m684.72 684.72h-282.36v56.52h395.28v-56.52z"/>
 <path d="m571.8 515.28h-169.44v56.52h395.28v-56.52z"/>
 <path d="m684.72 120h-451.8v960h734.16v-734.16h-56.52v-56.398h-56.398v-56.52h-56.52v-56.398l-56.52-0.003907v-56.52zm0 112.92v169.44h225.84v621.12h-621.12v-846.96h395.28z"/>
 </svg>
@@ -0,0 +1,4 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m541.45 262.22-14.297 48.703c-2.8125 8.8125-9.7031 15.703-18.469 18.609-5.8594 2.1562-12.703 4.6875-20.766 8.1562-8.3906 4.0781-18.234 4.0781-26.625 0l-46.078-25.688c-9.2812-4.9688-20.578-4.3125-29.156 1.7812-25.969 19.266-49.266 41.859-69.281 67.219-6.4219 8.4375-7.125 19.969-1.7812 29.156l25.781 44.156c4.5469 7.875 4.875 17.531 0.84375 25.688-3.6094 7.0781-6.4688 13.781-9.1406 20.531h0.046875c-3.2344 8.4844-10.312 14.953-19.078 17.391l-50.766 13.781c-10.219 2.625-17.906 11.062-19.453 21.516-4.4531 31.406-4.4531 63.328 0 94.781 1.3594 10.641 9.2344 19.266 19.688 21.609l50.297 13.781c8.9062 2.3906 16.125 8.9062 19.406 17.531 2.5312 6.6094 5.3906 13.219 8.7656 20.297 3.8438 7.9219 3.6094 17.25-0.70312 24.938l-25.781 44.625h-0.046875c-5.4375 9.1406-4.6406 20.719 1.9219 29.062 20.062 25.172 43.359 47.625 69.281 66.703 8.5312 6.3281 20.016 6.9844 29.25 1.6875l45.609-24.844c8.3906-4.2656 18.281-4.5 26.859-0.70312 7.0781 3.2344 13.781 5.8594 20.859 8.3906h0.046875c8.6719 2.9062 15.516 9.75 18.375 18.469l14.156 48.703v0.046875c2.5312 10.406 11.297 18.141 21.938 19.406 12.234 1.5 24.516 2.25 36.844 2.2969 12.047-0.28125 24.047-1.2188 36-2.8594 10.594-1.1719 19.406-8.7656 22.078-19.078l14.297-48.938v-0.046875c2.7188-8.6719 9.375-15.516 18-18.469 7.4531-2.625 14.156-5.2969 21-8.3906 8.625-3.9375 18.562-3.7031 27 0.5625l46.078 25.219c9.1406 5.3906 20.625 4.875 29.25-1.3125 26.016-19.266 49.359-41.812 69.516-67.078 6.4688-8.3906 7.1719-19.922 1.7812-29.062l-25.781-45c-4.3125-7.6406-4.5938-16.922-0.75-24.844 3.375-7.2188 6.2344-13.781 8.625-20.156h0.046875c3.2344-8.6719 10.453-15.281 19.406-17.766l50.062-13.688v0.046875c10.406-2.1562 18.375-10.594 19.922-21.141 4.4062-31.547 4.4062-63.516 0-95.062-1.5938-10.453-9.2812-18.984-19.594-21.562l-50.766-13.781 0.046875-0.046875c-8.7656-2.4375-15.891-8.8594-19.078-17.391-2.625-6.7031-5.5312-13.453-9-20.297-3.8906-8.0156-3.6094-17.391 0.70312-25.172l25.781-44.297c5.4375-9.1406 4.6875-20.625-1.7812-29.016-20.016-25.453-43.359-48.047-69.375-67.312-8.4375-6.0469-19.547-6.8438-28.781-2.0625l-45.844 25.078c-8.4844 4.0781-18.375 4.0781-26.906 0-7.9219-3.4688-14.766-6-20.625-8.1562-8.7188-2.8594-15.562-9.6562-18.469-18.375l-14.156-48.609c-2.625-10.359-11.344-18.047-21.984-19.312-12.188-1.4531-24.422-2.3438-36.703-2.625-12 0-24 1.5469-36 3.1406-10.781 1.0312-19.734 8.625-22.547 19.078zm58.547 175.18c65.766 0 125.06 39.609 150.24 100.41 25.172 60.75 11.25 130.69-35.25 177.19s-116.44 60.422-177.19 35.25c-60.797-25.172-100.41-84.469-100.41-150.24 0.09375-89.766 72.844-162.52 162.61-162.61z"/>
 </svg>
@@ -1,5 +0,0 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m937.31 531.24-50.766-13.922c-8.8125-2.3906-15.938-8.8594-19.172-17.391-2.5312-6.7031-5.5312-13.312-8.8594-20.297h-0.046875c-4.125-7.8281-4.125-17.203 0-25.078l25.781-44.297 0.046875 0.046875c5.3906-9.1406 4.7344-20.625-1.6875-29.062-20.062-25.453-43.453-48.141-69.469-67.453-8.4375-5.7656-19.359-6.4688-28.453-1.7812l-45.938 25.078h-0.046875c-8.4844 4.0781-18.375 4.0781-26.859 0-7.9219-3.4688-14.766-6-20.625-8.1562-8.7188-2.8125-15.562-9.6562-18.375-18.375l-14.156-48.609c-2.625-10.359-11.344-18.047-21.984-19.312-12.188-1.5-24.422-2.3438-36.703-2.625-12.047 0.46875-24.047 1.5469-36 3.2344-10.688 1.0781-19.594 8.6719-22.312 19.078l-14.156 48.703v0.046875c-2.8594 8.7188-9.75 15.609-18.469 18.469-5.8594 2.1562-12.703 4.6875-20.766 8.2969v-0.046875c-8.4844 4.0312-18.328 4.0312-26.766 0l-46.312-25.781c-9.2344-5.1094-20.531-4.4531-29.062 1.6875-26.016 19.266-49.312 41.906-69.375 67.312-6.4219 8.4375-7.0781 19.922-1.6406 29.062l25.781 44.297v-0.046875c4.5938 7.875 4.875 17.578 0.70312 25.688-3.4688 7.2188-6.4688 13.781-9 20.531-3.2344 8.5312-10.359 14.953-19.172 17.391l-50.766 13.922c-10.219 2.5312-17.859 10.969-19.453 21.375-4.5 31.406-4.5 63.328 0 94.781 1.2656 10.641 9.0938 19.312 19.547 21.609l50.391 13.781h0.046875c8.8594 2.4844 16.078 8.9531 19.406 17.531 2.5312 6.9375 5.4844 13.688 8.7656 20.297 3.8438 7.9219 3.6094 17.25-0.70312 24.938l-25.922 44.625c-5.3906 9.1875-4.5938 20.672 1.9219 29.062 20.062 25.219 43.359 47.672 69.234 66.844 8.5781 6.2812 20.062 6.8906 29.297 1.5469l45.703-24.844c8.3906-4.1719 18.234-4.4531 26.859-0.70312 6.8438 3.1406 13.781 5.9531 20.906 8.3906 8.625 3 15.375 9.8906 18.234 18.609l14.156 48c2.7188 10.688 11.906 18.516 22.922 19.453 11.953 1.6406 23.953 2.5781 36 2.8594 12.047-0.23438 24.047-1.2188 36-2.8594 10.641-1.125 19.5-8.7188 22.219-19.078l14.156-48.844c2.8125-8.6719 9.5156-15.562 18.094-18.609 7.4531-2.625 14.156-5.2969 21-8.3906 8.6719-3.8438 18.562-3.6562 27 0.5625l45.984 25.219c9.0938 5.4844 20.578 4.9219 29.156-1.3125 26.016-19.172 49.406-41.766 69.469-67.078 6.6094-8.3438 7.3594-19.969 1.7812-29.062l-25.641-45c-4.4062-7.5938-4.7344-16.922-0.84375-24.844 3.4688-7.0781 6.375-13.781 8.7656-20.156 3.2344-8.6719 10.453-15.281 19.406-17.766l49.453-13.641c10.641-1.9688 18.891-10.453 20.531-21.141 4.5-31.547 4.5-63.609 0-95.156-1.5-10.406-9.0938-18.891-19.219-21.609zm-3.8438 113.77c-0.60938 0.89062-1.5469 1.5-2.625 1.6875l-50.531 13.312c-15.984 4.4531-28.922 16.219-34.922 31.688-2.2969 6.2812-4.9688 12.469-7.9219 18.469-7.1719 14.812-6.6094 32.25 1.5938 46.547l25.688 44.391-0.046875 0.046875c0.70312 0.9375 0.70312 2.25 0 3.2344-18.844 23.719-40.828 44.812-65.25 62.766h-3.9375l-45.844-24.938-0.046875-0.046875c-14.766-7.5469-32.203-8.0625-47.391-1.3125-6.375 2.9062-12.891 5.5312-19.547 7.7812-15.422 5.6719-27.375 18.188-32.297 33.844l-14.391 49.453c-0.28125 1.2188-1.3594 2.1562-2.625 2.1562-11.016 1.5469-22.125 2.4375-33.234 2.625-11.391-0.1875-22.734-1.0312-33.984-2.625-1.3125-0.14062-2.3438-1.2188-2.5312-2.5312l-14.297-49.078h0.046875c-5.0156-15.703-17.109-28.219-32.672-33.703-6.7031-2.3906-12.844-4.9219-19.453-7.9219h0.046875c-7.0781-3-14.672-4.5469-22.359-4.5469-8.6719-0.046875-17.25 2.0625-24.938 6.0938l-45.938 24.938v0.046875c-1.2188 0.79688-2.7656 0.79688-3.9844 0-24.328-17.906-46.125-38.906-64.922-62.531-0.65625-0.98438-0.65625-2.25 0-3.2344l25.781-44.531c8.2031-14.297 8.7656-31.734 1.5938-46.547-3.1406-6.4688-5.7656-12-8.0625-18.609-5.8594-15.609-18.844-27.469-34.922-31.922l-50.766-13.453c-1.0312-0.1875-1.875-0.89062-2.25-1.9219-4.2188-29.578-4.2188-59.578 0-89.156 0.51562-0.9375 1.4531-1.6406 2.5312-1.9219l50.484-13.547c15.984-4.3594 28.922-16.078 34.828-31.547 2.4375-6.375 5.2031-12.656 8.25-18.75 7.125-14.906 6.4688-32.297-1.6875-46.641l-25.781-44.156v-0.046875c-0.51562-0.89062-0.51562-2.0625 0-3 18.75-23.766 40.5-44.953 64.781-63 1.4062-0.70312 3.0938-0.70312 4.4531 0l45.938 25.078h0.046875c14.719 7.7344 32.156 8.1562 47.25 1.2188 7.3125-3.2344 13.781-5.5312 19.312-7.5469 15.609-5.4844 27.703-17.953 32.672-33.75l14.391-49.219v0.046875c0.32812-1.2188 1.3594-2.1094 2.625-2.1562 12-1.6875 22.547-2.625 33-3.1406 10.453-0.46875 22.453 1.4531 34.453 3.1406 1.1719 0.32812 2.1094 1.3125 2.2969 2.5312l14.297 49.078h-0.046875c5.1094 15.609 17.156 27.984 32.672 33.469 5.5312 2.0625 12 4.3125 19.219 7.5469h-0.046875c15.141 6.9375 32.625 6.5156 47.391-1.2188l45.938-25.078h0.046875c1.3594-0.70312 2.9531-0.70312 4.3125 0 24.328 18.094 46.125 39.328 64.781 63.141 0.60938 0.89062 0.60938 2.1094 0 3l-25.875 43.781c-8.2031 14.438-8.7656 31.969-1.5938 46.922 3.0469 6.0469 5.7656 12.188 8.1562 18.516 5.8594 15.516 18.797 27.375 34.828 31.781l50.766 13.781c1.0312 0.28125 1.9688 0.98438 2.4844 1.9219 4.125 29.625 4.0781 59.719-0.23438 89.297z"/>
 <path d="m600 414.24c-49.266 0-96.516 19.594-131.34 54.422-34.828 34.828-54.422 82.078-54.422 131.34s19.594 96.516 54.422 131.34c34.828 34.828 82.078 54.422 131.34 54.422s96.516-19.594 131.34-54.422c34.828-34.828 54.422-82.078 54.422-131.34-0.046875-49.266-19.641-96.469-54.469-131.29s-82.031-54.422-131.29-54.469zm0 348c-65.812 0-125.11-39.656-150.24-100.45-25.172-60.797-11.203-130.78 35.391-177.24 46.594-46.5 116.58-60.328 177.32-35.016 60.75 25.266 100.27 84.656 100.12 150.47-0.14062 89.766-72.844 162.47-162.61 162.61z"/>
 </svg>
@@ -0,0 +1,4 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m1100 274.87v-50.016h-49.969v50.016h-550.08v-50.016h-199.97v50.016h-150v50.016h-49.969v150.05h49.969v100.03h-49.969v100.03h-49.969v100.03l-50.062 0.09375v150.05h49.969v50.016h300v-50.016h-49.969v-200.06h49.969v-50.016h199.97v-50.016h-150v-100.03h49.969v50.016h49.969v-100.03h49.969v150.05h49.969v-150.05h600l0.09375-200.16h-100.03zm-900.05 600.24h-49.969v50.016h-49.969v-50.016h-49.969v-50.016h49.969v-50.016h49.969v50.016h49.969zm450.05-450.19h-49.969v-50.016h49.969zm99.984 0h-49.969v-50.016h49.969zm100.03 0h-49.969v-50.016h49.969zm99.984 0h-49.969v-50.016h49.969zm99.984 0h-49.969v-50.016h49.969zm100.03 0h-49.969v-50.016h49.969z"/>
 </svg>
@@ -0,0 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m862.4 1125v-224.95h-74.953v-75l-374.9-0.046875v75h-74.953v224.95h74.953v75h374.86v-75h74.953zm-374.81-75v-150h224.9v150z"/>
 <path d="m487.6 0v75h-150v75h74.953v75l-74.953 0.046875v75h149.95v75h-149.95v75h149.95v300h149.95l0.046875-750.05z"/>
 </svg>
@@ -0,0 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m555 120-30 30 30 30-30 30 30 30-30 30 30 30-30 30 30 30-30 30 30 30-30 30 30 30-30 30 30 30-30 30 30 30-30 30 30 30-30 30 30 30-30 30 30 30-30 30-30-30c-9.9375 9.9844-19.969 19.969-29.953 30l30 30-30 30 30 30-30 30 30 30-30 30 30 30-30 30 30 30-30 30 30 30-30 30 30 30c30-30 59.953-60 89.953-90l-30-30 30-30-30-30 30-30-30-30 30-30-30-30 30-30-30-30 30-30 30 30 30-30 30 30c20.016-20.016 39.984-39.984 59.953-60l-30-30 30-30-30-30 30-30-30-30 30-30-30-30 30-30-30-30 30-30-30-30 30-30-30-30 30-30c-20.016-20.016-39.984-39.984-59.953-60l30-30c-20.016-20.016-39.984-39.984-59.953-60l30-30c-60.047-60-120.05-120-180-180l-30 30 30 30-30 30 30 30 30-30 30 30z"/>
 <path d="m495.05 180 30-30-30-30-30 30 30 30z"/>
 <path d="m495.05 180-30 30 30 30 30-30-30-30z"/>
 <path d="m495.05 240-30 30 30 30 30-30-30-30z"/>
 <path d="m495.05 300c-9.9844 10.031-20.016 20.016-30 30l30 30 30-30-30-30z"/>
 <path d="m495.05 360c-9.9844 10.031-20.016 20.016-30 30l30 30 30-30-30-30z"/>
 <path d="m495.05 420-30 30 30 30 30-30-30-30z"/>
 <path d="m495.05 480c-9.9844 10.031-20.016 20.016-30 30l30 30 30-30-30-30z"/>
 <path d="m495.05 540c-9.9844 10.031-20.016 20.016-30 30l30 30 30-30-30-30z"/>
 <path d="m495.05 600-30 30 30 30 30-30-30-30z"/>
 <path d="m495.05 660-30 30 30 30 30-30-30-30z"/>
 <path d="m495.05 720c-9.9844 9.9844-20.016 19.969-30 30l30 30 30-30-30-30z"/>
 </svg>
@@ -0,0 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m971.44 257.02v-57.141h-285.74v57.188h-57.141v57.188h-57.141v114.33h-57.141v171.47h-57.141v171.47h-57.141v114.33h-57.141v57.188h-57.141v57.188h914.29v-57.188h-57.141v-57.188h-57.141v-57.188h-57.141v-171.47h-57.141v114.33h-57.141v57.188h-57.141v-57.188h-57.141v57.188h-57.141v-57.188h-57.141v-171.47h57.141v-57.188h57.141v57.188h57.141v-114.33h57.141v114.33h57.141v-57.188h57.141v114.33h57.141l0.14062-342.98h-57.141v114.33h-114.28v-57.188h57.141v-57.188h57.141v-57.188h-57.141zm-114.28 171.47h-114.28v-57.188h57.141v-57.188h57.141z"/>
 <path d="m0 1000.1h57.141v-57.188l-57.141 0.046875v57.188z"/>
 <path d="m114.28 1000.1h114.28v-57.188h-114.28z"/>
 </svg>
@@ -0,0 +1,15 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m162.94 9.0469h411.79v65.625h-411.79z"/>
 <path d="m531.74 254.21h394.45v65.625h-394.45z"/>
 <path d="m531.74 144.79h394.45v65.625h-394.45z"/>
 <path d="m162.94 552.84h288.14v70.125h-288.14z"/>
 <path d="m825.14 552.84h101.06v70.125h-101.06z"/>
 <path d="m751.22 497.06v-116.16h-219.47v242.11h219.47v-70.172h-71.625v-55.781z"/>
 <path d="m162.94 679.6h288.14v70.125h-288.14z"/>
 <path d="m1109.5 240.61v-73.172h-83.719v-92.766h-73.172v92.766h66.375v794.21h-66.375v59.578l-866.63 0.046876v-791.95h76.172v276.05h288.14v-371.11h-288.14v-59.578h-86.719v92.766h-75.422v862.08h85.969v79.219h106.36v82.219h1008.4v-950.34zm-24.141 883.22h-778.36v-24.891h779.11v24.891z"/>
 <path d="m531.74 679.6h394.45v70.125h-394.45z"/>
 <path d="m531.74 788.21h394.45v70.125h-394.45z"/>
 <path d="m531.74 891.52h394.45v70.125h-394.45z"/>
 <path d="m162.94 805.55h288.14v156.14h-288.14z"/>
 </svg>
@@ -0,0 +1,4 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m1043.8 831.94-85.5-483.94c-9.5625-53.719-56.25-92.859-110.81-92.812h-33.938c-9.6094-32.719-41.062-54-75-50.812l-1.125-37.5c-1.6406-51.656-44.297-92.531-96-91.875h-82.875c-51.516-0.23438-93.844 40.734-95.25 92.25l-1.125 37.5c-33.891-3.0469-65.25 18.188-75 50.812h-34.688c-54.562-0.046875-101.25 39.094-110.81 92.812l-85.5 483.56c-15.609 88.219 40.453 173.26 127.69 193.69l67.688 15.938v27.188c0 31.078 25.172 56.25 56.25 56.25h383.63c31.078 0 56.25-25.172 56.25-56.25v-27.188l67.688-15.938c87.516-20.109 144-105.23 128.44-193.69zm-355.13 81.75 18.75 56.25h-215.06l18.75-56.25zm6.9375-37.5h-76.875v-63.188c33.938-6.6094 62.391-29.672 75.844-61.547 13.5-31.828 10.219-68.297-8.7188-97.266l-53.812-80.812c-6.7969-11.203-18.938-18.047-32.062-18.047s-25.266 6.8438-32.062 18.047l-53.812 80.812c-18.938 28.969-22.219 65.438-8.7188 97.266 13.453 31.875 41.906 54.938 75.844 61.547v63.188h-76.875l-70.312-53.812c-33.797-25.969-58.312-62.203-69.844-103.27s-9.4219-84.75 5.9062-124.55l98.625-251.26h264.37l97.688 251.26c15.328 39.797 17.438 83.484 5.9062 124.55s-36.047 77.297-69.844 103.27zm-194.81-707.44c0.70312-31.359 26.391-56.344 57.75-56.25h82.875c31.359-0.09375 57.047 24.891 57.75 56.25l1.125 36h-200.63zm-208.31 820.31c-67.594-15.844-111.14-81.609-99.375-150l85.5-483.94c6.375-35.812 37.5-61.875 73.875-61.875h33.938c6.0469 21.375 22.031 38.578 42.938 46.125l-94.312 241.87c-18.188 47.391-20.578 99.375-6.8438 148.26 13.688 48.891 42.797 92.016 82.969 123.05l64.688 49.5-23.062 67.875h-44.25c-22.641 0.046875-43.125 13.406-52.312 34.125zm615 0-63.75 15c-9.0469-20.859-29.578-34.359-52.312-34.5h-44.25l-23.062-67.875 64.688-49.5c40.078-30.984 69.141-74.109 82.875-122.9 13.688-48.75 11.344-100.69-6.75-148.03 0 0-93.75-242.26-93.75-242.06 20.812-7.6406 36.703-24.797 42.75-46.125h33.562c36.375 0 67.5 26.062 73.875 61.875l85.5 483.56c12.094 68.625-31.547 134.72-99.375 150.56z"/>
 </svg>
@@ -0,0 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m524.16 675.84h202.2v-50.641h101.04v-101.04h50.523v-252.6h-50.523v-101.04h-101.04v-50.52h-252.72v50.52h-101.04v101.04h-50.523v252.6h50.523v101.04h101.04v50.641z"/>
 <path d="m221.04 1029.5v50.52h757.92v-101.04h-50.52v-101.04h-50.52v-101.04h-101.04v-50.52h-353.76v50.52h-101.04v101.04h-50.52v101.04h-50.52z"/>
 </svg>
@@ -0,0 +1,4 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m1200 202.92h-1200v794.16h1200zm-366 206.06v263.34h52.406v183h-160.64v-183h52.406v-263.34h55.875zm-206.76 0v263.34h52.406v183h-160.64v-183h52.406v-263.34h55.875zm-206.76 0v263.34h52.406v183h-160.64v-183h52.406v-263.34h55.875zm-298.26 0h90.797v263.34h52.406v183h-143.86v-446.34zm956.26 446.34h-145.26v-183h52.406v-263.34h92.906v446.34z"/>
 </svg>
@@ -0,0 +1,16 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m563.04 489.24v-221.52h73.922v295.32h73.801v-295.32h73.918v-147.72h-369.24v147.72h73.797v295.32h73.801z"/>
 <path d="m415.44 563.04h73.801v73.801h-73.801z"/>
 <path d="m710.76 563.04h73.801v73.801h-73.801z"/>
 <path d="m341.52 636.96h73.801v73.801h-73.801z"/>
 <path d="m784.56 636.96h73.801v73.801h-73.801z"/>
 <path d="m267.72 710.76h73.801v73.801h-73.801z"/>
 <path d="m858.48 710.76h73.801v73.801h-73.801z"/>
 <path d="m193.8 784.56h73.801v73.801h-73.801z"/>
 <path d="m784.68 784.68h-73.918v-73.918h-221.52v73.918h-73.797v73.801h-73.922v73.801h516.96v-73.801h-73.801z"/>
 <path d="m932.28 784.56h73.801v73.801h-73.801z"/>
 <path d="m193.8 858.48h-73.801v147.72h73.801z"/>
 <path d="m1006.2 932.28v73.918h73.801v-147.72h-73.801z"/>
 <path d="m858.48 1006.2h-664.68v73.801h812.4v-73.801z"/>
 </svg>
@@ -0,0 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m969.3 600.06v-92.398h-46.332v-46.199h-45.961v-46.078h-92.27v-46.211h-46.309v-92.277h46.309v-184.57h-46.309v-46.078h-276.84v46.078h-46.309v184.58h46.309v92.277h-46.309v46.211h-92.281v46.078h-45.961v46.199h-46.32v92.398h-45.949v276.86h45.949v92.277h46.32v92.289h45.961v46.199h92.281v46.078h369.46v-46.078h92.27v-46.199h45.961v-92.289h46.332v-92.277h45.961v-276.86l-45.961 0.011719zm-92.293-46.32v46.32h-46.309v46.199h-45.961v46.078h-92.27v46.211h-184.92v-46.211h-92.27v-46.078h-45.961v-46.199h-46.32v-92.398h46.32v-46.199h92.27v-46.078h45.961v-184.58h-45.961v-92.277h45.961l0.003906-46.195h184.92v46.211h45.961v92.277h-45.961v184.58h45.961v46.078h92.27v46.199h46.309z"/>
 <path d="m646.13 138.54h46.332v46.078h-46.332z"/>
 <path d="m553.86 184.62v46.188h92.27v-46.188z"/>
 <path d="m507.53 138.54h46.32v46.078h-46.32z"/>
 </svg>
@@ -0,0 +1,26 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m540 60v-60h-59.953v60z"/>
 <path d="m719.95 60h-59.953v60h59.953z"/>
 <path d="m959.9 60h-59.953v60h59.953z"/>
 <path d="m599.95 120v60h59.953v-60z"/>
 <path d="m779.9 180v-60h-59.953v60z"/>
 <path d="m360.1 240v-60h-59.953v60z"/>
 <path d="m719.95 240v-60h-59.953v60z"/>
 <path d="m899.86 240h-59.953v60h59.953z"/>
 <path d="m779.9 300v60h59.953v-60z"/>
 <path d="m959.9 300h-59.953v60h59.953z"/>
 <path d="m360.1 360v60h299.9v-60z"/>
 <path d="m839.9 420h59.953v-60h-59.953z"/>
 <path d="m300.14 480h59.953v-60h-59.953z"/>
 <path d="m660 420v60h59.953v-60z"/>
 <path d="m240.1 540h59.953v-60h-59.953z"/>
 <path d="m719.95 480v60h59.953v-60z"/>
 <path d="m180.14 1200h539.81v-60h-479.86v-600h-59.953z"/>
 <path d="m839.9 1200v-660h-59.953v660z"/>
 <path d="m1019.9 540h-59.953v60h59.953z"/>
 <path d="m719.95 780h-179.95v60h179.95z"/>
 <path d="m899.86 840h59.953v-60h-59.953z"/>
 <path d="m719.95 900h-299.9v60h299.9z"/>
 <path d="m300.14 1080h419.81v-60l-419.81-0.046875z"/>
 </svg>
@@ -0,0 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <svg width="1200pt" height="1200pt" version="1.1" viewBox="0 0 1200 1200" xmlns="http://www.w3.org/2000/svg">
 <path d="m627.24 163.64v-54.562h-109.08v-54.562h54.516v-54.516h218.11v54.562h163.6v54.562h54.516v54.562h54.516v54.562h-54.516v54.562h109.08v54.562h-490.74v-54.562h-54.516v-54.562h109.08v-54.562h-54.516z"/>
 <path d="m790.82 600v54.562h218.11v-54.562h54.516v-54.562h54.516v-163.64h-436.22v163.64h54.516v54.562zm163.6-109.08v-54.562h109.08v54.562zm-54.562 54.562h54.516v54.562h-54.516zm-109.03-54.562v-54.562h109.08v54.562z"/>
 <path d="m354.61 1145.5v54.562h-163.55v-54.562h109.08v-54.562h-218.16v-54.562h54.516v-54.562h54.516v-54.562h54.516v-54.562h54.516v-54.562h54.516v-109.12h54.516v-109.12h54.516v-54.562h54.516v-54.562h54.516v-54.562h54.516v109.12h54.516v54.562h54.516v54.562h54.516v54.562h54.516v163.64h-54.516v109.12h-54.516v109.12h-54.516v54.562h-54.516v54.562h-54.516v-163.64h-54.516v54.562h-54.516v54.562h-109.08z"/>
 <path d="m899.86 763.64h54.516v54.562h-54.516z"/>
 <path d="m954.42 818.21h54.516v109.12h-54.516z"/>
 </svg>
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { dispatch, initialStateFor } from './dispatcher'
+import { dispatch, getLightStatus, initialStateFor } from './dispatcher'
 import type { World } from '../world/types'
 import type { GameState, ParsedCommand } from './types'
 import { SCHEMA_VERSION } from './types'
@@ -193,6 +193,21 @@ describe('dispatcher — take and drop', () => {
    const r = dispatch(s, { kind: 'verb-target', verb: 'drop', target: { canonical: 'torch', raw: 'torch' } }, world)
    expect(r.state.inventory.find((i) => i.id === 'torch')).toBeUndefined()
  })
  it('refuses to drop a lit lightable item', () => {
    const lightWorld: World = {
      ...world,
      items: {
        ...world.items,
        lamp: { id: 'lamp', names: ['lamp'], short: 'an oil lamp', long: 'An oil lamp.', initialState: { lit: false }, takeable: true, lightable: true },
      },
    }
    let s = initialStateFor(lightWorld)
    s = { ...s, inventory: [{ id: 'lamp', state: { lit: true, burn: 6 } }] }
    const r = dispatch(s, { kind: 'verb-target', verb: 'drop', target: { canonical: 'lamp', raw: 'lamp' } }, lightWorld)
    expect(r.appended.at(-1)?.text).toBe('Extinguish it first.')
    expect(r.state.inventory.find((i) => i.id === 'lamp')).toBeDefined()
  })
 })
 describe('dispatcher — examine', () => {
@@ -202,6 +217,29 @@ describe('dispatcher — examine', () => {
    const r = dispatch(s, { kind: 'verb-target', verb: 'examine', target: { canonical: 'torch', raw: 'torch' } }, world)
    expect(r.appended.some((l) => l.text.includes('iron oil lamp'))).toBe(true)
  })
  it('uses live match count when examining matches', () => {
    const matchWorld: World = {
      ...world,
      startingInventory: ['matches'],
      items: {
        ...world.items,
        matches: {
          id: 'matches',
          names: ['matches', 'match'],
          short: 'a matchbook',
          long: 'A damp matchbook with five matches left inside.',
          initialState: { uses: 4 },
          takeable: true,
          lighter: true,
          lighterUses: 5,
        },
      },
    }
    const s = initialStateFor(matchWorld)
    const r = dispatch(s, { kind: 'verb-target', verb: 'examine', target: { canonical: 'matches', raw: 'matches' } }, matchWorld)
    expect(r.appended.at(-1)?.text).toBe('A damp matchbook with four matches left inside.')
  })
 })
 describe('dispatcher — inventory', () => {
@@ -218,6 +256,151 @@ describe('dispatcher — inventory', () => {
  })
 })
 describe('light status', () => {
  it('shows the meter when carrying a lightable item even before it is lit', () => {
    const lightWorld: World = {
      ...world,
      items: {
        ...world.items,
        torch: {
          id: 'torch',
          names: ['torch', 'lamp'],
          short: 'an oil lamp',
          long: 'An iron oil lamp, unlit.',
          initialState: { lit: false },
          takeable: true,
          lightable: true,
        },
      },
    }
    const state: GameState = {
      ...initialStateFor(lightWorld),
      inventory: [{ id: 'torch', state: { lit: false } }],
    }
    expect(getLightStatus(state, lightWorld)).toEqual({
      itemId: 'torch',
      lit: false,
      turnsLeft: 0,
      maxTurns: 6,
    })
  })
  it('prefers a lit lightable item over an unlit one in inventory order', () => {
    const lightWorld: World = {
      ...world,
      items: {
        ...world.items,
        torch: {
          id: 'torch',
          names: ['torch', 'lamp'],
          short: 'an oil lamp',
          long: 'An iron oil lamp, unlit.',
          initialState: { lit: false },
          takeable: true,
          lightable: true,
        },
        candlestick: {
          id: 'candlestick',
          names: ['candlestick', 'candle'],
          short: 'a brass candlestick',
          long: 'A brass candlestick.',
          initialState: { lit: false },
          takeable: true,
          lightable: true,
        },
      },
    }
    const state: GameState = {
      ...initialStateFor(lightWorld),
      inventory: [
        { id: 'candlestick', state: { lit: false } },
        { id: 'torch', state: { lit: true, burn: 6 } },
      ],
    }
    expect(getLightStatus(state, lightWorld)).toEqual({
      itemId: 'torch',
      lit: true,
      turnsLeft: 6,
      maxTurns: 6,
    })
  })
  it('uses the configured light meter length and state keys', () => {
    const lightWorld: World = {
      ...world,
      mechanics: {
        light: {
          enabled: true,
          handler: 'light',
          maxTurns: 3,
          burnOn: ['wait'],
          stateKeys: { lit: 'isLit', burn: 'fuel' },
          ui: { meter: true, icon: 'candle' },
        },
      },
      items: {
        ...world.items,
        torch: {
          id: 'torch',
          names: ['torch', 'lamp'],
          short: 'an oil lamp',
          long: 'An iron oil lamp, unlit.',
          initialState: { isLit: false },
          takeable: true,
          lightable: true,
        },
      },
    }
    const state: GameState = {
      ...initialStateFor(lightWorld),
      inventory: [{ id: 'torch', state: { isLit: true, fuel: 2 } }],
    }
    expect(getLightStatus(state, lightWorld)).toEqual({
      itemId: 'torch',
      lit: true,
      turnsLeft: 2,
      maxTurns: 3,
    })
  })
  it('hides the meter when the light mechanic is disabled', () => {
    const lightWorld: World = {
      ...world,
      mechanics: {
        light: {
          enabled: false,
          handler: 'light',
          maxTurns: 6,
          burnOn: ['move', 'wait'],
          stateKeys: { lit: 'lit', burn: 'burn' },
          ui: { meter: true, icon: 'candle' },
        },
      },
      items: {
        ...world.items,
        torch: {
          id: 'torch',
          names: ['torch', 'lamp'],
          short: 'an oil lamp',
          long: 'An iron oil lamp, unlit.',
          initialState: { lit: false },
          takeable: true,
          lightable: true,
        },
      },
    }
    const state: GameState = {
      ...initialStateFor(lightWorld),
      inventory: [{ id: 'torch', state: { lit: true, burn: 6 } }],
    }
    expect(getLightStatus(state, lightWorld)).toBeNull()
  })
 })
 describe('ambiguous → disambiguation flow', () => {
  function makeAmbiguousWorld(): World {
    return {
@@ -369,6 +552,14 @@ describe('light/extinguish verbs (implicit lighter)', () => {
    expect(result.appended.at(-1)?.text).toBe("You can't light that.")
  })
  it('asks what to use a match with instead of lighting the matchbook alone', () => {
    const world = w()
    let state = initialStateFor(world)
    state = { ...state, inventory: [{ id: 'matches', state: { uses: 2 } }] }
    const result = dispatch(state, { kind: 'verb-target', verb: 'light', target: { canonical: 'matches', raw: 'match' } }, world)
    expect(result.appended.at(-1)?.text).toBe('Use match with what?')
  })
  it('emits the lighter-empty message when matches reach 0', () => {
    const world = w()
    let state = initialStateFor(world)
@@ -383,6 +574,152 @@ describe('light/extinguish verbs (implicit lighter)', () => {
    expect(texts).toContain('The book is empty.')
  })
  it('burns one segment on each wait and extinguishes when the last segment expires', () => {
    const world = w()
    let state = initialStateFor(world)
    state = { ...state, inventory: [{ id: 'lamp', state: { lit: true, burn: 6 } }] }
    const first = dispatch(state, { kind: 'verb-only', verb: 'wait' }, world)
    expect(first.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(5)
    expect(first.state.inventory.find((i) => i.id === 'lamp')?.state['lit']).toBe(true)
    const second = dispatch(first.state, { kind: 'verb-only', verb: 'wait' }, world)
    expect(second.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(4)
    const third = dispatch(second.state, { kind: 'verb-only', verb: 'wait' }, world)
    expect(third.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(3)
    const fourth = dispatch(third.state, { kind: 'verb-only', verb: 'wait' }, world)
    expect(fourth.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(2)
    const fifth = dispatch(fourth.state, { kind: 'verb-only', verb: 'wait' }, world)
    expect(fifth.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(1)
    expect(fifth.state.inventory.find((i) => i.id === 'lamp')?.state['lit']).toBe(true)
    const sixth = dispatch(fifth.state, { kind: 'verb-only', verb: 'wait' }, world)
    expect(sixth.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(0)
    expect(sixth.state.inventory.find((i) => i.id === 'lamp')?.state['lit']).toBe(false)
    expect(sixth.appended.map((l) => l.text)).toContain('The flame dies.')
  })
  it('burns one segment on movement', () => {
    const world = w()
    const movingWorld: World = {
      ...world,
      rooms: {
        ...world.rooms,
        r: {
          id: 'r',
          title: '[ R ]',
          descriptions: { firstVisit: '.', revisit: '.', examined: '.' },
          exits: { n: 'r2' },
          items: [],
        },
        r2: { id: 'r2', title: '[ R2 ]', descriptions: { firstVisit: '.', revisit: '.', examined: '.' }, exits: {}, items: [] },
      },
    }
    let state = initialStateFor(movingWorld)
    state = { ...state, inventory: [{ id: 'lamp', state: { lit: true, burn: 6 } }] }
    const result = dispatch(state, { kind: 'go', direction: 'n' }, movingWorld)
    expect(result.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(5)
    expect(result.state.location).toBe('r2')
  })
  it('uses configured maxTurns when lighting and burning down', () => {
    const baseWorld = w()
    const world: World = {
      ...baseWorld,
      mechanics: {
        light: {
          enabled: true,
          handler: 'light',
          maxTurns: 3,
          burnOn: ['wait'],
          stateKeys: { lit: 'lit', burn: 'burn' },
          ui: { meter: true, icon: 'candle' },
          messages: { flameDies: 'The configured light dies.' },
        },
      },
      items: {
        ...baseWorld.items,
        lamp: {
          id: 'lamp',
          names: ['lamp'],
          short: 'an oil lamp',
          long: '.',
          initialState: { lit: false },
          takeable: true,
          lightable: true,
          litText: 'The wick catches.',
        },
      },
    }
    let state = initialStateFor(world)
    state = { ...state, inventory: [
      { id: 'lamp', state: { lit: false } },
      { id: 'matches', state: { uses: 2 } },
    ] }
    const lit = dispatch(state, { kind: 'verb-target', verb: 'light', target: { canonical: 'lamp', raw: 'lamp' } }, world)
    expect(lit.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(3)
    const first = dispatch(lit.state, { kind: 'verb-only', verb: 'wait' }, world)
    expect(first.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(2)
    const second = dispatch(first.state, { kind: 'verb-only', verb: 'wait' }, world)
    expect(second.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(1)
    const third = dispatch(second.state, { kind: 'verb-only', verb: 'wait' }, world)
    expect(third.state.inventory.find((i) => i.id === 'lamp')?.state['lit']).toBe(false)
    expect(third.appended.map((l) => l.text)).toContain('The configured light dies.')
  })
  it('does not burn down on movement when move is not configured', () => {
    const world: World = {
      ...w(),
      mechanics: {
        light: {
          enabled: true,
          handler: 'light',
          maxTurns: 3,
          burnOn: ['wait'],
          stateKeys: { lit: 'lit', burn: 'burn' },
          ui: { meter: true, icon: 'candle' },
        },
      },
      rooms: {
        r: { id: 'r', title: '[ R ]', descriptions: { firstVisit: '.', revisit: '.', examined: '.' }, exits: { n: 'r2' }, items: [] },
        r2: { id: 'r2', title: '[ R2 ]', descriptions: { firstVisit: '.', revisit: '.', examined: '.' }, exits: {}, items: [] },
      },
    }
    let state = initialStateFor(world)
    state = { ...state, inventory: [{ id: 'lamp', state: { lit: true, burn: 3 } }] }
    const result = dispatch(state, { kind: 'go', direction: 'n' }, world)
    expect(result.state.inventory.find((i) => i.id === 'lamp')?.state['burn']).toBe(3)
  })
  it('disabling the light mechanic removes burn-down behavior', () => {
    const world: World = {
      ...w(),
      mechanics: {
        light: {
          enabled: false,
          handler: 'light',
          maxTurns: 6,
          burnOn: ['move', 'wait'],
          stateKeys: { lit: 'lit', burn: 'burn' },
          ui: { meter: true, icon: 'candle' },
        },
      },
    }
    let state = initialStateFor(world)
    state = { ...state, inventory: [{ id: 'lamp', state: { lit: true, burn: 1 } }] }
    const result = dispatch(state, { kind: 'verb-only', verb: 'wait' }, world)
    expect(result.state.inventory.find((i) => i.id === 'lamp')?.state).toEqual({ lit: true, burn: 1 })
    expect(result.appended.map((l) => l.text)).not.toContain('The flame dies.')
  })
  it('extinguishes a lit lamp', () => {
    const world = w()
    let state = initialStateFor(world)
@@ -459,6 +796,24 @@ describe('use verb routing', () => {
      rooms: { r: { id: 'r', title: '[ R ]', descriptions: { firstVisit: '.', revisit: '.', examined: '.' }, exits: {}, items: [] } },
      items: {
        rock: { id: 'rock', names: ['rock'], short: 'a rock', long: '.', initialState: {}, takeable: true },
        matches: { id: 'matches', names: ['matches', 'match'], short: 'a matchbook', long: '.', initialState: { uses: 2 }, takeable: true, lighter: true, lighterUses: 2, lighterEmptyText: 'The book is empty.' },
        letter: { id: 'letter', names: ['letter'], short: 'a letter', long: '.', initialState: {}, takeable: true, readable: true, readableText: 'Read me.' },
        'broken-cigarette': { id: 'broken-cigarette', names: ['cigarette', 'broken cigarette'], short: 'a broken cigarette', long: '.', initialState: { lit: false }, takeable: true, lightable: true, litText: 'The end glows once, then steadies. The smoke is bitter.' },
      },
      actions: {
        'burn-letter': {
          id: 'burn-letter',
          verbs: ['use'],
          requires: { allVisibleOrHeld: ['letter', 'matches'] },
          consumes: { inventory: ['letter'] },
          decrements: { item: 'matches', stateKey: 'uses' },
          setsFlags: { letterBurned: true },
          messages: {
            success: 'The letter catches at one corner. In a few breaths it is ash.',
            spent: 'The matchbook is empty.',
            missingRequired: "You don't see the letter here.",
          },
        },
      },
      encounters: {},
      endings: { true: { whenFlags: { _never: true }, narration: '' }, wrong: { whenFlags: { _never: true }, narration: '' }, bad: { whenFlags: { _never: true }, narration: '' } },
@@ -474,6 +829,123 @@ describe('use verb routing', () => {
    }, world)
    expect(result.appended.at(-1)?.text).toBe("You can't think how to use that here.")
  })
  it('asks what to use a bare match with', () => {
    const world = w()
    let state = initialStateFor(world)
    state = { ...state, inventory: [{ id: 'matches', state: { uses: 2 } }] }
    const result = dispatch(state, {
      kind: 'verb-target', verb: 'use', target: { canonical: 'matches', raw: 'match' },
    }, world)
    expect(result.appended.at(-1)?.text).toBe('Use match with what?')
  })
  it('burns the letter when using a match with it', () => {
    const world = w()
    let state = initialStateFor(world)
    state = { ...state, inventory: [{ id: 'matches', state: { uses: 2 } }, { id: 'letter', state: {} }] }
    const result = dispatch(state, {
      kind: 'verb-target-prep', verb: 'use',
      target: { canonical: 'matches', raw: 'match' },
      preposition: 'with',
      indirect: { canonical: 'letter', raw: 'letter' },
    }, world)
    expect(result.state.inventory.find((i) => i.id === 'letter')).toBeUndefined()
    expect(result.state.inventory.find((i) => i.id === 'matches')?.state['uses']).toBe(1)
    expect(result.state.flags['letterBurned']).toBe(true)
    expect(result.appended.at(-1)?.text).toContain('ash')
  })
  it('lights a lightable item when using a match with it', () => {
    const world = w()
    let state = initialStateFor(world)
    state = { ...state, inventory: [
      { id: 'matches', state: { uses: 2 } },
      { id: 'broken-cigarette', state: { lit: false } },
    ] }
    const result = dispatch(state, {
      kind: 'verb-target-prep', verb: 'use',
      target: { canonical: 'matches', raw: 'match' },
      preposition: 'with',
      indirect: { canonical: 'broken-cigarette', raw: 'cigarette' },
    }, world)
    expect(result.state.inventory.find((i) => i.id === 'broken-cigarette')?.state['lit']).toBe(true)
    expect(result.state.inventory.find((i) => i.id === 'matches')?.state['uses']).toBe(1)
    expect(result.appended.at(-1)?.text).toBe('The end glows once, then steadies. The smoke is bitter.')
  })
 })
 describe('handler-backed drink action', () => {
  function w(): World {
    return {
      startingRoom: 'r',
      startingInventory: ['whiskey'],
      rooms: {
        r: { id: 'r', title: '[ R ]', descriptions: { firstVisit: '.', revisit: '.', examined: '.' }, exits: {}, items: [] },
        'drunk-start': { id: 'drunk-start', title: '[ Drunk Start ]', descriptions: { firstVisit: 'The hall tips.', revisit: 'The hall tips again.', examined: '.' }, exits: { n: 'drunk-next' }, items: [] },
        'drunk-next': { id: 'drunk-next', title: '[ Drunk Next ]', descriptions: { firstVisit: 'The room doubles.', revisit: 'The room doubles again.', examined: '.' }, exits: { s: 'drunk-start' }, items: [] },
        vestibule: { id: 'vestibule', title: '[ Vestibule ]', descriptions: { firstVisit: '.', revisit: 'You wake somewhere else.', examined: '.' }, exits: {}, items: [] },
        pantry: { id: 'pantry', title: '[ Pantry ]', descriptions: { firstVisit: '.', revisit: '.', examined: '.' }, exits: {}, items: ['whiskey'] },
      },
      items: {
        whiskey: { id: 'whiskey', names: ['whiskey'], short: 'a bottle of whiskey', long: '.', initialState: {}, takeable: true },
      },
      actions: {
        'drink-whiskey': {
          id: 'drink-whiskey',
          verbs: ['drink'],
          handler: 'drunk-transition',
          requires: { allHeld: ['whiskey'] },
          consumes: { inventory: ['whiskey'] },
          drunkTransition: {
            destinationRoom: 'drunk-start',
            maxMoves: 2,
            wakeRoom: 'vestibule',
            resetRoom: 'pantry',
          },
          messages: {
            success: 'Custom drink text.',
            missingRequired: 'Hold it first.',
            tooManyMovesPassOut: 'Custom pass out.',
            reset: 'Custom reset.',
          },
        },
      },
      encounters: {},
      endings: { true: { whenFlags: { _never: true }, narration: '' }, wrong: { whenFlags: { _never: true }, narration: '' }, bad: { whenFlags: { _never: true }, narration: '' } },
    }
  }
  it('uses markdown action config for destination, move cap, wake room, and reset room', () => {
    const world = w()
    let state = initialStateFor(world)
    let result = dispatch(state, { kind: 'verb-target', verb: 'drink', target: { canonical: 'whiskey', raw: 'whiskey' } }, world)
    expect(result.state.location).toBe('drunk-start')
    expect(result.state.inventory.find((i) => i.id === 'whiskey')).toBeUndefined()
    expect(result.appended.map((l) => l.text)).toContain('Custom drink text.')
    state = {
      ...result.state,
      roomState: {
        ...result.state.roomState,
        pantry: { takenItems: ['whiskey'], droppedItems: ['whiskey'] },
      },
    }
    result = dispatch(state, { kind: 'go', direction: 'n' }, world)
    expect(result.state.location).toBe('drunk-next')
    expect(result.state.flags['drunkMoves']).toBe(1)
    result = dispatch(result.state, { kind: 'go', direction: 's' }, world)
    expect(result.state.location).toBe('vestibule')
    expect(result.state.flags['drunk']).toBe(false)
    expect(result.state.roomState['pantry']?.['takenItems']).toEqual([])
    expect(result.state.roomState['pantry']?.['droppedItems']).toEqual([])
    expect(result.appended.map((l) => l.text)).toContain('Custom pass out.')
    expect(result.appended.map((l) => l.text)).toContain('Custom reset.')
  })
 })
 describe('ending detection', () => {
@@ -1,15 +1,83 @@
-import type { World } from '../world/types'
+import { DEFAULT_WORLD_MESSAGES, type DeclarativeAction, type LightMechanicMessageKey, type World, type WorldMessageKey } from '../world/types'
-import type { GameState, ParsedCommand, DispatchResult, ItemInstance, TranscriptLine } from './types'
+import type { GameState, ParsedCommand, DispatchResult, ItemInstance, TranscriptLine, ResolveLevel } from './types'
-import { SCHEMA_VERSION, TRANSCRIPT_CAP } from './types'
+import { SCHEMA_VERSION, TRANSCRIPT_CAP, RESOLVE_LEVELS } from './types'
 import { applyVerbToEncounter, maybeTriggerEncounter } from './encounters'
-const HALFSTREET_ASCII = String.raw`
+type ActiveLightMechanic = NonNullable<NonNullable<World['mechanics']>['light']>
- _   _       _  __     ____  _                 _
+type ActiveResolveMechanic = NonNullable<NonNullable<World['mechanics']>['resolve']>
-| | | | __ _| |/ _|   / ___|| |_ _ __ ___  ___| |_
+
-| |_| |/ _\` | | |_    \___ \| __| '__/ _ \/ _ \ __|
+const DEFAULT_LIGHT_MECHANIC: ActiveLightMechanic = {
-|  _  | (_| | |  _|    ___) | |_| | |  __/  __/ |_
+  enabled: true,
-|_| |_|\__,_|_|_|     |____/ \__|_|  \___|\___|\__|
+  handler: 'light',
-`.trim()
+  maxTurns: 6,
  burnOn: ['move', 'wait'],
  stateKeys: { lit: 'lit', burn: 'burn' },
  ui: { meter: true, icon: 'candle' },
  messages: {},
 }
 const DEFAULT_RESOLVE_MECHANIC: ActiveResolveMechanic = {
  enabled: true,
  handler: 'resolve',
  ladder: RESOLVE_LEVELS,
  wrongVerbCost: 1,
  safeRooms: { recoverySteps: 1 },
  failure: { retreatAt: 'returning', afterRetreat: 'shaken' },
 }
 const DEFAULT_DRUNK_ACTION: DeclarativeAction = {
  id: 'drink-whiskey',
  verbs: ['drink'],
  handler: 'drunk-transition',
  requires: { allHeld: ['whiskey'] },
  consumes: { inventory: ['whiskey'] },
  drunkTransition: {
    destinationRoom: 'drunk-hall',
    maxMoves: 20,
    wakeRoom: 'foyer',
    resetRoom: 'kitchen',
  },
  messages: {
    success: 'You drink from the bottle. It tastes of smoke, sugar, and rainwater left too long in a pipe.',
    secretFoundPassOut: 'The faceless man steps backward into the dark. The floor rises under you, or you fall toward it.',
    tooManyMovesPassOut: 'The rooms keep turning until they become one room. Then even that room is gone.',
    reset: 'The bottle is not with you. Somewhere in the kitchen, it is half full again.',
  },
 }
 export interface LightStatus {
  itemId: string
  lit: boolean
  turnsLeft: number
  maxTurns: number
 }
 function message(world: World, key: WorldMessageKey): string {
  return world.messages?.[key] ?? DEFAULT_WORLD_MESSAGES[key]
 }
 function lightMechanic(world: World): ActiveLightMechanic {
  return world.mechanics?.light ?? DEFAULT_LIGHT_MECHANIC
 }
 function resolveMechanic(world: World): ActiveResolveMechanic {
  return world.mechanics?.resolve ?? DEFAULT_RESOLVE_MECHANIC
 }
 function drunkAction(world: World): DeclarativeAction {
  return Object.values(world.actions ?? {}).find((action) => action.handler === 'drunk-transition') ?? DEFAULT_DRUNK_ACTION
 }
 function recoverResolve(level: ResolveLevel, world: World): ResolveLevel {
  const mechanic = resolveMechanic(world)
  if (!mechanic.enabled || mechanic.safeRooms.recoverySteps === 0) return level
  const idx = mechanic.ladder.indexOf(level)
  if (idx <= 0) return level
  return mechanic.ladder[Math.max(0, idx - mechanic.safeRooms.recoverySteps)] ?? level
 }
 function lightMessage(world: World, key: LightMechanicMessageKey, fallback: WorldMessageKey): string {
  const mechanic = lightMechanic(world)
  return mechanic?.messages?.[key] ?? message(world, fallback)
 }
 export function initialStateFor(world: World): GameState {
  const startingRoom = world.rooms[world.startingRoom]
@@ -22,13 +90,14 @@ export function initialStateFor(world: World): GameState {
  })
  const opening: TranscriptLine[] = [
-    { kind: 'system', text: HALFSTREET_ASCII },
+    ...(world.game?.openingArt ? [{ kind: 'system' as const, text: world.game.openingArt }] : []),
    { kind: 'system', text: startingRoom.title },
    { kind: 'narration', text: startingRoom.descriptions.firstVisit },
  ]
  return {
    schemaVersion: SCHEMA_VERSION,
    transcriptCap: world.game?.transcriptCap,
    location: world.startingRoom,
    inventory,
    roomState: { [world.startingRoom]: { visited: true } },
@@ -37,14 +106,38 @@ export function initialStateFor(world: World): GameState {
    encounterState: {},
    lastNoun: null,
    pendingDisambiguation: null,
    pendingConfirmation: null,
    transcript: opening,
    endedWith: null,
  }
 }
 export function getLightStatus(state: GameState, world: World): LightStatus | null {
  const mechanic = lightMechanic(world)
  if (!mechanic?.enabled || mechanic.ui?.meter === false) return null
  let fallback: LightStatus | null = null
  for (const inst of state.inventory) {
    const def = world.items[inst.id]
    if (!def?.lightable) continue
    const lit = inst.state[mechanic.stateKeys.lit] === true
    const turnsLeft = lit ? getLightTurnsLeft(inst, world) : 0
    const status = {
      itemId: inst.id,
      lit,
      turnsLeft,
      maxTurns: mechanic.maxTurns,
    }
    if (lit) return status
    fallback = fallback ?? status
  }
  return fallback
 }
 function append(state: GameState, lines: TranscriptLine[]): GameState {
  const transcript = [...state.transcript, ...lines]
-  return { ...state, transcript: transcript.slice(-TRANSCRIPT_CAP) }
+  const cap = state.transcriptCap ?? TRANSCRIPT_CAP
  return { ...state, transcript: transcript.slice(-cap) }
 }
 export function getItemsInRoom(state: GameState, world: World, roomId: string): string[] {
@@ -64,12 +157,12 @@ function setRoomFlag(state: GameState, roomId: string, key: string, value: strin
  }
 }
 const ENDING_PRIORITY: ('true' | 'wrong' | 'bad')[] = ['true', 'wrong', 'bad']
 function evaluateEndings(state: GameState, world: World): GameState | null {
  if (state.endedWith) return null
-  for (const id of ENDING_PRIORITY) {
+  const priority = world.endingPriority ?? Object.keys(world.endings)
  for (const id of priority) {
    const ending = world.endings[id]
    if (!ending) continue
    const flags = ending.whenFlags
    let allMatch = true
    for (const [k, v] of Object.entries(flags)) {
@@ -86,37 +179,78 @@ function evaluateEndings(state: GameState, world: World): GameState | null {
 }
 function withEndingCheck(result: DispatchResult, world: World): DispatchResult {
  result = maybeResolveDrunkState(result, world)
  const updated = evaluateEndings(result.state, world)
  if (!updated) return result
  const endingLine: TranscriptLine = updated.transcript[updated.transcript.length - 1]!
  return { state: updated, appended: [...result.appended, endingLine] }
 }
-export function dispatch(state: GameState, command: ParsedCommand, world: World): DispatchResult {
+const CRITICAL_VERBS = new Set(['attack'])
 function isCriticalCommand(command: ParsedCommand): boolean {
  if (command.kind !== 'verb-target' && command.kind !== 'verb-target-prep') return false
  return CRITICAL_VERBS.has(command.verb)
 }
 function confirmationPrompt(command: ParsedCommand): string {
  if (command.kind === 'verb-target') {
    return `Are you sure you want to ${command.verb} ${command.target.raw}? Type yes to continue, or no to stop.`
  }
  if (command.kind === 'verb-target-prep') {
    return `Are you sure you want to ${command.verb} ${command.target.raw} ${command.preposition} ${command.indirect.raw}? Type yes to continue, or no to stop.`
  }
  return 'Are you sure? Type yes to continue, or no to stop.'
 }
 export function dispatch(state: GameState, command: ParsedCommand, world: World, confirmed = false): DispatchResult {
  if (command.kind === 'confirmation') {
    const pending = state.pendingConfirmation
    if (!pending) {
      return narrate(state, [{ kind: 'narration', text: message(world, 'nothing-to-confirm') }])
    }
    const cleared: GameState = { ...state, pendingConfirmation: null }
    if (!command.confirmed) {
      return narrate(cleared, [{ kind: 'narration', text: message(world, 'cancelled') }])
    }
    return dispatch(cleared, pending.command, world, true)
  }
  if (state.pendingConfirmation) {
    state = { ...state, pendingConfirmation: null }
  }
  // Once the game has ended, only restart/undo (handled by the UI) can clear state.
  if (state.endedWith) {
    return narrate(state, [{ kind: 'narration', text: world.game?.endedText ?? 'The story has ended. Type `restart` or `undo`.' }])
  }
  if (!confirmed && isCriticalCommand(command)) {
    const prompt = confirmationPrompt(command)
    const next: GameState = { ...state, pendingConfirmation: { command, prompt } }
    return narrate(next, [{ kind: 'narration', text: prompt }])
  }
  // Disambiguation reply: re-issue the original verb with the chosen target.
  if (command.kind === 'disambiguation') {
    const pending = state.pendingDisambiguation
    if (!pending) {
-      return narrate(state, [{ kind: 'narration', text: 'Nothing to choose between.' }])
+      return narrate(state, [{ kind: 'narration', text: message(world, 'nothing-to-choose') }])
    }
    const cleared: GameState = { ...state, pendingDisambiguation: null }
    return dispatch(
      cleared,
      { kind: 'verb-target', verb: pending.verb, target: { canonical: command.chosen, raw: command.chosen } },
      world,
      confirmed,
    )
  }
  // Once the game has ended, only restart/undo (handled by the UI) can clear state.
  if (state.endedWith) {
    return narrate(state, [{ kind: 'narration', text: 'The story has ended. Type `restart` or `undo`.' }])
  }
  if (command.kind === 'unknown') {
    const text =
-      command.reason === 'unknown-verb' ? 'You consider the words, but they don\'t fit this place.'
+      command.reason === 'unknown-verb' ? message(world, 'unknown-verb')
-      : command.reason === 'unknown-noun' ? 'You don\'t see anything like that here.'
+      : command.reason === 'unknown-noun' ? message(world, 'unknown-noun')
-      : 'You hesitate.'
+      : message(world, 'malformed')
    return narrate(state, [{ kind: 'narration', text }])
  }
@@ -149,7 +283,8 @@ export function dispatch(state: GameState, command: ParsedCommand, world: World)
    }
    if (command.verb === 'look') return withEndingCheck(handleLook(state, world), world)
    if (command.verb === 'inventory') return withEndingCheck(handleInventory(state, world), world)
-    if (command.verb === 'wait') return withEndingCheck(narrate(state, [{ kind: 'narration', text: 'Time passes.' }]), world)
+    if (command.verb === 'wait') return withEndingCheck(handleWait(state, world), world)
    if (command.verb === 'listen') return withEndingCheck(narrate(state, [{ kind: 'narration', text: message(world, 'listen') }]), world)
  }
  if (command.kind === 'verb-target') {
@@ -163,9 +298,16 @@ export function dispatch(state: GameState, command: ParsedCommand, world: World)
    if (command.verb === 'drop') return withEndingCheck(handleDrop(stateWithNoun, command.target.canonical, world), world)
    if (command.verb === 'examine' || command.verb === 'look') return withEndingCheck(handleExamine(stateWithNoun, command.target.canonical, world), world)
    if (command.verb === 'read') return withEndingCheck(handleRead(stateWithNoun, command.target.canonical, world), world)
    if (command.verb === 'drink') return withEndingCheck(handleDrink(stateWithNoun, command.target.canonical, world), world)
    if (command.verb === 'light') return withEndingCheck(handleLight(stateWithNoun, command.target.canonical, null, world), world)
    if (command.verb === 'extinguish') return withEndingCheck(handleExtinguish(stateWithNoun, command.target.canonical, world), world)
-    if (command.verb === 'use') return withEndingCheck(narrate(stateWithNoun, [{ kind: 'narration', text: "You can't think how to use that here." }]), world)
+    if (command.verb === 'use') {
      const target = world.items[command.target.canonical]
      if (target?.lighter && !target.lightable) {
        return withEndingCheck(narrate(stateWithNoun, [{ kind: 'narration', text: message(world, 'use-lighter-with-what') }]), world)
      }
      return withEndingCheck(narrate(stateWithNoun, [{ kind: 'narration', text: message(world, 'use-unknown') }]), world)
    }
    return withEndingCheck(narrate(stateWithNoun, [{ kind: 'narration', text: `You're not sure how to ${command.verb} that.` }]), world)
  }
@@ -180,12 +322,16 @@ export function dispatch(state: GameState, command: ParsedCommand, world: World)
      return withEndingCheck(handleLight(stateWithNoun, command.target.canonical, command.indirect.canonical, world), world)
    }
    if (command.verb === 'use') {
-      return withEndingCheck(narrate(stateWithNoun, [{ kind: 'narration', text: "You can't think how to use that here." }]), world)
+      const actionResult = handleDeclarativeAction(stateWithNoun, command, world)
      if (actionResult) return withEndingCheck(actionResult, world)
      const lightResult = handleUseAsLight(stateWithNoun, command.target.canonical, command.indirect.canonical, world)
      if (lightResult) return withEndingCheck(lightResult, world)
      return withEndingCheck(narrate(stateWithNoun, [{ kind: 'narration', text: message(world, 'use-unknown') }]), world)
    }
    return withEndingCheck(narrate(stateWithNoun, [{ kind: 'narration', text: `You're not sure how to ${command.verb} that.` }]), world)
  }
-  return narrate(state, [{ kind: 'narration', text: 'Nothing happens.' }])
+  return narrate(state, [{ kind: 'narration', text: message(world, 'nothing-happens') }])
 }
 function narrate(state: GameState, lines: TranscriptLine[]): DispatchResult {
@@ -207,11 +353,11 @@ function handleMeta(state: GameState, verb: 'restart' | 'undo' | 'hint' | 'save'
 function handleGo(state: GameState, direction: 'n' | 's' | 'e' | 'w' | 'u' | 'd', world: World): DispatchResult {
  const room = world.rooms[state.location]
-  if (!room) return narrate(state, [{ kind: 'narration', text: 'You are nowhere.' }])
+  if (!room) return narrate(state, [{ kind: 'narration', text: message(world, 'nowhere') }])
  const dest = room.exits[direction]
  if (!dest) {
-    return narrate(state, [{ kind: 'narration', text: 'You can\'t go that way.' }])
+    return narrate(state, [{ kind: 'narration', text: message(world, 'no-exit') }])
  }
  const lock = room.lockedExits?.[direction]
@@ -223,7 +369,7 @@ function handleGo(state: GameState, direction: 'n' | 's' | 'e' | 'w' | 'u' | 'd'
  }
  const destRoom = world.rooms[dest]
-  if (!destRoom) return narrate(state, [{ kind: 'narration', text: 'The way ahead is unfinished.' }])
+  if (!destRoom) return narrate(state, [{ kind: 'narration', text: message(world, 'unfinished-exit') }])
  const visited = !!state.roomState[dest]?.['visited']
  const description = visited ? destRoom.descriptions.revisit : destRoom.descriptions.firstVisit
@@ -232,16 +378,24 @@ function handleGo(state: GameState, direction: 'n' | 's' | 'e' | 'w' | 'u' | 'd'
  next = setRoomFlag(next, dest, 'visited', true)
  if (destRoom.safe) {
-    const ladder = ['steady', 'shaken', 'reeling', 'returning'] as const
+    next = { ...next, resolveLevel: recoverResolve(state.resolveLevel, world) }
    const idx = ladder.indexOf(state.resolveLevel)
    if (idx > 0) next = { ...next, resolveLevel: ladder[idx - 1]! }
  }
  const lightTick = advanceLightState(next, 'move', world)
  next = lightTick.state
  const arrivalLines: TranscriptLine[] = [
    { kind: 'system', text: destRoom.title },
    { kind: 'narration', text: description },
    ...lightTick.lines,
  ]
-  const result = narrate(next, arrivalLines)
+  let result = narrate(next, arrivalLines)
  if (state.flags['drunk'] === true && dest.startsWith('drunk-')) {
    const moved = advanceDrunkTurns(result.state, world)
    if (moved.appended.length > 0) return { state: moved.state, appended: [...arrivalLines, ...moved.appended] }
    result = { state: moved.state, appended: arrivalLines }
  }
  // Trigger any encounter waiting in this room.
  const triggered = maybeTriggerEncounter(result.state, world)
@@ -251,9 +405,115 @@ function handleGo(state: GameState, direction: 'n' | 's' | 'e' | 'w' | 'u' | 'd'
  return result
 }
 function handleDrink(state: GameState, itemId: string, world: World): DispatchResult {
  const action = drunkAction(world)
  const targetItems = new Set([
    ...(action.requires?.allHeld ?? []),
    ...(action.requires?.allVisibleOrHeld ?? []),
    ...(action.consumes?.inventory ?? []),
  ])
  if (!action.verbs.includes('drink') || !targetItems.has(itemId)) {
    return narrate(state, [{ kind: 'narration', text: message(world, 'cannot-drink') }])
  }
  const requiredHeld = action.requires?.allHeld ?? [...targetItems]
  const held = requiredHeld.every((requiredId) => state.inventory.some((i) => i.id === requiredId))
  if (!held) {
    return narrate(state, [{ kind: 'narration', text: action.messages.missingRequired ?? message(world, 'need-carrying') }])
  }
  const config = action.drunkTransition ?? DEFAULT_DRUNK_ACTION.drunkTransition!
  const consumed = new Set(action.consumes?.inventory ?? [itemId])
  const dest = world.rooms[config.destinationRoom]
  const next: GameState = {
    ...state,
    location: config.destinationRoom,
    inventory: state.inventory.filter((i) => !consumed.has(i.id)),
    flags: { ...state.flags, drunk: true, drunkMoves: 0, drunkSecretFound: false },
  }
  const visited = !!next.roomState[config.destinationRoom]?.['visited']
  const withVisit = setRoomFlag(next, config.destinationRoom, 'visited', true)
  const lines: TranscriptLine[] = [
    { kind: 'narration', text: action.messages.success },
  ]
  if (dest) {
    lines.push(
      { kind: 'system', text: dest.title },
      { kind: 'narration', text: visited ? dest.descriptions.revisit : dest.descriptions.firstVisit },
    )
  }
  return narrate(withVisit, lines)
 }
 function maybeResolveDrunkState(result: DispatchResult, world: World): DispatchResult {
  if (result.state.flags['drunk'] !== true) return result
  if (result.state.flags['drunkSecretFound'] === true) {
    const action = drunkAction(world)
    const passed = passOutFromDrunk(
      result.state,
      world,
      action.messages.secretFoundPassOut ?? DEFAULT_DRUNK_ACTION.messages.secretFoundPassOut!,
    )
    return { state: passed.state, appended: [...result.appended, ...passed.appended] }
  }
  return result
 }
 function advanceDrunkTurns(state: GameState, world: World): DispatchResult {
  const action = drunkAction(world)
  const config = action.drunkTransition ?? DEFAULT_DRUNK_ACTION.drunkTransition!
  const current = typeof state.flags['drunkMoves'] === 'number' ? state.flags['drunkMoves'] : 0
  const moves = current + 1
  const next = { ...state, flags: { ...state.flags, drunkMoves: moves } }
  if (moves < config.maxMoves) return { state: next, appended: [] }
  return passOutFromDrunk(
    next,
    world,
    action.messages.tooManyMovesPassOut ?? DEFAULT_DRUNK_ACTION.messages.tooManyMovesPassOut!,
  )
 }
 function passOutFromDrunk(state: GameState, world: World, preface: string): DispatchResult {
  const action = drunkAction(world)
  const config = action.drunkTransition ?? DEFAULT_DRUNK_ACTION.drunkTransition!
  const resetItem = action.consumes?.inventory?.[0] ?? 'whiskey'
  const wakeRoom = world.rooms[config.wakeRoom]
  const resetRoomState = state.roomState[config.resetRoom] ?? {}
  const resetTaken = ((resetRoomState['takenItems'] ?? []) as string[]).filter((id) => id !== resetItem)
  const resetDropped = ((resetRoomState['droppedItems'] ?? []) as string[]).filter((id) => id !== resetItem)
  const next: GameState = {
    ...state,
    location: config.wakeRoom,
    inventory: state.inventory.filter((i) => i.id !== resetItem),
    flags: { ...state.flags, drunk: false, drunkMoves: 0, drunkSecretFound: false },
    roomState: {
      ...state.roomState,
      [config.resetRoom]: {
        ...resetRoomState,
        takenItems: resetTaken,
        droppedItems: resetDropped,
      },
      [config.wakeRoom]: { ...(state.roomState[config.wakeRoom] ?? {}), visited: true },
    },
  }
  const lines: TranscriptLine[] = [
    { kind: 'narration', text: preface },
    { kind: 'system', text: wakeRoom?.title ?? `[ ${config.wakeRoom} ]` },
    { kind: 'narration', text: wakeRoom?.descriptions.revisit ?? `You wake in ${config.wakeRoom}.` },
    { kind: 'narration', text: action.messages.reset ?? DEFAULT_DRUNK_ACTION.messages.reset! },
  ]
  return narrate(next, lines)
 }
 function handleWait(state: GameState, world: World): DispatchResult {
  const lightTick = advanceLightState(state, 'wait', world)
  return narrate(lightTick.state, [
    { kind: 'narration', text: message(world, 'time-passes') },
    ...lightTick.lines,
  ])
 }
 function handleLook(state: GameState, world: World): DispatchResult {
  const room = world.rooms[state.location]
-  if (!room) return narrate(state, [{ kind: 'narration', text: 'You see nothing.' }])
+  if (!room) return narrate(state, [{ kind: 'narration', text: message(world, 'see-nothing') }])
  const items = getItemsInRoom(state, world, state.location)
  const itemNarration = describeRoomItems(items.map((id) => world.items[id]?.short ?? id))
  return narrate(state, [
@@ -282,30 +542,31 @@ function joinList(values: string[]): string {
 function handleInventory(state: GameState, world: World): DispatchResult {
  if (state.inventory.length === 0) {
-    return narrate(state, [{ kind: 'narration', text: 'You are empty-handed.' }])
+    return narrate(state, [{ kind: 'narration', text: message(world, 'inventory-empty') }])
  }
  const lines = state.inventory.map((inst) => {
    const item = world.items[inst.id]
-    const litSuffix = inst.state['lit'] === true ? ' (lit)' : ''
+    const mechanic = lightMechanic(world)
    const litSuffix = mechanic?.enabled && inst.state[mechanic.stateKeys.lit] === true ? ' (lit)' : ''
    return `  ${item?.short ?? inst.id}${litSuffix}`
  })
  return narrate(state, [
-    { kind: 'narration', text: 'You are carrying:' },
+    { kind: 'narration', text: message(world, 'inventory-heading') },
    { kind: 'narration', text: lines.join('\n') },
  ])
 }
 function handleTake(state: GameState, itemId: string, world: World): DispatchResult {
  const item = world.items[itemId]
-  if (!item) return narrate(state, [{ kind: 'narration', text: 'You don\'t see that here.' }])
+  if (!item) return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-here') }])
-  if (!item.takeable) return narrate(state, [{ kind: 'narration', text: 'You can\'t take that.' }])
+  if (!item.takeable) return narrate(state, [{ kind: 'narration', text: message(world, 'cannot-take') }])
  const itemsHere = getItemsInRoom(state, world, state.location)
  if (!itemsHere.includes(itemId)) {
-    return narrate(state, [{ kind: 'narration', text: 'You don\'t see that here.' }])
+    return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-here') }])
  }
  if (state.inventory.find((i) => i.id === itemId)) {
-    return narrate(state, [{ kind: 'narration', text: 'You already have it.' }])
+    return narrate(state, [{ kind: 'narration', text: message(world, 'already-have') }])
  }
  const wasInRoomBase = (world.rooms[state.location]?.items ?? []).includes(itemId)
@@ -320,12 +581,18 @@ function handleTake(state: GameState, itemId: string, world: World): DispatchRes
    const dropped = (next.roomState[state.location]?.['droppedItems'] ?? []) as string[]
    next = setRoomFlag(next, state.location, 'droppedItems', dropped.filter((id) => id !== itemId))
  }
-  return narrate(next, [{ kind: 'narration', text: 'Taken.' }])
+  return narrate(next, [{ kind: 'narration', text: message(world, 'taken') }])
 }
-function handleDrop(state: GameState, itemId: string, _world: World): DispatchResult {
+function handleDrop(state: GameState, itemId: string, world: World): DispatchResult {
  if (!state.inventory.find((i) => i.id === itemId)) {
-    return narrate(state, [{ kind: 'narration', text: 'You don\'t have that.' }])
+    return narrate(state, [{ kind: 'narration', text: message(world, 'dont-have') }])
  }
  const itemDef = world.items[itemId]
  const itemInst = state.inventory.find((i) => i.id === itemId) ?? null
  const mechanic = lightMechanic(world)
  if (mechanic?.enabled && itemDef?.lightable && itemInst?.state[mechanic.stateKeys.lit] === true) {
    return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'dropLit', 'drop-lit') }])
  }
  let next: GameState = {
    ...state,
@@ -333,60 +600,78 @@ function handleDrop(state: GameState, itemId: string, _world: World): DispatchRe
  }
  const dropped = (next.roomState[state.location]?.['droppedItems'] ?? []) as string[]
  next = setRoomFlag(next, state.location, 'droppedItems', [...dropped, itemId])
-  return narrate(next, [{ kind: 'narration', text: 'Dropped.' }])
+  return narrate(next, [{ kind: 'narration', text: message(world, 'dropped') }])
 }
 function handleExamine(state: GameState, itemId: string, world: World): DispatchResult {
  const item = world.items[itemId]
-  if (!item) return narrate(state, [{ kind: 'narration', text: 'You don\'t see anything like that.' }])
+  if (!item) return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-anything') }])
  const inventoryInst = state.inventory.find((i) => i.id === itemId) ?? null
  const visible =
-    state.inventory.find((i) => i.id === itemId) ||
+    inventoryInst ||
    getItemsInRoom(state, world, state.location).includes(itemId)
-  if (!visible) return narrate(state, [{ kind: 'narration', text: 'You don\'t see anything like that.' }])
+  if (!visible) return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-anything') }])
-  return narrate(state, [{ kind: 'narration', text: item.long }])
+  return narrate(state, [{ kind: 'narration', text: describeItem(itemId, item.long, inventoryInst) }])
 }
 function describeItem(itemId: string, longDescription: string, inst: ItemInstance | null): string {
  if (itemId !== 'matches' || typeof inst?.state['uses'] !== 'number') return longDescription
  const uses = inst.state['uses']
  const noun = uses === 1 ? 'match' : 'matches'
  const count = spellSmallCount(uses)
  return longDescription.replace(/with \w+ matches? left inside\./i, `with ${count} ${noun} left inside.`)
 }
 function spellSmallCount(value: number): string {
  const words = ['no', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten']
  return words[value] ?? String(value)
 }
 function handleRead(state: GameState, itemId: string, world: World): DispatchResult {
  const item = world.items[itemId]
-  if (!item) return narrate(state, [{ kind: 'narration', text: "You don't see anything like that." }])
+  if (!item) return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-anything') }])
  const visible =
    state.inventory.find((i) => i.id === itemId) ||
    getItemsInRoom(state, world, state.location).includes(itemId)
-  if (!visible) return narrate(state, [{ kind: 'narration', text: "You don't see anything like that." }])
+  if (!visible) return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-anything') }])
  if (!item.readable || !item.readableText) {
-    return narrate(state, [{ kind: 'narration', text: "There's nothing to read on it." }])
+    return narrate(state, [{ kind: 'narration', text: message(world, 'nothing-to-read') }])
  }
  return narrate(state, [{ kind: 'narration', text: item.readableText }])
 }
 function handleLight(state: GameState, targetId: string, instrumentId: string | null, world: World): DispatchResult {
  const mechanic = lightMechanic(world)
  if (!mechanic?.enabled) return narrate(state, [{ kind: 'narration', text: message(world, 'nothing-happens') }])
  const target = world.items[targetId]
-  if (!target) return narrate(state, [{ kind: 'narration', text: "You don't see anything like that." }])
+  if (!target) return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-anything') }])
-  if (!target.lightable) return narrate(state, [{ kind: 'narration', text: "You can't light that." }])
+  if (target.lighter && !target.lightable) return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'useLighterWithWhat', 'use-lighter-with-what') }])
  if (!target.lightable) return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'cannotLight', 'cannot-light') }])
  const targetInst = state.inventory.find((i) => i.id === targetId) ?? null
  const visibleInRoom = getItemsInRoom(state, world, state.location).includes(targetId)
  if (!targetInst && !visibleInRoom) {
-    return narrate(state, [{ kind: 'narration', text: "You don't see anything like that." }])
+    return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-anything') }])
  }
  // The 'lit' state lives on the inventory instance for inventory items, or
  // (eventually) on roomState for items left in a room. For now we only
  // support lighting items the player is carrying.
  if (!targetInst) {
-    return narrate(state, [{ kind: 'narration', text: "You'd have to be carrying it." }])
+    return narrate(state, [{ kind: 'narration', text: message(world, 'need-carrying') }])
  }
-  if (targetInst.state['lit'] === true) {
+  if (targetInst.state[mechanic.stateKeys.lit] === true) {
-    return narrate(state, [{ kind: 'narration', text: "It's already lit." }])
+    return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'alreadyLit', 'already-lit') }])
  }
  // Pick an instrument. If explicit, validate it; if implicit, find any.
  let lighterInst = null as typeof state.inventory[number] | null
  if (instrumentId) {
    lighterInst = state.inventory.find((i) => i.id === instrumentId) ?? null
-    if (!lighterInst) return narrate(state, [{ kind: 'narration', text: "You don't have that." }])
+    if (!lighterInst) return narrate(state, [{ kind: 'narration', text: message(world, 'dont-have') }])
    const lighterDef = world.items[instrumentId]
-    if (!lighterDef?.lighter) return narrate(state, [{ kind: 'narration', text: "That isn't going to help." }])
+    if (!lighterDef?.lighter) return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'notHelpful', 'not-helpful') }])
    if (typeof lighterInst.state['uses'] === 'number' && lighterInst.state['uses'] <= 0) {
-      return narrate(state, [{ kind: 'narration', text: "It is spent." }])
+      return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'spent', 'spent') }])
    }
  } else {
    for (const inst of state.inventory) {
@@ -397,7 +682,7 @@ function handleLight(state: GameState, targetId: string, instrumentId: string |
      break
    }
    if (!lighterInst) {
-      return narrate(state, [{ kind: 'narration', text: 'You have nothing to light it with.' }])
+      return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'noLighter', 'no-lighter') }])
    }
  }
@@ -406,28 +691,157 @@ function handleLight(state: GameState, targetId: string, instrumentId: string |
  const lighterUsesField = typeof lighterInst.state['uses'] === 'number' ? lighterInst.state['uses'] : null
  const newLighterUses = lighterUsesField === null ? null : lighterUsesField - 1
  const newInventory = state.inventory.map((i) => {
-    if (i.id === targetInst.id) return { ...i, state: { ...i.state, lit: true } }
+    if (i.id === targetInst.id) return { ...i, state: { ...i.state, [mechanic.stateKeys.lit]: true, [mechanic.stateKeys.burn]: mechanic.maxTurns } }
    if (i.id === lighterInst!.id && newLighterUses !== null) return { ...i, state: { ...i.state, uses: newLighterUses } }
    return i
  })
-  const lines: TranscriptLine[] = [{ kind: 'narration', text: target.litText ?? 'It catches.' }]
+  const lines: TranscriptLine[] = [{ kind: 'narration', text: target.litText ?? lightMessage(world, 'flameCatches', 'flame-catches') }]
  if (newLighterUses === 0) {
-    lines.push({ kind: 'narration', text: lighterDef.lighterEmptyText ?? 'It is spent.' })
+    lines.push({ kind: 'narration', text: lighterDef.lighterEmptyText ?? lightMessage(world, 'spent', 'spent') })
  }
  return narrate({ ...state, inventory: newInventory }, lines)
 }
 function handleDeclarativeAction(
  state: GameState,
  command: Extract<ParsedCommand, { kind: 'verb-target-prep' }>,
  world: World,
 ): DispatchResult | null {
  const action = findDeclarativeAction(command, world)
  if (!action) return null
  for (const itemId of action.requires?.allVisibleOrHeld ?? []) {
    if (!isVisibleOrHeld(state, world, itemId)) {
      return narrate(state, [{ kind: 'narration', text: action.messages.missingRequired ?? message(world, 'dont-see-anything') }])
    }
  }
  for (const itemId of action.requires?.allHeld ?? []) {
    if (!state.inventory.some((i) => i.id === itemId)) {
      return narrate(state, [{ kind: 'narration', text: action.messages.missingRequired ?? message(world, 'dont-have') }])
    }
  }
  const decrement = action.decrements
  const decremented = decrement ? state.inventory.find((i) => i.id === decrement.item) : null
  if (decrement && !decremented) {
    return narrate(state, [{ kind: 'narration', text: action.messages.missingRequired ?? message(world, 'dont-have') }])
  }
  const decrementStateValue = decrement ? decremented?.state[decrement.stateKey] : null
  const decrementedValue: number | null = typeof decrementStateValue === 'number' ? decrementStateValue : null
  if (decrementedValue !== null && decrementedValue <= 0) {
    return narrate(state, [{ kind: 'narration', text: action.messages.spent ?? message(world, 'spent') }])
  }
  const consumed = new Set(action.consumes?.inventory ?? [])
  let next: GameState = {
    ...state,
    inventory: state.inventory
      .filter((i) => !consumed.has(i.id))
      .map((i) =>
        decrement && i.id === decrement.item && decrementedValue !== null
          ? { ...i, state: { ...i.state, [decrement.stateKey]: decrementedValue - 1 } }
          : i,
      ),
    flags: { ...state.flags, ...(action.setsFlags ?? {}) },
  }
  for (const itemId of consumed) {
    next = removeVisibleRoomItem(next, world, itemId)
  }
  const lines: TranscriptLine[] = [{ kind: 'narration', text: action.messages.success }]
  if (decrementedValue === 1 && action.messages.spent) {
    lines.push({ kind: 'narration', text: action.messages.spent })
  }
  return narrate(next, lines)
 }
 function findDeclarativeAction(
  command: Extract<ParsedCommand, { kind: 'verb-target-prep' }>,
  world: World,
 ): DeclarativeAction | null {
  const commandItems = new Set([command.target.canonical, command.indirect.canonical])
  for (const action of Object.values(world.actions ?? {})) {
    if (!action.verbs.includes(command.verb)) continue
    const required = [...(action.requires?.allVisibleOrHeld ?? []), ...(action.requires?.allHeld ?? [])]
    if (required.length > 0 && required.every((itemId) => commandItems.has(itemId))) return action
  }
  return null
 }
 function isVisibleOrHeld(state: GameState, world: World, itemId: string): boolean {
  return state.inventory.some((i) => i.id === itemId) || getItemsInRoom(state, world, state.location).includes(itemId)
 }
 function removeVisibleRoomItem(state: GameState, world: World, itemId: string): GameState {
  if (!getItemsInRoom(state, world, state.location).includes(itemId)) return state
  const baseItems = world.rooms[state.location]?.items ?? []
  let next = state
  if (baseItems.includes(itemId)) {
    const taken = (next.roomState[state.location]?.['takenItems'] ?? []) as string[]
    next = setRoomFlag(next, state.location, 'takenItems', [...new Set([...taken, itemId])])
  }
  const dropped = (next.roomState[state.location]?.['droppedItems'] ?? []) as string[]
  if (dropped.includes(itemId)) {
    next = setRoomFlag(next, state.location, 'droppedItems', dropped.filter((id) => id !== itemId))
  }
  return next
 }
 function handleUseAsLight(state: GameState, firstId: string, secondId: string, world: World): DispatchResult | null {
  if (!lightMechanic(world)?.enabled) return null
  const first = world.items[firstId]
  const second = world.items[secondId]
  if (first?.lighter && second?.lightable) return handleLight(state, secondId, firstId, world)
  if (second?.lighter && first?.lightable) return handleLight(state, firstId, secondId, world)
  return null
 }
 function handleExtinguish(state: GameState, targetId: string, world: World): DispatchResult {
  const mechanic = lightMechanic(world)
  if (!mechanic?.enabled) return narrate(state, [{ kind: 'narration', text: message(world, 'nothing-happens') }])
  const target = world.items[targetId]
-  if (!target) return narrate(state, [{ kind: 'narration', text: "You don't see anything like that." }])
+  if (!target) return narrate(state, [{ kind: 'narration', text: message(world, 'dont-see-anything') }])
-  if (!target.lightable) return narrate(state, [{ kind: 'narration', text: "You can't extinguish that." }])
+  if (!target.lightable) return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'cannotExtinguish', 'cannot-extinguish') }])
  const targetInst = state.inventory.find((i) => i.id === targetId)
-  if (!targetInst) return narrate(state, [{ kind: 'narration', text: "You'd have to be carrying it." }])
+  if (!targetInst) return narrate(state, [{ kind: 'narration', text: message(world, 'need-carrying') }])
-  if (targetInst.state['lit'] !== true) {
+  if (targetInst.state[mechanic.stateKeys.lit] !== true) {
-    return narrate(state, [{ kind: 'narration', text: "It isn't lit." }])
+    return narrate(state, [{ kind: 'narration', text: lightMessage(world, 'notLit', 'not-lit') }])
  }
  const newInventory = state.inventory.map((i) =>
-    i.id === targetId ? { ...i, state: { ...i.state, lit: false } } : i,
+    i.id === targetId ? { ...i, state: { ...i.state, [mechanic.stateKeys.lit]: false, [mechanic.stateKeys.burn]: 0 } } : i,
  )
-  return narrate({ ...state, inventory: newInventory }, [{ kind: 'narration', text: target.extinguishedText ?? 'The flame dies.' }])
+  return narrate({ ...state, inventory: newInventory }, [{ kind: 'narration', text: target.extinguishedText ?? lightMessage(world, 'flameDies', 'flame-dies') }])
 }
 function advanceLightState(state: GameState, trigger: 'move' | 'wait', world: World): { state: GameState; lines: TranscriptLine[] } {
  const mechanic = lightMechanic(world)
  if (!mechanic?.enabled || !mechanic.burnOn.includes(trigger)) return { state, lines: [] }
  let changed = false
  const lines: TranscriptLine[] = []
  const inventory = state.inventory.map((inst) => {
    const def = world.items[inst.id]
    if (!def?.lightable || inst.state[mechanic.stateKeys.lit] !== true) return inst
    const turnsLeft = getLightTurnsLeft(inst, world)
    const nextTurns = Math.max(0, turnsLeft - 1)
    changed = true
    if (nextTurns === 0) {
      lines.push({ kind: 'narration', text: def.extinguishedText ?? lightMessage(world, 'flameDies', 'flame-dies') })
      return { ...inst, state: { ...inst.state, [mechanic.stateKeys.lit]: false, [mechanic.stateKeys.burn]: 0 } }
    }
    return { ...inst, state: { ...inst.state, [mechanic.stateKeys.burn]: nextTurns } }
  })
  return changed ? { state: { ...state, inventory }, lines } : { state, lines }
 }
 function getLightTurnsLeft(inst: ItemInstance, world: World): number {
  const mechanic = lightMechanic(world)
  const turns = inst.state[mechanic.stateKeys.burn]
  if (typeof turns === 'number') return Math.max(0, turns)
  return inst.state[mechanic.stateKeys.lit] === true ? mechanic.maxTurns : 0
 }
@@ -10,7 +10,7 @@ const world: World = {
      id: 'foyer',
      title: '[ Foyer ]',
      descriptions: { firstVisit: 'Foyer.', revisit: 'Foyer.', examined: 'Foyer.' },
-      exits: { n: 'stair' },
+      exits: { n: 'stair', e: 'chapel' },
      items: [],
      safe: true,
    },
@@ -29,10 +29,19 @@ const world: World = {
      exits: { u: 'stair' },
      items: [],
    },
    chapel: {
      id: 'chapel',
      title: '[ Chapel ]',
      descriptions: { firstVisit: 'Chapel.', revisit: 'Chapel.', examined: 'Chapel.' },
      exits: { s: 'foyer' },
      items: ['vial'],
      encounter: 'basilisk',
    },
  },
  items: {
    mirror: { id: 'mirror', names: ['mirror', 'tarnished mirror'], short: 'a tarnished mirror', long: 'A small mirror, tarnished black.', initialState: {}, takeable: true },
    sword: { id: 'sword', names: ['sword', 'cane sword'], short: 'a cane sword', long: 'A slim cane sword.', initialState: {}, takeable: true },
    vial: { id: 'vial', names: ['vial'], short: 'a vial', long: 'A small vial.', initialState: {}, takeable: true },
  },
  encounters: {
    revenant: {
@@ -59,6 +68,22 @@ const world: World = {
      onFailed: { narration: 'You stagger back.', retreatTo: 'foyer' },
      defaultWrongVerbNarration: 'The revenant does not seem to notice.',
    },
    basilisk: {
      id: 'basilisk',
      aliases: ['basilisk'],
      startsIn: 'chapel',
      initialPhase: 'sleeping',
      phases: {
        sleeping: {
          description: 'An eye opens beneath the altar.',
          transitions: [
            { verb: 'pour', target: 'vial', requires: { item: 'vial' }, narration: 'The eye closes.', to: 'resolved' },
          ],
        },
      },
      onResolved: { setFlags: { basiliskSpared: true } },
      defaultWrongVerbNarration: 'The eye watches.',
    },
  },
  endings: {
    true:  { whenFlags: { _never: true }, narration: '' },
@@ -67,6 +92,23 @@ const world: World = {
  },
 }
 function withResolveMechanic(overrides: Partial<NonNullable<NonNullable<World['mechanics']>['resolve']>>): World {
  return {
    ...world,
    mechanics: {
      resolve: {
        enabled: true,
        handler: 'resolve',
        ladder: ['steady', 'shaken', 'reeling', 'returning'],
        wrongVerbCost: 1,
        safeRooms: { recoverySteps: 1 },
        failure: { retreatAt: 'returning', afterRetreat: 'shaken' },
        ...overrides,
      },
    },
  }
 }
 describe('encounters — phase advancement', () => {
  it('triggers an encounter on entering its room', () => {
    let s = initialStateFor(world)
@@ -87,11 +129,25 @@ describe('encounters — phase advancement', () => {
  it('wrong verb costs resolve and surfaces a clue', () => {
    let s = initialStateFor(world)
    s = dispatch(s, { kind: 'go', direction: 'n' }, world).state
-    const r = dispatch(s, { kind: 'verb-target', verb: 'attack', target: { canonical: 'revenant', raw: 'revenant' } }, world)
+    const prompt = dispatch(s, { kind: 'verb-target', verb: 'attack', target: { canonical: 'revenant', raw: 'revenant' } }, world)
    expect(prompt.state.pendingConfirmation).toBeDefined()
    expect(prompt.appended.at(-1)?.text).toContain('Are you sure')
    const r = dispatch(prompt.state, { kind: 'confirmation', confirmed: true }, world)
    expect(r.state.resolveLevel).toBe('shaken')
    expect(r.state.encounterState['revenant']).toBe('shaken')
  })
  it('cancels a confirmed attack when the player says no', () => {
    let s = initialStateFor(world)
    s = dispatch(s, { kind: 'go', direction: 'n' }, world).state
    const prompt = dispatch(s, { kind: 'verb-target', verb: 'attack', target: { canonical: 'revenant', raw: 'revenant' } }, world)
    const r = dispatch(prompt.state, { kind: 'confirmation', confirmed: false }, world)
    expect(r.state.pendingConfirmation).toBeNull()
    expect(r.state.resolveLevel).toBe('steady')
    expect(r.state.encounterState['revenant']).toBe('wary')
    expect(r.appended.at(-1)?.text).toBe('Cancelled.')
  })
  it('falls back to defaultWrongVerbNarration for unrecognized verbs', () => {
    let s = initialStateFor(world)
    s = dispatch(s, { kind: 'go', direction: 'n' }, world).state
@@ -104,7 +160,8 @@ describe('encounters — phase advancement', () => {
    s = dispatch(s, { kind: 'go', direction: 'n' }, world).state
    // Force resolve to 'returning' so the next failure retreats.
    s = { ...s, resolveLevel: 'returning' }
-    const r = dispatch(s, { kind: 'verb-target', verb: 'attack', target: { canonical: 'revenant', raw: 'revenant' } }, world)
+    s = dispatch(s, { kind: 'verb-target', verb: 'attack', target: { canonical: 'revenant', raw: 'revenant' } }, world).state
    const r = dispatch(s, { kind: 'confirmation', confirmed: true }, world)
    expect(r.state.location).toBe('foyer')
    expect(r.appended.some((l) => l.text.includes('stagger back'))).toBe(true)
  })
@@ -116,4 +173,55 @@ describe('encounters — phase advancement', () => {
    s = dispatch(s, { kind: 'go', direction: 's' }, world).state
    expect(s.resolveLevel).toBe('steady')
  })
  it('uses markdown resolve config for wrong-verb cost', () => {
    const configured = withResolveMechanic({ wrongVerbCost: 2 })
    let s = initialStateFor(configured)
    s = dispatch(s, { kind: 'go', direction: 'n' }, configured).state
    const r = dispatch(s, { kind: 'verb-target', verb: 'push', target: { canonical: 'revenant', raw: 'revenant' } }, configured)
    expect(r.state.resolveLevel).toBe('reeling')
  })
  it('uses markdown resolve config for safe-room recovery', () => {
    const configured = withResolveMechanic({ safeRooms: { recoverySteps: 2 } })
    let s = initialStateFor(configured)
    s = { ...s, resolveLevel: 'reeling' }
    s = dispatch(s, { kind: 'go', direction: 'n' }, configured).state
    s = dispatch(s, { kind: 'go', direction: 's' }, configured).state
    expect(s.resolveLevel).toBe('steady')
  })
  it('uses markdown resolve config for post-retreat level', () => {
    const configured = withResolveMechanic({ failure: { retreatAt: 'returning', afterRetreat: 'reeling' } })
    let s = initialStateFor(configured)
    s = dispatch(s, { kind: 'go', direction: 'n' }, configured).state
    s = { ...s, resolveLevel: 'returning' }
    s = dispatch(s, { kind: 'verb-target', verb: 'attack', target: { canonical: 'revenant', raw: 'revenant' } }, configured).state
    const r = dispatch(s, { kind: 'confirmation', confirmed: true }, configured)
    expect(r.state.location).toBe('foyer')
    expect(r.state.resolveLevel).toBe('reeling')
  })
  it('allows a required item to be the direct target in a target-preposition encounter command', () => {
    let s = initialStateFor(world)
    s = {
      ...s,
      inventory: [...s.inventory, { id: 'vial', state: {} }],
      roomState: { ...s.roomState, chapel: { takenItems: ['vial'] } },
    }
    s = dispatch(s, { kind: 'go', direction: 'e' }, world).state
    const r = dispatch(
      s,
      {
        kind: 'verb-target-prep',
        verb: 'pour',
        target: { canonical: 'vial', raw: 'vial' },
        preposition: 'on',
        indirect: { canonical: 'basilisk', raw: 'basilisk' },
      },
      world,
    )
    expect(r.state.flags['basiliskSpared']).toBe(true)
    expect(r.appended.some((l) => l.text.includes('eye closes'))).toBe(true)
  })
 })
@@ -2,6 +2,17 @@ import type { World } from '../world/types'
 import type { GameState, ParsedCommand, DispatchResult, TranscriptLine, ResolveLevel } from './types'
 import { TRANSCRIPT_CAP, RESOLVE_LEVELS } from './types'
 type ActiveResolveMechanic = NonNullable<NonNullable<World['mechanics']>['resolve']>
 const DEFAULT_RESOLVE_MECHANIC: ActiveResolveMechanic = {
  enabled: true,
  handler: 'resolve',
  ladder: RESOLVE_LEVELS,
  wrongVerbCost: 1,
  safeRooms: { recoverySteps: 1 },
  failure: { retreatAt: 'returning', afterRetreat: 'shaken' },
 }
 function append(state: GameState, lines: TranscriptLine[]): GameState {
  const transcript = [...state.transcript, ...lines]
  return { ...state, transcript: transcript.slice(-TRANSCRIPT_CAP) }
@@ -38,11 +49,26 @@ export function maybeTriggerEncounter(state: GameState, world: World): DispatchR
  return narrate(next, [{ kind: 'narration', text: phase.description }])
 }
-function bumpResolve(level: ResolveLevel, cost: 0 | 1 | 2 | undefined): ResolveLevel {
+function resolveMechanic(world: World): ActiveResolveMechanic {
-  if (!cost) return level
+  return world.mechanics?.resolve ?? DEFAULT_RESOLVE_MECHANIC
-  const idx = RESOLVE_LEVELS.indexOf(level)
+}
-  const newIdx = Math.min(RESOLVE_LEVELS.length - 1, idx + cost)
+
-  return RESOLVE_LEVELS[newIdx]!
+function bumpResolve(level: ResolveLevel, cost: 0 | 1 | 2 | undefined, world: World): ResolveLevel {
  const mechanic = resolveMechanic(world)
  if (!mechanic.enabled || !cost) return level
  const idx = mechanic.ladder.indexOf(level)
  if (idx < 0) return level
  const newIdx = Math.min(mechanic.ladder.length - 1, idx + cost)
  return mechanic.ladder[newIdx]!
 }
 function shouldRetreat(level: ResolveLevel, cost: 0 | 1 | 2 | undefined, world: World): boolean {
  const mechanic = resolveMechanic(world)
  return mechanic.enabled && !!cost && level === mechanic.failure.retreatAt
 }
 function afterRetreatResolve(world: World): ResolveLevel {
  return resolveMechanic(world).failure.afterRetreat
 }
 export interface EncounterResolution {
@@ -96,19 +122,20 @@ export function applyVerbToEncounter(
        }
      }
    }
-    if (t.requires && instrumentId && t.requires.item !== instrumentId) return false
+    if (t.requires && instrumentId && t.requires.item !== instrumentId && t.requires.item !== targetId) return false
    return true
  })
  if (!transition) {
    // Wrong verb — apply default narration and resolve cost.
    if (!verb || (targetId !== null && targetId !== encId)) return null  // verb is unrelated to this encounter
-    const newResolve = bumpResolve(state.resolveLevel, 1)
+    const wrongVerbCost = resolveMechanic(world).wrongVerbCost
-    if (state.resolveLevel === 'returning') {
+    const newResolve = bumpResolve(state.resolveLevel, wrongVerbCost, world)
    if (shouldRetreat(state.resolveLevel, wrongVerbCost, world)) {
      // Retreat.
      const retreat = def.onFailed
      if (retreat) {
-        const next: GameState = { ...state, location: retreat.retreatTo, resolveLevel: 'shaken' }
+        const next: GameState = { ...state, location: retreat.retreatTo, resolveLevel: afterRetreatResolve(world) }
        const dest = world.rooms[retreat.retreatTo]
        const lines: TranscriptLine[] = [
          { kind: 'narration', text: retreat.narration },
@@ -125,10 +152,10 @@ export function applyVerbToEncounter(
  }
  // Right verb — but if it has a resolve cost and player is already at 'returning', retreat.
-  if (transition.resolveCost && transition.resolveCost > 0 && state.resolveLevel === 'returning') {
+  if (shouldRetreat(state.resolveLevel, transition.resolveCost, world)) {
    const retreat = def.onFailed
    if (retreat) {
-      const next: GameState = { ...state, location: retreat.retreatTo, resolveLevel: 'shaken' }
+      const next: GameState = { ...state, location: retreat.retreatTo, resolveLevel: afterRetreatResolve(world) }
      const dest = world.rooms[retreat.retreatTo]
      const lines: TranscriptLine[] = [
        { kind: 'narration', text: transition.narration },
@@ -142,13 +169,14 @@ export function applyVerbToEncounter(
  // Right verb — narrate and transition.
  let next: GameState = { ...state }
  if (transition.resolveCost) {
-    next = { ...next, resolveLevel: bumpResolve(next.resolveLevel, transition.resolveCost) }
+    next = { ...next, resolveLevel: bumpResolve(next.resolveLevel, transition.resolveCost, world) }
  }
  if (transition.to === 'resolved') {
    const newEncState = { ...next.encounterState }
    delete newEncState[encId]
    let resolvedFlags = { ...next.flags, [`${encId}.resolved`]: true }
    if (transition.setFlags) resolvedFlags = { ...resolvedFlags, ...transition.setFlags }
    if (def.onResolved?.setFlags) resolvedFlags = { ...resolvedFlags, ...def.onResolved.setFlags }
    next = { ...next, encounterState: newEncState, flags: resolvedFlags }
  } else if (transition.to === 'failed') {
@@ -157,7 +185,7 @@ export function applyVerbToEncounter(
      const dest = world.rooms[retreat.retreatTo]
      const newEncState = { ...next.encounterState }
      delete newEncState[encId]
-      next = { ...next, location: retreat.retreatTo, encounterState: newEncState, resolveLevel: 'shaken' }
+      next = { ...next, location: retreat.retreatTo, encounterState: newEncState, resolveLevel: afterRetreatResolve(world) }
      const lines: TranscriptLine[] = [
        { kind: 'narration', text: transition.narration },
        { kind: 'narration', text: retreat.narration },
@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest'
 import { parse } from './parser'
-import type { ParserContext } from './parser'
+import type { ParserContext, ParserVocabulary } from './parser'
 const emptyCtx: ParserContext = {
  knownItems: [],
@@ -16,6 +16,10 @@ describe('parser — verb-only commands', () => {
    expect(parse('look', emptyCtx)).toEqual({ kind: 'verb-only', verb: 'look' })
  })
  it('recognizes bare "listen"', () => {
    expect(parse('listen', emptyCtx)).toEqual({ kind: 'verb-only', verb: 'listen' })
  })
  it('recognizes bare "inventory" and short forms', () => {
    expect(parse('inventory', emptyCtx)).toEqual({ kind: 'verb-only', verb: 'inventory' })
    expect(parse('inv', emptyCtx)).toEqual({ kind: 'verb-only', verb: 'inventory' })
@@ -32,6 +36,18 @@ describe('parser — verb-only commands', () => {
  })
 })
 describe('parser — confirmations', () => {
  it('recognizes yes and no confirmation replies', () => {
    expect(parse('yes', emptyCtx)).toEqual({ kind: 'confirmation', confirmed: true })
    expect(parse('y', emptyCtx)).toEqual({ kind: 'confirmation', confirmed: true })
    expect(parse('no', emptyCtx)).toEqual({ kind: 'confirmation', confirmed: false })
  })
  it('keeps n as the north direction shortcut', () => {
    expect(parse('n', emptyCtx)).toEqual({ kind: 'go', direction: 'n' })
  })
 })
 describe('parser — direction shortcuts', () => {
  it('maps single-letter directions', () => {
    expect(parse('n', emptyCtx)).toEqual({ kind: 'go', direction: 'n' })
@@ -76,6 +92,45 @@ describe('parser — unknown input', () => {
 })
 describe('parser — verb + target', () => {
  it('uses vocabulary supplied by world markdown', () => {
    const vocabulary: ParserVocabulary = {
      directions: {
        n: ['n', 'northward'],
        s: ['s'],
        e: ['e'],
        w: ['w'],
        u: ['u'],
        d: ['d'],
      },
      prepositions: ['beside'],
      stopWords: ['the'],
      noTargetVerbs: ['look'],
      metaVerbs: ['restart'],
      verbs: {
        go: ['go'],
        look: ['look', 'observe'],
        take: ['take hold of'],
      },
    }
    const ctx: ParserContext = {
      knownItems: ['lamp'],
      knownEncounters: [],
      visibleNouns: [{ id: 'lamp', aliases: ['lamp'] }],
      inventoryItemIds: [],
      lastNoun: null,
      awaitingDisambiguation: null,
      vocabulary,
    }
    expect(parse('observe', ctx)).toEqual({ kind: 'verb-only', verb: 'look' })
    expect(parse('northward', ctx)).toEqual({ kind: 'go', direction: 'n' })
    expect(parse('go northward', ctx)).toEqual({ kind: 'go', direction: 'n' })
    expect(parse('take hold of the lamp', ctx)).toEqual({
      kind: 'verb-target',
      verb: 'take',
      target: { canonical: 'lamp', raw: 'lamp' },
    })
  })
  it('recognizes slice-two encounter verbs', () => {
    const ctx: ParserContext = {
      knownItems: [],
@@ -100,6 +155,24 @@ describe('parser — verb + target', () => {
    })
  })
  it('recognizes pour commands with an indirect target', () => {
    const ctx: ParserContext = {
      knownItems: ['silver-vial'],
      knownEncounters: ['basilisk'],
      visibleNouns: [{ id: 'basilisk', aliases: ['basilisk'] }],
      inventoryItemIds: ['silver-vial'],
      lastNoun: null,
      awaitingDisambiguation: null,
    }
    expect(parse('pour silver-vial on basilisk', ctx)).toEqual({
      kind: 'verb-target-prep',
      verb: 'pour',
      target: { canonical: 'silver-vial', raw: 'silver-vial' },
      preposition: 'on',
      indirect: { canonical: 'basilisk', raw: 'basilisk' },
    })
  })
  it('resolves a single visible noun', () => {
    const ctx: ParserContext = {
      knownItems: ['torch'],
@@ -328,7 +401,7 @@ describe('verb-target-prep with "with"', () => {
    knownEncounters: [],
    visibleNouns: [
      { id: 'lamp', aliases: ['lamp'] },
-      { id: 'matches', aliases: ['matches', 'matchbook'] },
+      { id: 'matches', aliases: ['matches', 'match', 'matchbook'] },
    ],
    inventoryItemIds: ['matches'],
    lastNoun: null,
@@ -346,6 +419,17 @@ describe('verb-target-prep with "with"', () => {
    })
  })
  it('parses singular "match" aliases', () => {
    const cmd = parse('use match with lamp', ctx)
    expect(cmd).toEqual({
      kind: 'verb-target-prep',
      verb: 'use',
      target: { canonical: 'matches', raw: 'match' },
      preposition: 'with',
      indirect: { canonical: 'lamp', raw: 'lamp' },
    })
  })
  it('parses "use shears on vines" into verb-target-prep', () => {
    const localCtx: ParserContext = {
      knownItems: ['shears', 'ivy-figure'],
@@ -1,5 +1,14 @@
 import type { ParsedCommand, NounRef, Verb, MetaVerb, Direction, PendingDisambiguation } from './types'
 export interface ParserVocabulary {
  directions: Record<Direction, string[]>
  prepositions: string[]
  stopWords: string[]
  noTargetVerbs: Verb[]
  metaVerbs: MetaVerb[]
  verbs: Partial<Record<Verb, string[]>>
 }
 export interface ParserContext {
  /** All item ids that exist in the world (for noun matching). */
  knownItems: string[]
@@ -11,61 +20,115 @@ export interface ParserContext {
  inventoryItemIds: string[]
  lastNoun: NounRef | null
  awaitingDisambiguation: PendingDisambiguation | null
  vocabulary?: ParserVocabulary
 }
-/** Verb synonym table: each entry maps an alias to the canonical Verb. */
+export const SUPPORTED_VERBS: Verb[] = [
-const VERB_SYNONYMS: Record<string, Verb> = {
+  'go',
-  // movement
+  'look',
-  go: 'go', walk: 'go', move: 'go',
+  'examine',
-  // perception
+  'take',
-  look: 'look', l: 'look',
+  'drop',
-  examine: 'examine', x: 'examine', inspect: 'examine',
+  'use',
-  // inventory
+  'open',
-  inventory: 'inventory', inv: 'inventory', i: 'inventory',
+  'close',
-  // manipulation
+  'read',
-  take: 'take', get: 'take', grab: 'take', 'pick up': 'take',
+  'light',
-  drop: 'drop', put: 'drop', leave: 'drop',
+  'extinguish',
-  use: 'use', combine: 'use',
+  'attack',
-  open: 'open', close: 'close',
+  'inventory',
-  read: 'read', light: 'light', extinguish: 'extinguish', douse: 'extinguish',
+  'wait',
-  attack: 'attack', kill: 'attack', fight: 'attack', strike: 'attack',
+  'hold',
-  hold: 'hold', show: 'hold',
+  'push',
-  push: 'push', press: 'push',
+  'pull',
-  pull: 'pull',
+  'cut',
-  cut: 'cut', trim: 'cut',
+  'play',
-  play: 'play',
+  'listen',
-  uncover: 'open',
+  'pour',
-  wait: 'wait', z: 'wait',
+  'drink',
 ]
 export const SUPPORTED_META_VERBS: MetaVerb[] = ['restart', 'undo', 'hint', 'save', 'quit', 'theme']
 export const DEFAULT_PARSER_VOCABULARY: ParserVocabulary = {
  directions: {
    n: ['n', 'north'],
    s: ['s', 'south'],
    e: ['e', 'east'],
    w: ['w', 'west'],
    u: ['u', 'up'],
    d: ['d', 'down'],
  },
  prepositions: ['with', 'on', 'in', 'to'],
  stopWords: ['at', 'the', 'a', 'an'],
  noTargetVerbs: ['look', 'inventory', 'wait', 'listen'],
  metaVerbs: ['restart', 'undo', 'hint', 'save', 'quit', 'theme'],
  verbs: {
    go: ['go', 'walk', 'move'],
    look: ['look', 'l'],
    examine: ['examine', 'x', 'inspect'],
    inventory: ['inventory', 'inv', 'i'],
    take: ['take', 'get', 'grab', 'pick up'],
    drop: ['drop', 'put', 'leave'],
    use: ['use', 'combine'],
    open: ['open', 'uncover'],
    close: ['close'],
    drink: ['drink', 'sip'],
    read: ['read'],
    light: ['light'],
    extinguish: ['extinguish', 'douse'],
    attack: ['attack', 'kill', 'fight', 'strike'],
    hold: ['hold', 'show'],
    push: ['push', 'press'],
    pull: ['pull'],
    cut: ['cut', 'trim'],
    play: ['play'],
    listen: ['listen'],
    pour: ['pour'],
    wait: ['wait', 'z'],
  },
 }
-const DIRECTION_WORDS: Record<string, Direction> = {
+interface CompiledVocabulary {
-  n: 'n', north: 'n',
+  directionWords: Record<string, Direction>
-  s: 's', south: 's',
+  metaVerbs: Record<string, MetaVerb>
-  e: 'e', east: 'e',
+  verbSynonyms: Record<string, Verb>
-  w: 'w', west: 'w',
+  multiWordVerbs: string[]
-  u: 'u', up: 'u',
+  noTargetVerbs: Set<string>
-  d: 'd', down: 'd',
+  stopWords: Set<string>
  prepositions: Set<string>
 }
-const META_VERBS: Record<string, MetaVerb> = {
+function normalizeAlias(value: string): string {
-  restart: 'restart',
+  return value.trim().toLowerCase().replace(/\s+/g, ' ')
  undo: 'undo',
  hint: 'hint',
  save: 'save',
  quit: 'quit',
  theme: 'theme',
 }
-/** Verbs that legally take no target. */
+function compileVocabulary(vocabulary: ParserVocabulary): CompiledVocabulary {
-const VERB_ONLY_VERBS = new Set<string>(['look', 'inventory', 'wait'])
+  const directionWords: Record<string, Direction> = {}
  for (const [direction, aliases] of Object.entries(vocabulary.directions) as [Direction, string[]][]) {
    for (const alias of aliases) directionWords[normalizeAlias(alias)] = direction
  }
-/** Two-word verb prefixes (e.g. "pick up X"). */
+  const metaVerbs: Record<string, MetaVerb> = {}
-const TWO_WORD_VERBS = ['pick up']
+  for (const verb of vocabulary.metaVerbs) metaVerbs[normalizeAlias(verb)] = verb
-/** Leading stop-words stripped from the noun phrase before matching. */
+  const verbSynonyms: Record<string, Verb> = {}
-const STOP_WORDS = new Set(['at', 'the', 'a', 'an'])
+  for (const [verb, aliases] of Object.entries(vocabulary.verbs) as [Verb, string[]][]) {
    for (const alias of aliases) verbSynonyms[normalizeAlias(alias)] = verb
  }
-const PREPOSITIONS = new Set(['with', 'on', 'in', 'to'])
+  return {
    directionWords,
    metaVerbs,
    verbSynonyms,
    multiWordVerbs: Object.keys(verbSynonyms)
      .filter((alias) => alias.includes(' '))
      .sort((a, b) => b.split(' ').length - a.split(' ').length),
    noTargetVerbs: new Set(vocabulary.noTargetVerbs),
    stopWords: new Set(vocabulary.stopWords.map(normalizeAlias)),
    prepositions: new Set(vocabulary.prepositions.map(normalizeAlias)),
  }
 }
 function resolveNoun(rawTokens: string[], ctx: ParserContext): { id: string; alias: string } | null {
  const phrase = rawTokens.join(' ')
@@ -87,39 +150,41 @@ function tokenize(input: string): string[] {
  return input.trim().toLowerCase().split(/\s+/).filter(Boolean)
 }
-function matchTwoWordVerb(tokens: string[]): { verb: Verb; rest: string[] } | null {
+function matchMultiWordVerb(tokens: string[], vocabulary: CompiledVocabulary): { verb: Verb; rest: string[] } | null {
-  if (tokens.length < 2) return null
+  for (const phrase of vocabulary.multiWordVerbs) {
-  const head = tokens.slice(0, 2).join(' ')
+    const phraseTokens = phrase.split(' ')
-  for (const phrase of TWO_WORD_VERBS) {
+    if (tokens.length >= phraseTokens.length && tokens.slice(0, phraseTokens.length).join(' ') === phrase) {
-    if (phrase === head) {
+      const verb = vocabulary.verbSynonyms[phrase]
-      const verb = VERB_SYNONYMS[phrase]
+      if (verb) return { verb, rest: tokens.slice(phraseTokens.length) }
      if (verb) return { verb, rest: tokens.slice(2) }
    }
  }
  return null
 }
 export function parse(rawInput: string, ctx: ParserContext): ParsedCommand {
  const vocabulary = compileVocabulary(ctx.vocabulary ?? DEFAULT_PARSER_VOCABULARY)
  const trimmed = rawInput.trim()
  if (!trimmed) return { kind: 'unknown', raw: '', reason: 'malformed' }
  const tokens = tokenize(trimmed)
  const head = tokens[0]!
  if (tokens.length === 1 && ['yes', 'y'].includes(head)) {
    return { kind: 'confirmation', confirmed: true }
  }
  if (tokens.length === 1 && head === 'no') {
    return { kind: 'confirmation', confirmed: false }
  }
  // Meta-commands take precedence (single-word).
-  if (META_VERBS[head] && tokens.length === 1) {
+  if (vocabulary.metaVerbs[head] && tokens.length === 1) {
-    return { kind: 'meta', verb: META_VERBS[head]! }
+    return { kind: 'meta', verb: vocabulary.metaVerbs[head]! }
  }
  // Direction shortcuts: "n", "north", "go n", "go north".
-  if (DIRECTION_WORDS[head] && tokens.length === 1) {
+  if (vocabulary.directionWords[head] && tokens.length === 1) {
-    return { kind: 'go', direction: DIRECTION_WORDS[head]! }
+    return { kind: 'go', direction: vocabulary.directionWords[head]! }
  }
  if (head === 'go' && tokens.length === 2) {
    const dir = DIRECTION_WORDS[tokens[1]!]
    if (dir) return { kind: 'go', direction: dir }
  }
  // Disambiguation reply: a single-word answer matching one of the candidates.
  // Must be checked before verb resolution so "brass" / "iron" etc. are caught.
  if (ctx.awaitingDisambiguation && tokens.length === 1) {
@@ -134,15 +199,15 @@ export function parse(rawInput: string, ctx: ParserContext): ParsedCommand {
    }
  }
-  // Two-word verb (e.g. "pick up X").
+  // Multi-word verb aliases (e.g. "pick up X").
-  const twoWord = matchTwoWordVerb(tokens)
+  const twoWord = matchMultiWordVerb(tokens, vocabulary)
  let verb: Verb | undefined
  let rest: string[]
  if (twoWord) {
    verb = twoWord.verb
    rest = twoWord.rest
  } else {
-    verb = VERB_SYNONYMS[head]
+    verb = vocabulary.verbSynonyms[head]
    rest = tokens.slice(1)
  }
@@ -150,26 +215,31 @@ export function parse(rawInput: string, ctx: ParserContext): ParsedCommand {
    return { kind: 'unknown', raw: trimmed, reason: 'unknown-verb' }
  }
  if (verb === 'go' && rest.length === 1) {
    const dir = vocabulary.directionWords[rest[0]!]
    if (dir) return { kind: 'go', direction: dir }
  }
  // Strip leading stop-words from the noun phrase (e.g. "at", "the", "a", "an").
-  while (rest.length > 0 && STOP_WORDS.has(rest[0]!)) {
+  while (rest.length > 0 && vocabulary.stopWords.has(rest[0]!)) {
    rest = rest.slice(1)
  }
  if (rest.length === 0) {
-    if (VERB_ONLY_VERBS.has(verb)) {
+    if (vocabulary.noTargetVerbs.has(verb)) {
-      return { kind: 'verb-only', verb: verb as 'look' | 'inventory' | 'wait' }
+      return { kind: 'verb-only', verb: verb as 'look' | 'inventory' | 'wait' | 'listen' }
    }
    return { kind: 'unknown', raw: trimmed, reason: 'malformed' }
  }
  // Detect a preposition splitting target | indirect.
-  const prepIdx = rest.findIndex((tok) => PREPOSITIONS.has(tok))
+  const prepIdx = rest.findIndex((tok) => vocabulary.prepositions.has(tok))
  if (prepIdx > 0 && prepIdx < rest.length - 1) {
    const targetTokens = rest.slice(0, prepIdx)
    const prep = rest[prepIdx]!
    let indirectTokens = rest.slice(prepIdx + 1)
    // Strip stop-words at the head of the indirect phrase too ("on the table").
-    while (indirectTokens.length > 0 && STOP_WORDS.has(indirectTokens[0]!)) {
+    while (indirectTokens.length > 0 && vocabulary.stopWords.has(indirectTokens[0]!)) {
      indirectTokens = indirectTokens.slice(1)
    }
    if (indirectTokens.length > 0) {
@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest'
 import { parse } from './parser'
 import type { ParserContext } from './parser'
-import { dispatch, initialStateFor } from './dispatcher'
+import { dispatch, getItemsInRoom, initialStateFor } from './dispatcher'
 import { world } from '../world'
 import type { GameState } from './types'
@@ -30,6 +30,7 @@ function ctxFor(state: GameState): ParserContext {
    inventoryItemIds: state.inventory.map((i) => i.id),
    lastNoun: state.lastNoun,
    awaitingDisambiguation: state.pendingDisambiguation,
    vocabulary: world.parser,
  }
 }
@@ -51,6 +52,7 @@ describe('playthrough — sample world', () => {
      'take lamp',
      'e',            // hallway → cellar-stair (triggers rat encounter)
      'attack rat',
      'yes',
    ])
    expect(state.flags['ratGone']).toBe(true)
    expect(state.location).toBe('cellar-stair')
@@ -107,4 +109,231 @@ describe('playthrough — sample world', () => {
      'damp-sheet',
    ]))
  })
  it('plays through the upper-floor slice', () => {
    const state = play([
      'n',                 // gate → foyer
      'n',                 // foyer → hallway
      'u',                 // hallway → parlor
      'u',                 // parlor → upper stair
      'wait',
      'u',                 // upper stair → bedroom
      'e',                 // bedroom → nursery
      'read drawing',
      'take dog',
      'w',
      'u',                 // bedroom → attic
    ])
    expect(state.flags['stair-sleeper.resolved']).toBe(true)
    expect(state.flags['hallwayShifted']).toBe(true)
    expect(state.location).toBe('attic')
    expect(state.inventory.map((i) => i.id)).toContain('toy-dog')
  })
  it('plays through the garden and grounds slice', () => {
    const state = play([
      'n',                 // gate → foyer
      'n',                 // foyer → hallway
      'u',                 // hallway → parlor
      'u',                 // parlor → upper stair
      'wait',
      'u',                 // upper stair → bedroom
      'e',                 // bedroom → nursery
      'take dog',
      'w',
      'd',                 // bedroom → upper stair
      'd',                 // upper stair → parlor
      'd',                 // parlor → hallway
      'n',                 // hallway → dining-room
      'close curtains',
      'e',                 // dining-room → kitchen
      'e',                 // kitchen → back-door
      'e',                 // back-door → garden
      'wait',
      'n',                 // garden → well
      'd',                 // well → well-shaft
      'hold dog',
    ])
    expect(state.flags['garden-procession.resolved']).toBe(true)
    expect(state.flags['child-beneath-well.resolved']).toBe(true)
    expect(state.flags['gardenQuiet']).toBe(true)
    expect(state.flags['childPassedWell']).toBe(true)
    expect(state.location).toBe('well-shaft')
  })
  it('plays through the lower-passages slice', () => {
    const state = play([
      'n',                 // gate → foyer
      'n',                 // foyer → hallway
      'n',                 // hallway → dining-room
      'close curtains',
      'n',                 // dining-room → conservatory
      'take shears',
      'cut vines with shears',
      's',                 // conservatory → dining-room
      'w',                 // dining-room → hallway
      'd',                 // hallway → music-room
      'play note',
      'n',                 // music-room → servants-passage
      'wait',
      'e',                 // servants-passage → laundry
      'wait',
      'take damp sheet',
      'w',                 // laundry → servants-passage
      's',                 // servants-passage → music-room
      'u',                 // music-room → hallway
      'n',                 // hallway → dining-room
      'e',                 // dining-room → kitchen
      'e',                 // kitchen → back-door
      'e',                 // back-door → garden
      'wait',
      'n',                 // garden → well
      'd',                 // well → well-shaft
      'wait',
      'd',                 // well-shaft → tunnel
      'n',                 // tunnel → ossuary
      'take ring',
      'leave ring',
      'e',                 // ossuary → flooded-passage
      'use water with sheet',
      'take boat',
      'n',                 // flooded-passage → root-chamber
      'listen',
      'e',                 // root-chamber → burial-gallery
      'examine portraits',
      'take register',
      'read register',
      'e',                 // burial-gallery → antechamber
      'e',                 // antechamber → vault
    ])
    expect(state.flags['bone-keeper.resolved']).toBe(true)
    expect(state.flags['reflection.resolved']).toBe(true)
    expect(state.flags['root-movement.resolved']).toBe(true)
    expect(state.flags['portrait-woman.resolved']).toBe(true)
    expect(state.flags['burialRingPlaced']).toBe(true)
    expect(state.flags['reflectionObscured']).toBe(true)
    expect(state.flags['rootsListenedTo']).toBe(true)
    expect(state.flags['familyResemblanceSeen']).toBe(true)
    expect(state.location).toBe('vault')
    expect(state.inventory.map((i) => i.id)).toEqual(expect.arrayContaining([
      'damp-sheet',
      'toy-boat',
      'family-register',
    ]))
  })
  it('plays through the conditional rain-room branch', () => {
    const state = play([
      'n',                 // gate → foyer
      'n',                 // foyer → hallway
      'u',                 // hallway → parlor
      'u',                 // parlor → upper stair
      'wait',
      'd',                 // upper stair → parlor
      's',                 // parlor → wrong hallway
      'wait',
      'n',                 // wrong hallway → rain room
      'look basin',
    ])
    expect(state.flags['distant-steps.resolved']).toBe(true)
    expect(state.flags['rainwater-basin.resolved']).toBe(true)
    expect(state.flags['rainRoomEntered']).toBe(true)
    expect(state.endedWith).toBe('replacement')
  })
  it('reaches the expanded true ending through the vault choice', () => {
    const state = play([
      'n',                 // gate → foyer
      'n',                 // foyer → hallway
      'n',                 // hallway → dining-room
      'close curtains',
      'n',                 // dining-room → conservatory
      'take shears',
      'cut vines with shears',
      's',                 // conservatory → dining-room
      'w',                 // dining-room → hallway
      'd',                 // hallway → music-room
      'play note',
      'n',                 // music-room → servants-passage
      'wait',
      'e',                 // servants-passage → laundry
      'wait',
      'take damp sheet',
      'w',                 // laundry → servants-passage
      's',                 // servants-passage → music-room
      'u',                 // music-room → hallway
      'n',                 // hallway → dining-room
      'e',                 // dining-room → kitchen
      'e',                 // kitchen → back-door
      'e',                 // back-door → garden
      'wait',
      'n',                 // garden → well
      'd',                 // well → well-shaft
      'wait',
      'd',                 // well-shaft → tunnel
      'n',                 // tunnel → ossuary
      'take ring',
      'leave ring',
      'e',                 // ossuary → flooded-passage
      'use water with sheet',
      'n',                 // flooded-passage → root-chamber
      'listen',
      'e',                 // root-chamber → burial-gallery
      'examine portraits',
      'take register',
      'e',                 // burial-gallery → antechamber
      'e',                 // antechamber → vault
      'n',                 // vault → chapel
      'take vial',
      'pour vial on basilisk',
      's',                 // chapel → vault
      'read register',
    ])
    expect(state.flags['basiliskSpared']).toBe(true)
    expect(state.flags['nameSpoken']).toBe(true)
    expect(state.endedWith).toBe('true')
  })
  it('passes out after wandering the drunk rooms too long', () => {
    const state = play([
      'n',                 // gate → foyer
      'n',                 // foyer → hallway
      'n',                 // hallway → dining-room
      'e',                 // dining-room → kitchen
      'take whiskey',
      'drink whiskey',
      'e', 'w', 'e', 'w', 'e',
      'w', 'e', 'w', 'e', 'w',
      'e', 'w', 'e', 'w', 'e',
      'w', 'e', 'w', 'e', 'w',
    ])
    expect(state.location).toBe('foyer')
    expect(state.flags['drunk']).toBe(false)
    expect(state.flags['drunkMoves']).toBe(0)
    expect(getItemsInRoom(state, world, 'kitchen')).toContain('whiskey')
  })
  it('finds the faceless man in the drunk rooms and wakes in the foyer', () => {
    const state = play([
      'n',                 // gate → foyer
      'n',                 // foyer → hallway
      'n',                 // hallway → dining-room
      'e',                 // dining-room → kitchen
      'take whiskey',
      'drink whiskey',
      'u',                 // drunk hall → drunk landing
      'listen',
    ])
    expect(state.location).toBe('foyer')
    expect(state.flags['facelessManMet']).toBe(true)
    expect(state.flags['houseDebtNamed']).toBe(true)
    expect(state.flags['drunk']).toBe(false)
  })
 })
@@ -13,6 +13,7 @@ const baseState = (overrides: Partial<GameState> = {}): GameState => ({
  encounterState: {},
  lastNoun: null,
  pendingDisambiguation: null,
  pendingConfirmation: null,
  transcript: [],
  endedWith: null,
  ...overrides,
@@ -9,7 +9,7 @@ export type Direction = 'n' | 's' | 'e' | 'w' | 'u' | 'd'
 export type Verb =
  | 'go' | 'look' | 'examine' | 'take' | 'drop' | 'use' | 'open' | 'close'
  | 'read' | 'light' | 'extinguish' | 'attack' | 'inventory' | 'wait'
-  | 'hold' | 'push' | 'pull' | 'cut' | 'play'
+  | 'hold' | 'push' | 'pull' | 'cut' | 'play' | 'listen' | 'pour' | 'drink'
 export type MetaVerb = 'restart' | 'undo' | 'hint' | 'save' | 'quit' | 'theme'
@@ -21,7 +21,8 @@ export interface NounRef {
 }
 export type ParsedCommand =
-  | { kind: 'verb-only'; verb: Verb | 'look' | 'inventory' | 'wait' }
+  | { kind: 'confirmation'; confirmed: boolean }
  | { kind: 'verb-only'; verb: Verb | 'look' | 'inventory' | 'wait' | 'listen' }
  | { kind: 'verb-target'; verb: Verb; target: NounRef }
  | { kind: 'verb-target-prep'; verb: Verb; target: NounRef; preposition: string; indirect: NounRef }
  | { kind: 'ambiguous'; verb: Verb; rawNoun: string; candidates: string[] }
@@ -39,6 +40,7 @@ export interface ItemInstance {
 }
 export type EncounterPhase = string  // phase names are encounter-specific
 export type EndingId = string
 export interface TranscriptLine {
  kind: 'narration' | 'player' | 'system' | 'ending'
@@ -51,8 +53,14 @@ export interface PendingDisambiguation {
  prompt: string
 }
 export interface PendingConfirmation {
  command: ParsedCommand
  prompt: string
 }
 export interface GameState {
  schemaVersion: number
  transcriptCap?: number
  location: RoomId
  inventory: ItemInstance[]
  /** Per-room state: visited, items dropped, descriptive flags. */
@@ -66,10 +74,12 @@ export interface GameState {
  lastNoun: NounRef | null
  /** Pending multi-word disambiguation, set when the parser cannot decide. */
  pendingDisambiguation: PendingDisambiguation | null
  /** Pending confirmation for dangerous/game-changing commands. */
  pendingConfirmation: PendingConfirmation | null
  /** Capped at 200 entries; older entries are dropped on append. */
  transcript: TranscriptLine[]
  /** Set true when the player has reached an ending. UI shows ending screen. */
-  endedWith: 'true' | 'wrong' | 'bad' | null
+  endedWith: EndingId | null
 }
 export interface DispatchResult {
@@ -1,23 +1,33 @@
 ---
 import '../ui/crt.css'
-import gearIcon from '../assets/noun-gear-8323296.svg?url'
+import { world } from '../world'
 const buildNumber = process.env.CI_PIPELINE_NUMBER ?? 'local'
 const ui = world.ui
 const footerLinks = ui?.footer.links ?? []
 const firstFooterLink = footerLinks[0]
 const remainingFooterLinks = footerLinks.slice(1)
 const bugReport = ui?.bugReport
 const bugpinConfig = bugReport?.enabled ? bugReport.bugpin : undefined
 const bugsinkDsn =
  bugReport?.enabled && bugReport.bugsink?.enabled ? bugReport.bugsink.dsn : ''
 ---
 <html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
-    <title>Halfstreet — Ethan J Lewis</title>
+    <title>{ui?.pageTitle ?? `${world.game?.title ?? 'Halfstreet'} - Ethan J Lewis`}</title>
-    <meta name="description" content="A gothic mystery." />
+    <meta name="description" content={ui?.description ?? world.game?.description ?? 'A gothic mystery.'} />
-    <meta name="robots" content="noindex" />
+    <meta name="robots" content={ui?.robots ?? 'noindex'} />
    <link rel="icon" href="/favicon.ico" sizes="any" />
    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
    <link rel="icon" href="/favicon-96x96.png" type="image/png" sizes="96x96" />
    <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
    <link rel="manifest" href="/site.webmanifest" />
-    <meta name="theme-color" content="#1a0d00" />
+    <meta name="theme-color" content={ui?.themeColor ?? '#1a0d00'} />
  </head>
-  <body>
+  <body data-bugsink-dsn={bugsinkDsn}>
    <div class="mystery-root" data-mystery-root>
      <div class="mystery-bezel">
        <div class="mystery-options" data-mystery-options>
@@ -27,9 +37,15 @@ import gearIcon from '../assets/noun-gear-8323296.svg?url'
            data-options-toggle
            aria-label="Options"
            aria-expanded="false"
            style={`--gear-icon: url(${gearIcon})`}
          >
-            <span class="mystery-options-icon" aria-hidden="true"></span>
+            <svg
              class="mystery-options-icon"
              aria-hidden="true"
              viewBox="0 0 1200 1200"
              focusable="false"
            >
              <path d="m541.45 262.22-14.297 48.703c-2.8125 8.8125-9.7031 15.703-18.469 18.609-5.8594 2.1562-12.703 4.6875-20.766 8.1562-8.3906 4.0781-18.234 4.0781-26.625 0l-46.078-25.688c-9.2812-4.9688-20.578-4.3125-29.156 1.7812-25.969 19.266-49.266 41.859-69.281 67.219-6.4219 8.4375-7.125 19.969-1.7812 29.156l25.781 44.156c4.5469 7.875 4.875 17.531 0.84375 25.688-3.6094 7.0781-6.4688 13.781-9.1406 20.531h0.046875c-3.2344 8.4844-10.312 14.953-19.078 17.391l-50.766 13.781c-10.219 2.625-17.906 11.062-19.453 21.516-4.4531 31.406-4.4531 63.328 0 94.781 1.3594 10.641 9.2344 19.266 19.688 21.609l50.297 13.781c8.9062 2.3906 16.125 8.9062 19.406 17.531 2.5312 6.6094 5.3906 13.219 8.7656 20.297 3.8438 7.9219 3.6094 17.25-0.70312 24.938l-25.781 44.625h-0.046875c-5.4375 9.1406-4.6406 20.719 1.9219 29.062 20.062 25.172 43.359 47.625 69.281 66.703 8.5312 6.3281 20.016 6.9844 29.25 1.6875l45.609-24.844c8.3906-4.2656 18.281-4.5 26.859-0.70312 7.0781 3.2344 13.781 5.8594 20.859 8.3906h0.046875c8.6719 2.9062 15.516 9.75 18.375 18.469l14.156 48.703v0.046875c2.5312 10.406 11.297 18.141 21.938 19.406 12.234 1.5 24.516 2.25 36.844 2.2969 12.047-0.28125 24.047-1.2188 36-2.8594 10.594-1.1719 19.406-8.7656 22.078-19.078l14.297-48.938v-0.046875c2.7188-8.6719 9.375-15.516 18-18.469 7.4531-2.625 14.156-5.2969 21-8.3906 8.625-3.9375 18.562-3.7031 27 0.5625l46.078 25.219c9.1406 5.3906 20.625 4.875 29.25-1.3125 26.016-19.266 49.359-41.812 69.516-67.078 6.4688-8.3906 7.1719-19.922 1.7812-29.062l-25.781-45c-4.3125-7.6406-4.5938-16.922-0.75-24.844 3.375-7.2188 6.2344-13.781 8.625-20.156h0.046875c3.2344-8.6719 10.453-15.281 19.406-17.766l50.062-13.688v0.046875c10.406-2.1562 18.375-10.594 19.922-21.141 4.4062-31.547 4.4062-63.516 0-95.062-1.5938-10.453-9.2812-18.984-19.594-21.562l-50.766-13.781 0.046875-0.046875c-8.7656-2.4375-15.891-8.8594-19.078-17.391-2.625-6.7031-5.5312-13.453-9-20.297-3.8906-8.0156-3.6094-17.391 0.70312-25.172l25.781-44.297c5.4375-9.1406 4.6875-20.625-1.7812-29.016-20.016-25.453-43.359-48.047-69.375-67.312-8.4375-6.0469-19.547-6.8438-28.781-2.0625l-45.844 25.078c-8.4844 4.0781-18.375 4.0781-26.906 0-7.9219-3.4688-14.766-6-20.625-8.1562-8.7188-2.8594-15.562-9.6562-18.469-18.375l-14.156-48.609c-2.625-10.359-11.344-18.047-21.984-19.312-12.188-1.4531-24.422-2.3438-36.703-2.625-12 0-24 1.5469-36 3.1406-10.781 1.0312-19.734 8.625-22.547 19.078zm58.547 175.18c65.766 0 125.06 39.609 150.24 100.41 25.172 60.75 11.25 130.69-35.25 177.19s-116.44 60.422-177.19 35.25c-60.797-25.172-100.41-84.469-100.41-150.24 0.09375-89.766 72.844-162.52 162.61-162.61z" />
            </svg>
          </button>
          <div class="mystery-options-menu" data-options-menu hidden>
            <div class="mystery-options-group" aria-label="Screen">
@@ -45,12 +61,21 @@ import gearIcon from '../assets/noun-gear-8323296.svg?url'
            </div>
            <div class="mystery-options-group" aria-label="Game">
              <div class="mystery-options-label">Game</div>
              {ui?.features.chips !== false && (
                <>
                  <button type="button" data-chips-choice="on" aria-pressed="true">Chips On</button>
                  <button type="button" data-chips-choice="off" aria-pressed="false">Chips Off</button>
                </>
              )}
              <button type="button" data-restart-choice>Restart</button>
            </div>
          </div>
        </div>
        <div class="mystery-transcript" data-mystery-transcript aria-live="polite" aria-atomic="false"></div>
-        <div class="mystery-chips" data-mystery-chips></div>
+        <div class="mystery-controls">
          {ui?.features.chips !== false && <div class="mystery-chips" data-mystery-chips></div>}
          {ui?.features.lightMeter !== false && <div class="mystery-light-meter" data-mystery-light-meter aria-hidden="true"></div>}
        </div>
        <div class="mystery-input-row">
          <input
            class="mystery-input"
@@ -66,11 +91,39 @@ import gearIcon from '../assets/noun-gear-8323296.svg?url'
        </div>
      </div>
      <footer class="mystery-footer">
-        © 2026 <a href="https://ethanjlewis.com">Ethan J Lewis</a>
+        {ui?.footer.copyrightHref ? <a href={ui.footer.copyrightHref}>{ui.footer.copyright}</a> : <span>{ui?.footer.copyright ?? '© 2026 Ethan J Lewis'}</span>}
-        <span aria-hidden="true">|</span>
+        {firstFooterLink && (
-        <a href="https://half.st/ejlewis/halfstreet/src/branch/main/LICENSE">GNU 3.0</a>
+          <>
-        <span aria-hidden="true">|</span>
+            <span aria-hidden="true">|</span>
-        <a href="https://half.st/ejlewis/halfstreet">Source Code</a>
+            <a href={firstFooterLink.href}>{firstFooterLink.label}</a>
          </>
        )}
        {ui?.footer.showBuild !== false && (
          <>
            <span aria-hidden="true">|</span>
            <span>{ui?.footer.buildLabel ?? 'Build #'}{buildNumber}</span>
          </>
        )}
        {remainingFooterLinks.map((link) => (
          <>
            <span aria-hidden="true">|</span>
            <a href={link.href}>{link.label}</a>
          </>
        ))}
        {bugpinConfig && (
          <>
            <span aria-hidden="true">|</span>
            <button
              type="button"
              class="mystery-footer-bug-report"
              data-bug-report-trigger
              data-bugpin-server={bugpinConfig.serverUrl}
              data-bugpin-key={bugpinConfig.apiKey}
              aria-describedby="bug-report-status"
            >{bugReport?.label ?? 'Report a Bug'}</button>
            <span id="bug-report-status" class="mystery-footer-status" aria-live="polite"></span>
          </>
        )}
      </footer>
    </div>
    <script>
@@ -82,15 +135,21 @@ import gearIcon from '../assets/noun-gear-8323296.svg?url'
      const storedCursor = (() => {
        try { return localStorage.getItem('halfstreet:cursor:v1') } catch { return null }
      })()
      const storedChips = (() => {
        try { return localStorage.getItem('halfstreet:chips:v1') } catch { return null }
      })()
      document.documentElement.setAttribute('data-mystery-theme', stored === 'ansi' ? 'ansi' : 'amber')
      document.documentElement.setAttribute(
        'data-mystery-cursor',
        storedCursor === 'block' || storedCursor === 'underscore' ? storedCursor : 'bar',
      )
      document.documentElement.setAttribute('data-mystery-chips-state', storedChips === 'off' ? 'off' : 'on')
    </script>
    <script>
      import '../ui/terminal.ts'
      import '../ui/theme.ts'
      import '../ui/error-tracking.ts'
      import '../ui/bug-report.ts'
    </script>
  </body>
 </html>
@@ -0,0 +1,126 @@
 interface BugPinAPI {
  init: (config: { apiKey: string, serverUrl: string }) => Promise<void> | void
  open: () => void
  close: () => void
 }
 declare global {
  interface Window {
    BugPin?: BugPinAPI
  }
 }
 const launcherSelector = [
  '.fixed.bottom-5.right-5',
  '.fixed.bottom-5.left-5',
  '.fixed.top-5.right-5',
  '.fixed.top-5.left-5',
 ].join(',')
 const button = document.querySelector<HTMLButtonElement>('[data-bug-report-trigger]')
 let loadPromise: Promise<void> | null = null
 let initialized = false
 let launcherObserver: MutationObserver | null = null
 function setStatus(message: string): void {
  const targetId = button?.getAttribute('aria-describedby')
  const target = targetId ? document.getElementById(targetId) : null
  if (target) target.textContent = message
 }
 function buildWidgetSrc(serverUrl: string): string {
  return `${serverUrl.replace(/\/$/, '')}/widget.js`
 }
 function loadWidget(serverUrl: string): Promise<void> {
  if (window.BugPin) return Promise.resolve()
  if (loadPromise) return loadPromise
  loadPromise = new Promise<void>((resolve, reject) => {
    const script = document.createElement('script')
    script.src = buildWidgetSrc(serverUrl)
    script.async = true
    script.addEventListener('load', () => resolve())
    script.addEventListener('error', () => {
      loadPromise = null
      reject(new Error(`Failed to load BugPin widget from ${script.src}`))
    })
    document.head.appendChild(script)
  })
  return loadPromise
 }
 function hideBugPinLauncher(): void {
  const host = document.getElementById('bugpin-widget')
  const root = host?.shadowRoot
  if (!root) return
  for (const launcher of root.querySelectorAll<HTMLElement>(launcherSelector)) {
    launcher.hidden = true
    launcher.style.display = 'none'
    launcher.setAttribute('aria-hidden', 'true')
  }
 }
 function watchBugPinLauncher(): void {
  const host = document.getElementById('bugpin-widget')
  const root = host?.shadowRoot
  if (!root || launcherObserver) return
  hideBugPinLauncher()
  launcherObserver = new MutationObserver(() => hideBugPinLauncher())
  launcherObserver.observe(root, { childList: true, subtree: true })
 }
 function waitForBugPinEffects(): Promise<void> {
  return new Promise((resolve) => {
    requestAnimationFrame(() => setTimeout(resolve, 0))
  })
 }
 async function openBugReport(serverUrl: string, apiKey: string): Promise<void> {
  await loadWidget(serverUrl)
  if (!window.BugPin) {
    throw new Error('BugPin widget loaded, but window.BugPin is unavailable')
  }
  if (!initialized) {
    await window.BugPin.init({ apiKey, serverUrl })
    initialized = true
    watchBugPinLauncher()
    await waitForBugPinEffects()
  }
  hideBugPinLauncher()
  window.BugPin.open()
  hideBugPinLauncher()
 }
 if (button) {
  const serverUrl = button.dataset.bugpinServer
  const apiKey = button.dataset.bugpinKey
  if (serverUrl && apiKey) {
    button.addEventListener('click', async (event) => {
      event.preventDefault()
      setStatus('')
      button.disabled = true
      try {
        await openBugReport(serverUrl, apiKey)
      } catch (err) {
        console.error('[bug-report]', err)
        setStatus("Couldn't open bug reporter - try refreshing.")
      } finally {
        button.disabled = false
      }
    })
  }
 }
 if (window.BugPin) {
  requestAnimationFrame(() => watchBugPinLauncher())
 }
 export {}
@@ -1,6 +1,6 @@
 import type { Chip } from './chips'
-const CHIP_CONTAINER = '[data-mystery-chips]'
+const CHIP_CONTAINER = '.mystery-chips[data-mystery-chips]'
 export function renderChips(chips: Chip[], onSelect: (command: string) => void): void {
  const container = document.querySelector<HTMLDivElement>(CHIP_CONTAINER)
@@ -39,12 +39,28 @@ describe('computeChips — sample world', () => {
    expect(chips.find((c) => c.kind === 'encounter' && c.label === 'ATTACK RAT' && c.command === 'attack rat')).toBeTruthy()
  })
-  it('always includes LOOK, INV, USE, and HELP', () => {
+  it('always includes LOOK, INV, USE, WAIT, and HELP', () => {
    const s = initialStateFor(world)
    const chips = computeChips(s, world)
    expect(chips.find((c) => c.command === 'look')).toBeTruthy()
    expect(chips.find((c) => c.command === 'inventory')).toBeTruthy()
    expect(chips.find((c) => c.label === 'USE' && c.command === 'use ')).toBeTruthy()
    expect(chips.find((c) => c.command === 'wait')).toBeTruthy()
    expect(chips.find((c) => c.command === 'help')).toBeTruthy()
  })
  it('shows only confirmation chips while a dangerous command is pending', () => {
    const s = {
      ...initialStateFor(world),
      pendingConfirmation: {
        command: { kind: 'verb-target' as const, verb: 'attack' as const, target: { canonical: 'rat', raw: 'rat' } },
        prompt: 'Are you sure?',
      },
    }
    const chips = computeChips(s, world)
    expect(chips).toEqual([
      { kind: 'meta', label: 'YES', command: 'yes', disabled: false },
      { kind: 'meta', label: 'NO', command: 'no', disabled: false },
    ])
  })
 })
@@ -20,6 +20,13 @@ export function computeChips(state: GameState, world: World): Chip[] {
  const room = world.rooms[state.location]
  if (!room) return out
  if (state.pendingConfirmation) {
    return [
      { kind: 'meta', label: 'YES', command: 'yes', disabled: false },
      { kind: 'meta', label: 'NO', command: 'no', disabled: false },
    ]
  }
  // Direction chips: enabled if exit exists, dimmed otherwise.
  const dirs: Direction[] = ['n', 's', 'e', 'w', 'u', 'd']
  for (const d of dirs) {
@@ -69,6 +76,7 @@ export function computeChips(state: GameState, world: World): Chip[] {
  out.push({ kind: 'meta', label: 'LOOK', command: 'look', disabled: false })
  out.push({ kind: 'meta', label: 'INV', command: 'inventory', disabled: false })
  out.push({ kind: 'meta', label: 'USE', command: 'use ', disabled: false })
  out.push({ kind: 'meta', label: 'WAIT', command: 'wait', disabled: false })
  out.push({ kind: 'meta', label: 'HELP', command: 'help', disabled: false })
  return out
@@ -89,11 +89,35 @@ body {
  text-align: center;
 }
-.mystery-footer a {
+.mystery-footer a,
 .mystery-footer-bug-report {
  color: var(--m-fg);
  text-decoration: none;
 }
 .mystery-footer-bug-report {
  background: none;
  border: none;
  padding: 0;
  margin: 0;
  font: inherit;
  cursor: pointer;
 }
 .mystery-footer-bug-report:hover,
 .mystery-footer-bug-report:focus-visible {
  text-decoration: underline;
 }
 .mystery-footer-bug-report:disabled {
  cursor: progress;
  opacity: 0.55;
 }
 .mystery-footer-status {
  color: var(--m-fg);
 }
 .mystery-footer span {
  margin: 0 0.5ch;
 }
@@ -115,6 +139,35 @@ body {
  z-index: 1;
 }
 .mystery-bezel::after {
  content: '';
  position: absolute;
  inset: 0;
  pointer-events: none;
  z-index: 2;
  opacity: 0;
 }
 :root[data-mystery-drunk] .mystery-bezel::after {
  background:
    linear-gradient(
      93deg,
      transparent 0 48%,
      color-mix(in srgb, var(--m-fg) 12%, transparent) 49% 50%,
      transparent 51% 100%
    ),
    repeating-linear-gradient(
      to bottom,
      transparent 0 9px,
      color-mix(in srgb, var(--m-fg) 8%, transparent) 9px 10px,
      transparent 10px 23px
    );
  mix-blend-mode: screen;
  opacity: 0.32;
  transform: translateX(0.32ch) skewX(-1.4deg);
  animation: mystery-drunk-screen 5.8s ease-in-out infinite;
 }
 .mystery-options {
  position: absolute;
  top: 8px;
@@ -137,10 +190,9 @@ body {
 .mystery-options-icon {
  width: 23px;
  height: 23px;
  background: currentColor;
  display: block;
-  mask: var(--gear-icon) center / contain no-repeat;
+  fill: currentColor;
-  -webkit-mask: var(--gear-icon) center / contain no-repeat;
+  flex: 0 0 auto;
 }
 .mystery-options-menu {
@@ -191,6 +243,10 @@ body {
  cursor: pointer;
 }
 .mystery-options .mystery-options-toggle {
  padding: 0;
 }
 .mystery-options button[aria-pressed='true'],
 .mystery-options-toggle[aria-expanded='true'] {
  color: var(--m-fg);
@@ -201,8 +257,9 @@ body {
  flex: 1;
  min-height: 0;
  overflow-y: auto;
  overflow-anchor: none;
  overscroll-behavior: contain;
-  scrollbar-color: var(--m-dim) transparent;
+  scrollbar-color: var(--m-dim) var(--m-bg);
  scrollbar-width: thin;
  white-space: pre-wrap;
  word-break: break-word;
@@ -217,11 +274,17 @@ body {
 }
 .mystery-transcript::-webkit-scrollbar-track {
-  background: transparent;
+  background: var(--m-bg);
  border: 0;
 }
 .mystery-transcript::-webkit-scrollbar-thumb {
  background: var(--m-dim);
  border: 0;
 }
 .mystery-transcript > div {
  max-width: 80ch;
 }
 .mystery-transcript .system {
@@ -230,6 +293,16 @@ body {
  margin-top: 0.6em;
 }
 .mystery-transcript .room-title {
  scroll-margin-top: 0;
 }
 .mystery-transcript .room-scroll-spacer {
  max-width: none;
  margin: 0;
  pointer-events: none;
 }
 .mystery-transcript .ascii-art {
  max-width: 100%;
  overflow-x: auto;
@@ -238,9 +311,11 @@ body {
  overflow-wrap: normal;
  font-size: clamp(9px, 2vw, 14px);
  line-height: 1.1;
  margin-bottom: 0.75em;
 }
 .mystery-transcript .help {
  position: relative;
  color: var(--m-fg);
  font-weight: normal;
  border: 1px var(--m-divider-style) var(--m-dim);
@@ -248,6 +323,34 @@ body {
  margin: 0.75em 0;
 }
 .mystery-transcript .help .mystery-help-body {
  padding-right: 3ch;
 }
 .mystery-transcript .help .mystery-help-close {
  position: absolute;
  top: 6px;
  right: 6px;
  width: 24px;
  height: 24px;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  background: transparent;
  color: var(--m-fg);
  border: 1px solid var(--m-dim);
  border-radius: 2px;
  font: inherit;
  line-height: 1;
  cursor: pointer;
 }
 .mystery-transcript .help .mystery-help-close:hover,
 .mystery-transcript .help .mystery-help-close:focus-visible {
  border-color: var(--m-fg);
  outline: none;
 }
 .mystery-transcript .player {
  color: var(--m-accent-2);
 }
@@ -258,6 +361,30 @@ body {
  margin: 0.25em 0;
 }
 :root[data-mystery-drunk] .mystery-transcript {
  filter: blur(0.35px) contrast(1.05);
  text-shadow:
    0.055em 0.02em currentColor,
    -0.075em -0.015em color-mix(in srgb, var(--m-fg) 50%, transparent),
    0.14em 0 color-mix(in srgb, var(--m-accent-2) 26%, transparent),
    0 0 4px currentColor;
  animation: mystery-drunk-copy 6.4s ease-in-out infinite;
 }
 :root[data-mystery-drunk] .mystery-transcript .player,
 :root[data-mystery-drunk] .mystery-transcript .system,
 :root[data-mystery-drunk] .mystery-transcript .narration {
  transform: translateX(0.12ch) skewX(-1.2deg);
 }
 :root[data-mystery-drunk] .mystery-transcript > div:nth-child(2n) {
  transform: translateX(-0.18ch) skewX(0.8deg);
 }
 :root[data-mystery-drunk] .mystery-transcript > div:nth-child(3n) {
  transform: translateX(0.28ch) skewX(-1.4deg);
 }
 .mystery-input-row {
  display: flex;
  align-items: center;
@@ -320,19 +447,142 @@ body {
  animation: mystery-cursor-blink 1.05s steps(1, end) infinite;
 }
 :root[data-mystery-drunk] .mystery-input-row {
  filter: blur(0.2px);
  transform: translateX(0.2ch);
  text-shadow:
    0.12em 0 currentColor,
    -0.16em 0 color-mix(in srgb, var(--m-accent-2) 42%, transparent),
    0 0 5px currentColor;
 }
 :root[data-mystery-drunk] .mystery-input-row::before {
  content: '>>';
  letter-spacing: -0.4ch;
 }
 :root[data-mystery-drunk] .mystery-input-display::after {
  text-shadow:
    0.22em 0 currentColor,
    -0.18em 0 color-mix(in srgb, var(--m-fg) 50%, transparent);
 }
 :root[data-mystery-input-focused] .mystery-input-display::after {
  animation: mystery-cursor-blink 1.05s steps(1, end) infinite;
 }
@keyframes mystery-cursor-blink {
  0%, 49% { opacity: 1; }
  50%, 100% { opacity: 0; }
 }
@keyframes mystery-drunk-copy {
  0%, 18%, 100% {
    filter: blur(0.2px) contrast(1.03);
    transform: translate(0, 0) skewX(0);
  }
  36% {
    filter: blur(0.8px) contrast(1.08);
    transform: translate(0.12ch, -0.04em) skewX(-0.25deg);
  }
  58% {
    filter: blur(0.3px) contrast(1.04);
    transform: translate(-0.06ch, 0.02em) skewX(0.08deg);
  }
  76% {
    filter: blur(0.65px) contrast(1.07);
    transform: translate(-0.18ch, 0.05em) skewX(0.32deg);
  }
 }
@keyframes mystery-drunk-screen {
  0%, 100% { transform: translateX(0.32ch) skewX(-1.4deg); }
  45% { transform: translateX(-0.22ch) skewX(1.1deg); }
  72% { transform: translateX(0.5ch) skewX(-0.6deg); }
 }
 .mystery-controls {
  display: flex;
  align-items: flex-start;
  justify-content: space-between;
  gap: 14px;
  position: relative;
  z-index: 2;
  margin-top: 8px;
 }
 .mystery-chips {
  display: flex;
  flex-wrap: wrap;
  gap: 4px;
  padding: 6px 0 4px;
-  position: relative;
+  min-width: 0;
-  z-index: 2;
+  flex: 1 1 auto;
-  margin-top: 8px;
+}
 :root[data-mystery-chips-state='off'] .mystery-chips {
  display: none;
 }
 .mystery-light-meter {
  flex: 0 0 auto;
  width: 98px;
  min-height: 58px;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: flex-start;
  gap: 4px;
  color: var(--m-fg);
  opacity: 0.8;
 }
 .mystery-light-meter[data-lit='true'] {
  color: var(--m-fg);
  opacity: 1;
 }
 .mystery-light-icon {
  width: 30px;
  height: 30px;
  display: block;
  color: var(--m-dim);
  opacity: 0.85;
 }
 .mystery-light-icon svg {
  width: 100%;
  height: 100%;
  display: block;
  fill: currentColor;
 }
 .mystery-light-leds {
  width: 100%;
  display: flex;
  gap: 4px;
  justify-content: center;
 }
 .mystery-light-segment {
  width: 8px;
  height: 8px;
  border-radius: 999px;
  background: var(--m-dim);
  box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.15) inset;
  opacity: 0.45;
 }
 .mystery-light-segment[data-segment-state='lit'] {
  background: currentColor;
  opacity: 1;
  box-shadow: 0 0 7px currentColor;
 }
 .mystery-light-meter[data-lit='true'] .mystery-light-icon {
  color: var(--m-fg);
  opacity: 1;
  filter: drop-shadow(0 0 2px currentColor) drop-shadow(0 0 6px currentColor);
 }
 .mystery-chip {
@@ -351,6 +601,17 @@ body {
  cursor: not-allowed;
 }
 :root[data-mystery-drunk] .mystery-chip {
  transform: rotate(-0.6deg);
  text-shadow:
    0.1em 0 currentColor,
    -0.1em 0 color-mix(in srgb, var(--m-fg) 35%, transparent);
 }
 :root[data-mystery-drunk] .mystery-chip:nth-child(2n) {
  transform: translateY(1px) rotate(0.8deg);
 }
 .mystery-transcript .ending {
  margin-top: 2em;
  margin-bottom: 1em;
@@ -377,6 +638,19 @@ body {
  .mystery-chip {
    padding: 4px 7px;
  }
  .mystery-controls {
    gap: 10px;
  }
  .mystery-light-meter {
    width: 90px;
  }
  .mystery-light-icon {
    width: 27px;
    height: 27px;
  }
 }
 [data-mystery-input].ended {
@@ -0,0 +1,12 @@
 import * as Sentry from '@sentry/browser'
 const dsn = document.body?.dataset.bugsinkDsn ?? ''
 if (dsn) {
  Sentry.init({
    dsn,
    tracesSampleRate: 0,
    replaysSessionSampleRate: 0,
    replaysOnErrorSampleRate: 0,
  })
 }
@@ -1,35 +1,31 @@
 import { parse } from '../engine/parser'
 import type { ParserContext } from '../engine/parser'
-import { dispatch, initialStateFor, getItemsInRoom } from '../engine/dispatcher'
+import { dispatch, initialStateFor, getItemsInRoom, getLightStatus } from '../engine/dispatcher'
 import { saveState, loadState, clearSave } from '../engine/save'
 import { world } from '../world'
 import { DEFAULT_WORLD_MESSAGES, type WorldMessageKey } from '../world/types'
 import type { GameState, TranscriptLine } from '../engine/types'
 import { TRANSCRIPT_CAP } from '../engine/types'
 import { computeChips } from './chips'
 import { renderChips } from './chip-render'
 import LIGHT_ICON_SVG from '../assets/noun-candle-6409709.svg?raw'
 const transcriptEl = document.querySelector<HTMLDivElement>('[data-mystery-transcript]')
 const inputEl = document.querySelector<HTMLInputElement>('[data-mystery-input]')
 const inputDisplayEl = document.querySelector<HTMLSpanElement>('[data-mystery-input-display]')
 const lightMeterEl = document.querySelector<HTMLDivElement>('[data-mystery-light-meter]')
-const HELP_TEXT = `You arrive at the address, but you do not remember what has happened. The road behind you is gone...
+const HELP_TEXT = world.game?.helpText ?? `This is a text adventure. Type short commands to act.`
 const UI_FEATURES = world.ui?.features ?? {
  chips: true,
  lightMeter: true,
  typedEffect: true,
  roomScroll: true,
 }
-This is a text adventure. Type short commands to act in the house.
+function message(key: WorldMessageKey): string {
-
+  return world.messages?.[key] ?? DEFAULT_WORLD_MESSAGES[key]
-Common commands:
+}
 look                    describe the room again
 n, s, e, w, u, d        move by direction
 take lamp               pick something up
 examine letter          inspect something nearby or held
 read letter             read a readable object
 inventory               see what you carry
 light lamp with matches use one thing with another
 wait                    let the room continue
 undo                    step back once
 restart                 begin again
 theme                   change the terminal colors
 Most commands are verb first, then the thing: examine gate, take lamp, use key on door.`
 if (!transcriptEl || !inputEl || !inputDisplayEl) {
  console.error('[halfstreet] terminal mount points missing')
@@ -42,6 +38,51 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
  let historyIndex: number | null = null
  let historyDraft = ''
  let idleHintTimer: number | null = null
  let renderQueue: Promise<void> = Promise.resolve()
  let renderGeneration = 0
  let roomScrollSpacer: HTMLDivElement | null = null
  const TYPE_INTERVAL_MS = 8
  const TYPE_CHARS_PER_TICK = 3
  const ROOM_SCROLL_MS = 180
  const syncLightMeter = (): void => {
    if (!UI_FEATURES.lightMeter) return
    if (!lightMeterEl) return
    const status = getLightStatus(state, world)
    lightMeterEl.hidden = !status
    if (!status) {
      lightMeterEl.innerHTML = ''
      lightMeterEl.dataset['lit'] = 'false'
      lightMeterEl.dataset['turnsLeft'] = '0'
      return
    }
    lightMeterEl.innerHTML = ''
    lightMeterEl.dataset['lit'] = 'true'
    lightMeterEl.dataset['turnsLeft'] = String(status.turnsLeft)
    const icon = document.createElement('div')
    icon.className = 'mystery-light-icon'
    icon.setAttribute('aria-hidden', 'true')
    icon.innerHTML = LIGHT_ICON_SVG
    lightMeterEl.appendChild(icon)
    const leds = document.createElement('div')
    leds.className = 'mystery-light-leds'
    const turnsLeft = Math.max(0, Math.min(status.maxTurns, status.turnsLeft))
    for (let i = 0; i < status.maxTurns; i++) {
      const segment = document.createElement('span')
      segment.className = 'mystery-light-segment'
      const lit = i < turnsLeft
      segment.dataset['segmentState'] = lit ? 'lit' : 'dim'
      segment.style.backgroundColor = lit ? 'var(--m-fg)' : 'var(--m-dim)'
      segment.style.boxShadow = lit ? '0 0 7px var(--m-fg)' : '0 0 0 1px rgba(0, 0, 0, 0.15) inset'
      segment.style.opacity = lit ? '1' : '0.45'
      leds.appendChild(segment)
    }
    lightMeterEl.appendChild(leds)
  }
  if (!restored) {
    // Fresh state already includes the opening narration in its transcript.
@@ -52,6 +93,7 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
  }
  function refreshChips(): void {
    if (!UI_FEATURES.chips) return
    renderChips(computeChips(state, world), (command) => {
      clearIdleHint()
      inputEl!.value = command
@@ -73,12 +115,20 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
    inputEl!.classList.toggle('ended', state.endedWith !== null)
  }
  const syncDrunkEffect = (): void => {
    document.documentElement.toggleAttribute('data-mystery-drunk', state.flags['drunk'] === true)
  }
  const syncCommandLine = (): void => {
    const visibleText = inputEl.value || inputEl.placeholder
    inputDisplayEl.textContent = visibleText
    inputDisplayEl.dataset['placeholder'] = inputEl.value ? 'false' : inputEl.placeholder ? 'true' : 'false'
  }
  const syncInputFocus = (focused: boolean): void => {
    document.documentElement.toggleAttribute('data-mystery-input-focused', focused)
  }
  const buildParserContext = (s: GameState): ParserContext => {
    const room = world.rooms[s.location]
    const visibleNouns: { id: string; aliases: string[] }[] = []
@@ -106,21 +156,127 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
      inventoryItemIds: s.inventory.map((i) => i.id),
      lastNoun: s.lastNoun,
      awaitingDisambiguation: s.pendingDisambiguation,
      vocabulary: world.parser,
    }
  }
-  const renderAll = (lines: TranscriptLine[]): void => {
+  const wait = (ms: number): Promise<void> =>
    new Promise((resolve) => {
      window.setTimeout(resolve, ms)
    })
  const isAsciiArtLine = (line: TranscriptLine): boolean =>
    line.kind === 'system' && line.text.includes('|_| |_|')
  const isRoomTitleLine = (line: TranscriptLine): boolean => {
    if (line.kind !== 'system') return false
    const trimmed = line.text.trim()
    return /^\[\s*.+\s*\]$/.test(trimmed) && !trimmed.includes('|')
  }
  const typeLine = async (el: HTMLDivElement, text: string): Promise<void> => {
    el.textContent = ''
    for (let i = TYPE_CHARS_PER_TICK; i < text.length; i += TYPE_CHARS_PER_TICK) {
      el.textContent = text.slice(0, i)
      await wait(TYPE_INTERVAL_MS)
    }
    el.textContent = text
  }
  const scrollToTopOf = async (el: HTMLElement): Promise<void> => {
    if (!transcriptEl) return
    transcriptEl.scrollTo({ top: Math.max(0, el.offsetTop), behavior: 'smooth' })
    await wait(ROOM_SCROLL_MS)
  }
  const updateRoomScrollSpacer = (anchor?: HTMLElement): void => {
    if (!transcriptEl) return
    if (!roomScrollSpacer) {
      roomScrollSpacer = document.createElement('div')
      roomScrollSpacer.className = 'room-scroll-spacer'
      roomScrollSpacer.setAttribute('aria-hidden', 'true')
    }
    const spacerHeight = Math.max(0, transcriptEl.clientHeight - (anchor?.offsetHeight ?? 0))
    roomScrollSpacer.style.height = `${spacerHeight}px`
    if (roomScrollSpacer.parentElement !== transcriptEl) {
      transcriptEl.appendChild(roomScrollSpacer)
    }
  }
  const scrollToContentBottom = (): void => {
    if (!transcriptEl) return
    updateRoomScrollSpacer()
    const contentBottom = roomScrollSpacer?.offsetTop ?? transcriptEl.scrollHeight
    transcriptEl.scrollTop = Math.max(0, contentBottom - transcriptEl.clientHeight)
  }
  const appendTranscriptElement = (el: HTMLDivElement): void => {
    if (!transcriptEl) return
    updateRoomScrollSpacer()
    if (roomScrollSpacer?.parentElement === transcriptEl) {
      transcriptEl.insertBefore(el, roomScrollSpacer)
      return
    }
    transcriptEl.appendChild(el)
  }
  const renderLines = async (
    lines: TranscriptLine[],
    animate: boolean,
    shouldScroll: boolean,
    generation: number,
  ): Promise<void> => {
    if (!transcriptEl) return
    const roomTitleInBatch = shouldScroll && animate && lines.some(isRoomTitleLine)
    let roomTitleEl: HTMLDivElement | null = null
    for (const line of lines) {
      if (generation !== renderGeneration) return
      const el = document.createElement('div')
      el.className = line.kind
-      if (line.kind === 'system' && line.text.includes('|_| |_|')) {
+      const asciiArt = isAsciiArtLine(line)
      const roomTitle = roomTitleInBatch && isRoomTitleLine(line)
      if (asciiArt) {
        el.classList.add('ascii-art')
      }
-      el.textContent = line.text
+      if (isRoomTitleLine(line)) {
-      transcriptEl.appendChild(el)
+        el.classList.add('room-title')
      }
      const shouldType = animate && line.kind !== 'player' && !asciiArt && !roomTitle
      el.textContent = shouldType ? '' : line.text
      appendTranscriptElement(el)
      if (roomTitle) {
        roomTitleEl = el
        updateRoomScrollSpacer(el)
        await scrollToTopOf(el)
        if (generation !== renderGeneration) return
      }
      if (shouldType) {
        await typeLine(el, line.text)
        if (generation !== renderGeneration) return
      }
      if (shouldScroll && !roomTitleInBatch) {
        scrollToContentBottom()
      }
    }
-    transcriptEl.scrollTop = transcriptEl.scrollHeight
+
    if (shouldScroll && !roomTitleEl) {
      scrollToContentBottom()
    }
  }
  const renderAll = (lines: TranscriptLine[], options: { animate?: boolean; scroll?: boolean } = {}): void => {
    const animate = (options.animate ?? true) && UI_FEATURES.typedEffect
    const shouldScroll = options.scroll ?? true
    const generation = renderGeneration
    renderQueue = renderQueue.then(() => renderLines(lines, animate, shouldScroll, generation)).catch((err) => {
      console.error('[halfstreet] render error', err)
    })
  }
  const clearIdleHint = (): void => {
@@ -150,42 +306,78 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
    clearTransientHelp()
    const el = document.createElement('div')
    el.className = 'system help'
-    el.dataset.transientHelp = 'true'
+    el.dataset['transientHelp'] = 'true'
-    el.textContent = HELP_TEXT
+
-    transcriptEl.appendChild(el)
+    const close = document.createElement('button')
    close.type = 'button'
    close.className = 'mystery-help-close'
    close.dataset['helpClose'] = 'true'
    close.setAttribute('aria-label', 'Close help')
    close.textContent = 'x'
    close.addEventListener('click', (e) => {
      e.stopPropagation()
      clearTransientHelp()
      return
    })
    const text = document.createElement('div')
    text.className = 'mystery-help-body'
    text.textContent = HELP_TEXT
    el.append(close, text)
    appendTranscriptElement(el)
    transientHelpEl = el
-    transcriptEl.scrollTop = transcriptEl.scrollHeight
+    scrollToContentBottom()
  }
  document.addEventListener('pointerdown', (e) => {
    if (!transientHelpEl) return
    const target = e.target as Node | null
    if (target && transientHelpEl.contains(target)) return
    clearTransientHelp()
  })
  const hideHelpOnInput = (): void => {
    if (!transientHelpEl) return
    window.setTimeout(() => {
      if (inputEl.value.trim().length > 0) clearTransientHelp()
    })
  }
  // For UI-originated lines (player input, restart/undo/quit messages, error
  // notices). Pushes into state.transcript so they survive reload, then renders.
  // Engine-originated lines (from dispatch) are already in state.transcript;
  // those use renderAll directly.
-  const appendLines = (lines: TranscriptLine[]): void => {
+  const appendLines = (lines: TranscriptLine[], options: { animate?: boolean; scroll?: boolean } = {}): void => {
    state = { ...state, transcript: [...state.transcript, ...lines].slice(-TRANSCRIPT_CAP) }
-    renderAll(lines)
+    renderAll(lines, options)
  }
  const restart = (): void => {
    const confirmed = confirm('Restart? Your progress will be lost.')
    if (!confirmed) {
-      appendLines([{ kind: 'system', text: '(restart cancelled)' }])
+      appendLines([{ kind: 'system', text: '(restart cancelled)' }], { scroll: false })
      return
    }
    clearSave()
    state = initialStateFor(world)
    renderGeneration += 1
    renderQueue = Promise.resolve()
    transcriptEl.innerHTML = ''
    inputEl.value = ''
    syncCommandLine()
-    renderAll(state.transcript)
+    renderAll(state.transcript, { animate: false })
    saveState(state)
    refreshChips()
    syncLightMeter()
    syncEndedUI()
    syncDrunkEffect()
  }
-  renderAll(state.transcript)
+  renderAll(state.transcript, { animate: false })
  refreshChips()
  syncLightMeter()
  syncEndedUI()
  syncDrunkEffect()
  syncCommandLine()
  scheduleIdleHint()
@@ -218,13 +410,13 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
    commandHistory = [...commandHistory, raw].slice(-50)
    historyIndex = null
    historyDraft = ''
-    appendLines([{ kind: 'player', text: raw }])
+    appendLines([{ kind: 'player', text: raw }], { scroll: false })
    // Once the game has ended, only restart and undo are allowed.
    if (state.endedWith !== null) {
      const lower = raw.trim().toLowerCase()
      if (lower !== 'restart' && lower !== 'undo') {
-        appendLines([{ kind: 'system', text: 'The story has ended. Type `restart` or `undo`.' }])
+        appendLines([{ kind: 'system', text: 'The story has ended. Type `restart` or `undo`.' }], { scroll: false })
        return
      }
    }
@@ -243,12 +435,14 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
      if (lastState) {
        state = lastState
        lastState = null
-        appendLines([{ kind: 'system', text: '(undone)' }])
+        appendLines([{ kind: 'system', text: '(undone)' }], { scroll: false })
        saveState(state)
        refreshChips()
        syncLightMeter()
        syncEndedUI()
        syncDrunkEffect()
      } else {
-        appendLines([{ kind: 'system', text: 'There is no further back.' }])
+        appendLines([{ kind: 'system', text: message('no-undo') }], { scroll: false })
      }
      return
    }
@@ -263,24 +457,33 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
      const ctx = buildParserContext(state)
      const command = parse(raw, ctx)
      lastState = state
      const previousLocation = state.location
      const result = dispatch(state, command, world)
      state = result.state
-      renderAll(result.appended)  // dispatch already pushed these into state.transcript
+      const shouldScrollToRoom = UI_FEATURES.roomScroll && command.kind === 'go' && state.location !== previousLocation
      renderAll(result.appended, { scroll: shouldScrollToRoom })  // dispatch already pushed these into state.transcript
      saveState(state)
      transcriptEl.scrollTop = transcriptEl.scrollHeight
      if (raw.trim().toLowerCase() === 'theme') {
        document.dispatchEvent(new CustomEvent('halfstreet-toggle-theme'))
      }
      refreshChips()
      syncLightMeter()
      syncEndedUI()
      syncDrunkEffect()
    } catch (err) {
      console.error('[halfstreet] dispatch error', err)
-      appendLines([{ kind: 'system', text: '[ The terminal hums and resets. ]' }])
+      appendLines([{ kind: 'system', text: '[ The terminal hums and resets. ]' }], { scroll: false })
    }
  })
  inputEl.addEventListener('input', syncCommandLine)
-  inputEl.addEventListener('focus', clearIdleHint)
+  inputEl.addEventListener('focus', () => {
    syncInputFocus(true)
    clearIdleHint()
  })
  inputEl.addEventListener('blur', () => {
    syncInputFocus(false)
  })
  inputEl.addEventListener('pointerdown', clearIdleHint)
  inputEl.parentElement?.addEventListener('pointerdown', () => {
@@ -301,10 +504,16 @@ if (!transcriptEl || !inputEl || !inputDisplayEl) {
      return
    }
    if (e.key === 'Escape') {
      if (transientHelpEl) {
        e.preventDefault()
        clearTransientHelp()
        return
      }
      saveState(state)
      window.location.href = '/'
    }
  })
  document.addEventListener('halfstreet-restart', restart)
  inputEl.addEventListener('input', hideHelpOnInput)
 }
@@ -1,8 +1,10 @@
 const STORAGE_KEY = 'halfstreet:theme:v1'
 const CURSOR_STORAGE_KEY = 'halfstreet:cursor:v1'
 const CHIPS_STORAGE_KEY = 'halfstreet:chips:v1'
 type Theme = 'amber' | 'ansi'
 type Cursor = 'bar' | 'block' | 'underscore'
 type Chips = 'on' | 'off'
 function getStored(): Theme {
  try {
@@ -21,6 +23,14 @@ function getStoredCursor(): Cursor {
  }
 }
 function getStoredChips(): Chips {
  try {
    return localStorage.getItem(CHIPS_STORAGE_KEY) === 'off' ? 'off' : 'on'
  } catch {
    return 'on'
  }
 }
 function setTheme(theme: Theme): void {
  document.documentElement.setAttribute('data-mystery-theme', theme)
  try {
@@ -45,9 +55,22 @@ function setCursor(cursor: Cursor): void {
  }
 }
 function setChips(chips: Chips): void {
  document.documentElement.setAttribute('data-mystery-chips-state', chips)
  try {
    localStorage.setItem(CHIPS_STORAGE_KEY, chips)
  } catch {
    // ignore
  }
  for (const btn of document.querySelectorAll<HTMLButtonElement>('[data-chips-choice]')) {
    btn.setAttribute('aria-pressed', btn.dataset['chipsChoice'] === chips ? 'true' : 'false')
  }
 }
 const initial = getStored()
 setTheme(initial)
 setCursor(getStoredCursor())
 setChips(getStoredChips())
 const optionsRoot = document.querySelector<HTMLElement>('[data-mystery-options]')
 const optionsToggle = document.querySelector<HTMLButtonElement>('[data-options-toggle]')
@@ -88,6 +111,13 @@ document.querySelectorAll<HTMLButtonElement>('[data-cursor-choice]').forEach((bt
  })
 })
 document.querySelectorAll<HTMLButtonElement>('[data-chips-choice]').forEach((btn) => {
  btn.addEventListener('click', () => {
    const next = (btn.dataset['chipsChoice'] as Chips | undefined) ?? 'on'
    setChips(next)
  })
 })
 document.querySelector<HTMLButtonElement>('[data-restart-choice]')?.addEventListener('click', () => {
  setOptionsOpen(false)
  document.dispatchEvent(new CustomEvent('halfstreet-restart'))
@@ -4,7 +4,7 @@
  "showTags": false,
  "showAttachments": false,
  "hideUnresolved": false,
-  "showOrphans": true,
+  "showOrphans": false,
  "collapse-color-groups": false,
  "colorGroups": [
    {
@@ -37,9 +37,9 @@
    }
  ],
  "collapse-display": false,
-  "showArrow": false,
+  "showArrow": true,
-  "textFadeMultiplier": 0,
+  "textFadeMultiplier": -3,
-  "nodeSizeMultiplier": 1.82265625,
+  "nodeSizeMultiplier": 2.2138427734375,
  "lineSizeMultiplier": 5,
  "collapse-forces": false,
  "centerStrength": 0.518713248970312,
@@ -0,0 +1,11 @@
 {
  "markdown:add-metadata-property": [],
  "editor:toggle-source": [
    {
      "modifiers": [
        "Mod"
      ],
      "key": ";"
    }
  ]
 }
@@ -0,0 +1,6 @@
 ---
 short:
 readable:
 takeable:
 names:
 ---
@@ -17,6 +17,7 @@ views:
      - exitW
      - exitU
      - exitD
      - items
  - type: cards
    name: Items
    filters:
@@ -29,3 +30,11 @@ views:
      - takeable
      - names
      - formula.Room
  - type: cards
    name: Items By Room
    filters:
      and:
        - file.inFolder("items")
    order:
      - file.name
      - formula.Room
@@ -1,18 +1,12 @@
 - [x] Need to add help text when user types "help". This should give them some common commands and explain the concepts behind text adventure games. It should also include an exceprt at the beginning from the opening text.  "You arrive at the address, but you do not remember what has happened. The road behind you is gone...". The help text should disappear after the user types a new prompt (i.e., it's not persistent).
 - [x] Need to add  the tiles from mobile to desktop view.
 - [x] Enhance tiles with contextual awareness, enabling tiles to appear in rooms when appropriate (e.g. "attack rat").
 - [ ] Create a mechanic that asks "Are you sure?" before taking critical actions like attacking or other game-changing mechanics that might affect the final ending.
 - [x] Add a tile for USE 
 - [ ] Add contextual awareness and autocomplete. For example a popup that appears above the USE text or when a user types "use". The user is able to autofill the rest of the thing by using the keyboard to toggle through the inv list and tab-complete the option, (or tap on mobile) "e.g. use (matches, light, letter) *on* (lamp)" - the word "on" there being suggested. Suggestions for autocomplete are in italics. This is one modern design element we're going to add.
 - [x] Add a footer with "By [Ethan J Lewis](https://ethanjlewis.com) | [Source Code](https://half.st/ejlewis/halfstreet) | [GNU General Public License v3.0](https://half.st/ejlewis/halfstreet/src/branch/main/LICENSE)"
 - [x] Add "Half Street" as ASCII Art to the intro text.
 - [x] Add logic to make the last sentence in the examined description conditional. This is where we'll list items in the room. (e.g., "The hallway runs further than the house should be wide. The dust on the floor is undisturbed except where you have walked. *The oil lamp is on the side table.*")
 - [ ] Create a new item with a mechanic: whiskey bottle. When the user drinks it they get drunk and are transported to the "drunk rooms" which are a bit of a maze and things get a little topsy-turvy. The player chances to lose an item (returning to its original spot) when they get drunk and wakes up several turns later somewhere else predetermined.
 - [ ] Add lightened descriptions to darkened rooms. About half the rooms should be too dark to see anything (affects ability to move forward, can't see exits or entounters, except for maybe hints at the encounters, like sounds or shapes in the dark) Add frontmatter property to all rooms: (dark: true/false). Make text in darkened rooms a grey color.
 - [x] Fix mobile - scrolling issue (page grows as the terminal grows).
 - [x] Fix mobile - ascii text art at beginning too big to render
 - [ ] Implement a simple "stealth mechanic", where sometimes it's advantageous to have the light out.
 - [ ] Implement a simple (optional?) minimap in the UI? - Maybe tied to an item? Once you get the map the minimap appears? Can we POC it?
 - [x] Feature: Ability to retain console history, e.g., scroll through previous commands with up and down arrows.
 - [x] Feature: Grey italicized "type here..."  text that appears near the terminal if the user doesn't click into the terminal within 30 seconds of entering the game or click the help button. The text disappears once a user clicks in the terminal, or selects a card.
 - [x] Change footer to "Copyright (C) 2026 [Ethan J Lewis](https://ethanjlewis.com) | [GNU 3.0](https://half.st/ejlewis/halfstreet/src/branch/main/LICENSE)| [Source Code](https://half.st/ejlewis/halfstreet)"
@@ -26,3 +20,30 @@
 - [x] Feature: / brings focus to terminal
 - [x] Feature: Add "Restart" option to option menu
 - [x] Bug: gear icon is still wayyyyyyy toooo smallllll it needs to be like 4x larger at least.
 - [x] Add a "wait" tile.
 - [x] If the user says "light match" or "light match" the response should be "use match with what?"
 - [x] If the user says "use match with letter" they should burn the letter.
 - [x] There should be a lighter in the smoking room that allows unlimited lighting.
 - [x] Create a mechanic that asks "Are you sure?" before taking critical actions like attacking or other game-changing mechanics that might affect the final ending.
 - [ ] Add lightened descriptions to darkened rooms. About half the rooms should be too dark to see anything (affects ability to move forward, can't see exits or encounters, except for maybe hints at the encounters, like sounds or shapes in the dark) Add frontmatter property to all rooms: (dark: true/false). Make text in darkened rooms a grey color.
 - [ ] Implement a simple "stealth mechanic", where sometimes it's advantageous to have the light out.
 - [ ] Implement a simple (optional?) minimap in the UI? - Maybe tied to an item? Once you get the map the minimap appears? Can we POC it?
 - [x] Add a mechanic where after the player waits 3 times or moves six times the light goes out and needs to be relit. Or something along those lines. We need a sense of time. Maybe some situations blow out the light
 - [ ] Add attack options for most encounters. Rarely this will be a good idea though. 
 - [ ] Add a failure condition for attacking at the wrong time. Make the reasons for the failure condition contextual, for example, when they attack the stair sleeper they might trip on the stair and get injured. 
 - [ ] Add contextual awareness and autocomplete. For example a popup that appears above the USE text or when a user types "use". The user is able to autofill the rest of the thing by using the keyboard to toggle through the inv list and tab-complete the option, (or tap on mobile) "e.g. use (matches, light, letter) *on* (lamp)" - the word "on" there being suggested. Suggestions for autocomplete are in italics. This is one modern design element we're going to add.
 - [ ] Add a Notebook function. Automatically make notes as the game progresses.
 - [ ] Implement a carry mechanic. Decide whether we should have a limited carry ability (only able to carry a few things?) or we night need a full inventory system, where items are assigned to pockets or hand carry and we can only hand carry a couple of items?
 - [x] Implement a "drop" mechanic in order to drop items. Dropped items remain in the room in which they were dropped and can be picked up again.
 - [x] We need a light indicator that shows when the light is lit and how much time is left on the light. Use the svg file I dropped in the src/assets folder for the indicator. The indicator should be a 6-segment led that runs in a dotted line underneath the light indicator and burns out right to left. The color of the indicator should be bright when it's lit and dim when it's not. The indicator should be to the right of the tiles and sized appropriately.
 - [x] FEATURE: Add an option to disable the chips in the options menu.
 - [x] BUG: The new cursor doesn't appear on mobile.
 - [ ] FEATURE: Add a Safe to somewhere that it makes sense (the bedroom?) We can add a safe-cracking mini-game. The safe contains a single bullet, which can be used with the revolver. 
 - [ ] FEATURE: Add item Revolver, which can be used to kill the thing at the end. It comes with no bullets, so players need to defeat the safe-cracking minjgame. Place the revolver somewhere it takes the player some effort to find. 
 - [ ] Feature: A faceless voice that speaks in a whisper in the smoking room, which demands whiskey and dispenses riddles if the player finds a bottle of whiskey (but hasn't drunk it yet). The riddles are randomly chosen from a list of 25 difficult riddles (source them). If the riddle is answered correctly there needs to be some reward and maybe a major plot point is revealed. 
 - [x] Add item Whiskey bottle, half full of something smoky. In the kitchen. Drinking it gets the player drunk, which causes them to unlock the drunk rooms, which are a series of rooms where they can go many directions, but somehow end up in seemingly back in the same spot. They are essentially a maze of doors and hallways, ladders and levels. There should be boundaries established though, it shouldn't be endless. After 20 or so moves the player passes out and wakes up back in the foyer, with the whiskey bottle returned to the kitchen, somehow still half full. Add a random encounter in the dark rooms, a creaking floorboard helps you find a secret door that opens with a faceless man inside who gives you major plot info. After this encounter you pass out and wake up in the lobby as before. When the player is "drunk" the text on the terminal should appear blurry, like the user has double vision. 
 - [ ] Add a "Report a Bug" footer link backed by Bugpin (widget at bugpin.half.st -> forwards to GitHub Issues). Add Bugsink (@sentry/browser -> bugsink.half.st) for automatic JS error capture. Mark complete after manual verification: a test report appears in the Bugpin portal AND a GitHub issue is created AND a thrown error appears in the Bugsink portal.
 - [ ] BUG: It says the door closes behind you when you enter the lobby, but you can still exit S to the gate.
 - [x] FEATURE: Add a short "typed" effect to the text. Make it look like it's being typed out, if that makes sense, one character at a time. The effect should be brief. 
 - [x] FEATURE: Whenever you change rooms, scroll the text so the name of the room you're in is at the top. Users can scroll up to see the history. This should be an effect where the old text slides up to make room for the new text, and this should happen before the "typed" effect.
 - [ ] Open-source authoring architecture: follow [[open-source-authoring-roadmap]] to move as much story, parser, mechanic, action, and UI configuration as practical into markdown under `src/world` so authors can control it from Obsidian.
@@ -0,0 +1,27 @@
 ---
 id: burn-letter
 verbs: [use]
 requires:
  allVisibleOrHeld:
    - "[[letter]]"
    - "[[matches]]"
 consumes:
  inventory:
    - "[[letter]]"
 decrements:
  item: "[[matches]]"
  stateKey: uses
 setsFlags:
  letterBurned: true
 ---
 # Burn Letter
 ## success
 The letter catches at one corner. In a few breaths it is ash.
 ## spent
 The matchbook is empty.
 ## missingRequired
 You don't see the letter here.
@@ -0,0 +1,33 @@
 ---
 id: drink-whiskey
 verbs: [drink]
 handler: drunk-transition
 requires:
  allHeld:
    - "[[whiskey]]"
 consumes:
  inventory:
    - "[[whiskey]]"
 drunkTransition:
  destinationRoom: "[[drunk-hall]]"
  maxMoves: 20
  wakeRoom: "[[foyer]]"
  resetRoom: "[[kitchen]]"
 ---
 # Drink Whiskey
 ## success
 You drink from the bottle. It tastes of smoke, sugar, and rainwater left too long in a pipe.
 ## missingRequired
 You'd have to be carrying it.
 ## secretFoundPassOut
 The faceless man steps backward into the dark. The floor rises under you, or you fall toward it.
 ## tooManyMovesPassOut
 The rooms keep turning until they become one room. Then even that room is gone.
 ## reset
 The bottle is not with you. Somewhere in the kitchen, it is half full again.
@@ -0,0 +1,155 @@
 # Authoring Halfstreet
 Halfstreet is authored from this `src/world` vault. The TypeScript runtime loads and validates the markdown; ordinary story changes should start here.
 Use wikilinks for references when you can. The loader accepts `[[foyer]]` and stores it as `foyer`, so Obsidian links stay useful without changing runtime ids.
 ## Forking The Game
 The current open-source shape is a forkable Astro app. Keep `src/engine`, `src/ui`, and `src/pages` in place, then replace the markdown in this vault with your own rooms, items, encounters, endings, mechanics, actions, parser vocabulary, and UI labels.
 For a new game, update these files first:
 - `game.md`: title, starting room, starting inventory, ending priority, opening art, help text, and end text.
 - `parser.md`: direction words, verb aliases, prepositions, stop words, no-target verbs, and meta verbs.
 - `ui.md`: page title, meta description, footer labels and links, build label, and UI feature switches.
 - `templates/`: copy these starter files when adding new world content.
 After edits, run `npm test` from the repo root. Validation errors are meant to point back to the markdown field or section that needs fixing.
 ## Rooms
 Room files live in `rooms/`. Every room needs frontmatter plus three prose sections:
 - `## first-visit`
 - `## revisit`
 - `## examined`
 Set unused exits to `null`. Set exits to `[[room-id]]` when they lead somewhere. Put item ids in `items`, and set `encounter` when a room starts an encounter.
 ```yaml
 id: sample-room
 title: "[ Sample Room ]"
 exitN: "[[other-room]]"
 exitS: null
 exitE: null
 exitW: null
 exitU: null
 exitD: null
 items:
  - "[[sample-key]]"
 encounter: null
 safe: true
 ```
 Locked exits use a matching `exitXRequires` and `exitXLockedText` pair. The requirement must be an item id or a known flag.
 ```yaml
 exitN: "[[locked-room]]"
 exitNRequires: sample-key
 exitNLockedText: The door will not move.
 ```
 ## Items
 Item files live in `items/`. The prose before the first `##` header is the long description shown by `examine`.
 Use `readable: true` only when the item has a `## read` section. Use `lightable: true` for items that can be lit, and `lighter: true` for items that can light other items.
 ```yaml
 id: sample-key
 names: ["key", "sample key"]
 short: "a sample key"
 takeable: true
 initialState: {}
 ```
 Allowed optional item sections are:
 - `## read`
 - `## lit`
 - `## extinguished`
 - `## lighter-empty`
 ## Encounters
 Encounter files live in `encounters/`. Encounters are state machines: `initialPhase` points to a phase, each phase points to a description section, and each transition points to a narration section.
 ```yaml
 id: sample-encounter
 startsIn: "[[sample-room]]"
 initialPhase: waiting
 aliases: [figure, shape]
 defaultWrongVerbNarration: wrong-verb
 phases:
  waiting:
    description: waiting
    transitions:
      - verb: wait
        chipLabel: WAIT
        narration: waited
        to: resolved
 ```
 Use `onResolved.setFlags` for flags that endings or locked exits can read. Use `requires.item` on a transition when the player must hold a specific item.
 ## Endings
 Ending files live in `endings/`. `whenFlags` controls when an ending is available, and the markdown body is the ending narration.
 Quote ids that look like booleans:
 ```yaml
 id: "true"
 whenFlags:
  familySecretKnown: true
 ```
 Bare `id: true` is parsed as a boolean by YAML before the loader sees it.
 ## Mechanics
 Mechanic files live in `mechanics/`. They configure named TypeScript handlers without moving the algorithms into markdown.
 `mechanics/light.md` controls the light timer, burn triggers, state keys, meter setting, and fallback light prose. `mechanics/resolve.md` controls resolve levels, wrong-verb cost, safe-room recovery, and retreat behavior.
 Keep `handler` set to the supported handler name. Set `enabled: false` to disable a mechanic cleanly.
 ## Actions
 Action files live in `actions/`. Simple actions can require visible or held items, consume inventory, decrement item state, set flags, and narrate success.
 ```yaml
 id: sample-action
 verbs: [use]
 requires:
  allVisibleOrHeld:
    - "[[sample-key]]"
 setsFlags:
  sampleActionDone: true
 ```
 Every default action needs `## success`. Handler-backed actions may require extra sections. For example, the `drunk-transition` handler requires `## success`, `## secretFoundPassOut`, `## tooManyMovesPassOut`, and `## reset`.
 ## Game, Parser, Messages, And UI
 - `game.md` controls the title, description, starting room, starting inventory, ending priority, transcript cap, opening art, help text, and ended text.
 - `parser.md` controls directions, verb aliases, prepositions, stop words, no-target verbs, and meta verbs.
 - `messages.md` controls common system prose.
 - `ui.md` controls page metadata, footer labels and links, build label visibility, and UI feature toggles.
 ## Common Validation Errors
 `missing required section "## first-visit"`: add the exact section header to the room file. Section names must use only letters, digits, hyphens, and underscores.
 `## read section is required when readable: true`: either add `## read` to the item or remove `readable: true`.
 `frontmatter references missing section`: an encounter phase, transition, or failure references a prose key that does not exist. Add the section or fix the key.
 `exitNRequires is set but exitNLockedText is missing`: locked exits need both the requirement and locked narration fields.
 `references unknown item` or `references unknown room`: check the wikilink/id spelling and make sure the referenced file exists in the matching folder.
 `endingPriority references "true" but endings/true.md is missing`: quote boolean-like ids in YAML and make sure the ending file exists.
 `unknown message section` or `unknown item section`: the loader only accepts known section keys. Rename the header to one of the allowed keys for that file type.
@@ -1,7 +1,83 @@
 import { describe, it, expect } from 'vitest'
-import { world } from './index'
+import { assembleWorld, world } from './index'
 import type { GameManifest, Item, Room, World } from './types'
 const manifest: GameManifest = {
  id: 'test',
  title: 'Test',
  description: 'A tiny test world.',
  startingRoom: 'foyer',
  startingInventory: ['letter'],
  endingPriority: ['true'],
 }
 const rooms: Record<string, Room> = {
  foyer: {
    id: 'foyer',
    title: '[ Foyer ]',
    descriptions: {
      firstVisit: 'You are here.',
      revisit: 'Still here.',
      examined: 'A foyer.',
    },
    exits: {},
    items: [],
  },
 }
 const items: Record<string, Item> = {
  letter: {
    id: 'letter',
    names: ['letter'],
    short: 'a letter',
    long: 'A folded letter.',
    initialState: {},
    takeable: true,
  },
 }
 const endings: World['endings'] = {
  true: { whenFlags: {}, narration: 'The end.' },
 }
 function build(overrides: Partial<Parameters<typeof assembleWorld>[0]> = {}) {
  return assembleWorld({
    game: manifest,
    rooms,
    items,
    endings,
    encounters: {},
    encounterDocs: [],
    ...overrides,
  })
 }
 describe('assembled world', () => {
  it('assembles a minimal manifest-backed world', () => {
    const result = build()
    expect(result.startingRoom).toBe('foyer')
    expect(result.startingInventory).toEqual(['letter'])
    expect(result.endingPriority).toEqual(['true'])
  })
  it('rejects a game manifest with an unknown starting room', () => {
    expect(() => build({
      game: { ...manifest, startingRoom: 'missing-room' },
    })).toThrow(/startingRoom references "missing-room"/)
  })
  it('rejects a game manifest with an unknown starting inventory item', () => {
    expect(() => build({
      game: { ...manifest, startingInventory: ['missing-item'] },
    })).toThrow(/startingInventory references unknown item "missing-item"/)
  })
  it('rejects a game manifest with an unknown ending priority entry', () => {
    expect(() => build({
      game: { ...manifest, endingPriority: ['missing-ending'] },
    })).toThrow(/endingPriority references "missing-ending"/)
  })
  it('contains the authored opening and main-floor rooms', () => {
    expect(Object.keys(world.rooms)).toEqual(expect.arrayContaining([
      'outside-gate',
@@ -16,10 +92,15 @@ describe('assembled world', () => {
      'music-room',
      'servants-passage',
      'laundry',
      'stair-up',
      'bedroom',
      'nursery',
      'attic',
      'chapel',
    ]))
  })
-  it('contains the authored opening and main-floor items', () => {
+  it('contains the authored opening, main-floor, and upper-floor items', () => {
    expect(Object.keys(world.items)).toEqual(expect.arrayContaining([
      'broken-cigarette',
      'lamp',
@@ -33,6 +114,10 @@ describe('assembled world', () => {
      'grandfather-clock',
      'dinner-place-setting',
      'covered-cage',
      'childs-drawing',
      'music-box',
      'toy-dog',
      'silver-vial',
    ]))
  })
@@ -44,6 +129,24 @@ describe('assembled world', () => {
    }
  })
  it('hallway prose names every enabled exit', () => {
    const hallway = world.rooms['hallway']
    expect(hallway).toBeDefined()
    if (!hallway) throw new Error('hallway room is missing')
    expect(hallway.exits).toEqual({
      n: 'dining-room',
      s: 'foyer',
      e: 'cellar-stair',
      w: 'smoking-room',
      u: 'parlor',
      d: 'music-room',
    })
    const prose = `${hallway.descriptions.firstVisit}\n${hallway.descriptions.examined}`.toLowerCase()
    for (const word of ['north', 'south', 'east', 'west', 'up', 'down']) {
      expect(prose, `hallway prose should mention ${word}`).toContain(word)
    }
  })
  it('all room item refs resolve to known items', () => {
    for (const room of Object.values(world.rooms)) {
      for (const itemId of room.items) {
@@ -61,16 +164,356 @@ describe('assembled world', () => {
  })
  it('startingRoom is a known room', () => {
    expect(world.game?.startingRoom).toBe(world.startingRoom)
    expect(world.rooms[world.startingRoom]).toBeDefined()
  })
  it('startingInventory items are known', () => {
    expect(world.game?.startingInventory).toEqual(world.startingInventory)
    for (const itemId of world.startingInventory) {
      expect(world.items[itemId]).toBeDefined()
    }
  })
  it('game manifest text is loaded from markdown', () => {
    expect(world.game?.title).toBe('Halfstreet')
    expect(world.game?.openingArt).toContain('____')
    expect(world.game?.helpText).toContain('This is a text adventure.')
    expect(world.game?.endedText).toContain('The story has ended.')
  })
  it('parser vocabulary is loaded from markdown', () => {
    expect(world.parser?.verbs.take).toContain('pick up')
    expect(world.parser?.verbs.open).toContain('uncover')
    expect(world.parser?.directions.n).toContain('north')
  })
  it('UI config is loaded from markdown', () => {
    expect(world.ui?.pageTitle).toBe('Halfstreet - Ethan J Lewis')
    expect(world.ui?.footer.links.map((link) => link.label)).toEqual(['GNU 3.0', 'Source Code'])
    expect(world.ui?.footer.showBuild).toBe(true)
    expect(world.ui?.features.typedEffect).toBe(true)
  })
  it('system messages are loaded from markdown', () => {
    expect(world.messages?.['unknown-verb']).toContain("don't fit this place")
    expect(world.messages?.taken).toBe('Taken.')
  })
  it('light mechanic config is loaded from markdown', () => {
    expect(world.mechanics?.light?.enabled).toBe(true)
    expect(world.mechanics?.light?.maxTurns).toBe(6)
    expect(world.mechanics?.light?.burnOn).toEqual(['move', 'wait'])
    expect(world.mechanics?.light?.messages?.flameDies).toBe('The flame dies.')
  })
  it('resolve mechanic config is loaded from markdown', () => {
    expect(world.mechanics?.resolve?.enabled).toBe(true)
    expect(world.mechanics?.resolve?.ladder).toEqual(['steady', 'shaken', 'reeling', 'returning'])
    expect(world.mechanics?.resolve?.safeRooms.recoverySteps).toBe(1)
    expect(world.mechanics?.resolve?.failure.afterRetreat).toBe('shaken')
  })
  it('declarative actions are loaded from markdown', () => {
    expect(world.actions?.['burn-letter']?.verbs).toEqual(['use'])
    expect(world.actions?.['burn-letter']?.requires?.allVisibleOrHeld).toEqual(['letter', 'matches'])
    expect(world.actions?.['burn-letter']?.messages.success).toContain('ash')
  })
  it('handler-backed actions are loaded from markdown', () => {
    expect(world.actions?.['drink-whiskey']?.verbs).toEqual(['drink'])
    expect(world.actions?.['drink-whiskey']?.handler).toBe('drunk-transition')
    expect(world.actions?.['drink-whiskey']?.requires?.allHeld).toEqual(['whiskey'])
    expect(world.actions?.['drink-whiskey']?.drunkTransition).toEqual({
      destinationRoom: 'drunk-hall',
      maxMoves: 20,
      wakeRoom: 'foyer',
      resetRoom: 'kitchen',
    })
  })
  it('loads a markdown-owned encounter phase machine', () => {
    expect(world.encounters.rat).toMatchObject({
      id: 'rat',
      startsIn: 'cellar-stair',
      initialPhase: 'lurking',
      onResolved: { setFlags: { ratGone: true } },
      defaultWrongVerbNarration: 'The rat watches.',
    })
    const lurking = world.encounters.rat?.phases.lurking
    expect(lurking).toBeDefined()
    expect(lurking?.transitions).toEqual([
      {
        verb: 'attack',
        target: 'rat',
        chipLabel: 'ATTACK RAT',
        chipCommand: 'attack rat',
        narration: 'You stamp. The rat squeals and is gone into the dark.',
        to: 'resolved',
      },
      {
        verb: 'wait',
        chipLabel: 'WAIT',
        narration: 'The rat does not move. Neither do you.',
        to: 'lurking',
      },
    ])
  })
  it('loads the first migrated encounter batch from markdown', () => {
    expect(world.encounters['window-guest']).toMatchObject({
      aliases: ['guest', 'window guest', 'curtains', 'curtain', 'window'],
      onResolved: { setFlags: { curtainsClosed: true } },
      onFailed: { retreatTo: 'hallway' },
    })
    expect(world.encounters['covered-cage']).toMatchObject({
      aliases: ['covered cage', 'cage', 'birdcage', 'cloth'],
      onResolved: { setFlags: { cageUncovered: true } },
      onFailed: { retreatTo: 'hallway' },
    })
    expect(world.encounters['piano-echo']).toMatchObject({
      aliases: ['piano echo', 'piano', 'note', 'key'],
      onResolved: { setFlags: { musicSolved: true } },
      onFailed: { retreatTo: 'hallway' },
    })
    expect(world.encounters['window-guest']?.phases['standing-outside']?.transitions[0]?.chipCommand).toBe('close curtains')
    expect(world.encounters['covered-cage']?.phases.rustling?.transitions[0]?.chipCommand).toBe('uncover cage')
    expect(world.encounters['piano-echo']?.phases.listening?.transitions[0]?.chipCommand).toBe('play note')
  })
  it('loads the wait-resolved encounter batch from markdown', () => {
    expect(world.encounters['breathing-wall']).toMatchObject({
      aliases: ['breathing wall', 'wall', 'walls', 'breathing'],
      onResolved: { setFlags: { breathingWallPassed: true } },
      onFailed: { retreatTo: 'music-room' },
    })
    expect(world.encounters['linen-shape']).toMatchObject({
      aliases: ['linen shape', 'shape', 'sheet', 'sheets', 'linen'],
      onResolved: { setFlags: { linenShapeEmpty: true } },
      onFailed: { retreatTo: 'servants-passage' },
    })
    expect(world.encounters['stair-sleeper']).toMatchObject({
      aliases: ['stair sleeper', 'sleeper', 'figure', 'person', 'body'],
      onResolved: { setFlags: { hallwayShifted: true } },
      onFailed: { retreatTo: 'parlor' },
    })
    expect(world.encounters['breathing-wall']?.phases.audible?.transitions[0]).toMatchObject({ verb: 'wait', chipLabel: 'WAIT', to: 'resolved' })
    expect(world.encounters['linen-shape']?.phases.hanging?.transitions[0]).toMatchObject({ verb: 'wait', chipLabel: 'WAIT', to: 'resolved' })
    expect(world.encounters['stair-sleeper']?.phases.seated?.transitions[0]).toMatchObject({ verb: 'wait', chipLabel: 'WAIT', to: 'resolved' })
  })
  it('loads the item-gated encounter batch from markdown', () => {
    expect(world.encounters['ivy-figure']).toMatchObject({
      aliases: ['ivy figure', 'figure', 'ivy', 'vines', 'vine'],
      onResolved: { setFlags: { conservatoryVinesCut: true } },
      onFailed: { retreatTo: 'dining-room' },
    })
    expect(world.encounters['child-beneath-well']).toMatchObject({
      aliases: ['child', 'well child', 'child beneath well', 'barefoot child'],
      onResolved: { setFlags: { childPassedWell: true } },
      onFailed: { retreatTo: 'well' },
    })
    expect(world.encounters['bone-keeper']).toMatchObject({
      aliases: ['bone keeper', 'keeper', 'hands', 'bones', 'ribs'],
      onResolved: { setFlags: { burialRingPlaced: true } },
      onFailed: { retreatTo: 'tunnel' },
    })
    expect(world.encounters['ivy-figure']?.phases.hidden?.transitions).toEqual([
      expect.objectContaining({ verb: 'cut', requires: { item: 'pruning-shears' }, chipCommand: 'cut vines' }),
      expect.objectContaining({ verb: 'use', requires: { item: 'pruning-shears' }, chipCommand: 'use vines with shears' }),
    ])
    expect(world.encounters['child-beneath-well']?.phases.climbing?.transitions).toEqual([
      expect.objectContaining({ verb: 'hold', requires: { item: 'toy-dog' }, setFlags: { woofReturned: true }, chipCommand: 'hold dog' }),
      expect.objectContaining({ verb: 'wait', chipLabel: 'WAIT', to: 'resolved' }),
    ])
    expect(world.encounters['bone-keeper']?.phases.arranging?.transitions[0]).toMatchObject({
      verb: 'drop',
      target: 'burial-ring',
      requires: { item: 'burial-ring' },
      chipCommand: 'leave ring',
    })
  })
  it('loads the garden and lower-passage encounter batch from markdown', () => {
    expect(world.encounters['garden-procession']).toMatchObject({
      aliases: ['garden procession', 'procession', 'lanterns', 'lantern', 'lights', 'hedge'],
      onResolved: { setFlags: { gardenQuiet: true } },
      onFailed: { retreatTo: 'back-door' },
    })
    expect(world.encounters.reflection).toMatchObject({
      aliases: ['reflection', 'water', 'black water', 'face', 'reflected figure'],
      onResolved: { setFlags: { reflectionObscured: true } },
      onFailed: { retreatTo: 'ossuary' },
    })
    expect(world.encounters['root-movement']).toMatchObject({
      aliases: ['root movement', 'roots', 'root', 'opening'],
      onResolved: { setFlags: { rootsListenedTo: true } },
      onFailed: { retreatTo: 'flooded-passage' },
    })
    expect(world.encounters['garden-procession']?.phases.passing?.transitions[0]).toMatchObject({
      verb: 'wait',
      chipLabel: 'WAIT',
      to: 'resolved',
    })
    expect(world.encounters.reflection?.phases.following?.transitions[0]).toMatchObject({
      verb: 'use',
      target: 'reflection',
      requires: { item: 'damp-sheet' },
      chipCommand: 'use water with sheet',
    })
    expect(world.encounters['root-movement']?.phases.shifting?.transitions[0]).toMatchObject({
      verb: 'listen',
      chipCommand: 'listen',
      to: 'resolved',
    })
  })
  it('loads the final encounter batch from markdown', () => {
    expect(world.encounters['portrait-woman']).toMatchObject({
      aliases: ['portrait woman', 'woman', 'portrait', 'portraits', 'veil', 'funeral veil'],
      onResolved: { setFlags: { familyResemblanceSeen: true } },
      onFailed: { retreatTo: 'root-chamber' },
    })
    expect(world.encounters.basilisk).toMatchObject({
      aliases: ['basilisk', 'creature', 'eye', 'altar', 'coil'],
      onResolved: { setFlags: { basiliskSpared: true } },
      onFailed: { retreatTo: 'vault' },
    })
    expect(world.encounters['vault-memory']).toMatchObject({
      aliases: ['vault memory', 'memory', 'bed', 'photograph', 'photo', 'thing', 'buried thing'],
    })
    expect(world.encounters['creaking-floorboard']).toMatchObject({
      aliases: ['creaking floorboard', 'floorboard', 'board', 'creak', 'secret door', 'faceless man', 'man', 'voice'],
    })
    expect(world.encounters['distant-steps']).toMatchObject({
      aliases: ['distant steps', 'steps', 'footsteps', 'hallway'],
      onResolved: { setFlags: { distantStepsPassed: true } },
      onFailed: { retreatTo: 'parlor' },
    })
    expect(world.encounters['rainwater-basin']).toMatchObject({
      aliases: ['rainwater basin', 'basin', 'water', 'rainwater', 'reflection'],
      onResolved: { setFlags: { rainRoomEntered: true, houseAcceptedYou: true } },
      onFailed: { retreatTo: 'wrong-hallway' },
    })
    expect(world.encounters['portrait-woman']?.phases.watching?.transitions[0]).toMatchObject({
      verb: 'examine',
      chipCommand: 'examine portraits',
    })
    expect(world.encounters.basilisk?.phases.sleeping?.transitions).toEqual([
      expect.objectContaining({ verb: 'pour', requires: { item: 'silver-vial' }, chipCommand: 'pour vial on basilisk' }),
      expect.objectContaining({ verb: 'use', requires: { item: 'silver-vial' }, chipCommand: 'use basilisk with vial' }),
    ])
    expect(world.encounters['vault-memory']?.phases.buried?.transitions).toEqual([
      expect.objectContaining({ verb: 'read', requires: { item: 'family-register' }, setFlags: { nameSpoken: true } }),
      expect.objectContaining({ verb: 'take', setFlags: { tookPhotograph: true } }),
      expect.objectContaining({ verb: 'attack', setFlags: { disturbedVault: true } }),
    ])
    expect(world.encounters['creaking-floorboard']?.phases.creaking?.transitions).toEqual([
      expect.objectContaining({ verb: 'listen', setFlags: { drunkSecretFound: true, facelessManMet: true, houseDebtNamed: true } }),
      expect.objectContaining({ verb: 'open', setFlags: { drunkSecretFound: true, facelessManMet: true, houseDebtNamed: true } }),
    ])
    expect(world.encounters['distant-steps']?.phases.approaching?.transitions[0]).toMatchObject({
      verb: 'wait',
      to: 'resolved',
    })
    expect(world.encounters['rainwater-basin']?.phases.reflecting?.transitions).toEqual([
      expect.objectContaining({ verb: 'look', chipCommand: 'look basin' }),
      expect.objectContaining({ verb: 'examine', chipCommand: 'examine basin' }),
    ])
  })
  it('rejects duplicate handler-backed action owners', () => {
    expect(() => build({
      actions: {
        first: {
          id: 'first',
          verbs: ['drink'],
          handler: 'drunk-transition',
          requires: { allHeld: ['letter'] },
          drunkTransition: {
            destinationRoom: 'foyer',
            maxMoves: 1,
            wakeRoom: 'foyer',
            resetRoom: 'foyer',
          },
          messages: {
            success: 'ok',
            secretFoundPassOut: 'secret',
            tooManyMovesPassOut: 'moves',
            reset: 'reset',
          },
        },
        second: {
          id: 'second',
          verbs: ['drink'],
          handler: 'drunk-transition',
          requires: { allHeld: ['letter'] },
          drunkTransition: {
            destinationRoom: 'foyer',
            maxMoves: 1,
            wakeRoom: 'foyer',
            resetRoom: 'foyer',
          },
          messages: {
            success: 'ok',
            secretFoundPassOut: 'secret',
            tooManyMovesPassOut: 'moves',
            reset: 'reset',
          },
        },
      },
    })).toThrow(/handler "drunk-transition" is already used by actions\/first\.md/)
  })
  it('reports the action field that references an unknown item', () => {
    expect(() => build({
      actions: {
        burn: {
          id: 'burn',
          verbs: ['use'],
          requires: { allVisibleOrHeld: ['letter', 'missing-match'] },
          messages: { success: 'ok' },
        },
      },
    })).toThrow(/actions\/burn\.md: requires\.allVisibleOrHeld references unknown item "missing-match"/)
  })
  it('reports the drunk transition field that references an unknown room', () => {
    expect(() => build({
      actions: {
        drink: {
          id: 'drink',
          verbs: ['drink'],
          handler: 'drunk-transition',
          requires: { allHeld: ['letter'] },
          drunkTransition: {
            destinationRoom: 'missing-room',
            maxMoves: 1,
            wakeRoom: 'foyer',
            resetRoom: 'foyer',
          },
          messages: {
            success: 'ok',
            secretFoundPassOut: 'secret',
            tooManyMovesPassOut: 'moves',
            reset: 'reset',
          },
        },
      },
    })).toThrow(/actions\/drink\.md: drunkTransition\.destinationRoom references unknown room "missing-room"/)
  })
  it('ending priority references loaded endings', () => {
    expect(world.endingPriority).toEqual(world.game?.endingPriority)
    for (const endingId of world.endingPriority ?? []) {
      expect(world.endings[endingId], endingId).toBeDefined()
    }
  })
  it('endings have non-empty narration where the original did', () => {
-    expect(world.endings.true.narration.length).toBeGreaterThan(0)
+    expect(world.endings['true']?.narration.length).toBeGreaterThan(0)
  })
 })
@@ -1,183 +0,0 @@
 import type { EncounterDef } from './types'
 import { narration } from './loader'
 export const encounters: Record<string, EncounterDef> = {
  rat: {
    id: 'rat',
    startsIn: 'cellar-stair',
    initialPhase: 'lurking',
    phases: {
      lurking: {
        description: narration('rat', 'lurking'),
        transitions: [
          {
            verb: 'attack',
            target: 'rat',
            chipLabel: 'ATTACK RAT',
            chipCommand: 'attack rat',
            narration: narration('rat', 'attack-rat-resolved'),
            to: 'resolved',
          },
          {
            verb: 'wait',
            chipLabel: 'WAIT',
            narration: narration('rat', 'wait-stays'),
            to: 'lurking',
          },
        ],
      },
    },
    onResolved: { setFlags: { ratGone: true } },
    defaultWrongVerbNarration: 'The rat watches.',
  },
  'window-guest': {
    id: 'window-guest',
    aliases: ['guest', 'window guest', 'curtains', 'curtain', 'window'],
    startsIn: 'dining-room',
    initialPhase: 'standing-outside',
    phases: {
      'standing-outside': {
        description: narration('window-guest', 'standing-outside'),
        transitions: [
          {
            verb: 'close',
            target: 'window-guest',
            chipLabel: 'CLOSE CURTAINS',
            chipCommand: 'close curtains',
            narration: narration('window-guest', 'close-window-guest-resolved'),
            to: 'resolved',
          },
        ],
      },
    },
    onResolved: { setFlags: { curtainsClosed: true } },
    onFailed: { narration: narration('window-guest', 'failed'), retreatTo: 'hallway' },
    defaultWrongVerbNarration: narration('window-guest', 'wrong-verb'),
  },
  'ivy-figure': {
    id: 'ivy-figure',
    aliases: ['ivy figure', 'figure', 'ivy', 'vines', 'vine'],
    startsIn: 'conservatory',
    initialPhase: 'hidden',
    phases: {
      hidden: {
        description: narration('ivy-figure', 'hidden'),
        transitions: [
          {
            verb: 'cut',
            target: 'ivy-figure',
            chipLabel: 'CUT VINES',
            chipCommand: 'cut vines',
            requires: { item: 'pruning-shears' },
            narration: narration('ivy-figure', 'cut-ivy-figure-resolved'),
            to: 'resolved',
          },
          {
            verb: 'use',
            target: 'ivy-figure',
            chipLabel: 'USE SHEARS',
            chipCommand: 'use vines with shears',
            requires: { item: 'pruning-shears' },
            narration: narration('ivy-figure', 'cut-ivy-figure-resolved'),
            to: 'resolved',
          },
        ],
      },
    },
    onResolved: { setFlags: { conservatoryVinesCut: true } },
    onFailed: { narration: narration('ivy-figure', 'failed'), retreatTo: 'dining-room' },
    defaultWrongVerbNarration: narration('ivy-figure', 'wrong-verb'),
  },
  'covered-cage': {
    id: 'covered-cage',
    aliases: ['covered cage', 'cage', 'birdcage', 'cloth'],
    startsIn: 'smoking-room',
    initialPhase: 'rustling',
    phases: {
      rustling: {
        description: narration('covered-cage', 'rustling'),
        transitions: [
          {
            verb: 'open',
            target: 'covered-cage',
            chipLabel: 'UNCOVER CAGE',
            chipCommand: 'uncover cage',
            narration: narration('covered-cage', 'open-covered-cage-resolved'),
            to: 'resolved',
          },
        ],
      },
    },
    onResolved: { setFlags: { cageUncovered: true } },
    onFailed: { narration: narration('covered-cage', 'failed'), retreatTo: 'hallway' },
    defaultWrongVerbNarration: narration('covered-cage', 'wrong-verb'),
  },
  'piano-echo': {
    id: 'piano-echo',
    aliases: ['piano echo', 'piano', 'note', 'key'],
    startsIn: 'music-room',
    initialPhase: 'listening',
    phases: {
      listening: {
        description: narration('piano-echo', 'listening'),
        transitions: [
          {
            verb: 'play',
            target: 'piano-echo',
            chipLabel: 'PLAY NOTE',
            chipCommand: 'play note',
            narration: narration('piano-echo', 'play-piano-echo-resolved'),
            to: 'resolved',
          },
        ],
      },
    },
    onResolved: { setFlags: { musicSolved: true } },
    onFailed: { narration: narration('piano-echo', 'failed'), retreatTo: 'hallway' },
    defaultWrongVerbNarration: narration('piano-echo', 'wrong-verb'),
  },
  'breathing-wall': {
    id: 'breathing-wall',
    aliases: ['breathing wall', 'wall', 'walls', 'breathing'],
    startsIn: 'servants-passage',
    initialPhase: 'audible',
    phases: {
      audible: {
        description: narration('breathing-wall', 'audible'),
        transitions: [
          {
            verb: 'wait',
            chipLabel: 'WAIT',
            narration: narration('breathing-wall', 'wait-resolved'),
            to: 'resolved',
          },
        ],
      },
    },
    onResolved: { setFlags: { breathingWallPassed: true } },
    onFailed: { narration: narration('breathing-wall', 'failed'), retreatTo: 'music-room' },
    defaultWrongVerbNarration: narration('breathing-wall', 'wrong-verb'),
  },
  'linen-shape': {
    id: 'linen-shape',
    aliases: ['linen shape', 'shape', 'sheet', 'sheets', 'linen'],
    startsIn: 'laundry',
    initialPhase: 'hanging',
    phases: {
      hanging: {
        description: narration('linen-shape', 'hanging'),
        transitions: [
          {
            verb: 'wait',
            chipLabel: 'WAIT',
            narration: narration('linen-shape', 'wait-resolved'),
            to: 'resolved',
          },
        ],
      },
    },
    onResolved: { setFlags: { linenShapeEmpty: true } },
    onFailed: { narration: narration('linen-shape', 'failed'), retreatTo: 'servants-passage' },
    defaultWrongVerbNarration: narration('linen-shape', 'wrong-verb'),
  },
 }
@@ -0,0 +1,55 @@
 ---
 id: basilisk
 startsIn: "[[chapel]]"
 initialPhase: sleeping
 aliases: [basilisk, creature, eye, altar, coil]
 onResolved:
  setFlags:
    basiliskSpared: true
 onFailed:
  narration: failed
  retreatTo: "[[vault]]"
 defaultWrongVerbNarration: wrong-verb
 phases:
  sleeping:
    description: sleeping
    transitions:
      - verb: pour
        target: silver-vial
        chipLabel: POUR VIAL
        chipCommand: pour vial on basilisk
        requires:
          item: "[[silver-vial]]"
        narration: pour-vial-resolved
        to: resolved
      - verb: use
        target: basilisk
        chipLabel: USE VIAL
        chipCommand: use basilisk with vial
        requires:
          item: "[[silver-vial]]"
        narration: pour-vial-resolved
        to: resolved
 ---
 ## sleeping
 Something large is coiled beneath the altar.
 You become aware of the eye first.
 Not glowing. Merely open.
 ## pour-vial-resolved
 The wax breaks beneath your thumb.
 You pour the vial over the cracked altar stone. The clear liquid disappears into it without running. Beneath the altar, the coil withdraws slowly, scale against stone, until there is only the smell of rain on dust.
 The eye closes last.
 ## wrong-verb
 The open eye receives the motion without interest.
 Your own eyes begin to water. You look away too late.
 ## failed
 The chapel floor tilts under you. When you find the wall, you are back in the vault with the taste of stone in your mouth.
@@ -0,0 +1,39 @@
 ---
 id: bone-keeper
 startsIn: "[[ossuary]]"
 initialPhase: arranging
 aliases: [bone keeper, keeper, hands, bones, ribs]
 onResolved:
  setFlags:
    burialRingPlaced: true
 onFailed:
  narration: failed
  retreatTo: "[[tunnel]]"
 defaultWrongVerbNarration: wrong-verb
 phases:
  arranging:
    description: arranging
    transitions:
      - verb: drop
        target: "[[burial-ring]]"
        chipLabel: LEAVE RING
        chipCommand: leave ring
        requires:
          item: "[[burial-ring]]"
        narration: leave-burial-ring-resolved
        to: resolved
 ---
 ## arranging
 Something kneels before the shelves of bone. It has no face you can make out, only hands, and the hands are placing ribs in order of size.
 ## leave-burial-ring-resolved
 You set the ring among the bones.
 The hands stop their work. One finger touches the crest, gently, and the shelves settle as if relieved of a small but unbearable error.
 ## wrong-verb
 The arranging hands pause. A rib turns slowly in their grip.
 ## failed
 The bones clatter all at once. You retreat to the tunnel with the sound following you in pieces.
@@ -2,6 +2,22 @@
 id: breathing-wall
 startsIn: "[[servants-passage]]"
 initialPhase: audible
 aliases: [breathing wall, wall, walls, breathing]
 onResolved:
  setFlags:
    breathingWallPassed: true
 onFailed:
  narration: failed
  retreatTo: "[[music-room]]"
 defaultWrongVerbNarration: wrong-verb
 phases:
  audible:
    description: audible
    transitions:
      - verb: wait
        chipLabel: WAIT
        narration: wait-resolved
        to: resolved
 ---
 ## audible
@@ -10,10 +26,10 @@ The wall beside your shoulder breathes in. The opposite wall answers.
 ## wait-resolved
 You stand still.
-The passage narrows, then forgets to. The breathing passes on ahead of you.
+The passage narrows, then forgets to. The breathing passes on ahead of you, down the wall and out of reach.
 ## wrong-verb
 The walls take a slower breath.
 ## failed
-The boards lean close enough to touch your sleeves. You retreat into the music room.
+The boards lean close enough to touch your sleeves. You retreat into the music room before they can close around you.
@@ -0,0 +1,60 @@
 ---
 id: child-beneath-well
 startsIn: "[[well-shaft]]"
 initialPhase: climbing
 aliases: [child, well child, child beneath well, barefoot child]
 onResolved:
  setFlags:
    childPassedWell: true
 onFailed:
  narration: failed
  retreatTo: "[[well]]"
 defaultWrongVerbNarration: wrong-verb
 phases:
  climbing:
    description: climbing
    transitions:
      - verb: hold
        target: "[[toy-dog]]"
        chipLabel: SHOW DOG
        chipCommand: hold dog
        requires:
          item: "[[toy-dog]]"
        narration: hold-toy-dog-resolved
        setFlags:
          woofReturned: true
        to: resolved
      - verb: wait
        chipLabel: WAIT
        narration: wait-resolved
        to: resolved
 ---
 ## climbing
 Something moves below before you do.
 A child emerges from the tunnel beneath the well, barefoot and breathless, one hand against the stone wall as it climbs past you. It does not stop. A draft of cold air follows after it.
 Then it is gone upward toward the garden.
 ## hold-toy-dog-resolved
 The child pauses at the garden gate.
 "You found Woof."
 Or perhaps: "Wolf."
 The child takes the toy carefully and disappears into the overgrowth.
 The garden grows quieter afterward.
 ## wait-resolved
 You let the child climb past.
 Small bare feet find the rungs without looking. The cold draft follows upward, and after a while the shaft is only stone again.
 ## wrong-verb
 The child does not look at you. It climbs as if something below still has its name.
 ## failed
 The cold rises too quickly. You climb back to the well with your hands numb around the rungs.
@@ -2,6 +2,24 @@
 id: covered-cage
 startsIn: "[[smoking-room]]"
 initialPhase: rustling
 aliases: [covered cage, cage, birdcage, cloth]
 onResolved:
  setFlags:
    cageUncovered: true
 onFailed:
  narration: failed
  retreatTo: "[[hallway]]"
 defaultWrongVerbNarration: wrong-verb
 phases:
  rustling:
    description: rustling
    transitions:
      - verb: open
        target: covered-cage
        chipLabel: UNCOVER CAGE
        chipCommand: uncover cage
        narration: open-covered-cage-resolved
        to: resolved
 ---
 ## rustling
@@ -15,7 +33,7 @@ The cage is empty. A few pale feathers cling to the wire, though no bird could h
 Somewhere far above you, wings beat once inside a wall.
 ## wrong-verb
-The cloth trembles.
+The cloth trembles, then goes still again.
 ## failed
-The rustling grows too close to your ear. You leave the room before you decide to.
+The rustling grows too close to your ear. You leave the room before you decide to, and the cage is still covered when you look back.
@@ -0,0 +1,45 @@
 ---
 id: creaking-floorboard
 startsIn: "[[drunk-landing]]"
 initialPhase: creaking
 aliases: [creaking floorboard, floorboard, board, creak, secret door, faceless man, man, voice]
 defaultWrongVerbNarration: wrong-verb
 phases:
  creaking:
    description: creaking
    transitions:
      - verb: listen
        chipLabel: LISTEN
        chipCommand: listen
        narration: listen-resolved
        setFlags:
          drunkSecretFound: true
          facelessManMet: true
          houseDebtNamed: true
        to: resolved
      - verb: open
        target: creaking-floorboard
        chipLabel: OPEN BOARD
        chipCommand: open floorboard
        narration: listen-resolved
        setFlags:
          drunkSecretFound: true
          facelessManMet: true
          houseDebtNamed: true
        to: resolved
 ---
 ## creaking
 One floorboard creaks after you have stopped moving.
 It creaks again, softer, from under the wrong foot.
 ## listen-resolved
 You listen.
 The board lifts by itself. Beneath it is a narrow door, and behind the door a man without a face sits with his hands folded.
 "Halfstreet keeps what is owed," he whispers. "It does not know the difference between a debt and a child."
 ## wrong-verb
 The floorboard waits until you breathe, then creaks beneath that too.
@@ -0,0 +1,37 @@
 ---
 id: distant-steps
 startsIn: "[[wrong-hallway]]"
 initialPhase: approaching
 aliases: [distant steps, steps, footsteps, hallway]
 onResolved:
  setFlags:
    distantStepsPassed: true
 onFailed:
  narration: failed
  retreatTo: "[[parlor]]"
 defaultWrongVerbNarration: wrong-verb
 phases:
  approaching:
    description: approaching
    transitions:
      - verb: wait
        chipLabel: WAIT
        narration: wait-resolved
        to: resolved
 ---
 ## approaching
 The footsteps come closer without growing louder.
 They stop whenever you move.
 ## wait-resolved
 You stand still.
 The steps pass through you with the cold, careful pressure of someone carrying a tray through a dark room. When they are gone, the hallway is shorter by one door.
 ## wrong-verb
 The hallway lengthens. The footsteps begin again from farther away.
 ## failed
 You turn back too quickly and find the parlor waiting with all its chairs facing you.
@@ -0,0 +1,35 @@
 ---
 id: garden-procession
 startsIn: "[[garden]]"
 initialPhase: passing
 aliases: [garden procession, procession, lanterns, lantern, lights, hedge]
 onResolved:
  setFlags:
    gardenQuiet: true
 onFailed:
  narration: failed
  retreatTo: "[[back-door]]"
 defaultWrongVerbNarration: wrong-verb
 phases:
  passing:
    description: passing
    transitions:
      - verb: wait
        chipLabel: WAIT
        narration: wait-resolved
        to: resolved
 ---
 ## passing
 Lanterns pass behind the hedge in a slow line. Each flame is held at the height of a face, but the leaves show no faces through them.
 ## wait-resolved
 You remain silent.
 The lanterns go by one after another, counting themselves in light. When the last has passed, the hedge exhales and the garden belongs to the rain again.
 ## wrong-verb
 The nearest lantern stops.
 ## failed
 The procession turns with one motion. You are back at the kitchen door before you remember retreating, and something in the hedge has learned your footstep.
@@ -2,6 +2,34 @@
 id: ivy-figure
 startsIn: "[[conservatory]]"
 initialPhase: hidden
 aliases: [ivy figure, figure, ivy, vines, vine]
 onResolved:
  setFlags:
    conservatoryVinesCut: true
 onFailed:
  narration: failed
  retreatTo: "[[dining-room]]"
 defaultWrongVerbNarration: wrong-verb
 phases:
  hidden:
    description: hidden
    transitions:
      - verb: cut
        target: ivy-figure
        chipLabel: CUT VINES
        chipCommand: cut vines
        requires:
          item: "[[pruning-shears]]"
        narration: cut-ivy-figure-resolved
        to: resolved
      - verb: use
        target: ivy-figure
        chipLabel: USE SHEARS
        chipCommand: use vines with shears
        requires:
          item: "[[pruning-shears]]"
        narration: cut-ivy-figure-resolved
        to: resolved
 ---
 ## hidden
@@ -13,7 +41,7 @@ The shears close with a sound like teeth.
 The figure falls apart leaf by leaf. Behind it, the glass is only glass.
 ## wrong-verb
-The vines tighten without moving.
+The vines tighten without moving. Their silence feels deliberate.
 ## failed
-The ivy catches at your wrists. When you pull free, you are back among the cold plates of the dining room.
+The ivy catches at your wrists. When you pull free, you are back among the cold plates of the dining room, with leaves clinging to your sleeves.
@@ -2,10 +2,26 @@
 id: linen-shape
 startsIn: "[[laundry]]"
 initialPhase: hanging
 aliases: [linen shape, shape, sheet, sheets, linen]
 onResolved:
  setFlags:
    linenShapeEmpty: true
 onFailed:
  narration: failed
  retreatTo: "[[servants-passage]]"
 defaultWrongVerbNarration: wrong-verb
 phases:
  hanging:
    description: hanging
    transitions:
      - verb: wait
        chipLabel: WAIT
        narration: wait-resolved
        to: resolved
 ---
 ## hanging
-One hanging sheet has the weight and outline of a person standing behind it.
+One hanging sheet has the weight and outline of a person standing behind it. The shape shifts when you look straight at it.
 ## wait-resolved
 You wait.
@@ -13,7 +29,7 @@ You wait.
 The sheet stirs. Nothing stands behind it. Nothing had stood behind it.
 ## wrong-verb
-The shape seems to lean toward you.
+The shape seems to lean toward you, then settles back into stillness.
 ## failed
-You push through the hanging sheets and come out in the servants' passage, breathing hard.
+You push through the hanging sheets and come out in the servants' passage, breathing hard, with damp cloth brushing your face.
@@ -2,6 +2,24 @@
 id: piano-echo
 startsIn: "[[music-room]]"
 initialPhase: listening
 aliases: [piano echo, piano, note, key]
 onResolved:
  setFlags:
    musicSolved: true
 onFailed:
  narration: failed
  retreatTo: "[[hallway]]"
 defaultWrongVerbNarration: wrong-verb
 phases:
  listening:
    description: listening
    transitions:
      - verb: play
        target: piano-echo
        chipLabel: PLAY NOTE
        chipCommand: play note
        narration: play-piano-echo-resolved
        to: resolved
 ---
 ## listening
@@ -13,7 +31,7 @@ You play the waiting note.
 The answer comes at once, nearer than before. A narrow part of the wall settles back into shadow.
 ## wrong-verb
-The answering note repeats, patient and exact.
+The answering note repeats, patient and exact. It sounds as if it has not moved at all.
 ## failed
 The wrong chord goes through the floorboards. You climb back to the hallway before the echo finishes.
@@ -0,0 +1,37 @@
 ---
 id: portrait-woman
 startsIn: "[[burial-gallery]]"
 initialPhase: watching
 aliases: [portrait woman, woman, portrait, portraits, veil, funeral veil]
 onResolved:
  setFlags:
    familyResemblanceSeen: true
 onFailed:
  narration: failed
  retreatTo: "[[root-chamber]]"
 defaultWrongVerbNarration: wrong-verb
 phases:
  watching:
    description: watching
    transitions:
      - verb: examine
        target: portrait-woman
        chipLabel: EXAMINE PORTRAITS
        chipCommand: examine portraits
        narration: examine-portraits-resolved
        to: resolved
 ---
 ## watching
 One ruined portrait has not lost its eyes. The woman in it watches from behind a funeral veil, though the paint around her face has split to canvas.
 ## examine-portraits-resolved
 You examine the portraits one by one.
 Damage has made a family resemblance where blood may not have. Then the veiled woman's mouth, still painted, shows you the part you did not want to see: your own expression, waiting inside hers.
 ## wrong-verb
 The veiled portrait watches you with patient, damaged eyes.
 ## failed
 The veil lifts though nothing touches it. You step back into the root chamber before the face beneath can finish becoming familiar.
@@ -0,0 +1,46 @@
 ---
 id: rainwater-basin
 startsIn: "[[rain-room]]"
 initialPhase: reflecting
 aliases: [rainwater basin, basin, water, rainwater, reflection]
 onResolved:
  setFlags:
    rainRoomEntered: true
    houseAcceptedYou: true
 onFailed:
  narration: failed
  retreatTo: "[[wrong-hallway]]"
 defaultWrongVerbNarration: wrong-verb
 phases:
  reflecting:
    description: reflecting
    transitions:
      - verb: look
        target: rainwater-basin
        chipLabel: LOOK BASIN
        chipCommand: look basin
        narration: look-resolved
        to: resolved
      - verb: examine
        target: rainwater-basin
        chipLabel: EXAMINE BASIN
        chipCommand: examine basin
        narration: look-resolved
        to: resolved
 ---
 ## reflecting
 The basin shows no ceiling. It shows a hallway instead, and in that hallway a lamp going out.
 ## look-resolved
 You look into the rainwater.
 Rooms gather there one beneath another: nursery, chapel, vault, gate. For a moment they fit together correctly. Then your reflection enters them from the wrong side, and every door in the image opens inward.
 When you look up, the room has learned you.
 ## wrong-verb
 Rain touches your hands, though you are not beneath it.
 ## failed
 The rain rises without filling the basin. You step back into the wrong hallway before it reaches your mouth.
@@ -2,8 +2,25 @@
 id: rat
 startsIn: "[[cellar-stair]]"
 initialPhase: lurking
 onResolved:
  setFlags:
    ratGone: true
 defaultWrongVerbNarration: wrong-verb
 phases:
  lurking:
    description: lurking
    transitions:
      - verb: attack
        target: rat
        chipLabel: ATTACK RAT
        chipCommand: attack rat
        narration: attack-rat-resolved
        to: resolved
      - verb: wait
        chipLabel: WAIT
        narration: wait-stays
        to: lurking
 ---
 ![[Pasted image 20260509213136.png]]
 ## lurking
 A heavy rat watches you from the third step. Its eyes catch the light.
@@ -12,3 +29,6 @@ You stamp. The rat squeals and is gone into the dark.
 ## wait-stays
 The rat does not move. Neither do you.
 ## wrong-verb
 The rat watches.
@@ -0,0 +1,39 @@
 ---
 id: reflection
 startsIn: "[[flooded-passage]]"
 initialPhase: following
 aliases: [reflection, water, black water, face, reflected figure]
 onResolved:
  setFlags:
    reflectionObscured: true
 onFailed:
  narration: failed
  retreatTo: "[[ossuary]]"
 defaultWrongVerbNarration: wrong-verb
 phases:
  following:
    description: following
    transitions:
      - verb: use
        target: reflection
        chipLabel: USE SHEET
        chipCommand: use water with sheet
        requires:
          item: "[[damp-sheet]]"
        narration: obscure-water-resolved
        to: resolved
 ---
 ## following
 Your reflection in the black water is a half-second late. When you stop, it finishes the motion after you.
 ## obscure-water-resolved
 You spread the damp sheet across the water.
 The cloth drinks the reflection into itself. For a moment a face presses up beneath the linen, then slackens into ordinary wet cloth.
 ## wrong-verb
 The reflected figure takes a step you have not taken.
 ## failed
 The water rises without rising. You stumble back into the ossuary before the face below reaches the surface.
@@ -0,0 +1,36 @@
 ---
 id: root-movement
 startsIn: "[[root-chamber]]"
 initialPhase: shifting
 aliases: [root movement, roots, root, opening]
 onResolved:
  setFlags:
    rootsListenedTo: true
 onFailed:
  narration: failed
  retreatTo: "[[flooded-passage]]"
 defaultWrongVerbNarration: wrong-verb
 phases:
  shifting:
    description: shifting
    transitions:
      - verb: listen
        chipLabel: LISTEN
        chipCommand: listen
        narration: listen-resolved
        to: resolved
 ---
 ## shifting
 The roots stir whenever your light touches them. Their movement is slow, but every opening in the room is narrower than it was a breath ago.
 ## listen-resolved
 You put out the light and listen.
 In darkness, the roots stop pretending to be wood. They creak like a house settling around a sleeping child, then draw back from the eastern opening.
 ## wrong-verb
 The roots tighten against one another, dry fibers whispering overhead.
 ## failed
 The roots drop like ropes. You force your way back to the flooded passage with bark dust in your mouth.
@@ -0,0 +1,35 @@
 ---
 id: stair-sleeper
 startsIn: "[[stair-up]]"
 initialPhase: seated
 aliases: [stair sleeper, sleeper, figure, person, body]
 onResolved:
  setFlags:
    hallwayShifted: true
 onFailed:
  narration: failed
  retreatTo: "[[parlor]]"
 defaultWrongVerbNarration: wrong-verb
 phases:
  seated:
    description: seated
    transitions:
      - verb: wait
        chipLabel: WAIT
        narration: wait-resolved
        to: resolved
 ---
 ## seated
 Someone sits halfway up the stair with their back to you. Their head rests against the banister. One hand lies open on the runner.
 ## wait-resolved
 You do not speak.
 After a while, the figure leans aside, not waking. The stair above is not the same stair, but it is open.
 ## wrong-verb
 The seated figure draws one breath. The sound is too small for the body that made it.
 ## failed
 The sleeper turns before you see the face. The stair folds down under your feet, and the parlor receives you again.
@@ -0,0 +1,60 @@
 ---
 id: vault-memory
 startsIn: "[[vault]]"
 initialPhase: buried
 aliases: [vault memory, memory, bed, photograph, photo, thing, buried thing]
 defaultWrongVerbNarration: wrong-verb
 phases:
  buried:
    description: buried
    transitions:
      - verb: read
        target: family-register
        chipLabel: READ REGISTER
        chipCommand: read register
        requires:
          item: "[[family-register]]"
        narration: read-register-resolved
        setFlags:
          nameSpoken: true
        to: resolved
      - verb: take
        target: vault-memory
        chipLabel: TAKE PHOTO
        chipCommand: take photograph
        narration: take-photograph-resolved
        setFlags:
          tookPhotograph: true
        to: resolved
      - verb: attack
        target: vault-memory
        chipLabel: ATTACK BED
        chipCommand: attack bed
        narration: attack-bed-resolved
        setFlags:
          disturbedVault: true
        to: resolved
 ---
 ## buried
 The bed waits in the center of the vault. The photograph lies face down on the coverlet.
 The family register feels heavier here, as if all its missing pages have returned at once.
 ## read-register-resolved
 You read the name from the register.
 The letters are difficult only until you say them. Then they seem to have been waiting in your mouth since the gate.
 ## take-photograph-resolved
 You take the photograph.
 It is dry and light and terribly easy to lift.
 ## attack-bed-resolved
 You strike the little bed.
 The sound is small. The house hears it anyway.
 ## wrong-verb
 The photograph remains face down. The bedclothes do not stir.
@@ -2,10 +2,28 @@
 id: window-guest
 startsIn: "[[dining-room]]"
 initialPhase: standing-outside
 aliases: [guest, window guest, curtains, curtain, window]
 onResolved:
  setFlags:
    curtainsClosed: true
 onFailed:
  narration: failed
  retreatTo: "[[hallway]]"
 defaultWrongVerbNarration: wrong-verb
 phases:
  standing-outside:
    description: standing-outside
    transitions:
      - verb: close
        target: window-guest
        chipLabel: CLOSE CURTAINS
        chipCommand: close curtains
        narration: close-window-guest-resolved
        to: resolved
 ---
 ## standing-outside
-Rain touches the dining-room window from the wrong side. Someone stands beyond the glass with their head bowed.
+Rain touches the dining-room window from the wrong side. Someone stands beyond the glass with their head bowed. Their coat is too dark to make out properly.
 ## close-window-guest-resolved
 You draw the curtains together before you look closely.
@@ -13,7 +31,7 @@ You draw the curtains together before you look closely.
 For a moment, cloth and rain hold the same shape. Then there is only the table behind you.
 ## wrong-verb
-The figure outside lifts its face a little.
+The figure outside lifts its face a little, as if disappointed by your hesitation.
 ## failed
-The glass shows too much. You find yourself back in the hallway with the taste of rain in your mouth.
+The glass shows too much. For one instant there is a second dining room beyond it. Then you are back in the hallway with rain in your mouth.
@@ -1,6 +1,13 @@
 ---
 id: bad
 whenFlags:
-  _never: true
+  tookPhotograph: true
 ---
 You take the photograph.
 The child in it is you.
 Behind you, on the stairs, someone has come up to meet you.
 You do not go down again.
@@ -0,0 +1,17 @@
 ---
 id: mercy
 whenFlags:
  nameSpoken: true
  woofReturned: true
  basiliskSpared: true
  burialRingPlaced: true
  familyResemblanceSeen: true
 ---
 You remain in the vault until the lamp goes out.
 The house is quiet.
 Somewhere above, floorboards settle one final time.
 By morning, Halfstreet contains one fewer restless thing.
@@ -0,0 +1,15 @@
 ---
 id: replacement
 whenFlags:
  houseAcceptedYou: true
  rainRoomEntered: true
  hallwayShifted: true
 ---
 You open the front door.
 Someone is standing at the gate outside.
 They look tired. Rain-darkened. Lost.
 After a moment, you understand they have arrived for you.
@@ -1,7 +1,18 @@
 ---
 id: true
 whenFlags:
-  ratGone: true
+  nameSpoken: true
  basiliskSpared: true
  burialRingPlaced: true
  familyResemblanceSeen: true
 ---
-You stand at the top of the stair. The thing below has settled. The door behind you opens, and outside, finally, is morning.
+You stand in the vault. What is buried at Halfstreet is buried because it was loved, and grieved, and finally let go.
 You set the lamp beside it.
 You speak the name aloud.
 The house settles around you like a long exhalation.
 Outside, the road exists again.
@@ -1,6 +1,15 @@
 ---
 id: wrong
 whenFlags:
-  _never: true
+  disturbedVault: true
 ---
 You disturb what should have remained untouched.
 The house rearranges itself around your leaving.
 Corridors repeat.
 Doors return you to themselves.
 The hallway grows longer.
@@ -0,0 +1,47 @@
 ---
 id: halfstreet
 title: Halfstreet
 description: A gothic mystery.
 startingRoom: "[[outside-gate]]"
 startingInventory:
  - "[[letter]]"
  - "[[matches]]"
  - "[[broken-cigarette]]"
 endingPriority:
  - mercy
  - "true"
  - replacement
  - bad
  - wrong
 transcriptCap: 200
 ---
 ## opening-art
 _   _       _  __     ____  _                 _
 | | | | __ _| |/ _|   / ___|| |_ _ __ ___  ___| |_
 | |_| |/ _` | | |_    \___ \| __| '__/ _ \/ _ \ __|
 |  _  | (_| | |  _|    ___) | |_| | |  __/  __/ |_
 |_| |_|\__,_|_|_|     |____/ \__|_|  \___|\___|\__|
 ## help
 You arrive at the address, but you do not remember what has happened. The road behind you is gone...
 This is a text adventure. Type short commands to act in the house.
 Common commands:
 look                    describe the room again
 n, s, e, w, u, d        move by direction
 take lamp               pick something up
 examine letter          inspect something nearby or held
 read letter             read a readable object
 inventory               see what you carry
 light lamp with matches use one thing with another
 wait                    let the room continue
 undo                    step back once
 restart                 begin again
 theme                   change the terminal colors
 Most commands are verb first, then the thing: examine gate, take lamp, use key on door.
 ## ended
 The story has ended. Type `restart` or `undo`.
@@ -1,15 +1,37 @@
-import type { World, Room, Item } from './types'
+import type { World, Room, Item, GameManifest, EncounterDef } from './types'
 import {
  parseAction,
  parseGame,
  parseLightMechanic,
  parseMessages,
  parseParser,
  parseUi,
  parseResolveMechanic,
  parseRoom,
  parseItem,
  parseEnding,
  parseEncounterNarration,
  type ParsedEncounterNarration,
 } from './loader'
 // Importing loader (above) triggers auto-registration of encounter narrations.
 // ESM evaluates dependencies first, so by the time encounters.ts is evaluated below,
 // narration() can resolve all keys.
 import { encounters } from './encounters'
 const gameFiles = import.meta.glob<string>('./game.md', {
  eager: true, query: '?raw', import: 'default',
 })
 const parserFiles = import.meta.glob<string>('./parser.md', {
  eager: true, query: '?raw', import: 'default',
 })
 const uiFiles = import.meta.glob<string>('./ui.md', {
  eager: true, query: '?raw', import: 'default',
 })
 const messageFiles = import.meta.glob<string>('./messages.md', {
  eager: true, query: '?raw', import: 'default',
 })
 const mechanicFiles = import.meta.glob<string>('./mechanics/*.md', {
  eager: true, query: '?raw', import: 'default',
 })
 const actionFiles = import.meta.glob<string>('./actions/*.md', {
  eager: true, query: '?raw', import: 'default',
 })
 const roomFiles = import.meta.glob<string>('./rooms/*.md', {
  eager: true, query: '?raw', import: 'default',
 })
@@ -23,11 +45,48 @@ const encounterFiles = import.meta.glob<string>('./encounters/*.md', {
  eager: true, query: '?raw', import: 'default',
 })
 // Re-parse encounter docs here so we can validate startsIn / initialPhase against encounters.ts.
 // (The loader already auto-registered narrations from these same files at module init.)
 const encounterDocs = Object.entries(encounterFiles).map(([path, raw]) =>
  parseEncounterNarration(raw, path),
 )
 const markdownEncounters: Record<string, EncounterDef> = {}
 for (const doc of encounterDocs) {
  if (!doc.encounter) {
    throw new Error(`encounters/${doc.id}.md is missing phases frontmatter`)
  }
  if (markdownEncounters[doc.id]) throw new Error(`encounters/${doc.id}.md: duplicate markdown encounter id "${doc.id}"`)
  markdownEncounters[doc.id] = doc.encounter
 }
 const encounters: Record<string, EncounterDef> = markdownEncounters
 const gameEntry = Object.entries(gameFiles)[0]
 if (!gameEntry) {
  throw new Error('world/game.md is missing')
 }
 const game = parseGame(gameEntry[1], gameEntry[0])
 const parserEntry = Object.entries(parserFiles)[0]
 if (!parserEntry) {
  throw new Error('world/parser.md is missing')
 }
 const parser = parseParser(parserEntry[1], parserEntry[0])
 const uiEntry = Object.entries(uiFiles)[0]
 const ui = uiEntry ? parseUi(uiEntry[1], uiEntry[0]) : undefined
 const messageEntry = Object.entries(messageFiles)[0]
 const messages = messageEntry ? parseMessages(messageEntry[1], messageEntry[0]) : undefined
 const mechanics: World['mechanics'] = {}
 for (const [path, raw] of Object.entries(mechanicFiles)) {
  if (path.endsWith('/light.md')) {
    mechanics.light = parseLightMechanic(raw, path)
  } else if (path.endsWith('/resolve.md')) {
    mechanics.resolve = parseResolveMechanic(raw, path)
  }
 }
 const actions: NonNullable<World['actions']> = {}
 for (const [path, raw] of Object.entries(actionFiles)) {
  const action = parseAction(raw, path)
  if (actions[action.id]) throw new Error(`${path}: duplicate action id "${action.id}"`)
  actions[action.id] = action
 }
 // Build rooms map.
 const rooms: Record<string, Room> = {}
@@ -46,85 +105,179 @@ for (const [path, raw] of Object.entries(itemFiles)) {
 }
 // Build endings.
-const endings: World['endings'] = {
+const endings: World['endings'] = {}
  true: { whenFlags: {}, narration: '' },
  wrong: { whenFlags: {}, narration: '' },
  bad: { whenFlags: {}, narration: '' },
 }
 const seenEndings = new Set<string>()
 for (const [path, raw] of Object.entries(endingFiles)) {
  const { id, ending } = parseEnding(raw, path)
  if (seenEndings.has(id)) throw new Error(`${path}: duplicate ending id "${id}"`)
  endings[id] = ending
  seenEndings.add(id)
 }
-const requiredEndings = ['true', 'wrong', 'bad'] as const
+
-for (const id of requiredEndings) {
+interface AssembleWorldInput {
-  if (!seenEndings.has(id)) {
+  game: GameManifest
-    throw new Error(`endings/${id}.md is missing — every ending id must have a markdown file.`)
+  ui?: World['ui']
-  }
+  parser?: World['parser']
  messages?: World['messages']
  mechanics?: World['mechanics']
  actions?: World['actions']
  rooms: Record<string, Room>
  items: Record<string, Item>
  endings: World['endings']
  encounters: Record<string, EncounterDef>
  encounterDocs: ParsedEncounterNarration[]
 }
-// Cross-reference validation.
+export function assembleWorld({
-// Build set of all known flag names from encounter setFlags and ending whenFlags.
+  game,
-const knownFlags = new Set<string>()
+  ui,
-for (const enc of Object.values(encounters)) {
+  parser,
-  if (enc.onResolved?.setFlags) {
+  messages,
-    for (const flagName of Object.keys(enc.onResolved.setFlags)) knownFlags.add(flagName)
+  mechanics,
  actions,
  rooms,
  items,
  endings,
  encounters,
  encounterDocs,
 }: AssembleWorldInput): World {
  // Build set of all known flag names from encounter setFlags and ending whenFlags.
  const knownFlags = new Set<string>()
  for (const enc of Object.values(encounters)) {
    if (enc.onResolved?.setFlags) {
      for (const flagName of Object.keys(enc.onResolved.setFlags)) knownFlags.add(flagName)
    }
  }
  for (const action of Object.values(actions ?? {})) {
    if (action.setsFlags) {
      for (const flagName of Object.keys(action.setsFlags)) knownFlags.add(flagName)
    }
  }
  for (const ending of Object.values(endings)) {
    for (const flagName of Object.keys(ending.whenFlags)) knownFlags.add(flagName)
  }
 }
 for (const ending of Object.values(endings)) {
  for (const flagName of Object.keys(ending.whenFlags)) knownFlags.add(flagName)
 }
-for (const room of Object.values(rooms)) {
+  for (const id of game.endingPriority) {
-  for (const [dir, dest] of Object.entries(room.exits)) {
+    if (!endings[id]) {
-    if (!rooms[dest!]) {
+      throw new Error(`game.md: endingPriority references "${id}" but endings/${id}.md is missing.`)
      throw new Error(`rooms/${room.id}.md: exit${dir.toUpperCase()} references "${dest}" but no such room exists.`)
    }
  }
-  for (const itemId of room.items) {
+
-    if (!items[itemId]) {
+  for (const room of Object.values(rooms)) {
-      throw new Error(`rooms/${room.id}.md: items[] references unknown item "${itemId}"`)
+    for (const [dir, dest] of Object.entries(room.exits)) {
      if (!rooms[dest!]) {
        throw new Error(`rooms/${room.id}.md: exit${dir.toUpperCase()} references "${dest}" but no such room exists.`)
      }
    }
-  }
+    for (const itemId of room.items) {
-  if (room.encounter && !encounters[room.encounter]) {
+      if (!items[itemId]) {
-    throw new Error(`rooms/${room.id}.md: encounter "${room.encounter}" is not defined`)
+        throw new Error(`rooms/${room.id}.md: items[] references unknown item "${itemId}"`)
-  }
+      }
-  if (room.lockedExits) {
+    }
-    for (const [dir, lock] of Object.entries(room.lockedExits)) {
+    if (room.encounter && !encounters[room.encounter]) {
-      const isItem = items[lock.requires] !== undefined
+      throw new Error(`rooms/${room.id}.md: encounter "${room.encounter}" is not defined`)
-      const isFlag = knownFlags.has(lock.requires)
+    }
-      if (!isItem && !isFlag) {
+    if (room.lockedExits) {
-        const knownItemList = Object.keys(items).join(', ') || '(none)'
+      for (const [dir, lock] of Object.entries(room.lockedExits)) {
-        const knownFlagList = [...knownFlags].join(', ') || '(none)'
+        const isItem = items[lock.requires] !== undefined
-        throw new Error(
+        const isFlag = knownFlags.has(lock.requires)
-          `rooms/${room.id}.md: exit${dir.toUpperCase()}Requires "${lock.requires}" matches no known item or flag. ` +
+        if (!isItem && !isFlag) {
-          `Known items: ${knownItemList}. Known flags: ${knownFlagList}.`,
+          const knownItemList = Object.keys(items).join(', ') || '(none)'
-        )
+          const knownFlagList = [...knownFlags].join(', ') || '(none)'
          throw new Error(
            `rooms/${room.id}.md: exit${dir.toUpperCase()}Requires "${lock.requires}" matches no known item or flag. ` +
            `Known items: ${knownItemList}. Known flags: ${knownFlagList}.`,
          )
        }
      }
    }
  }
 }
-// Validate encounter narration registry: every encounter in TS has a markdown doc.
+  if (!rooms[game.startingRoom]) {
-for (const enc of Object.values(encounters)) {
+    throw new Error(`game.md: startingRoom references "${game.startingRoom}" but no such room exists.`)
  const doc = encounterDocs.find(d => d.id === enc.id)
  if (!doc) {
    throw new Error(`encounters/${enc.id}.md: missing narration markdown for encounter "${enc.id}"`)
  }
-  if (doc.startsIn !== enc.startsIn) {
+  for (const itemId of game.startingInventory) {
-    throw new Error(`encounters/${enc.id}.md: startsIn "${doc.startsIn}" does not match encounters.ts "${enc.startsIn}"`)
+    if (!items[itemId]) {
      throw new Error(`game.md: startingInventory references unknown item "${itemId}"`)
    }
  }
-  if (doc.initialPhase !== enc.initialPhase) {
+
-    throw new Error(`encounters/${enc.id}.md: initialPhase "${doc.initialPhase}" does not match encounters.ts "${enc.initialPhase}"`)
+  const actionHandlers = new Map<string, string>()
  for (const action of Object.values(actions ?? {})) {
    if (action.handler) {
      const previous = actionHandlers.get(action.handler)
      if (previous) {
        throw new Error(
          `actions/${action.id}.md: handler "${action.handler}" is already used by actions/${previous}.md. ` +
          'Only one action may own a handler-backed behavior.',
        )
      }
      actionHandlers.set(action.handler, action.id)
    }
    const referencedItems: Array<[string, string]> = [
      ...(action.requires?.allHeld ?? []).map((id): [string, string] => ['requires.allHeld', id]),
      ...(action.requires?.allVisibleOrHeld ?? []).map((id): [string, string] => ['requires.allVisibleOrHeld', id]),
      ...(action.consumes?.inventory ?? []).map((id): [string, string] => ['consumes.inventory', id]),
      ...(action.decrements ? [['decrements.item', action.decrements.item] as [string, string]] : []),
    ]
    for (const [field, itemId] of referencedItems) {
      if (!items[itemId]) {
        throw new Error(`actions/${action.id}.md: ${field} references unknown item "${itemId}"`)
      }
    }
    if (action.handler === 'drunk-transition') {
      const config = action.drunkTransition
      if (!config) {
        throw new Error(`actions/${action.id}.md uses drunk-transition but is missing drunkTransition config`)
      }
      for (const [key, roomId] of Object.entries({
        destinationRoom: config.destinationRoom,
        wakeRoom: config.wakeRoom,
        resetRoom: config.resetRoom,
      })) {
        if (!rooms[roomId]) {
          throw new Error(`actions/${action.id}.md: drunkTransition.${key} references unknown room "${roomId}"`)
        }
      }
    }
  }
  // Validate encounter narration registry: every encounter has a markdown doc.
  for (const enc of Object.values(encounters)) {
    const doc = encounterDocs.find(d => d.id === enc.id)
    if (!doc) {
      throw new Error(`encounters/${enc.id}.md: missing narration markdown for encounter "${enc.id}"`)
    }
  }
  return {
    game,
    ui,
    parser,
    messages,
    mechanics,
    actions,
    startingRoom: game.startingRoom,
    startingInventory: game.startingInventory,
    endingPriority: game.endingPriority,
    rooms,
    items,
    encounters,
    endings,
  }
 }
-export const world: World = {
+export const world: World = assembleWorld({
-  startingRoom: 'outside-gate',
+  game,
-  startingInventory: ['letter', 'matches', 'broken-cigarette'],
+  ui,
  parser,
  messages,
  mechanics,
  actions,
  rooms,
  items,
  encounters,
  endings,
-}
+  encounterDocs,
 })
@@ -0,0 +1,9 @@
 ---
 id: altar-stone
 names: ["altar", "altar stone", "cracked altar", "altar-stone"]
 short: "a cracked altar stone"
 takeable: false
 initialState: {}
 ---
 The altar has split across the center. The crack is narrow enough to hide a thread and deep enough to swallow light.
@@ -0,0 +1,9 @@
 ---
 id: burial-ring
 names: ["ring", "burial ring", "crest ring", "burial-ring"]
 short: "a burial ring"
 takeable: true
 initialState: {}
 ---
 The ring is too small for your hand. A worn crest remains on its face: a gate, a vine, and something below them that may be a well or an eye.
@@ -8,10 +8,10 @@ initialState:
  lit: false
 ---
-A brass candlestick, heavy at the base. The candle inside it is burned low but not spent.
+A brass candlestick, heavy at the base. The candle inside it is burned low but not spent. It holds a little light very steadily, as if it dislikes being noticed.
 ## lit
-The wick takes. The flame bends toward the nearest doorway.
+The wick takes. The flame stands upright for a moment, then bends toward the nearest doorway.
 ## extinguished
-The candle gutters out. For a moment the smoke leans against your hand.
+The candle gutters out. For a moment the smoke leans against your hand before it thins.
@@ -0,0 +1,15 @@
 ---
 id: childs-drawing
 names: ["drawing", "child's drawing", "childs drawing", "crayon drawing", "childs-drawing"]
 short: "a child's drawing"
 takeable: false
 readable: true
 initialState: {}
 ---
 A child's drawing is pinned to the wall with two black tacks. It shows a hallway with too many doors and a small square room where the house has no room to keep one.
 ## read
 Beneath the drawing, in blunt blue crayon, someone has written:
 NOT THIS HALL
@@ -6,4 +6,4 @@ takeable: true
 initialState: {}
 ---
-A sheet still wet from some old washing. It smells of rainwater and closed rooms.
+A sheet still wet from some old washing. It smells of rainwater and closed rooms. It keeps the cold longer than cloth should.
@@ -0,0 +1,15 @@
 ---
 id: family-register
 names: ["register", "ledger", "family register", "family-register"]
 short: "a family register"
 takeable: true
 readable: true
 initialState: {}
 ---
 The register is bound in black cloth, swollen at the corners from damp. Several pages have been cut out so neatly that their absence feels official.
 ## read
 Names repeat across three generations. Births answer deaths. Deaths answer births.
 One name appears in a different hand each time, always beside the same date, always corrected and written again beneath itself.
@@ -1,15 +1,20 @@
 ---
 id: matches
-names: ["matches", "safety matches", "matchbook", "box"]
+names:
-short: "a matchbook"
+  - matches
  - match
  - safety matches
  - matchbook
  - box
 short: a matchbook
 takeable: true
 lighter: true
-lighterUses: 4
+lighterUses: 5
 initialState:
-  uses: 4
+  uses: 5
 ---
-A damp matchbook with four matches left inside.
+A damp matchbook with five matches left inside.
 ## lighter-empty
 The last match flares, burns down, and goes out. The book is empty.
@@ -6,4 +6,4 @@ takeable: true
 initialState: {}
 ---
-A tiny key on a black ribbon. It is too small for any door in the house.
+A tiny key on a black ribbon. It is too small for any door in the house, and yet the ribbon has been tied and retied as if someone meant to keep it safe.
@@ -0,0 +1,10 @@
 ---
 id: music-box
 names: ["music box", "box", "nursery music box", "music-box"]
 short: "a bolted music box"
 takeable: false
 initialState:
  wound: false
 ---
 The music box is bolted to the nursery shelf. A tiny keyhole waits below a painted house with all its windows shut.
@@ -0,0 +1,9 @@
 ---
 id: portrait-frame
 names: ["frame", "portrait frame", "shattered frame", "portrait-frame"]
 short: "a shattered portrait frame"
 takeable: false
 initialState: {}
 ---
 The backing has warped away from the frame. Someone wrote beneath it, then scratched the writing into harmless lines.
@@ -6,4 +6,4 @@ takeable: true
 initialState: {}
 ---
-Iron pruning shears with dark soil in the hinge. The handles are cold through your palm.
+Iron pruning shears with dark soil in the hinge. The handles are cold through your palm. They have been used often enough to remember the shape of branches.
@@ -0,0 +1,11 @@
 ---
 id: rainwater-basin
 names: ["basin", "rainwater basin", "rainwater", "water", "rainwater-basin"]
 short: "a rainwater basin"
 takeable: false
 initialState: {}
 ---
 The basin is cut directly into the floor. Rain strikes its surface without making rings.
 If you lean near it, the water shows rooms you have already left.
@@ -0,0 +1,11 @@
 ---
 id: rusted-key
 names: ["key", "rusted key", "rusted-key"]
 short: "a rusted key"
 takeable: true
 initialState: {}
 ---
 The key is furred with rust except where fingers have worried the bow clean. Its teeth are thin, almost eaten through.
 It smells faintly of rain.
@@ -7,4 +7,4 @@ lighter: true
 initialState: {}
 ---
-A silver lighter with a worn crest on one side. It opens with a small reluctant click.
+A silver lighter with a worn crest on one side. It opens with a small reluctant click, then catches as if it had been waiting to be asked.
@@ -0,0 +1,11 @@
 ---
 id: silver-vial
 names: ["vial", "silver vial", "silver-vial"]
 short: "a silver vial"
 takeable: true
 initialState: {}
 ---
 The vial is cold enough to sting your fingers. Its stopper has been sealed with black wax and pressed with the same worn crest: gate, vine, and the shape beneath them.
 Something clear moves inside, though the vial is still.
@@ -0,0 +1,9 @@
 ---
 id: toy-boat
 names: ["toy boat", "wooden boat", "boat", "toy-boat"]
 short: "a wooden toy boat"
 takeable: true
 initialState: {}
 ---
 The boat has been carved from a single piece of soft wood. Its mast is broken. Along one side, a child's thumbnail has pressed a row of moons into the paint.
@@ -0,0 +1,20 @@
 ---
 id: toy-dog
 names: ["toy dog", "stuffed dog", "dog", "woof", "wolf", "toy-dog"]
 short: "a stuffed dog"
 takeable: true
 initialState: {}
 ---
 The toy dog is several shades darker than it used to be.  
 His fur is matted down in areas and worn from years of handling.
 A name is stitched into one paw in faded blue thread:
 WOOF
 Or perhaps:
 WOLF
 The stitching has begun to loosen.
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
ejlewis	89bb69bcfa	chore: obsidian docs ci/woodpecker/push/woodpecker Pipeline was successful Details	2026-05-17 23:35:13 -05:00
ejlewis	18aa517319	feat(ui): add bug reporting integrations	2026-05-17 23:34:17 -05:00
ejlewis	a51bb6f86f	docs: implementation plan for bug reporting Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-17 23:02:46 -05:00
ejlewis	4f6460297f	docs: design for Bugpin + Bugsink bug reporting Footer link triggers Bugpin's screenshot widget (lazy-loaded) which forwards to GitHub Issues. Bugsink captures uncaught JS errors via the Sentry SDK. Both servers live on the half.st host. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	2026-05-17 22:57:34 -05:00
ejlewis	03482693ea	Open source markdown authoring workflow ci/woodpecker/push/woodpecker Pipeline was successful Details	2026-05-13 17:59:13 -05:00
ejlewis	7b1b5d0f6c	chore: add build number and release scripts ci/woodpecker/push/woodpecker Pipeline was successful Details	2026-05-12 20:52:35 -05:00
ejlewis	e7b74c827a	fix(engine): burn lamp one segment per wait	2026-05-12 20:31:50 -05:00
ejlewis	52fb869976	feat(mystery): add altered rooms and drunk sequence	2026-05-12 20:22:20 -05:00
ejlewis	0755213d6a	feat(ui): add confirmations and terminal motion ci/woodpecker/push/woodpecker Pipeline was successful Details	2026-05-12 19:44:18 -05:00
ejlewis	cc98aa180b	feat(world): expand Halfstreet content slices ci/woodpecker/push/woodpecker Pipeline was successful Details	2026-05-12 14:48:19 -05:00
ejlewis	26dd91947f	feat: add kitchen and glitchtip wiring ci/woodpecker/push/woodpecker Pipeline was successful Details	2026-05-10 12:03:12 -05:00
ejlewis	4d9077d586	feat(world): add light timer and indicator ci/woodpecker/push/woodpecker Pipeline was successful Details	2026-05-10 10:17:42 -05:00
ejlewis	d56c0c8363	Implement match interactions and wait chip ci/woodpecker/push/woodpecker Pipeline was successful Details	2026-05-10 07:56:31 -05:00
ejlewis	83e4877852	feat(content): add upper floor slice	2026-05-10 07:34:51 -05:00