@frotzinc/zcode-ui 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to `@frotzinc/zcode-ui`. Versions follow [Semantic Versioning](https://semver.org/). Part of [frotz, Inc.](https://frotzinc.com).
+
+## [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,35 @@
+<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 }>()
+
+// 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"
+      ><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,75 @@
+<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('')
+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 }))
+    .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 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">
+            <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 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,93 @@
+<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` is unused until frotztrace's
+ * Phase 4, when it lights the bytes a running machine changed.
+ */
+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
+
+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="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.join(' · ') }}</td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+  </section>
+</template>

package/app/components/MapView.vue

@@ -0,0 +1,143 @@
+<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'
+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="var(--ui-bg-elevated)"
+              :stroke="r.number === graph.start ? 'var(--frotz-lamp-text)' : 'var(--ui-border-accented)'"
+              :stroke-width="r.number === graph.start ? 3 : 1.5"
+            />
+            <text :x="r.col * CELL" :y="r.row * CELL + 5" text-anchor="middle" font-size="14" fill="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>
+            <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>

package/app/components/ObjectTree.vue

@@ -0,0 +1,176 @@
+<script setup lang="ts">
+import type { StoryFile } from '@frotzinc/zcode'
+import type { MachineView } from '../utils/live'
+
+/**
+ * The object tree, as an ARIA tree (WAI-ARIA APG "tree view"): one tab stop;
+ * Up/Down move, Right opens or goes to the first child, Left closes or goes to
+ * the parent, Home/End, Enter/Space opens the object, and typing a letter
+ * jumps to the next object whose name starts with it. Rendered flat, with
+ * aria-level, so only open branches are in the DOM.
+ */
+const props = defineProps<{ story: StoryFile; selected?: number; live?: MachineView }>()
+
+const objects = computed(() => props.story.objects.objects)
+const count = computed(() => objects.value.length)
+const get = (n: number) => (n >= 1 && n <= count.value ? objects.value[n - 1] : undefined)
+
+/** Children of each object, by following child then sibling; a cycle (a broken file) stops the walk. */
+const children = computed(() => {
+  const out = new Map<number, number[]>()
+  for (const o of objects.value) {
+    const list: number[] = []
+    const seen = new Set<number>()
+    for (let c = o.child; get(c) && !seen.has(c); c = get(c)!.sibling) {
+      seen.add(c)
+      list.push(c)
+    }
+    out.set(o.number, list)
+  }
+  return out
+})
+const roots = computed(() => objects.value.filter(o => !get(o.parent)).map(o => o.number))
+
+const open = ref(new Set<number>())
+// Rooms (the roots' children are their contents) start open; so does the path to the selected object.
+watch(roots, r => (open.value = new Set(r.filter(n => (children.value.get(n)?.length ?? 0) > 0))), { immediate: true })
+watch(() => props.selected, (n) => {
+  const next = new Set(open.value)
+  const seen = new Set<number>()
+  for (let p = get(n ?? 0)?.parent ?? 0; get(p) && !seen.has(p); p = get(p)!.parent) {
+    seen.add(p)
+    next.add(p)
+  }
+  open.value = next
+}, { immediate: true })
+
+interface Row { key: string; n: number; level: number; setSize: number; posInSet: number; parent: number; empty?: boolean }
+/**
+ * The visible rows, depth first, without recursion (a deep tree can't overflow the stack). An object
+ * shows at most once: in a broken file one could be reached twice, or in a loop.
+ */
+const rows = computed<Row[]>(() => {
+  const out: Row[] = []
+  // A level's objects are claimed when the level is reached, so its set size and positions count
+  // only what is shown there (a broken file can list an object twice, or loop).
+  const claimed = new Set<number>()
+  const claim = (list: number[]) =>
+    list.filter((n) => {
+      if (claimed.has(n)) return false
+      claimed.add(n)
+      return true
+    })
+  const stack: { list: number[]; i: number; level: number; parent: number }[] = [{ list: claim(roots.value), i: 0, level: 1, parent: 0 }]
+  while (stack.length) {
+    const top = stack.at(-1)!
+    if (top.i >= top.list.length) {
+      stack.pop()
+      continue
+    }
+    const n = top.list[top.i++]!
+    const row: Row = { key: `${top.parent}-${n}`, n, level: top.level, setSize: top.list.length, posInSet: top.i, parent: top.parent }
+    out.push(row)
+    if (open.value.has(n)) {
+      const kids = claim(children.value.get(n) ?? [])
+      if (kids.length) stack.push({ list: kids, i: 0, level: top.level + 1, parent: n })
+      else row.empty = true // open, but every child is shown elsewhere: not expandable here
+    }
+  }
+  return out
+})
+
+/** The tab stop follows a node, not a row index, so opening or closing a branch above it keeps it. */
+const focusedKey = ref('')
+const focused = computed(() => Math.max(0, rows.value.findIndex(r => r.key === focusedKey.value)))
+watch(() => props.selected, (n) => {
+  const r = rows.value.find(x => x.n === n)
+  if (r) focusedKey.value = r.key
+}, { immediate: true, flush: 'post' })
+
+const tree = useTemplateRef<HTMLElement>('tree')
+function focusRow(i: number) {
+  const r = rows.value[Math.max(0, Math.min(rows.value.length - 1, i))]
+  if (!r) return
+  focusedKey.value = r.key
+  nextTick(() => tree.value?.querySelector<HTMLElement>(`[data-row="${focused.value}"]`)?.focus())
+}
+function toggle(n: number) {
+  const next = new Set(open.value)
+  if (next.has(n)) next.delete(n)
+  else next.add(n)
+  open.value = next
+}
+const hasChildren = (n: number) => (children.value.get(n)?.length ?? 0) > 0
+const name = (n: number) => objectName(props.story, n)
+const go = (n: number) => (location.hash = `object/${n}`)
+
+function onKey(e: KeyboardEvent) {
+  const r = rows.value[focused.value]
+  if (!r) return
+  switch (e.key) {
+    case 'ArrowDown': focusRow(focused.value + 1); break
+    case 'ArrowUp': focusRow(focused.value - 1); break
+    case 'Home': focusRow(0); break
+    case 'End': focusRow(rows.value.length - 1); break
+    case 'ArrowRight':
+      if (!hasChildren(r.n)) return
+      if (!open.value.has(r.n)) toggle(r.n)
+      else focusRow(focused.value + 1)
+      break
+    case 'ArrowLeft':
+      if (open.value.has(r.n) && hasChildren(r.n)) toggle(r.n)
+      else if (r.parent) focusRow(rows.value.findIndex(x => x.n === r.parent))
+      else return
+      break
+    case 'Enter':
+    case ' ':
+      go(r.n)
+      break
+    default: {
+      // Type-ahead: the next object (after this one) whose name starts with the letter.
+      if (e.key.length !== 1 || e.ctrlKey || e.metaKey || e.altKey) return
+      const k = e.key.toLowerCase()
+      const len = rows.value.length
+      for (let j = 1; j <= len; j++) {
+        const i = (focused.value + j) % len
+        if (name(rows.value[i]!.n).toLowerCase().startsWith(k)) {
+          focusRow(i)
+          break
+        }
+      }
+    }
+  }
+  e.preventDefault()
+}
+</script>
+
+<template>
+  <ul ref="tree" role="tree" aria-label="Object tree" class="flex flex-col py-1 text-sm" @keydown="onKey">
+    <li
+      v-for="(r, i) in rows"
+      :key="r.key"
+      role="treeitem"
+      :data-row="i"
+      :aria-level="r.level"
+      :aria-setsize="r.setSize"
+      :aria-posinset="r.posInSet"
+      :aria-expanded="hasChildren(r.n) && !r.empty ? open.has(r.n) : undefined"
+      :aria-selected="r.n === selected"
+      :tabindex="i === focused ? 0 : -1"
+      class="flex cursor-pointer items-center gap-1 rounded py-1 pr-2 outline-offset-[-2px] hover:bg-elevated"
+      :class="r.n === selected ? 'bg-elevated font-semibold text-highlighted' : ''"
+      :style="{ paddingLeft: `${(r.level - 1) * 1.1 + 0.25}rem` }"
+      @click="focusedKey = r.key; go(r.n)"
+    >
+      <span
+        class="inline-flex size-5 shrink-0 items-center justify-center text-muted"
+        aria-hidden="true"
+        @click.stop="focusedKey = r.key; hasChildren(r.n) && toggle(r.n)"
+      >
+        <UIcon v-if="hasChildren(r.n)" :name="open.has(r.n) ? 'i-lucide-chevron-down' : 'i-lucide-chevron-right'" class="size-4" />
+      </span>
+      <span class="truncate">{{ name(r.n) }}</span>
+      <span class="data ml-auto pl-2 text-xs text-muted">{{ r.n }}</span>
+    </li>
+  </ul>
+</template>

package/app/components/RefLink.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+import type { StoryFile } from '@frotzinc/zcode'
+
+/** A link to anything with a model Id, labelled as txd would name it. */
+const props = defineProps<{ story: StoryFile; id: string; label?: string }>()
+const text = computed(() => props.label ?? idLabel(props.story, props.id))
+</script>
+
+<template>
+  <a :href="idRoute(id)" class="text-lamp underline-offset-2 hover:underline">{{ text }}</a>
+</template>

package/app/components/Referrers.vue

@@ -0,0 +1,45 @@
+<script setup lang="ts">
+import type { StoryFile } from '@frotzinc/zcode'
+
+/** Both directions of the cross-reference index for one Id: what refers to it, and what it refers to. */
+const props = defineProps<{ story: StoryFile; id: string; fromTitle?: string; toTitle?: string }>()
+const entry = computed(() => props.story.xrefs[props.id])
+const from = useLimit(() => entry.value?.from ?? [], 100)
+const to = useLimit(() => entry.value?.to ?? [], 100)
+watch(() => props.id, () => {
+  from.reset()
+  to.reset()
+})
+</script>
+
+<template>
+  <div class="grid gap-6 md:grid-cols-2">
+    <section :aria-label="fromTitle ?? 'Referred to from'" class="flex flex-col gap-2">
+      <h2 class="font-display text-xl font-semibold text-highlighted">
+        {{ fromTitle ?? 'Referred to from' }} <span class="data text-base text-muted">{{ entry?.from.length ?? 0 }}</span>
+      </h2>
+      <p v-if="!entry?.from.length" class="text-sm text-muted">Nothing in the file refers to this.</p>
+      <ul v-else class="flex flex-col gap-1 text-sm">
+        <li v-for="(s, i) in from.shown.value" :key="i" class="flex gap-2">
+          <RefLink :story="story" :id="s.id" />
+          <span class="data text-muted">at {{ hex(s.address) }}</span>
+        </li>
+      </ul>
+      <UButton v-if="from.remaining.value" color="neutral" variant="link" class="w-fit px-0" @click="from.more">
+        Show more ({{ from.remaining.value }} left)
+      </UButton>
+    </section>
+    <section :aria-label="toTitle ?? 'Refers to'" class="flex flex-col gap-2">
+      <h2 class="font-display text-xl font-semibold text-highlighted">
+        {{ toTitle ?? 'Refers to' }} <span class="data text-base text-muted">{{ entry?.to.length ?? 0 }}</span>
+      </h2>
+      <p v-if="!entry?.to.length" class="text-sm text-muted">This refers to nothing the index tracks.</p>
+      <ul v-else class="flex flex-col gap-1 text-sm">
+        <li v-for="t in to.shown.value" :key="t"><RefLink :story="story" :id="t" /></li>
+      </ul>
+      <UButton v-if="to.remaining.value" color="neutral" variant="link" class="w-fit px-0" @click="to.more">
+        Show more ({{ to.remaining.value }} left)
+      </UButton>
+    </section>
+  </div>
+</template>

package/app/components/SearchPalette.vue

@@ -0,0 +1,59 @@
+<script setup lang="ts">
+import type { StoryFile } from '@frotzinc/zcode'
+
+/** ⌘K / Ctrl+K: jump to any routine, object, string, dictionary word or global, by name or address. */
+const props = defineProps<{ story: StoryFile }>()
+const open = defineModel<boolean>('open', { default: false })
+const { goToId } = useHashRoute()
+const hex4 = (n: number) => n.toString(16).padStart(4, '0')
+const clip = (s: string) => (s.length > 70 ? `${s.slice(0, 70)}…` : s).replace(/\s+/g, ' ')
+
+const groups = computed(() => {
+  const s = props.story
+  const pick = (id: string) => () => {
+    open.value = false
+    goToId(id)
+  }
+  return [
+    {
+      id: 'objects',
+      label: 'Objects',
+      items: s.objects.objects.map(o => ({ label: o.shortName.text || `(object ${o.number})`, suffix: `#${o.number}`, icon: 'i-lucide-box', onSelect: pick(o.id) })),
+    },
+    {
+      id: 'routines',
+      label: 'Routines',
+      // With names on, a routine is found by its source name, and by its R-number too.
+      items: s.code.routines.map((r, i) => {
+        const txd = `R${String(i + 1).padStart(4, '0')}`
+        const name = routineName(s, r.address)
+        return { label: name, ...(name !== txd ? { text: txd } : {}), suffix: hex4(r.address), icon: 'i-lucide-code', onSelect: pick(r.id) }
+      }),
+    },
+    {
+      id: 'dictionary',
+      label: 'Dictionary',
+      items: s.dictionary.entries.map(e => ({ label: e.word, suffix: hex4(e.address), icon: 'i-lucide-book-a', onSelect: pick(e.id) })),
+    },
+    {
+      id: 'globals',
+      label: 'Globals',
+      items: s.globals.map(g => ({ label: globalName(g.number), text: `G${g.number.toString(16).padStart(2, '0')}`, suffix: hex4(g.address), icon: 'i-lucide-variable', onSelect: pick(g.id) })),
+    },
+    {
+      id: 'strings',
+      label: 'Strings',
+      // Shown clipped, searched whole: `text` is a search key, not displayed.
+      items: s.strings.map(x => ({ label: clip(x.text), text: x.text, suffix: hex4(x.address), icon: 'i-lucide-quote', onSelect: pick(x.id) })),
+    },
+  ]
+})
+</script>
+
+<template>
+  <UModal v-model:open="open" title="Go to" description="Find a routine, object, string, dictionary word or global by name or address.">
+    <template #content>
+      <UCommandPalette :groups="groups" placeholder="Search by name or address…" class="h-96" :fuse="{ resultLimit: 40, fuseOptions: { keys: ['label', 'suffix', 'text'] } }" @update:open="open = $event" />
+    </template>
+  </UModal>
+</template>

package/app/components/StatTile.vue

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+defineProps<{ value: string | number; label: string; to?: string }>()
+</script>
+
+<template>
+  <component
+    :is="to ? 'a' : 'div'"
+    :href="to"
+    class="flex flex-col gap-1 rounded-xl border border-default bg-muted px-5 py-4 transition-colors"
+    :class="to ? 'hover:border-[var(--frotz-lamp)]' : ''"
+  >
+    <span class="data text-3xl font-semibold text-highlighted sm:text-4xl">{{ value }}</span>
+    <span class="text-sm text-muted">{{ label }}</span>
+  </component>
+</template>

package/app/components/ViewHeader.vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+/** A view's title, what it shows, a way back up (for detail views), and "Copy as text". */
+defineProps<{ title: string; eyebrow?: string; back?: { to: string; label: string }; copy?: () => string; copyLabel?: string }>()
+</script>
+
+<template>
+  <header class="flex flex-col gap-3">
+    <a v-if="back" :href="back.to" class="w-fit text-sm text-muted hover:underline">← {{ back.label }}</a>
+    <p v-if="eyebrow" class="data text-sm text-lamp">{{ eyebrow }}</p>
+    <div class="flex flex-wrap items-end justify-between gap-4">
+      <h1 class="font-display text-3xl font-bold tracking-tight text-highlighted sm:text-4xl">{{ title }}</h1>
+      <CopyText v-if="copy" :text="copy" :label="copyLabel" />
+    </div>
+    <p v-if="$slots.default" class="max-w-3xl text-muted"><slot /></p>
+  </header>
+</template>

package/app/composables/useHashRoute.ts

@@ -0,0 +1,47 @@
+/**
+ * The view is the URL hash, so every view can be bookmarked and shared: #overview,
+ * #routine/27f8, #object/47, #string/1352c, #dict/215d, #memory/objects.
+ * A model Id maps to a route one to one: its first ':' becomes '/'.
+ */
+export interface HashRoute {
+  view: string
+  id?: string
+}
+
+const current = ref<HashRoute>({ view: 'overview' })
+
+function read(): HashRoute {
+  let h: string
+  try {
+    h = decodeURIComponent(location.hash.replace(/^#/, ''))
+  } catch {
+    return { view: 'overview' } // a malformed escape (a stray '%'): not a route
+  }
+  if (!h) return { view: 'overview' }
+  const slash = h.indexOf('/')
+  return slash < 0 ? { view: h } : { view: h.slice(0, slash), id: h.slice(slash + 1) }
+}
+
+let listening = false
+
+export function useHashRoute() {
+  if (import.meta.client && !listening) {
+    listening = true
+    current.value = read()
+    window.addEventListener('hashchange', () => (current.value = read()))
+  }
+  /** Go to a route: `go('routine', '27f8')`, or a model Id: `goToId('routine:27f8')`. */
+  const go = (view: string, id?: string) => {
+    location.hash = id ? `${view}/${id}` : view
+  }
+  const goToId = (id: string) => {
+    const i = id.indexOf(':')
+    go(id.slice(0, i), id.slice(i + 1))
+  }
+  /** Replace the current route without a history entry (replaceState fires no hashchange). */
+  const replace = (view: string) => {
+    history.replaceState(null, '', `#${view}`)
+    current.value = read()
+  }
+  return { route: current, go, goToId, replace }
+}

package/app/composables/useSymbols.ts

@@ -0,0 +1,69 @@
+import { MAX_DEBUG_FILE, type StoryFile, type Symbols } from '@frotzinc/zcode'
+
+/**
+ * Names from Inform's debug file (gameinfo.dbg), over the story that's open.
+ * Dropped anywhere, or chosen on the Symbols view. A debug file written for
+ * another story is refused, not applied. `names` (the header's Names/Numbers
+ * switch) chooses whether views show them; the story itself never changes.
+ */
+const symbols = shallowRef<Symbols | null>(null)
+const symbolsFile = ref('')
+const symbolsStatus = ref<'none' | 'loading' | 'ready' | 'failed'>('none')
+const symbolsMessage = ref('')
+/** The last file chosen was refused (whatever is loaded stays). */
+const symbolsError = ref(false)
+/** The loaded file says which story it was written for, and it's this one (else: names shown unchecked). */
+const symbolsVerified = ref(false)
+const names = ref(true)
+let generation = 0
+
+/** The symbols the views should use: loaded, for this story, and switched on. */
+export const activeSymbols = computed<Symbols | undefined>(() => (names.value && symbols.value ? symbols.value : undefined))
+
+/** A debug file by its look: Inform's are named *.dbg, and are XML. */
+export const isDebugFile = (file: File) => /\.dbg$/i.test(file.name)
+
+export function useSymbols() {
+  async function loadSymbols(file: File, story: StoryFile) {
+    const mine = ++generation
+    symbolsStatus.value = 'loading'
+    symbolsMessage.value = ''
+    symbolsError.value = false
+    try {
+      // Checked before reading: an oversized file is never loaded into memory.
+      if (file.size > MAX_DEBUG_FILE) throw new Error(`It is ${Math.round(file.size / 1048576)} MB, more than a debug file can be.`)
+      const [{ readSymbols, symbolsMatch }, text] = await Promise.all([import('@frotzinc/zcode'), file.text()])
+      if (mine !== generation) return
+      const s = readSymbols(text)
+      const usable = Object.keys(s.routines).length > 0 || Object.keys(s.objects).length > 0
+      if (!usable) throw new Error(s.problems[0] ?? 'It has no names in it.')
+      const match = symbolsMatch(story.bytes, s)
+      if (match === false) throw new Error(`${file.name} was written for another story file, so its names would be wrong here.`)
+      symbols.value = markRaw(s)
+      symbolsFile.value = file.name
+      symbolsStatus.value = 'ready'
+      symbolsVerified.value = match === true
+      names.value = true
+      // A file with no story prefix can't be checked: its names are shown, and that is said.
+      symbolsMessage.value = [match === undefined ? `${file.name} doesn't say which story it was written for, so its names can't be checked against this one.` : '', ...s.problems].filter(Boolean).join(' ')
+    } catch (e) {
+      if (mine !== generation) return
+      symbolsStatus.value = symbols.value ? 'ready' : 'failed'
+      symbolsError.value = true
+      symbolsMessage.value = `${file.name} couldn't be used: ${e instanceof Error ? e.message : String(e)}`
+    }
+  }
+
+  function clearSymbols() {
+    generation++
+    symbols.value = null
+    symbolsFile.value = ''
+    symbolsStatus.value = 'none'
+    symbolsMessage.value = ''
+    symbolsError.value = false
+    symbolsVerified.value = false
+    names.value = true
+  }
+
+  return { symbols, symbolsFile, symbolsStatus, symbolsMessage, symbolsError, symbolsVerified, names, loadSymbols, clearSymbols }
+}

package/app/utils/live.ts

@@ -0,0 +1,19 @@
+/**
+ * A running machine, as a view sees it: where it is, and what changed since it last stopped.
+ *
+ * A placeholder until frotztrace's Phase 3, when @frotzinc/zmachine exports the real type and this
+ * file re-exports it. Every view takes it as an optional `live` prop; without one (frotzlens, a
+ * story file at rest) a view renders exactly as it always has.
+ */
+export interface MachineView {
+  /** The program counter: the next instruction to run. */
+  pc?: number
+  /** Index of the frame being looked at (0 = the outermost). */
+  frame?: number
+  /** What the machine wrote since the last stop. */
+  changed?: {
+    addresses: ReadonlySet<number>
+    objects: ReadonlySet<number>
+    globals: ReadonlySet<number>
+  }
+}

package/app/utils/map-layout.ts

@@ -0,0 +1,98 @@
+/**
+ * Grid placement for the map: Trizbort's rule, as frotzsmith's map draws it
+ * (ported from frotzsmith's app/composables/map-graph.ts, by the same author,
+ * keyed by object number here instead of room name). The start room sits at
+ * (0, 0); each exit puts its room one step away in its compass direction,
+ * or the nearest free cell when that one is taken; up, down, in and out go
+ * to the nearest free cell. Rooms no exit reaches start a group of their own.
+ */
+import type { Direction, RoomGraph } from '@frotzinc/zcode'
+
+export interface PlacedRoom { number: number; name: string; col: number; row: number }
+/** grid: drawn on its compass step; routine: an exit a routine decides (drawn dashed). */
+export interface Connector { from: number; to: number; dir: Direction; grid: boolean; routine: boolean }
+export interface MapLayout {
+  rooms: PlacedRoom[]
+  connectors: Connector[]
+  bounds: { minCol: number; maxCol: number; minRow: number; maxRow: number }
+}
+
+export const DELTA: Record<Direction, [number, number]> = {
+  n: [0, -1], s: [0, 1], e: [1, 0], w: [-1, 0],
+  ne: [1, -1], nw: [-1, -1], se: [1, 1], sw: [-1, 1],
+  u: [0, 0], d: [0, 0], in: [0, 0], out: [0, 0],
+}
+
+/** Each exit that reaches a room, or for a routine exit each room it can return: what the map draws. */
+export function mapEdges(g: RoomGraph): { from: number; to: number; dir: Direction; routine: boolean }[] {
+  const rooms = new Set(g.rooms.map(r => r.number))
+  return g.exits.flatMap(e =>
+    (e.to !== undefined ? [e.to] : (e.candidates ?? [])).filter(t => rooms.has(t)).map(to => ({ from: e.from, to, dir: e.dir, routine: e.kind === 'routine' })),
+  )
+}
+
+export function layoutMap(g: RoomGraph): MapLayout {
+  const edges = mapEdges(g)
+  const pos = new Map<number, [number, number]>()
+  const occupied = new Set<string>()
+  const key = (c: number, r: number) => `${c},${r}`
+  const place = (room: number, c: number, r: number) => {
+    pos.set(room, [c, r])
+    occupied.add(key(c, r))
+  }
+  // Rings outward until a free cell: there are only so many rooms, so one always turns up.
+  const nearestFree = (c: number, r: number): [number, number] => {
+    for (let ring = 0; ; ring++)
+      for (let dc = -ring; dc <= ring; dc++)
+        for (let dr = -ring; dr <= ring; dr++) {
+          if (Math.max(Math.abs(dc), Math.abs(dr)) !== ring) continue
+          if (!occupied.has(key(c + dc, r + dr))) return [c + dc, r + dr]
+        }
+  }
+  const compass = (e: { dir: Direction }) => DELTA[e.dir][0] !== 0 || DELTA[e.dir][1] !== 0
+  /**
+   * Place rooms from placed ones until nothing more can be. Compass exits go first, each to its step
+   * (or the nearest free cell); only when none is left does one up/down/in/out exit place its room,
+   * so a room any compass exit reaches is put by that, whatever order the exits come in.
+   */
+  const relax = () => {
+    for (;;) {
+      let changed = false
+      for (const e of edges) {
+        const from = pos.get(e.from)
+        if (!from || pos.has(e.to) || !compass(e)) continue
+        const [dc, dr] = DELTA[e.dir]
+        if (!occupied.has(key(from[0] + dc, from[1] + dr))) place(e.to, from[0] + dc, from[1] + dr)
+        else place(e.to, ...nearestFree(from[0] + dc, from[1] + dr))
+        changed = true
+      }
+      if (changed) continue
+      const e = edges.find(x => pos.has(x.from) && !pos.has(x.to))
+      if (!e) return
+      const from = pos.get(e.from)!
+      place(e.to, ...nearestFree(from[0], from[1]))
+    }
+  }
+  const first = g.start ?? g.rooms[0]?.number
+  if (first !== undefined) place(first, 0, 0)
+  relax()
+  for (const r of g.rooms) {
+    if (pos.has(r.number)) continue
+    place(r.number, ...nearestFree(0, 0))
+    relax()
+  }
+
+  const connectors = edges.map(e => {
+    const a = pos.get(e.from)!
+    const b = pos.get(e.to)!
+    const [dc, dr] = DELTA[e.dir]
+    return { ...e, grid: (dc !== 0 || dr !== 0) && b[0] === a[0] + dc && b[1] === a[1] + dr }
+  })
+  const placed = [...pos.values()]
+  const cols = placed.map(p => p[0])
+  const rows = placed.map(p => p[1])
+  const bounds = placed.length
+    ? { minCol: Math.min(...cols), maxCol: Math.max(...cols), minRow: Math.min(...rows), maxRow: Math.max(...rows) }
+    : { minCol: 0, maxCol: 0, minRow: 0, maxRow: 0 }
+  return { rooms: g.rooms.map(r => ({ ...r, col: pos.get(r.number)![0], row: pos.get(r.number)![1] })), connectors, bounds }
+}

package/app/utils/nav.ts

@@ -0,0 +1,10 @@
+/** One entry in AppNav: a view, by its route key. */
+export interface NavView {
+  key: string
+  label: string
+  icon: string
+  /** How many things the view lists, shown at the right. */
+  count?: number
+  /** A word shown at the right instead of a count. */
+  tag?: string
+}

package/app/utils/story.ts

@@ -0,0 +1,87 @@
+/**
+ * Names for the things in a story, as txd and infodump print them (R0001,
+ * S001, an object's short name, a dictionary word), and the hash route for any
+ * model Id. Worked out once per story and cached.
+ */
+import type { StoryFile } from '@frotzinc/zcode'
+import { txdRoutineName, txdStringName } from '@frotzinc/zcode/format'
+import { activeSymbols } from '../composables/useSymbols'
+
+export const hex = (n: number, width = 4) => n.toString(16).padStart(width, '0')
+
+/** The hash route for a model Id: `routine:27f8` → `#routine/27f8`. */
+export const idRoute = (id: string) => `#${id.replace(':', '/')}`
+
+interface Index {
+  routineNumber: Map<number, number>
+  stringNumber: Map<number, number>
+  stringByAddress: Map<number, { text: string }>
+  dictByAddress: Map<number, { word: string }>
+}
+
+const cache = new WeakMap<StoryFile, Index>()
+
+export function storyIndex(story: StoryFile): Index {
+  let i = cache.get(story)
+  if (!i) {
+    i = {
+      routineNumber: new Map(story.code.routines.map((r, n) => [r.address, n + 1])),
+      stringNumber: new Map(story.strings.map((s, n) => [s.address, n + 1])),
+      stringByAddress: new Map(story.strings.map(s => [s.address, s])),
+      dictByAddress: new Map(story.dictionary.entries.map(e => [e.address, e])),
+    }
+    cache.set(story, i)
+  }
+  return i
+}
+
+/**
+ * A routine's name: its source name when a debug file is loaded and names are on, else txd's
+ * (R0001), from zcode, so a link reads exactly as the disassembly does.
+ */
+export const routineName = (story: StoryFile, address: number) => activeSymbols.value?.routines[address]?.name ?? txdRoutineName(story, address)
+export const stringName = txdStringName
+
+/** A global: its source name with symbols, else txd's G00. */
+export const globalName = (n: number) => activeSymbols.value?.globals[n] ?? `G${hex(n, 2)}`
+/** An attribute, property or action number, with its source name when there is one. */
+export const attributeName = (n: number) => activeSymbols.value?.attributes[n]
+export const propertyName = (n: number) => activeSymbols.value?.properties[n]
+export const actionName = (n: number) => activeSymbols.value?.actions[n]
+
+export const objectName = (story: StoryFile, n: number) =>
+  story.objects.objects[n - 1]?.shortName.text || `object ${n}`
+
+export const clip = (s: string, n = 60) => {
+  const one = s.replace(/\s+/g, ' ')
+  return one.length > n ? `${one.slice(0, n)}…` : one
+}
+
+/** A short, readable label for any model Id. */
+export function idLabel(story: StoryFile, id: string): string {
+  const [kind, rest = ''] = id.split(':')
+  const n = parseInt(rest, kind === 'object' || kind === 'global' || kind === 'abbrev' ? 10 : 16)
+  switch (kind) {
+    case 'routine': return routineName(story, n)
+    case 'string': {
+      const s = storyIndex(story).stringByAddress.get(n)
+      return s ? `${stringName(story, n)} “${clip(s.text, 40)}”` : stringName(story, n)
+    }
+    case 'object': return `${objectName(story, n)} (#${n})`
+    case 'dict': {
+      const e = storyIndex(story).dictByAddress.get(n)
+      return e ? `“${e.word}”` : `word at ${hex(n)}`
+    }
+    case 'global': return globalName(n)
+    default: return id
+  }
+}
+
+/** Show a long list a page at a time: `shown` is the first `limit`, `more()` adds a page. */
+export function useLimit<T>(list: () => T[], step = 200) {
+  const limit = ref(step)
+  const shown = computed(() => list().slice(0, limit.value))
+  const remaining = computed(() => Math.max(0, list().length - limit.value))
+  const more = () => (limit.value += step)
+  return { shown, remaining, more, reset: () => (limit.value = step) }
+}

package/nuxt.config.ts

@@ -0,0 +1,12 @@
+/**
+ * @frotzinc/zcode-ui — the Z-machine story views shared by frotzlens and frotztrace, as a Nuxt layer.
+ *
+ *   export default defineNuxtConfig({ extends: ['@frotzinc/nuxt-base', '@frotzinc/zcode-ui'] })
+ *
+ * Gives, auto-imported: the views (ObjectTree, GlobalsView, MapView, Disassembly, HexPane,
+ * SearchPalette, AppNav) and their parts (RefLink, Referrers, ViewHeader, CopyText, StatTile,
+ * NotFound); the composables useHashRoute and useSymbols; and the utils in app/utils (hex,
+ * routineName, idLabel, layoutMap, …). It adds no colors, fonts or CSS: the look is
+ * @frotzinc/nuxt-base's, so every frotz, Inc. app looks the same. The app lists @nuxt/ui in `modules`.
+ */
+export default defineNuxtConfig({})

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@frotzinc/zcode-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The Z-machine story views of frotzlens as a Nuxt layer: object tree, globals, map, disassembly, hex, go-to palette and the pieces they share, for frotzlens and frotztrace.",
+  "license": "MIT",
+  "author": "Christopher Schweda",
+  "type": "module",
+  "homepage": "https://github.com/cschweda/frotzlens/tree/main/packages/zcode-ui",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cschweda/frotzlens.git",
+    "directory": "packages/zcode-ui"
+  },
+  "bugs": {
+    "url": "https://github.com/cschweda/frotzlens/issues"
+  },
+  "keywords": [
+    "z-machine",
+    "interactive-fiction",
+    "nuxt",
+    "nuxt-layer",
+    "nuxt-ui",
+    "frotzinc"
+  ],
+  "main": "./nuxt.config.ts",
+  "exports": {
+    ".": "./nuxt.config.ts",
+    "./nuxt.config.ts": "./nuxt.config.ts",
+    "./utils/*": "./app/utils/*.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "nuxt.config.ts",
+    "app",
+    "!**/*.test.ts",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@frotzinc/zcode": "0.4.1"
+  },
+  "peerDependencies": {
+    "@nuxt/ui": "^4.12.0",
+    "nuxt": "^4.6.0",
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "vitest": "^5.1.0",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }