@frotzinc/zcode-ui 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to `@frotzinc/zcode-ui`. Versions follow [Semantic Versioning](https://semver.org/). Part of [frotz, Inc.](https://frotzinc.com).
+
+## [0.2.0] - 2026-11-08
+
+The views light a running machine (frotztrace Phase 4). Without `live` or `breakpoints`, each renders exactly as before.
+
+### Added
+- **`Disassembly`**: with `live`, the PC's line is marked (with "current instruction" for screen readers); with `breakpoints`, a gutter button per line (`aria-pressed`) emits `toggleBreakpoint`.
+- **`GlobalsView`**: with `live`, a "Now" column read from the running machine's memory, and the globals changed since the last stop marked "changed".
+- **`MapView`**: with `live`, the player's room (`real_location`, or `location`) is marked and the visited rooms shaded, with "you are here" and "visited" in the list.
+- **`useSymbols().symbolsText`**: the debug file's text as read, so frotzlens can hand it to frotztrace.
+- **`ObjectTree`** and **`HexPane`**: with `live`, what changed is lit, with a "changed" badge or count as its text equivalent. Give `ObjectTree` a story whose objects are read live (`zcode`'s `liveTables`) to show the tree as it is now.
+
+## [0.1.1] - 2026-11-08
+
+### Changed
+- `MachineView` is now the Debugger's own type from `@frotzinc/zmachine` (0.2.0), re-exported; the same shape as the placeholder it replaces. `@frotzinc/zmachine` is a new dependency, for the type.
+
+## [0.1.0] - 2026-11-08
+
+The first release: frotzlens's story views, moved out of the app (and relicensed MIT by their author) so frotztrace can show a running story with the same components.
+
+### Added
+- **Views:** `ObjectTree`, `GlobalsView`, `MapView`, `SearchPalette`, and `AppNav`, which now takes the app's list of views (`views`, `active`) instead of building frotzlens's.
+- **New, split out of frotzlens's views:** `Disassembly` (from the routine view) and `HexPane` (from the memory view; `v-model:top`, `notes`, `inRange`).
+- **Parts:** `RefLink`, `Referrers`, `ViewHeader`, `CopyText`, `StatTile`, `NotFound`.
+- **Composables and utils:** `useHashRoute`, `useSymbols`, `activeSymbols`, the naming and routing utils (`hex`, `idRoute`, `idLabel`, `routineName`, …), `useLimit`, `storyIndex`, `layoutMap`.
+- **`MachineView`**, the type of the optional `live` prop the views take; a placeholder until `@frotzinc/zmachine` exports the real one. A view given no `live` (or one, in this release) renders as before.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christopher Schweda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @frotzinc/zcode-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Z-machine story views of [frotzlens](https://frotzlens.frotzinc.com), as a Nuxt layer, so that frotzlens (a story file at rest) and frotztrace (a story running under a debugger) show a story with the same components, the same links and the same look. Part of [frotz, Inc.](https://frotzinc.com)
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ['@frotzinc/nuxt-base', '@frotzinc/zcode-ui'],
+  modules: ['@nuxt/ui'],
+})
+```
+
+Everything below is auto-imported. The story is a `StoryFile` from [`@frotzinc/zcode`](https://www.npmjs.com/package/@frotzinc/zcode).
+
+| | |
+|---|---|
+| **Views** | `ObjectTree` (an ARIA tree), `GlobalsView`, `MapView`, `Disassembly` (one routine, txd's layout, every operand a link), `HexPane` (paged hex with "Go to address"), `SearchPalette` (⌘K / Ctrl+K), `AppNav` (takes the app's own list of views) |
+| **Parts** | `RefLink`, `Referrers`, `ViewHeader`, `CopyText`, `StatTile`, `NotFound` |
+| **Composables** | `useHashRoute` (the view is the URL hash: `#routine/27f8`), `useSymbols` (names from Inform's `gameinfo.dbg`; `activeSymbols`) |
+| **Utils** | `hex`, `idRoute`, `idLabel`, `routineName`, `objectName`, `globalName`, `attributeName`, `propertyName`, `actionName`, `useLimit`, `storyIndex`, `layoutMap`; the types `MachineView` and `NavView` (also importable as `@frotzinc/zcode-ui/utils/live` and `/utils/nav`) |
+
+**The look is not here.** Colors, fonts and the family shell (header, footer, About menu) are [`@frotzinc/nuxt-base`](https://www.npmjs.com/package/@frotzinc/nuxt-base)'s, and this layer adds none, so frotzsmith, frotzlens, frotzplay and frotztrace look like one product, dark by default.
+
+**`live`.** `ObjectTree`, `GlobalsView`, `MapView`, `Disassembly` and `HexPane` take an optional `live` prop, a `MachineView` (the program counter, the frame, what changed since the last stop). In 0.1 it is accepted and ignored: without it, and with it, a view renders exactly as frotzlens has always shown it. frotztrace's later releases light what changed.
+
+Peer dependencies: `nuxt` ^4.6, `@nuxt/ui` ^4.12, `vue` ^3.5.
+
+MIT © Christopher Schweda. Extracted from frotzlens (GPL-3.0-or-later), whose author relicensed these files MIT for the move.

package/app/components/AppNav.vue

@@ -0,0 +1,33 @@
+<script setup lang="ts">
+import type { NavView } from '../utils/nav'
+
+/**
+ * The views, left of the content on wide screens and a scrolling row above it on narrow ones. Each
+ * app supplies its own list; `active` is the key of the view being shown.
+ */
+const props = defineProps<{ views: NavView[]; active: string }>()
+
+// On a narrow screen the nav is a scrolling row: keep the current view in sight.
+const nav = useTemplateRef<HTMLElement>('nav')
+watch(() => props.active, () => nextTick(() => nav.value?.querySelector('[aria-current="page"]')?.scrollIntoView({ block: 'nearest', inline: 'nearest' })), { immediate: true })
+</script>
+
+<template>
+  <nav ref="nav" aria-label="Views" class="lg:sticky lg:top-20 lg:self-start">
+    <ul class="-mx-1 flex gap-1 overflow-x-auto pb-1 lg:mx-0 lg:w-52 lg:flex-col lg:overflow-visible">
+      <li v-for="v in views" :key="v.key">
+        <a
+          :href="`#${v.key}`"
+          :aria-current="active === v.key ? 'page' : undefined"
+          class="flex items-center gap-2 whitespace-nowrap rounded-md px-3 py-2 text-sm transition-colors hover:bg-elevated"
+          :class="active === v.key ? 'bg-elevated font-semibold text-highlighted' : 'text-muted'"
+        >
+          <UIcon :name="v.icon" class="size-4 shrink-0" :class="active === v.key ? 'text-lamp' : ''" aria-hidden="true" />
+          {{ v.label }}
+          <span v-if="v.count !== undefined" class="data ml-auto pl-2 text-xs text-muted">{{ v.count }}</span>
+          <span v-else-if="v.tag" class="ml-auto rounded-full border border-default px-1.5 text-xs text-muted">{{ v.tag }}</span>
+        </a>
+      </li>
+    </ul>
+  </nav>
+</template>

package/app/components/CopyText.vue

@@ -0,0 +1,24 @@
+<script setup lang="ts">
+/** "Copy as text": the view's section in Ztools' format, made only when asked for. */
+const props = defineProps<{ text: () => string; label?: string }>()
+const status = ref('')
+let timer: ReturnType<typeof setTimeout> | undefined
+
+async function copy() {
+  try {
+    await navigator.clipboard.writeText(props.text())
+    status.value = 'Copied'
+  } catch {
+    status.value = "Couldn't copy: the browser didn't allow it"
+  }
+  clearTimeout(timer)
+  timer = setTimeout(() => (status.value = ''), 2500)
+}
+</script>
+
+<template>
+  <div class="flex items-center gap-3">
+    <UButton color="neutral" variant="outline" icon="i-lucide-copy" @click="copy">{{ label ?? 'Copy as text' }}</UButton>
+    <span role="status" aria-live="polite" class="text-sm text-muted">{{ status }}</span>
+  </div>
+</template>

package/app/components/Disassembly.vue

@@ -0,0 +1,48 @@
+<script setup lang="ts">
+import type { RoutineView } from '@frotzinc/zcode/format'
+import type { MachineView } from '../utils/live'
+
+/**
+ * One routine's disassembly, as txd lays it out: every routine, string, object and dictionary word
+ * it uses is a link, and a branch or jump target moves focus to its line. `live` is unused until
+ * frotztrace's Phase 4, when it marks the program counter.
+ */
+const props = defineProps<{ view: RoutineView; address: number; live?: MachineView; breakpoints?: ReadonlySet<number> }>()
+/** frotztrace: a line's gutter button was pressed. */
+const emit = defineEmits<{ toggleBreakpoint: [address: number] }>()
+/** The gutter (the PC, breakpoints) only when there's something to show: frotzlens's view is unchanged. */
+const gutter = computed(() => !!props.live || !!props.breakpoints)
+
+// Labels: a branch or jump target scrolls to its line and focuses it (the route stays the routine).
+function jump(target: number) {
+  const el = document.getElementById(`at-${hex(target)}`)
+  el?.scrollIntoView({ block: 'center' })
+  el?.focus()
+}
+</script>
+
+<template>
+  <div class="overflow-x-auto rounded-xl border border-default bg-muted" role="region" aria-label="Disassembly" tabindex="0">
+    <div class="data min-w-max p-4 text-sm leading-6">
+      <div class="whitespace-pre text-highlighted">{{ props.view.header }}</div>
+      <div v-for="(n, i) in props.view.notes" :key="i" class="whitespace-pre text-muted">{{ n }}</div>
+      <div aria-hidden="true">&nbsp;</div>
+      <div
+        v-for="l in props.view.lines"
+        :id="`at-${hex(l.address)}`"
+        :key="l.address"
+        tabindex="-1"
+        class="whitespace-pre rounded focus:bg-elevated"
+        :class="live?.pc === l.address ? 'bg-elevated font-semibold' : ''"
+      ><span v-if="gutter" class="inline-flex w-12 items-center gap-1"><button
+          v-if="breakpoints"
+          type="button"
+          class="size-4 rounded-full border border-default leading-none"
+          :class="breakpoints.has(l.address) ? 'bg-[var(--frotz-lamp)]' : 'hover:bg-elevated'"
+          :aria-pressed="breakpoints.has(l.address)"
+          :aria-label="`Breakpoint at ${hex(l.address)}`"
+          @click="emit('toggleBreakpoint', l.address)"
+        /><span v-if="live?.pc === l.address" class="text-lamp" aria-hidden="true">▶</span><span v-if="live?.pc === l.address" class="sr-only">current instruction</span></span><span class="text-muted">{{ `${hex(l.address).padStart(5)}  ` }}</span><span class="text-lamp">{{ (l.label ? `${l.label}:` : '').padEnd(7) }}</span><template v-for="(p, j) in l.pieces" :key="j"><a v-if="p.id" :href="idRoute(p.id)" class="text-lamp underline decoration-dotted underline-offset-4 hover:decoration-solid">{{ p.text }}</a><a v-else-if="p.target !== undefined" :href="`#routine/${hex(address)}`" class="text-lamp underline decoration-dotted underline-offset-4 hover:decoration-solid" :aria-label="`${p.text}, the instruction at ${hex(p.target)}`" @click.prevent="jump(p.target)">{{ p.text }}</a><span v-else>{{ p.text }}</span></template></div>
+    </div>
+  </div>
+</template>

package/app/components/GlobalsView.vue

@@ -0,0 +1,83 @@
+<script setup lang="ts">
+import type { StoryFile } from '@frotzinc/zcode'
+import type { MachineView } from '../utils/live'
+
+/** The 240 global variables: their starting values, names (with a debug file) and the routines that use them. */
+const props = defineProps<{ story: StoryFile; fileName: string; id?: string; live?: MachineView }>()
+
+const number = computed(() => (props.id && /^\d+$/.test(props.id) ? Number(props.id) : undefined))
+const global = computed(() => (number.value === undefined ? undefined : props.story.globals[number.value]))
+
+const filter = ref('')
+/** Live (frotztrace): the value now, from the running machine's memory. */
+const nowOf = (address: number) => (props.live ? (props.live.memory[address]! << 8) | props.live.memory[address + 1]! : undefined)
+
+const rows = computed(() => {
+  const s = props.story
+  const q = filter.value.trim().toLowerCase()
+  return s.globals
+    // Uses: each place an instruction reads or writes it, as the detail's "Used by" counts them.
+    .map(g => ({ g, name: globalName(g.number), txd: `G${hex(g.number, 2)}`, uses: s.xrefs[g.id]?.from.length ?? 0, now: nowOf(g.address), changed: !!props.live?.changed.globals.has(g.number) }))
+    .filter(r => !q || r.name.toLowerCase().includes(q) || r.txd.toLowerCase() === q || hex(r.g.value).includes(q.replace(/^#|0x/, '')))
+})
+
+/** As text: each global, its name if any, and its starting value. */
+const asText = () =>
+  props.story.globals
+    .map(g => `G${hex(g.number, 2)}  ${hex(g.value)}${activeSymbols.value?.globals[g.number] ? `  ${activeSymbols.value.globals[g.number]}` : ''}`)
+    .join('\n') + '\n'
+</script>
+
+<template>
+  <div v-if="id === undefined" class="flex flex-col gap-6">
+    <ViewHeader title="Globals" :eyebrow="fileName" :copy="asText" copy-label="Copy the globals">
+      The 240 global variables (G00–Gef), with the value each starts with and the routines that use it.
+      <template v-if="!activeSymbols"> Load the game’s debug file to see their names.</template>
+    </ViewHeader>
+    <UInput v-model="filter" icon="i-lucide-search" placeholder="Search names, G-numbers or values" aria-label="Search globals" class="max-w-md" />
+    <div class="overflow-x-auto rounded-xl border border-default">
+      <table class="w-full text-sm">
+        <caption class="sr-only">Global variables</caption>
+        <thead class="bg-muted text-left text-muted">
+          <tr>
+            <th scope="col" class="px-4 py-2 font-semibold">Global</th>
+            <th v-if="activeSymbols" scope="col" class="px-4 py-2 font-semibold">Number</th>
+            <th scope="col" class="px-4 py-2 font-semibold">Address</th>
+            <th scope="col" class="px-4 py-2 font-semibold">Starts as</th>
+            <th v-if="live" scope="col" class="px-4 py-2 font-semibold">Now</th>
+            <th scope="col" class="px-4 py-2 text-right font-semibold">Used by</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr v-for="r in rows" :key="r.g.number" class="border-t border-default" :class="r.changed ? 'bg-elevated' : ''">
+            <td class="data px-4 py-1.5"><a :href="`#global/${r.g.number}`" class="text-lamp hover:underline">{{ r.name }}</a></td>
+            <td v-if="activeSymbols" class="data px-4 py-1.5 text-muted">{{ r.txd }}</td>
+            <td class="data px-4 py-1.5 text-muted">{{ hex(r.g.address) }}</td>
+            <td class="data px-4 py-1.5">{{ hex(r.g.value) }} <span class="text-muted">({{ r.g.value }})</span></td>
+            <td v-if="live" class="data px-4 py-1.5" :class="r.changed ? 'font-semibold text-lamp' : ''">
+              {{ hex(r.now!) }} <span class="text-muted">({{ r.now }})</span>
+              <span v-if="r.changed" class="ml-2 rounded-full border border-default px-1.5 font-sans text-xs text-lamp">changed</span>
+            </td>
+            <td class="data px-4 py-1.5 text-right">{{ r.uses }}</td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+    <p v-if="!rows.length" class="text-muted">{{ story.globals.length ? `No global matches “${filter}”.` : 'This file has no globals table.' }}</p>
+  </div>
+
+  <div v-else-if="global" class="flex flex-col gap-6">
+    <ViewHeader
+      :title="globalName(global.number)"
+      :eyebrow="`G${hex(global.number, 2)} · variable ${global.number + 16} · at ${hex(global.address)}`"
+      :back="{ to: '#globals', label: 'All globals' }"
+    />
+    <dl class="grid w-fit grid-cols-[auto_auto] gap-x-6 gap-y-1 text-sm">
+      <dt class="text-muted">Starts as</dt>
+      <dd class="data">{{ hex(global.value) }} ({{ global.value }})</dd>
+    </dl>
+    <Referrers :story="story" :id="global.id" from-title="Used by" />
+  </div>
+
+  <NotFound v-else :what="`global ${id}`" back="#globals" back-label="All globals" />
+</template>

package/app/components/HexPane.vue

@@ -0,0 +1,95 @@
+<script setup lang="ts">
+import type { MachineView } from '../utils/live'
+
+/**
+ * A hex view of bytes, a page of rows at a time so a large file stays quick, with "Go to address"
+ * and paging. `top` (v-model) is the first row's address. `notes` labels what begins in a row;
+ * `inRange` dims the bytes outside the part being shown. `live` (frotztrace) lights the bytes the
+ * running machine changed since it last stopped; pass the live memory as `bytes`.
+ */
+const props = defineProps<{
+  bytes: Uint8Array
+  notes?: (from: number, to: number) => string[]
+  inRange?: (address: number) => boolean
+  live?: MachineView
+}>()
+const top = defineModel<number>('top', { default: 0 })
+
+const ROWS = 32
+const size = computed(() => props.bytes.length)
+
+/** Jump to a row-aligned address. */
+const goTo = (a: number) => (top.value = Math.max(0, Math.min(Math.floor(a / 16) * 16, Math.max(0, size.value - 1) & ~15)))
+
+const rows = computed(() => {
+  const b = props.bytes
+  const out: { at: number; bytes: number[]; text: string; notes: string[] }[] = []
+  for (let r = 0; r < ROWS; r++) {
+    const at = top.value + r * 16
+    if (at >= b.length) break
+    const bytes = [...b.subarray(at, Math.min(at + 16, b.length))]
+    out.push({
+      at,
+      bytes,
+      text: bytes.map(x => (x >= 32 && x < 127 ? String.fromCharCode(x) : '.')).join(''),
+      notes: props.notes?.(at, at + 16) ?? [],
+    })
+  }
+  return out
+})
+const inPart = (a: number) => props.inRange?.(a) ?? true
+/** Live: how many of the row's bytes changed (the text equivalent of their highlight). */
+const changedIn = (at: number) => { let n = 0; for (let i = 0; i < 16; i++) if (props.live?.changed.addresses.has(at + i)) n++; return n }
+
+const jump = ref('')
+const jumpError = ref('')
+function onJump() {
+  const text = jump.value.trim().replace(/^(0x|\$)/i, '')
+  const a = /^[0-9a-f]+$/i.test(text) ? parseInt(text, 16) : NaN
+  if (!size.value) jumpError.value = 'The file is empty: there are no addresses.'
+  else if (Number.isNaN(a)) jumpError.value = `“${jump.value}” isn't a hex address.`
+  else if (a >= size.value) jumpError.value = `${hex(a)} is past the end of the file (${hex(size.value - 1)}).`
+  else {
+    jumpError.value = ''
+    goTo(a)
+  }
+}
+</script>
+
+<template>
+  <section aria-labelledby="hex-title" class="flex flex-col gap-4">
+    <div class="flex flex-wrap items-end justify-between gap-4">
+      <h2 id="hex-title" class="font-display text-2xl font-semibold text-highlighted">Bytes</h2>
+      <form class="flex items-center gap-2" @submit.prevent="onJump">
+        <label for="hex-jump" class="text-sm text-muted">Go to address</label>
+        <UInput id="hex-jump" v-model="jump" placeholder="1c97" class="data w-28" :aria-invalid="!!jumpError || undefined" />
+        <UButton type="submit" color="neutral" variant="outline">Go</UButton>
+      </form>
+    </div>
+    <p v-if="jumpError" role="alert" class="text-sm text-error">{{ jumpError }}</p>
+    <div v-if="!size">
+      <p class="text-muted">The file is empty.</p>
+    </div>
+    <div v-if="size" class="flex flex-wrap items-center gap-2">
+      <UButton color="neutral" variant="outline" icon="i-lucide-chevrons-up" :disabled="top === 0" aria-label="Previous page of bytes" @click="goTo(top - ROWS * 16)" />
+      <UButton color="neutral" variant="outline" icon="i-lucide-chevrons-down" :disabled="top + ROWS * 16 >= size" aria-label="Next page of bytes" @click="goTo(top + ROWS * 16)" />
+      <span class="data text-sm text-muted">{{ hex(top) }}–{{ hex(Math.min(top + ROWS * 16, size) - 1) }} of {{ hex(size - 1) }}</span>
+    </div>
+    <div v-if="size" class="overflow-x-auto rounded-xl border border-default bg-muted" role="region" aria-label="Bytes" tabindex="0">
+      <table class="data min-w-max text-sm leading-6">
+        <caption class="sr-only">Bytes from {{ hex(top) }}, 16 to a row</caption>
+        <thead class="sr-only">
+          <tr><th scope="col">Address</th><th scope="col">Bytes</th><th scope="col">As text</th><th scope="col">Starts here</th></tr>
+        </thead>
+        <tbody>
+          <tr v-for="r in rows" :key="r.at">
+            <th scope="row" class="px-4 text-left font-normal text-muted">{{ hex(r.at, 5) }}</th>
+            <td class="whitespace-pre px-2"><template v-for="(b, i) in r.bytes" :key="i"><span :class="live?.changed.addresses.has(r.at + i) ? 'rounded bg-[var(--frotz-lamp)] text-[var(--frotz-ground)]' : inPart(r.at + i) ? 'text-highlighted' : 'text-muted'">{{ hex(b, 2) }}</span>{{ i === 7 ? '  ' : i < 15 ? ' ' : '' }}</template></td>
+            <td class="whitespace-pre px-4 text-muted">{{ r.text }}</td>
+            <td class="whitespace-nowrap px-4 font-sans text-xs text-lamp">{{ [...r.notes, ...(changedIn(r.at) ? [`${changedIn(r.at)} changed`] : [])].join(' · ') }}</td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+  </section>
+</template>

package/app/components/MapView.vue

@@ -0,0 +1,166 @@
+<script setup lang="ts">
+import { roomGraph, toMapGraph, type RoomExit, type StoryFile } from '@frotzinc/zcode'
+import type { MachineView } from '../utils/live'
+
+/**
+ * The map of an Inform game, from its rooms' exits (which need the debug file
+ * to be found). Drawn on a grid, as frotzsmith's map is, and listed as text
+ * below — the list is the map for anyone who can't see the picture.
+ */
+const props = defineProps<{ story: StoryFile; fileName: string; live?: MachineView }>()
+const { symbols } = useSymbols()
+
+const graph = computed(() => (symbols.value ? roomGraph(props.story, symbols.value) : undefined))
+const map = computed(() => (graph.value ? layoutMap(graph.value) : undefined))
+
+const CELL = 170
+const W = 136
+const H = 52
+const PAD = 24
+const box = computed(() => {
+  const b = map.value?.bounds ?? { minCol: 0, maxCol: 0, minRow: 0, maxRow: 0 }
+  const x = b.minCol * CELL - W / 2 - PAD
+  const y = b.minRow * CELL - H / 2 - PAD
+  return { x, y, w: (b.maxCol - b.minCol) * CELL + W + PAD * 2, h: (b.maxRow - b.minRow) * CELL + H + PAD * 2 }
+})
+const at = computed(() => new Map(map.value?.rooms.map(r => [r.number, r]) ?? []))
+const centre = (n: number) => {
+  const r = at.value.get(n)!
+  return { x: r.col * CELL, y: r.row * CELL }
+}
+const short = (s: string) => (s.length > 18 ? `${s.slice(0, 17)}…` : s)
+
+const DIRS: Record<string, string> = {
+  n: 'north', s: 'south', e: 'east', w: 'west', ne: 'northeast', nw: 'northwest', se: 'southeast', sw: 'southwest',
+  u: 'up', d: 'down', in: 'in', out: 'out',
+}
+// A room's label: its short name, with its number when another room has the same name (as toMapGraph does).
+const nameCount = computed(() => {
+  const m = new Map<string, number>()
+  for (const r of graph.value?.rooms ?? []) m.set(objectName(props.story, r.number), (m.get(objectName(props.story, r.number)) ?? 0) + 1)
+  return m
+})
+const name = (n: number) => {
+  const plain = objectName(props.story, n)
+  return (nameCount.value.get(plain) ?? 0) > 1 ? `${plain} (${n})` : plain
+}
+function exitText(e: RoomExit): string {
+  if (e.kind === 'room') return ''
+  if (e.kind === 'door') return `through ${name(e.door!)}`
+  if (e.kind === 'routine') return e.candidates?.length ? 'decided as the game runs: perhaps' : 'decided as the game runs'
+  return 'no way through (a message)'
+}
+// Each room's exits, indexed once (a big map would otherwise rescan every exit per room).
+const exitIndex = computed(() => {
+  const m = new Map<number, RoomExit[]>()
+  for (const e of graph.value?.exits ?? []) m.set(e.from, [...(m.get(e.from) ?? []), e])
+  return m
+})
+const exitsFrom = (n: number) => exitIndex.value.get(n) ?? []
+const LINK = 'text-lamp underline decoration-dotted underline-offset-4 hover:decoration-solid'
+
+/**
+ * Live (frotztrace): the player's room and the rooms visited (the `visited` attribute), as they are
+ * now. The room is `real_location` when the library has it: in the dark, `location` is the
+ * darkness object, not a room.
+ */
+const here = computed(() => {
+  const s = symbols.value
+  if (!props.live || !s) return undefined
+  const named = (name: string) => Object.entries(s.globals).find(([, n]) => n === name)?.[0]
+  const g = named('real_location') ?? named('location')
+  if (g === undefined) return undefined
+  const a = props.story.header.globals + Number(g) * 2
+  return (props.live.memory[a]! << 8) | props.live.memory[a + 1]!
+})
+const visited = computed(() => {
+  const s = symbols.value
+  const attr = s && Object.entries(s.attributes).find(([, n]) => n === 'visited')?.[0]
+  if (!props.live || attr === undefined) return new Set<number>()
+  return new Set(props.story.objects.objects.filter(o => o.attributes.includes(Number(attr))).map(o => o.number))
+})
+const copy = () => JSON.stringify(toMapGraph(graph.value!), null, 2) + '\n'
+</script>
+
+<template>
+  <div class="flex flex-col gap-6">
+    <ViewHeader title="Map" :eyebrow="fileName" :copy="graph ? copy : undefined" copy-label="Copy the map (frotzsmith's shape)">
+      The rooms and the exits between them, from each room’s direction properties. Exits worked out as the
+      game runs are drawn to the rooms their routine can return, dashed.
+    </ViewHeader>
+
+    <div v-if="!symbols" class="flex flex-col gap-3 rounded-xl border border-default p-5">
+      <p>The map needs the game’s debug file: it finds exits by their property names (<code class="data">n_to</code>, <code class="data">s_to</code>, …).</p>
+      <a href="#symbols" class="w-fit text-lamp hover:underline">Load a debug file</a>
+    </div>
+    <p v-else-if="!graph" class="text-muted">This game has no direction properties to find exits by.</p>
+
+    <template v-else-if="map">
+      <p class="text-sm text-muted">
+        {{ graph.rooms.length }} {{ graph.rooms.length === 1 ? 'room' : 'rooms' }}<template v-if="graph.start">; the game starts in {{ name(graph.start) }}</template>.
+      </p>
+      <div class="overflow-x-auto rounded-xl border border-default bg-muted">
+        <svg
+          :viewBox="`${box.x} ${box.y} ${box.w} ${box.h}`"
+          :width="box.w"
+          :height="box.h"
+          class="mx-auto block max-w-none"
+          role="group"
+          :aria-label="`A map of ${graph.rooms.length} rooms; each links to its object. The list below gives each room's exits.`"
+        >
+          <g aria-hidden="true">
+            <line
+              v-for="(c, i) in map.connectors"
+              :key="i"
+              :x1="centre(c.from).x"
+              :y1="centre(c.from).y"
+              :x2="centre(c.to).x"
+              :y2="centre(c.to).y"
+              stroke="var(--frotz-lamp-text)"
+              stroke-width="2"
+              :stroke-dasharray="c.routine ? '6 5' : undefined"
+              stroke-opacity="0.7"
+            />
+          </g>
+          <a v-for="r in map.rooms" :key="r.number" :href="`#object/${r.number}`">
+            <title>{{ name(r.number) }}</title>
+            <rect
+              :x="r.col * CELL - W / 2"
+              :y="r.row * CELL - H / 2"
+              :width="W"
+              :height="H"
+              rx="8"
+              :fill="r.number === here ? 'var(--frotz-lamp)' : visited.has(r.number) ? 'var(--ui-bg-accented)' : 'var(--ui-bg-elevated)'"
+              :stroke="r.number === here || r.number === graph.start ? 'var(--frotz-lamp-text)' : 'var(--ui-border-accented)'"
+              :stroke-width="r.number === here ? 4 : r.number === graph.start ? 3 : 1.5"
+            />
+            <text :x="r.col * CELL" :y="r.row * CELL + 5" text-anchor="middle" font-size="14" :fill="r.number === here ? 'var(--frotz-ground)' : 'var(--ui-text-highlighted)'">{{ short(name(r.number)) }}</text>
+          </a>
+        </svg>
+      </div>
+
+      <section aria-labelledby="rooms-title" class="flex flex-col gap-3">
+        <h2 id="rooms-title" class="font-display text-xl font-semibold text-highlighted">Rooms and exits</h2>
+        <ul class="flex flex-col gap-3 text-sm">
+          <li v-for="r in graph.rooms" :key="r.number">
+            <a :href="`#object/${r.number}`" class="font-semibold text-lamp hover:underline">{{ name(r.number) }}</a>
+            <span v-if="r.number === graph.start" class="ml-2 text-xs text-muted">where the game starts</span>
+            <span v-if="r.number === here" class="ml-2 rounded-full border border-default px-1.5 text-xs text-lamp">you are here</span>
+            <span v-else-if="visited.has(r.number)" class="ml-2 text-xs text-muted">visited</span>
+            <ul v-if="exitsFrom(r.number).length" class="mt-1 flex flex-col gap-0.5 pl-4">
+              <li v-for="(e, i) in exitsFrom(r.number)" :key="i">
+                <span class="data inline-block w-24 text-muted">{{ DIRS[e.dir] }}</span>
+                {{ exitText(e) }}
+                <!-- Links inside a sentence are underlined, so they don't rely on colour alone (WCAG 1.4.1). -->
+                <template v-if="e.to !== undefined"><template v-if="e.kind === 'door'"> to </template><a :href="`#object/${e.to}`" :class="LINK">{{ name(e.to) }}</a></template>
+                <template v-for="(c, j) in e.kind === 'routine' ? e.candidates ?? [] : []" :key="c">{{ j ? ' or ' : ' ' }}<a :href="`#object/${c}`" :class="LINK">{{ name(c) }}</a></template>
+                <template v-if="e.kind === 'routine'"> (<a :href="`#routine/${hex(e.routine!)}`" :class="LINK">{{ routineName(story, e.routine!) }}</a>)</template>
+              </li>
+            </ul>
+            <p v-else class="pl-4 text-muted">No exits.</p>
+          </li>
+        </ul>
+      </section>
+    </template>
+  </div>
+</template>

package/app/components/NotFound.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+defineProps<{ what: string; back?: string; backLabel?: string }>()
+</script>
+
+<template>
+  <div class="flex flex-col gap-4">
+    <a :href="back ?? '#overview'" class="w-fit text-sm text-muted hover:underline">← {{ backLabel ?? 'Overview' }}</a>
+    <h1 class="font-display text-3xl font-bold text-highlighted">Nothing here</h1>
+    <p class="max-w-2xl text-muted">There's no {{ what }} in this file. ⌘K / Ctrl+K finds any routine, object, string or dictionary word by name or address.</p>
+  </div>
+</template>