@frotzinc/zcode-ui 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.

package/app/components/Disassembly.vue

@@ -7,7 +7,11 @@ import type { MachineView } from '../utils/live'
  * 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 }>()
+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) {
@@ -29,7 +33,16 @@ function jump(target: number) {
         :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>
+        :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

@@ -9,12 +9,15 @@ const number = computed(() => (props.id && /^\d+$/.test(props.id) ? Number(props
 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 }))
+    .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/, '')))
 })
 
@@ -41,15 +44,20 @@ const asText = () =>
             <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">
+          <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>

package/app/components/HexPane.vue

@@ -4,8 +4,8 @@ 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.
+ * `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
@@ -38,6 +38,8 @@ const rows = computed(() => {
   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('')
@@ -82,9 +84,9 @@ function onJump() {
         <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-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.join(' · ') }}</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>

package/app/components/MapView.vue

@@ -58,6 +58,27 @@ const exitIndex = computed(() => {
 })
 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>
 
@@ -109,11 +130,11 @@ const copy = () => JSON.stringify(toMapGraph(graph.value!), null, 2) + '\n'
               :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"
+              :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="var(--ui-text-highlighted)">{{ short(name(r.number)) }}</text>
+            <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>
@@ -124,6 +145,8 @@ const copy = () => JSON.stringify(toMapGraph(graph.value!), null, 2) + '\n'
           <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>

package/app/components/ObjectTree.vue

@@ -169,7 +169,8 @@ function onKey(e: KeyboardEvent) {
       >
         <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="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>

package/app/composables/useSymbols.ts

@@ -8,6 +8,8 @@ import { MAX_DEBUG_FILE, type StoryFile, type Symbols } from '@frotzinc/zcode'
  */
 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). */
@@ -40,6 +42,7 @@ export function useSymbols() {
       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
@@ -57,6 +60,7 @@ export function useSymbols() {
   function clearSymbols() {
     generation++
     symbols.value = null
+    symbolsText.value = ''
     symbolsFile.value = ''
     symbolsStatus.value = 'none'
     symbolsMessage.value = ''
@@ -65,5 +69,5 @@ export function useSymbols() {
     names.value = true
   }
 
-  return { symbols, symbolsFile, symbolsStatus, symbolsMessage, symbolsError, symbolsVerified, names, loadSymbols, clearSymbols }
+  return { symbols, symbolsFile, symbolsText, symbolsStatus, symbolsMessage, symbolsError, symbolsVerified, names, loadSymbols, clearSymbols }
 }

package/app/utils/live.ts

@@ -1,19 +1,7 @@
 /**
- * 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.
+ * 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 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>
-  }
-}
+export type { MachineView } from '@frotzinc/zmachine'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frotzinc/zcode-ui",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -38,7 +38,8 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@frotzinc/zcode": "0.4.1"
+    "@frotzinc/zcode": "0.5.0",
+    "@frotzinc/zmachine": "0.2.0"
   },
   "peerDependencies": {
     "@nuxt/ui": "^4.12.0",