@frotzinc/zcode-ui 0.0.0-stage → 0.2.0

package/app/components/ObjectTree.vue

@@ -0,0 +1,177 @@
+<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" :class="live?.changed.objects.has(r.n) ? 'font-semibold text-lamp' : ''">{{ name(r.n) }}</span>
+      <span v-if="live?.changed.objects.has(r.n)" class="rounded-full border border-default px-1.5 text-xs text-lamp">changed</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,73 @@
+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('')
+/** The debug file's text as read (frotzlens hands it to frotztrace with the story). */
+const symbolsText = shallowRef('')
+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)
+      symbolsText.value = text
+      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
+    symbolsText.value = ''
+    symbolsFile.value = ''
+    symbolsStatus.value = 'none'
+    symbolsMessage.value = ''
+    symbolsError.value = false
+    symbolsVerified.value = false
+    names.value = true
+  }
+
+  return { symbols, symbolsFile, symbolsText, symbolsStatus, symbolsMessage, symbolsError, symbolsVerified, names, loadSymbols, clearSymbols }
+}

package/app/utils/live.ts

@@ -0,0 +1,7 @@
+/**
+ * A running machine, as a view sees it: where it is, and what changed since it last stopped. The
+ * Debugger's own type (@frotzinc/zmachine, since frotztrace Phase 3), re-exported here: 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 type { MachineView } from '@frotzinc/zmachine'

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({})