Browser-based Specter DIY simulator for easier development and PR testing

### Problem

Testing Specter DIY changes currently requires a local development environment.

On Linux and macOS, the Unix simulator can be built and started locally. On Windows it is also possible, but typically requires Windows Subsystem for Linux (WSL).

For someone who only wants to quickly test a change, this means having to:

1. clone the repository
2. install/configure the required development environment
3. initialize dependencies/submodules
4. build the Unix simulator
5. start it manually
6. repeat parts of this process when testing another branch or PR

This works for active developers, but creates unnecessary friction for reviewers, occasional contributors, designers, testers, and users who simply want to verify whether a change works.

It also makes reviewing UI and workflow changes more time-consuming than necessary.

A reviewer should ideally not need a local Linux/macOS/WSL environment just to answer questions such as:

* Does this new screen look correct?
* Does this navigation flow work?
* Can I reproduce this bug?
* Does this QR flow work?
* Does this SD-card flow work?
* Does this Smartcard flow work?
* Does this PR introduce a regression?

---

## Proposed solution

Create an official **browser-based Specter DIY simulator** that runs the real Specter application directly in the user's browser.

The goal should be to run the actual Specter code rather than recreating the UI in HTML.

Conceptually:

```text
Browser
↓
WebAssembly / browser runtime
↓
MicroPython
↓
Specter DIY
↓
LVGL
↓
HTML Canvas
```

Hardware-specific functionality would only be replaced at the platform boundary with browser equivalents.

For example:

```text
Specter display → browser Canvas
Touch input → pointer/touch events
SD card → virtual browser filesystem
Camera / scanner → browser camera + QR decoder
Smartcard → virtual Smartcard transport/emulation
```

The actual Specter application, screens, wallet logic, QR handling and Smartcard-related application logic should remain unchanged as much as possible.

The simulator should emulate hardware at the lowest clean abstraction layer rather than rebuilding wallet behavior in JavaScript.

---

## Hosting via GitHub Pages

The simulator could be deployed directly through **GitHub Pages**.

For the official repository this could look like:

```text
https://cryptoadvance.github.io/specter-diy/
```

This keeps the simulator directly connected to the source repository and avoids requiring users to install anything locally.

The page would be built automatically through GitHub Actions.

---

## Pull request previews

A particularly useful extension would be to automatically build a browser simulator for pull requests.

Example:

```text
https://cryptoadvance.github.io/specter-diy/pr/421/
```

The important part is that this URL should represent the **latest successfully built commit of that PR**.

When a new commit is pushed:

```text
PR #421
↓
new commit
↓
tests
↓
firmware build
↓
browser simulator build
↓
/pr/421/ updated
```

The URL itself stays stable:

```text
https://cryptoadvance.github.io/specter-diy/pr/421/
```

but the simulator behind it always represents the latest successfully built PR commit.

This makes it easy to share the preview URL without creating a new URL for every commit.

---

## One automatically updated PR comment

To avoid cluttering PR discussions, the workflow should maintain **exactly one simulator/build comment**.

The workflow can identify its own comment using a hidden marker such as:

```html

```

When a new commit is successfully built:

1. find the existing Specter preview comment
2. delete it
3. post one new comment
4. the new comment appears at the bottom of the PR
5. it only references the latest commit

This avoids posting a new permanent comment for every commit while still keeping the current testing information visible at the bottom of the discussion.

Editing the same comment would also avoid spam, but deleting and recreating it has the advantage that the newest build information remains at the bottom of the PR conversation.

---

## Combine browser preview and firmware build

Specter already has automated CI that builds firmware for pull requests.

Instead of creating a separate user-facing system, the browser simulator should be integrated with that workflow.

The PR should ideally receive one combined comment similar to:

```text
🧪 Specter PR Build

Latest commit: 93bf210 ✅

🖥️ Test in Browser
https://cryptoadvance.github.io/specter-diy/pr/421/

⬇️ Download Firmware
[firmware artifact]

🔧 View Build Workflow / Logs
[GitHub Actions run]
```

This gives developers and reviewers a single place to find:

* the browser simulator
* the firmware artifact
* the CI/build logs
* the exact commit being tested

---

## Browser and firmware must match the same commit

The workflow should only publish/update the PR comment when the browser simulator and firmware correspond to the same commit SHA.

Example:

```text
PR HEAD:
93bf210

Firmware build:
93bf210 ✅

Browser simulator:
93bf210 ✅

→ publish/update preview
```

A stale browser build must never be presented as if it represented the newest firmware commit.

If one part of the build fails, the workflow should clearly indicate that rather than silently linking to an older successful build.

---

## Experimental build warning

The browser simulator and automatically built PR firmware are **development builds**.

They must not look like official Specter releases.

Every PR preview should contain a prominent warning such as:

> ⚠️ **EXPERIMENTAL DEVELOPMENT BUILD**
>
> This code has not been released or fully reviewed as production firmware.
>
> **Do not use this simulator or firmware with real funds.**
>
> Never enter a real seed phrase.
>
> Use test seeds and dedicated test hardware only.
>
> Installing experimental firmware may cause data loss or unexpected behavior.

The browser simulator should also permanently show a similar warning.

A browser-based simulator has none of the security guarantees of a real air-gapped Specter device.

---

## Fork support

Ideally, the browser build and GitHub Actions workflow should live directly inside the Specter DIY repository.

That means anyone who forks the project automatically inherits the browser-simulator build system.

For example:

```text
username/specter-diy
```

could publish its simulator at:

```text
https://username.github.io/specter-diy/
```

and potentially its own PR previews at:

```text
https://username.github.io/specter-diy/pr/17/
```

After enabling GitHub Actions/Pages in the fork, contributors would have a browser-accessible development environment without needing separate infrastructure.

This could make experimenting with Specter significantly easier.

---

## Why this would help

The main goal is to reduce the time between:

```text
change code
→ test change
→ share change
→ review change
```

Today:

```text
PR
↓
clone repository
↓
set up Linux/macOS/WSL
↓
build simulator
↓
start simulator
↓
test
```

With a browser simulator:

```text
PR
↓
click link
↓
test
```

For hardware testing:

```text
PR
↓
download automatically built firmware
↓
flash test device
↓
test
```

Both testing paths would be available from the same automated PR comment.

---

## Example PR experience

A reviewer could open a pull request and see:

```text
🧪 Specter PR Build

Latest commit: 93bf210 ✅

🖥️ Open Browser Simulator
https://cryptoadvance.github.io/specter-diy/pr/421/

⬇️ Download Firmware
Built from the same commit

🔧 View CI Logs

⚠️ Experimental development build.
Never use with real funds or real seed phrases.
```

If another commit is pushed, the previous preview comment is removed and replaced with a new one for the latest successfully built commit.

There should always be only one current Specter preview/build comment.

---

## Features useful for browser testing

A browser simulator would be especially useful if it can emulate common hardware interfaces.

Initial targets could include:

1. Real Specter/LVGL display rendered to Canvas
2. Touch/pointer interaction
3. Virtual SD card
4. File import/export
5. Browser camera access
6. QR-code scanning
7. Normal Specter QR-code output
8. Virtual Smartcard support
9. Restart/reset functionality
10. Source commit/build information

The virtual SD card should behave like Specter's existing `/sd` filesystem abstraction rather than simply being an HTML file upload widget.

Likewise, camera/QR support should integrate at Specter's hardware/platform boundary instead of bypassing the actual wallet logic.

### Virtual Smartcard support

Where supported by the respective Specter firmware or branch, the browser simulator should emulate Smartcards at the lowest clean hardware/transport boundary.

The goal should be to keep Specter's actual Smartcard-related application logic running unchanged.

The browser UI could provide a virtual Smartcard tray with functionality such as:

* insert/remove card
* reset card
* isolated per-card state
* PIN behavior where applicable
* multiple virtual card slots where supported
* different card types where supported by the firmware

The Smartcard implementation should not simply fake successful wallet operations at the UI level.

Instead, it should emulate the transport/protocol layer closely enough that the existing Specter Smartcard code interacts with it as if it were real hardware.

If a particular Specter version does not support Smartcards, those controls should not be shown for that build.

---

## Suggested implementation milestones

### Phase 1 — Browser simulator

* [ ] Run Specter/MicroPython in the browser
* [ ] Render the real LVGL display to a Canvas
* [ ] Support touch/pointer input
* [ ] Add virtual SD-card support
* [ ] Add file import/export
* [ ] Add browser camera access
* [ ] Add QR-code scanning
* [ ] Keep normal firmware-generated QR output working
* [ ] Add virtual Smartcard support where supported by the firmware
* [ ] Add restart/reset functionality
* [ ] Display source commit/build information
* [ ] Deploy to GitHub Pages
* [ ] Add automated browser smoke tests
* [ ] Add clear "never use real seeds/funds" warning

### Phase 2 — PR previews

* [ ] Build browser simulator automatically for PRs
* [ ] Publish stable `/pr//` URLs
* [ ] Ensure preview corresponds to latest successful PR commit
* [ ] Integrate with existing firmware-build workflow
* [ ] Add firmware artifact link to PR comment
* [ ] Add workflow/log link
* [ ] Maintain exactly one preview/build comment
* [ ] Delete/repost the comment after a new successful build so it remains at the bottom of the PR
* [ ] Verify browser build and firmware artifact use the same SHA

### Phase 3 — Fork support

* [ ] Keep browser build tooling inside the main repository
* [ ] Make GitHub Pages deployment easy to enable in forks
* [ ] Allow forks to expose their own simulator
* [ ] Allow fork PR previews using the same workflow
* [ ] Document setup for contributors

---

## Security considerations

The simulator should keep wallet data local to the browser wherever possible.

It should not upload:

* seed data
* SD-card files
* QR payloads
* Smartcard contents
* wallet data
* private keys

to ClavaStack, GitHub, or another backend.

The simulator runtime should also avoid gaining network capabilities that the physical device does not have.

PR and fork code should be treated as untrusted development code.

Any deployment workflow that requires write permissions or secrets should be separated from the workflow that executes/builds untrusted fork code.

---

## This would not replace local or hardware testing

The browser simulator is not intended to replace:

* local firmware development
* hardware-in-the-loop testing
* STM32-specific testing
* physical Smartcard testing
* release testing
* security review

It would instead provide a much faster way to:

* review UI changes
* reproduce bugs
* test QR workflows
* test SD-card workflows
* test Smartcard workflows
* review PRs
* test forks
* onboard contributors
* share development builds

The intended workflow becomes:

```text
Developer creates PR
↓
CI builds firmware + browser simulator
↓
One automatic PR comment appears
↓
Reviewer clicks browser link
↓
Reviewer can immediately test the change
```

This could significantly reduce the friction of Specter DIY development and make reviewing changes accessible to many more contributors.