Pravetz 82

Embedding

The Pravetz 82 is an Apple II clone, so rather than write a new machine we reuse the apple2js core (Will Scullin's Apple II, MIT) vendored here as apple2js-boot.js, and point it at the Pravetz ROMs that apple2js already carries: the system ROM pravetz82 and the Cyrillic character ROM pravetz82_char. We load the bundle as one plain <script> and drive the machine from a loop we control, so it can be paused and single-stepped for the debugger.

Boot. A tiny global picks the ROM pair; the bundle constructs the core Apple2 class (not its React UI), points it at a <canvas>, resets the 6502, then runs a loop on cpu.stepCycles():

// choose the Pravetz ROM + Cyrillic character ROM
window.__APPLE2JS_CFG = { rom: "pravetz82", characterRom: "pravetz82_char" };

const apple2 = new Apple2({
  canvas: document.querySelector("#screen"),
  rom: "pravetz82", characterRom: "pravetz82_char",
  e: false, enhanced: false, gl: false, tick: ()=>{}
});
await apple2.ready;
const cpu = apple2.getCPU(), io = apple2.getIO();
cpu.reset();                                // reset vector → Autostart ROM → ПРАВЕЦ / BASIC

The whole machine is plain objects. apple2js exposes everything the debugger needs as ordinary methods — no wasm heap to reach into:

Because the CPU, bus and I/O are ordinary JavaScript objects, the debugger single-steps with cpu.step(), reads and writes registers through getState/setState, disassembles from cpu.read, and implements breakpoints and watchpoints as host-side checks — with no changes to the emulator core.

Debugger integration

Wiring the Pravetz into the shared in-browser debugger reused the apple2js integration and added a Cyrillic keyboard.

1 · A boot shim we can pause. apple2js's normal entry builds a React UI and owns an internal requestAnimationFrame loop that cannot be single-stepped from outside. So the bundled boot constructs just the core Apple2 machine and drives it from a loop we control. When no breakpoints are armed it runs a whole frame fast with cpu.stepCycles(); when a breakpoint or watchpoint is set it steps one instruction at a time:

function runCycles(target){
  if (!bps.size && !wps.size){ cpu.stepCycles(target); return false; }
  for (let done=0; done<target; ){
    if (bps.has(cpu.getPC())) return true;   // execution breakpoint
    const pre = watchSnapshot(), c0 = cpu.getCycles();
    cpu.step(); done += cpu.getCycles() - c0;
    if (watchChanged(pre)) return true;     // value-change watchpoint
  }
}

2 · One self-contained script. apple2js loads its ROMs with dynamic import(); the bundle is built with webpack's dynamicImportMode: 'eager', so every ROM — including pravetz82 and pravetz82_char — is inlined. Nothing is fetched at runtime.

3 · A Cyrillic keyboard. On the Pravetz the character ROM holds the Cyrillic glyphs in the lower-case code range ($61–$7A), and the machine's Latin/Cyrillic switch chooses whether a letter key emits its upper-case (Latin) or lower-case (Cyrillic) code. The plug-in reproduces that with a ЛАТ/КИР toggle: in КИР mode a letter is sent as base+0x20, which pravetz82_char renders as the phonetic Cyrillic letter (a→А, b→Б, c→Ц). The same toggle also re-routes the physical keyboard via a capture-phase key handler.

Techniques for deeper access. The plug-in reaches into the running machine through apple2js's own surfaces — no fork of the core:

• Side-effect-free reads. The hex and disassembly views read the bus with a wrapper that skips the $C000–$C0FF soft-switch window, so auto-polling the view can never flip a display page or clear the keyboard strobe.
• Direct state. Registers are read and written through cpu.getState() / setState(); the status flags are the bits of state.s.
• Single instruction step. cpu.step() runs exactly one instruction — the primitive under Step and under the breakpoint loop.
• Breakpoints & watchpoints. Execution breakpoints compare cpu.getPC() before each instruction; memory watchpoints compare the watched addresses' values after each instruction — both host-side.

Architecture

The Pravetz 82 (Правец 82, 1982+) is a Bulgarian Apple II clone built by the Pravetz plant. It is faithful to the Apple ][ at the chip level, with a Cyrillic character generator and a Latin/Cyrillic keyboard switch as the main additions. Emulated here through the object-oriented apple2js core, every block is an ordinary JavaScript class hanging off Apple2:

• CPU6502 (from @whscullin/cpu6502) — the MOS 6502 interpreter. Memory is reached through page handlers registered with addPageHandler.
• Apple2IO — the $C0xx I/O space: keyboard latch, speaker, annunciators, game paddles and the peripheral-card slots.
• VideoModes with LoresPage / HiresPage — the text, lo-res and hi-res display, rastered to a 560×384 canvas. Text uses the pravetz82_char generator, which carries Latin upper case plus the Cyrillic set.
• RAM and ROM page handlers — 48K of main RAM plus the pravetz82 system ROM (the Pravetz monitor + an Applesoft-compatible BASIC); a LanguageCard adds the upper 16K.

Each frame steps the 6502 for a slice of time and blits the video. Because every component is an ordinary object with getState/setState, the whole machine is inspectable — which is what the debugger reads each refresh.