stm32f4-emu 1.0.0 → 1.1.1

package/README.md

@@ -7,7 +7,8 @@
 [![Pages](https://github.com/danish9661/stm32F4-emulator/actions/workflows/pages.yml/badge.svg)](https://github.com/danish9661/stm32F4-emulator/actions/workflows/pages.yml)
 
 An STM32F407 microcontroller emulator that runs real Cortex-M4 firmware. It
-combines a **Unicorn CPU core** (QEMU-derived, compiled to WASM) with a
+combines a **Rust CPU core** (a WASM-native Thumb-2 interpreter with exact
+Cortex-M exception entry/return, including the VFPv4-SP FPU) with a
 **Rust peripheral model** (RCC, USART, GPIO, DMA, ETH, TIM, NVIC, ...) also
 compiled to WASM — so the whole machine runs headless in **Node.js or a
 browser tab**, with no SDL, no native deps, no hardware.
@@ -32,18 +33,18 @@ scripted network (netsim) as fallback, a live UART terminal (with **UART
 RX input** — type into the console and the firmware reads it; newline
 characters excluded per HTML spec, see AGENTS.md §11), GPIO pin readout
 for banks A–E, and key peripheral registers. Interrupt-driven firmware
-(`rx_interrupt_test`, `rx_crypto_test`) is serviced by an opt-in guest-IRQ
-pump; polling firmware (the ETH demos) never uses it. For automation, a
+(`rx_interrupt_test`, `rx_crypto_test`) gets inline guest-IRQ delivery;
+polling firmware (the ETH demos) never uses it. For automation, a
 preset can auto-boot via the URL: `?fw=eth_http`, `?fw=blinky`, `?fw=crypto_test`, …
 
 ## DOOM (in the browser)
 
 **[`site/doom.html`](site/doom.html)** runs DOOM 1 shareware
-(doomgeneric, ported to the emulated F407) at ~25 FPS in a
-headless-Chrome-verified browser page — playable, but below DOOM's native
-35 fps: at ~918k guest instructions per rendered frame, 35 fps would need
-~32 MIPS and the Unicorn WASM core tops out near 20-24 (details and the
-measurements in AGENTS.md §16). Because the guest mixes one frame of audio
+(doomgeneric, ported to the emulated F407) at the full 35 fps in a
+headless-Chrome-verified browser page — playable: at ~1M guest instructions
+per rendered frame, 35 fps needs ~32 MIPS and the Rust core delivers ~65
+(details and the measurements in AGENTS.md §16/§22). Because the guest mixes
+one frame of audio
 per rendered frame, sound below 35 fps plays slightly slow and pitched-down
 rather than breaking up — the worklet rate-matches instead of inserting
 gaps, and the stats line reports it (`audio 0.72x`). The page: 320×200
@@ -182,9 +183,9 @@ watchdog timeouts close to spec) will diverge — see docs/progress-and-future.m
 ## Architecture
 
 ```
-firmware .bin ──► Unicorn WASM CPU ──► memory hooks
+firmware .bin ──► Rust WASM CPU (Thumb-2 + NVIC/exceptions)
                           │
-                    periph_read/write ──► Rust peripheral model (WASM)
+              peripheral MMIO ──► Rust peripheral model (WASM)
                                           RCC USART GPIO DMA ETH TIM NVIC
                           │
                     UART out / ETH TX frames ──► driver (cli.mjs / site/emulator.js)
@@ -192,9 +193,10 @@ firmware .bin ──► Unicorn WASM CPU ──► memory hooks
                     RX frames injected (netsim, or real gVisor gateway)
 ```
 
-- **CPU**: Unicorn 2.1.4 compiled to WASM executes Thumb-2 code; every
-  read/write to a hooked MMIO range is routed into the Rust model, which
-  answers by writing the modeled register value back into guest memory.
+- **CPU**: a pure-Rust Cortex-M4 Thumb-2 interpreter compiled to WASM;
+  peripheral accesses call straight into the Rust model, and guest IRQs
+  (SysTick, ETH, USART, SVC/PendSV) are delivered inline with exact
+  exception stacking — no native deps, no JIT, no hooks.
 - **Peripherals**: a `wasm-bindgen` crate (`stm32-periph-wasm/`); registers
   and bit fields come from the vendor SVD (`monox/stm32f407.svd`).
 - **Ethernet**: TX is captured from the DMA descriptors; RX frames are
@@ -223,8 +225,8 @@ firmware .bin ──► Unicorn WASM CPU ──► memory hooks
 │   ├── test_blinky.mjs      Node blinky GPIO test (npm test)
 │   ├── test_rx_interrupt.mjs Node UART-interrupt test (npm test)
 │   ├── test_component_*.mjs Component-API tests, one firmware each (npm test)
-│   ├── test_doom.mjs        Node DOOM boot/menu/gameplay/save test
-│   └── vendor/              Browser WASM build, SVD, Unicorn
+│   ├── test_doom_wasm.mjs  Node DOOM boot/menu/gameplay/save test
+│   └── vendor/              Browser WASM build (CPU + peripherals), SVD
 ├── index.mjs, package.json  npm package entry (stm32f4-emu)
 ├── mcp/                     MCP server (drive the emulator from an AI agent)
 ├── .github/workflows/       CI (Linux/Windows/macOS test matrix) + Pages deploy
@@ -296,6 +298,5 @@ rebuild — delete it so the vendor assets stay tracked/committed.
 ## License & Credits
 
 - **License**: GPL-3.0-only. See [LICENSE](LICENSE).
-- **Unicorn CPU Core**: Powered by [Unicorn.js](https://github.com/AlexAltea/unicorn.js) by [Alex Altea](https://github.com/AlexAltea) (WASM/JS port of the [Unicorn Engine](https://www.unicorn-engine.org/) CPU emulator, derived from QEMU, licensed under GPLv2).
 - **Heritage**: Fork and continuation of [nviennot/stm32-emulator](https://github.com/nviennot/stm32-emulator) (native SDL 3D printer emulator by Nicolas Viennot). The headless WASM peripheral model, networking stack, browser demo, virtual components API, MCP server, and npm package are new work built on that base.
 - **DOOM**: Ported using [doomgeneric](https://github.com/ozkl/doomgeneric) by Ozkan Sezgin.

package/cli.mjs

@@ -10,15 +10,12 @@
 // emulator advances the virtual RTC until a wakeup source (e.g. an RTC alarm)
 // fires — so firmware that enters STOP (e.g. deep_sleep_demo.bin) runs.
 import { readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import * as bindings from './site/vendor/stm32_periph_wasm.js';
 import { createEmulator } from './site/emulator.js';
 import { parseIntelHex, parseElf } from './site/loaders.js';
 
-const require = createRequire(import.meta.url);
-const unicornFactory = require('./site/vendor/unicorn_arm.cjs');
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const svdXml = readFileSync(resolve(__dirname, 'site/vendor/stm32f407.svd'), 'utf8');
 const wasmBytes = new Uint8Array(readFileSync(resolve(__dirname, 'site/vendor/stm32_periph_wasm_bg.wasm')));
@@ -35,7 +32,7 @@ Arguments:
 Options:
   -n, --inst <N>        instruction budget to run (default 20000000)
   -f, --format <fmt>    firmware format: auto|bin|hex|elf (default auto)
-  -v, --verbose         trace peripheral register reads/writes to stderr
+  -v, --verbose         trace guest PCs to stderr (capped per step)
   -l, --lowpower        halt on WFI/WFE and advance the virtual RTC until wakeup
   -h, --help            show this help
   -V, --version         show version
@@ -119,8 +116,8 @@ async function main() {
     let emu;
     try {
         emu = await createEmulator({
-            firmware, bindings, unicorn: unicornFactory, svdXml, wasmInit: wasmBytes,
-            extra_mem, verbose, lowpower,
+            firmware, bindings, svdXml, wasmInit: wasmBytes,
+            extra_mem, lowpower,
         });
     } catch (e) {
         fail(`emulator failed to load firmware: ${e.message}`);
@@ -132,7 +129,15 @@ async function main() {
     try {
         while (remaining > 0) {
             const take = Math.min(STEP, remaining);
+            if (verbose) { try { emu.traceStart(); } catch {} }
             const r = emu.step(take);
+            if (verbose) {
+                try {
+                    const pcs = emu.takeTrace() || [];
+                    const tail = pcs.slice(-8).map((p) => `0x${(p >>> 0).toString(16)}`).join(' ');
+                    if (tail) process.stderr.write(`[trace]${tail}\n`);
+                } catch {} finally { try { emu.traceStop(); } catch {} }
+            }
             remaining -= (r.instCount - lastInst);
             lastInst = r.instCount;
             const u = emu.drainUart();

package/index.d.ts

@@ -0,0 +1,48 @@
+/// <reference types="node" />
+
+import { createEmulator, CreateEmulatorOpts, EmulatorHandle } from './site/emulator.js';
+
+export * from './site/emulator.js';
+
+export interface CreateSTM32F407Opts extends CreateEmulatorOpts {
+  /** A Uint8Array, or a key into the bundled FIRMWARES table. */
+  firmware: Uint8Array | string;
+}
+
+export function createSTM32F407(opts?: CreateSTM32F407Opts): Promise<EmulatorHandle>;
+export function decodeFirmware(key: string): Uint8Array;
+export function createNetSim(opts?: any): any;
+
+export const FIRMWARES: Record<string, { bytes: string; [key: string]: unknown }>;
+export const bindings: any;
+export const unicornFactory: any;
+export const svdXml: string;
+
+// Component-attachment API (attach devices to an emulator handle).
+export class LED {
+  constructor(emu: any, port: string, num: number, opts?: { activeLow?: boolean });
+  on(): void;
+  off(): void;
+  toggle(): void;
+  read(): boolean;
+  onChange(cb: (on: boolean) => void): void;
+}
+export class Button {
+  constructor(emu: any, port: string, num: number, opts?: { activeLow?: boolean });
+  press(): void;
+  release(): void;
+  read(): boolean;
+  on(evt: 'down' | 'up', cb: () => void): void;
+}
+export class Pwm {
+  constructor(emu: any, timer: string, channel?: number, opts?: { clockHz?: number });
+  setDuty(percent: number): void;
+  read(): number;
+}
+export class Potentiometer {
+  constructor(emu: any, peripheral: string, channel?: number, opts?: { min?: number; max?: number });
+  set(value: number): void;
+}
+export class I2cRegisterDevice {
+  constructor(emu: any, peripheral: string, opts?: any);
+}

package/index.mjs

@@ -1,8 +1,7 @@
 // stm32f4-emu — Node API entry.
 // Wraps the browser/Node-universal emulator.js with the bundled assets
-// (SVD, wasm bindings, Unicorn) so Node consumers get a one-call setup.
+// (SVD, wasm bindings) so Node consumers get a one-call setup.
 import { readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import * as bindings from './site/vendor/stm32_periph_wasm.js';
 import { createEmulator } from './site/emulator.js';
 import { createNetSim } from './site/netsim.js';
@@ -14,23 +13,19 @@ import { STM32F4, GPIOPin, USART, DMAStream } from './site/stm32f4.js';
 // `firmware` option is optional (defer to loadBin/loadHex/loadELF after
 // create), matching the rp2040js / avr8js ergonomics.
 STM32F4.create = (opts = {}) => STM32F4._create({
-    bindings, unicorn: unicornFactory, svdXml, wasmInit: wasmBytes, ...opts,
+    bindings, svdXml, wasmInit: wasmBytes, ...opts,
 });
 
-const require = createRequire(import.meta.url);
-const unicornFactory = require('./site/vendor/unicorn_arm.cjs');
-
 const svdXml = readFileSync(new URL('./site/vendor/stm32f407.svd', import.meta.url), 'utf8');
 const wasmBytes = new Uint8Array(readFileSync(new URL('./site/vendor/stm32_periph_wasm_bg.wasm', import.meta.url)));
 
 // Decode a base64-encoded firmware from FIRMWARES.
+// Uses single-pass Uint8Array.from for fewer allocations than manual loop.
 export function decodeFirmware(key) {
     const fw = FIRMWARES[key];
     if (!fw) throw new Error(`unknown firmware '${key}' (have: ${Object.keys(FIRMWARES).join(', ')})`);
     const bin = atob(fw.bytes);
-    const out = new Uint8Array(bin.length);
-    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
-    return out;
+    return Uint8Array.from(bin, c => c.charCodeAt(0));
 }
 
 // Convenience: create an emulator with the bundled STM32F407 assets.
@@ -41,7 +36,7 @@ export async function createSTM32F407(opts = {}) {
     const { firmware } = opts;
     const bin = typeof firmware === 'string' ? decodeFirmware(firmware) : firmware;
     if (!bin) throw new Error('createSTM32F407 requires `firmware` (Uint8Array or a FIRMWARES key)');
-    return createEmulator({ ...opts, firmware: bin, bindings, unicorn: unicornFactory, svdXml, wasmInit: wasmBytes });
+    return createEmulator({ ...opts, firmware: bin, bindings, svdXml, wasmInit: wasmBytes });
 }
 
-export { createEmulator, createNetSim, FIRMWARES, bindings, unicornFactory, svdXml, LED, Button, Pwm, I2cRegisterDevice, Potentiometer, STM32F4, GPIOPin, USART, DMAStream };
+export { createEmulator, createNetSim, FIRMWARES, bindings, svdXml, LED, Button, Pwm, I2cRegisterDevice, Potentiometer, STM32F4, GPIOPin, USART, DMAStream };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "stm32f4-emu",
-  "version": "1.0.0",
-  "description": "STM32F407 emulator: Unicorn (WASM) CPU + Rust peripheral model. Runs real Cortex-M4 firmware in Node or the browser.",
+  "version": "1.1.1",
+  "description": "STM32F407 emulator: Rust CPU + peripheral model (WASM). Runs real Cortex-M4 firmware in Node or the browser.",
   "type": "module",
   "main": "index.mjs",
   "bin": {
@@ -9,6 +9,7 @@
     "stm32f4-mcp": "./mcp/server.mjs",
     "stm32f4-bridge": "./site/ws-bridge.mjs"
   },
+  "types": "index.d.ts",
   "exports": {
     ".": "./index.mjs",
     "./components": "./site/components.js",
@@ -18,26 +19,29 @@
     "./loaders": "./site/loaders.js",
     "./stm32f4": "./site/stm32f4.js",
     "./vendor": "./site/vendor/stm32_periph_wasm.js",
-    "./vendor/unicorn": "./site/vendor/unicorn_arm.cjs",
     "./remote": "./site/remote-emu.js",
-    "./ws-bridge": "./site/ws-bridge.mjs",
-    "./site": "./site/index.html"
+    "./ws-bridge": "./site/ws-bridge.mjs"
   },
   "files": [
     "index.mjs",
+    "index.d.ts",
     "cli.mjs",
     "README.md",
+    "LICENSE",
     "site/emulator.js",
+    "site/emulator.d.ts",
+    "site/stm32f4.js",
     "site/components.js",
-    "mcp/server.mjs",
     "site/netsim.js",
     "site/firmware.js",
     "site/loaders.js",
-    "site/index.html",
-    "site/app.js",
     "site/remote-emu.js",
     "site/ws-bridge.mjs",
-    "site/vendor/"
+    "site/app.js",
+    "site/index.html",
+    "site/vendor/",
+    "mcp/server.mjs",
+    "tools/make_firmware.mjs"
   ],
   "keywords": [
     "stm32",
@@ -45,7 +49,6 @@
     "emulator",
     "arm",
     "cortex-m4",
-    "unicorn",
     "wasm",
     "embedded",
     "firmware"
@@ -63,7 +66,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "test": "node site/test_stm32f4_api.mjs && node site/test_stm32f4_periph.mjs && node site/test_ws_bridge.mjs && node site/test_flow.mjs && node site/test_blinky.mjs && node site/test_rx_interrupt.mjs && node site/test_component_led.mjs && node site/test_component_button.mjs && node site/test_component_pwm.mjs && node site/test_component_i2cregfile.mjs && node site/test_component_adc.mjs && node site/test_multi_instance.mjs && node site/test_fsmc_dcmi.mjs && node site/test_fsmc.mjs && node site/test_dcmi.mjs && node site/probe_freertos.mjs   && node site/test_candemo.mjs && node site/test_lowpower.mjs   && node site/test_edge_cases.mjs && node site/test_can_inject.mjs   && node site/test_watchdog.mjs   && node site/test_wwdg.mjs   && node site/test_wwdg_window.mjs && node site/test_tim_capture.mjs && node site/test_qspi.mjs && node site/test_qspi_cdp.mjs && node site/test_browser.mjs",
+    "test": "node site/test_stm32f4_api.mjs && node site/test_stm32f4_periph.mjs && node site/test_ws_bridge.mjs && node site/test_flow.mjs && node site/test_blinky.mjs && node site/test_rx_interrupt.mjs && node site/test_component_led.mjs && node site/test_component_button.mjs && node site/test_component_pwm.mjs && node site/test_component_i2cregfile.mjs && node site/test_component_adc.mjs && node site/test_multi_instance.mjs && node site/test_fsmc_dcmi.mjs && node site/test_fsmc.mjs && node site/test_dcmi.mjs && node site/probe_freertos.mjs   && node site/test_candemo.mjs && node site/test_lowpower.mjs   && node site/test_edge_cases.mjs && node site/test_can_inject.mjs   && node site/test_watchdog.mjs   && node site/test_wwdg.mjs   && node site/test_wwdg_window.mjs && node site/test_tim_capture.mjs && node site/test_qspi.mjs && node site/test_fpu.mjs && node site/test_fpu_irq.mjs && node site/test_mpu.mjs && node site/test_usb.mjs && node site/test_qspi_cdp.mjs && node site/test_browser.mjs",
     "test:unit": "node site/test_stm32f4_api.mjs && node site/test_stm32f4_periph.mjs && node site/test_ws_bridge.mjs && node site/test_flow.mjs && node site/test_blinky.mjs && node site/test_rx_interrupt.mjs && node site/test_component_led.mjs && node site/test_component_button.mjs && node site/test_component_pwm.mjs && node site/test_component_i2cregfile.mjs && node site/test_component_adc.mjs && node site/test_multi_instance.mjs && node site/test_fsmc_dcmi.mjs && node site/test_fsmc.mjs && node site/test_dcmi.mjs && node site/probe_freertos.mjs   && node site/test_candemo.mjs && node site/test_lowpower.mjs   && node site/test_edge_cases.mjs && node site/test_can_inject.mjs   && node site/test_watchdog.mjs   && node site/test_wwdg.mjs   && node site/test_wwdg_window.mjs && node site/test_tim_capture.mjs && node site/test_qspi.mjs",
     "test:bridge": "node site/test_ws_bridge.mjs",
     "test:bridge:browser": "node site/test_bridge_cdp.mjs",
@@ -79,6 +82,9 @@
     "test:timcap": "node site/test_tim_capture.mjs",
     "test:lowpower": "node site/test_lowpower.mjs",
     "test:qspi": "node site/test_qspi.mjs",
+    "test:fpu": "node site/test_fpu.mjs",
+    "test:fpuirq": "node site/test_fpu_irq.mjs",
+    "test:mpu": "node site/test_mpu.mjs",
     "test:qspi:browser": "node site/test_qspi_cdp.mjs",
     "test:browser": "node site/test_browser.mjs",
     "test:edge": "node site/test_edge_cases.mjs",
@@ -89,7 +95,15 @@
     "bridge": "node site/ws-bridge.mjs",
     "firmwares": "node tools/make_firmware.mjs",
     "serve": "python3 -m http.server 8123 --directory site",
-    "prepack": "node tools/make_firmware.mjs"
+    "prepack": "node tools/make_firmware.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint site mcp tools index.mjs cli.mjs",
+    "format": "prettier --check .",
+    "format:write": "prettier --write .",
+    "build:wasm": "wasm-pack build stm32-periph-wasm --target web --out-dir ../site/vendor && rm -f site/vendor/.gitignore && cp monox/stm32f407.svd site/vendor/ 2>/dev/null || true; command -v wasm-opt >/dev/null 2>&1 && wasm-opt -O3 site/vendor/stm32_periph_wasm_bg.wasm -o site/vendor/stm32_periph_wasm_bg.wasm || echo 'wasm-opt not found, skipping'",
+    "build:wasm:node": "wasm-pack build stm32-periph-wasm --target nodejs --out-dir pkg",
+    "build:wasm:opt": "wasm-opt -O3 site/vendor/stm32_periph_wasm_bg.wasm -o site/vendor/stm32_periph_wasm_bg.wasm",
+    "test:wasm": "node site/test_wasm_cpu.mjs && node site/test_flow_wasm.mjs && node site/test_audio_wasm.mjs && node site/test_wasm_multi.mjs && node site/test_lowpower_wasm.mjs && node site/probe_freertos.mjs && node site/test_doom_wasm.mjs"
   },
   "dependencies": {
     "ws": "^8.21.3"
@@ -109,6 +123,9 @@
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "playwright": "^1.62.1",
-    "zod": "^3.25 || ^4.0"
+    "zod": "^3.25 || ^4.0",
+    "typescript": "^5.6.0",
+    "eslint": "^9.0.0",
+    "prettier": "^3.0.0"
   }
 }

package/site/app.js

@@ -2,10 +2,11 @@
 // Preset + custom (.bin/.hex/.elf/.map) firmware loading, Run/Stop/Reset,
 // an optional WebSocket gateway (real network stack) with a netsim fallback,
 // live UART terminal, GPIO/peripheral register readout, and packet viewer.
-import * as bindings from './vendor/stm32_periph_wasm.js';
+import * as bindings from './vendor/stm32_periph_wasm.js?v=13';
 import { createEmulator } from './emulator.js';
 import { createNetSim } from './netsim.js';
-import { FIRMWARES } from './firmware.js';
+import { createUsbHost } from './usbhost.js';
+import { FIRMWARES } from './firmware.js?v=9';
 import { parseIntelHex, parseElf, parseMap } from './loaders.js';
 import { createRemoteEmulator } from './remote-emu.js';
 
@@ -13,22 +14,19 @@ const $ = (id) => document.getElementById(id);
 const uartEl = $('uart'), statusEl = $('statusText'), dotEl = $('dot');
 const framesEl = $('frames');
 
-const decodeB64 = (b64) => {
-    const bin = atob(b64);
-    const u = new Uint8Array(bin.length);
-    for (let i = 0; i < bin.length; i++) u[i] = bin.charCodeAt(i);
-    return u;
-};
+const decodeB64 = (b64) => Uint8Array.from(atob(b64), c => c.charCodeAt(0));
+const HEX_TABLE = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, '0'));
 const hex = (arr, n = 32) => {
     let s = '';
-    for (let i = 0; i < Math.min(arr.length, n); i++) s += arr[i].toString(16).padStart(2, '0') + ' ';
+    const len = Math.min(arr.length, n);
+    for (let i = 0; i < len; i++) s += HEX_TABLE[arr[i]] + ' ';
     if (arr.length > n) s += '…';
     return s.trim();
 };
 const hex32 = (v) => '0x' + (v >>> 0).toString(16).padStart(8, '0');
 
 let session = 0;
-let emu = null, netsim = null, running = false;
+let emu = null, netsim = null, usbhost = null, running = false;
 let uartBuf = '', totalInst = 0, t0 = performance.now(), lastInst = 0, lastT = t0;
 let stepsDone = 0;
 let image = null;          // { flash, ram, extraMem, entry, symbols, name, uartAddr }
@@ -46,12 +44,12 @@ const ETH_RX_MAP = {
 // Interrupt-driven firmware: the emulator pumps guest IRQ handlers (USART RXNE
 // etc.). OFF for ETH firmware — the driver signals completion via SRAM
 // irq_flag and the guest ETH_IRQHandler would double-process DMASR/rx_desc.
-const IRQ_FIRMWARES = new Set(['rx_interrupt_test', 'rx_crypto_test', 'comprehensive_test', 'eth_irq_test']);
+const IRQ_FIRMWARES = new Set(['rx_interrupt_test', 'rx_crypto_test', 'comprehensive_test', 'eth_irq_test', 'edge_test', 'periph_test', 'fpu_irq_test', 'mpu_test']);
 
 // Interrupt-driven ETH firmware: the guest ETH_IRQHandler (run by the pump)
 // reads DMASR and scans rx_desc itself, so the driver must not write the
 // SRAM irq_flag/rx_frame_idx globals (irq_eth mode in emulator.js).
-const IRQ_ETH_FIRMWARES = new Set(['eth_irq_test']);
+const IRQ_ETH_FIRMWARES = new Set(['eth_irq_test', 'eth_dhcp', 'eth_test']);
 
 // Firmwares that exercise the WFI/STOP low-power path: the emulator halts the
 // core on WFI and advances the virtual RTC until an alarm/interrupt wakes it.
@@ -75,7 +73,38 @@ const DEVICE_FIRMWARES = {
     audio_play_test: { speaker: true },
     rtc_test: { rtc: { i2c: 'I2C1', addr: 0x68, init: RTC_INIT } },
     qspi_test: { qspi: [{ peripheral: 'QUADSPI', size: 256 }] },
-};
+    // new_periph_test exercises DCMI polled capture (DR increments + FNE),
+    // which needs a sensor frame — same idea as the audio_test WAV seed.
+    // Ramp pixels so consecutive DR reads differ.
+    new_periph_test: { camera: { width: 64, height: 48, pixels: Uint8Array.from({ length: 64 * 48 }, (_, i) => i & 0xFF) } },
+    deep_periph_test: { camera: { width: 64, height: 48, pixels: Uint8Array.from({ length: 64 * 48 }, (_, i) => i & 0xFF) } },
+    // periph_test talks to an I2C EEPROM at 0x50 (write/readback + blank
+    // check at addr 0). Blank image; the model handles the R/W protocol.
+    periph_test: { i2c_eeprom: [{ peripheral: 'I2C1', address: 0x50, data: new Uint8Array(256).fill(0xFF) }] },
+    edge_test: { i2c_eeprom: [{ peripheral: 'I2C1', address: 0x50, data: new Uint8Array(256).fill(0xFF) }], spi_flash: [{ peripheral: 'SPI3', jedec_id: 0xEF4016, size: 0x200000, cs: null, data: new Uint8Array(0x200000).fill(0xFF) }] },
+    // spi_tft_test talks to an SPI NOR flash on SPI3 (software CS PB12).
+    // Without it JEDEC/status reads return 0xFF and the checks FAIL.
+    // Blank 2 MB image, same shape as site/test_spi_flash.mjs.
+    spi_tft_test: { spi_flash: [{ peripheral: 'SPI3', jedec_id: 0xEF4015, size: 0x200000, cs: 'PB12', data: new Uint8Array(0x200000).fill(0xFF) }] },
+};
+
+// audio_test needs the same 64-sample PCM16 WAV the node harness
+// (site/test_audio.mjs) loads via audio_load_wav — without it the I2S DMA
+// reads fall back to generated audio and the firmware's checksum FAILs.
+function makeAudioTestWav() {
+    const N = 64, dataLen = N * 2;
+    const w = new Uint8Array(44 + dataLen);
+    const dv = new DataView(w.buffer);
+    const wstr = (o, s) => { for (let i = 0; i < s.length; i++) w[o + i] = s.charCodeAt(i); };
+    wstr(0, 'RIFF'); dv.setUint32(4, 36 + dataLen, true); wstr(8, 'WAVE');
+    wstr(12, 'fmt '); dv.setUint32(16, 16, true);
+    dv.setUint16(20, 1, true); dv.setUint16(22, 1, true);
+    dv.setUint32(24, 44100, true); dv.setUint32(28, 44100 * 2, true);
+    dv.setUint16(32, 2, true); dv.setUint16(34, 16, true);
+    wstr(36, 'data'); dv.setUint32(40, dataLen, true);
+    for (let i = 0; i < N; i++) dv.setInt16(44 + i * 2, (i * 300 + 7) & 0xFFFF, true);
+    return w;
+}
 
 // ── status + UART ──────────────────────────────────────────────────────────
 const setStatus = (text, cls) => {
@@ -83,10 +112,25 @@ const setStatus = (text, cls) => {
     dotEl.className = 'dot ' + cls;
 };
 
+let uartChunks = [], uartLen = 0;
 const appendUart = (chunk) => {
     if (!chunk) return;
-    uartBuf += chunk;
-    if (uartBuf.length > 200000) uartBuf = uartBuf.slice(-200000);
+    uartChunks.push(chunk);
+    uartLen += chunk.length;
+    // Keep last 200k chars without repeatedly copying 200k string (old: uartBuf+=chunk; slice)
+    while (uartLen > 200000) {
+        const first = uartChunks[0];
+        const excess = uartLen - 200000;
+        if (first.length <= excess) {
+            uartLen -= first.length;
+            uartChunks.shift();
+        } else {
+            uartChunks[0] = first.slice(excess);
+            uartLen = 200000;
+            break;
+        }
+    }
+    uartBuf = uartChunks.join('');
     const wasAtBottom = uartEl.scrollTop + uartEl.clientHeight >= uartEl.scrollHeight - 8;
     uartEl.textContent = uartBuf;
     if (wasAtBottom && $('chkAuto').checked) uartEl.scrollTop = uartEl.scrollHeight;
@@ -202,7 +246,7 @@ $('btnBoot').addEventListener('click', async () => {
         setBusy(false);
         $('btnRun').textContent = 'Run';
         setStatus('loading firmware…', 'stop');
-        uartEl.textContent = uartBuf = '';
+        uartEl.textContent = uartBuf = ''; uartChunks = []; uartLen = 0;
         framesEl.textContent = '';
         totalInst = 0; stepsDone = 0;
         t0 = lastT = performance.now(); lastInst = 0;
@@ -273,7 +317,7 @@ const boot = async () => {
     if (audioCtx) { try { audioCtx.close(); } catch (e) {} audioCtx = null; audioQueued = 0; }
 
     const fw = image.flash;
-    uartEl.textContent = uartBuf = '';
+    uartEl.textContent = uartBuf = ''; uartChunks = []; uartLen = 0;
     framesEl.textContent = '';
     totalInst = 0; stepsDone = 0;
     t0 = lastT = performance.now(); lastInst = 0;
@@ -282,6 +326,7 @@ const boot = async () => {
     if (bridgeUrl) {
         // ── remote mode: Node runs the emulator, browser is a thin client ──
         netsim = null;
+        usbhost = null;
         gw.tx = 0; gw.rx = 0;
         try {
             emu = await createRemoteEmulator(bridgeUrl, {
@@ -323,17 +368,21 @@ const boot = async () => {
         }
     } else {
         // ── local mode: WASM runs in the browser (default) ──
-        const svdXml = await fetch('vendor/stm32f407.svd').then((r) => r.text());
+        // NOTE (VENDOR_V): vendor asset versions (?v=13) must be bumped together
+        // after every wasm-pack rebuild, or browsers keep the stale model.
+        const svdXml = await fetch('vendor/stm32f407.svd?v=13').then((r) => r.text());
         if (id !== session) return;
 
         netsim = gw.connected ? null : createNetSim();
+        // Scripted USB host when the demo preset boots locally.
+        usbhost = (!bridgeUrl && image.name === 'usb_cdc_test') ? createUsbHost(bindings) : null;
         gw.tx = 0; gw.rx = 0;
         if (gw.connected) setGwStatus(true, gwLabel());
         emu = await createEmulator({
             firmware: fw,
             bindings,
-            unicorn: MUnicorn,
             svdXml,
+            wasmUrl: 'vendor/stm32_periph_wasm_bg.wasm?v=13',
             extra_mem: image.extraMem,
             uart_addr: image.uartAddr,
             enable_irqs: IRQ_FIRMWARES.has(image.name),
@@ -356,9 +405,25 @@ const boot = async () => {
             },
         });
         if (id !== session) { emu.close(); return; }
+        // Seed the model's audio source for audio_test (see makeAudioTestWav).
+        if (image.name === 'audio_test' && bindings.audio_load_wav) {
+            try { bindings.audio_load_wav(makeAudioTestWav()); } catch (e) {}
+        }
+        // Pre-feed one camera frame so DCMI capture has sensor data from the
+        // very first step (the firmware reads DR immediately after setting
+        // CAPTURE, before any per-step feed runs).
+        if ((image.name === 'new_periph_test' || image.name === 'deep_periph_test') && emu.camera) {
+            try {
+                const cam = DEVICE_FIRMWARES[image.name].camera;
+                emu.camera.feed(cam.width, cam.height, cam.pixels);
+            } catch (e) {}
+        }
     }
 
-    appendUart(`── booted ${image.name} ${bridgeUrl ? '(bridge ' + bridgeUrl + ')' : gw.connected ? '(gateway)' : '(netsim)'} ──\r\n`);
+    const bootTags = bridgeUrl
+        ? `(bridge ${bridgeUrl})`
+        : (gw.connected ? '(gateway)' : '(netsim)');
+    appendUart(`── booted ${image.name} ${bootTags} ──\r\n`);
     window.__emu = emu;          // debug handle (CDP smoke tests)
     window.__bindings = bindings;
     running = true;
@@ -382,8 +447,13 @@ const loop = async (id) => {
             return;
         }
         appendUart(emu.drainUart());
-        refreshStats();
-        renderLtdc();
+        // Scripted USB host for the usb_cdc_test preset (local mode only —
+        // USB has no gateway backend; this is the netsim equivalent).
+        try {
+            if (usbhost && !usbhost.done) usbhost.frame(uartBuf);
+        } catch (e) {}
+        await refreshStats();
+        await renderLtdc();
         renderDevices();
         await raf();
     }
@@ -414,7 +484,7 @@ $('btnReset').addEventListener('click', () => {
     }
     if (image) boot();
 });
-$('btnClear').addEventListener('click', () => { uartEl.textContent = uartBuf = ''; });
+$('btnClear').addEventListener('click', () => { uartEl.textContent = uartBuf = ''; uartChunks = []; uartLen = 0; });
 $('btnGw').addEventListener('click', connectGateway);
 
 const sendRx = (term) => {
@@ -584,18 +654,22 @@ let ltdcCtx = ltdcCanvas.getContext('2d');
 let ltdcCacheKey = '';
 let ltdcOff = document.createElement('canvas');
 
-const renderLtdc = () => {
+const renderLtdc = async () => {
     if (!emu || !ltdcCanvas.width) return;
     try {
-        const gcr = emu.read32(LTDC + 0x18);
-        const l1cr = emu.read32(LTDC + 0x84);
-        if (!(gcr & 1) || !(l1cr & 1)) { ltdcInfo.textContent = 'scanout idle'; return; }
-        const pf = emu.read32(LTDC + 0x94) & 7;
-        const cfbar = emu.read32(LTDC + 0xAC) >>> 0;
-        const cfblr = emu.read32(LTDC + 0xB0) >>> 0;
-        const cfblnr = emu.read32(LTDC + 0xB4) & 0x7FF;
-        const whpcr = emu.read32(LTDC + 0x88) >>> 0;
-        const wvpcr = emu.read32(LTDC + 0x8C) >>> 0;
+        const [gcr, l1cr, pfRaw, cfbarRaw, cfblrRaw, cfblnrRaw, whpcrRaw, wvpcrRaw] = await Promise.all([
+            emu.read32(LTDC + 0x18), emu.read32(LTDC + 0x84), emu.read32(LTDC + 0x94),
+            emu.read32(LTDC + 0xAC), emu.read32(LTDC + 0xB0), emu.read32(LTDC + 0xB4),
+            emu.read32(LTDC + 0x88), emu.read32(LTDC + 0x8C),
+        ]);
+        const gcrV = gcr >>> 0, l1crV = l1cr >>> 0;
+        if (!(gcrV & 1) || !(l1crV & 1)) { ltdcInfo.textContent = 'scanout idle'; return; }
+        const pf = pfRaw & 7;
+        const cfbar = cfbarRaw >>> 0;
+        const cfblr = cfblrRaw >>> 0;
+        const cfblnr = cfblnrRaw & 0x7FF;
+        const whpcr = whpcrRaw >>> 0;
+        const wvpcr = wvpcrRaw >>> 0;
         const bpp = pf === 2 ? 2 : 4;
         const lineBytes = Math.min(cfblr & 0x1FFF, 640 * bpp);
         const w = Math.min((((whpcr & 0xFFF) + 1) || (lineBytes / bpp)) | 0, 640);
@@ -609,6 +683,11 @@ const renderLtdc = () => {
         const key = pf + ':' + w + 'x' + lines + ':' + cfbar + ':' + pitch + ':' + (bindings.ltdc_get_frame_count ? bindings.ltdc_get_frame_count() : 0);
         if (key === ltdcCacheKey) return;
         ltdcCacheKey = key;
+        // Bridge mode has no direct uc.mem_read — skip framebuffer blit
+        if (!emu.uc || typeof emu.uc.mem_read !== 'function') {
+            ltdcInfo.textContent = `layer0 ${w}×${lines} ${pf === 2 ? 'RGB565' : 'ARGB8888'} @ ${hex32(cfbar)} (bridge — no fb read)`;
+            return;
+        }
         // Read (only the used width bytes per line — the model guest RAM is
         // byte-exact, so no opacity/color-key handling beyond the format).
         const rowBytes = Math.min(w * bpp, pitch || w * bpp);