Hot reload

Save a file; every attached target — simulator and devices — reloads in well under two seconds, usually much less. This page explains exactly what happens so the behavior never surprises you.

What a reload does

1. kog dev recompiles incrementally (typically < 300 ms) and pushes the new bundle to each attached target: the simulator over a local WebSocket dev hub, and a USB-connected board over the framed serial dev-link. Hot reload to a physical board is USB-only — there is no Wi-Fi code-push path.
2. The target tears down the current app: effects are disposed, JS-held hardware claims (pins, buses, PWM channels) are released, and the current screen's widgets are deleted.
3. The new bundle is evaluated in place and the app remounts. PSRAM boards assemble it in RAM; the no-PSRAM CYD streams it into an isolated alternating flash scratch region. The installed app and OTA staging region are untouched on both paths.
4. Navigation state is preserved — you land back on the screen you were editing, with the same route params.

What is and isn't preserved

	Preserved across reload
Current route + params	✅
useStorage values (device KV storage)	✅ (they're persistent by nature)
useState / in-memory state	❌ — remounts fresh in v1
Hardware claims	❌ — released and re-claimed by the new code (this is what you want)

State-preserving Fast Refresh (keeping useState values across reloads) is designed into the runtime's architecture and planned post-v1.

Connecting to a board

kog dev auto-detects a plugged-in board and attaches to it alongside the simulator (use --sim for the simulator only, or --port <p> to pick a specific serial port). To establish the link it pulses a reset on connect — the board announces itself once at boot, so kog dev reboots it to catch that announcement, exactly the way opening the port in a browser does. You'll see a Board linked … line once the handshake and ABI check pass; from then on every save hot-reloads to glass. If no board is found, kog dev just runs the simulator.

CYD tier (bare ESP32, no PSRAM)

The CYD is the most RAM-constrained blessed board. Its dev-link holds only one 4 KB wire chunk at a time and streams larger apps into one of two isolated flash scratch regions; it does not reserve a bundle-sized RAM buffer. MQuickJS then executes the relocated bytecode in place from flash, leaving the 96 KB JS arena and networking headroom available to the app. A pre-transfer ready handshake keeps the host from sending chunks while the device erases the inactive scratch region.

Errors during development

• Compile errors never reach the device: they render as an overlay in the simulator and in your terminal, with the file/line and a web-developer-readable message.
• Runtime errors show a compact error screen on the target and a full source-mapped stack in the terminal.
• console.log/warn/error from every target streams to the kog dev terminal, labeled and source-mapped. Console calls are stripped from --release builds.