docs: update-v86.js rewrite + SMB/v86/testing knowledge (#348)

* Rewrite update-v86.js for the current build pipeline

Both v86 fixes we've been carrying are now real branches on the fork
(PR #1540 electron-renderer-fs-loader, PR #1541 ide-shared-registers)
combined as felixrieseberg/v86:windows95-base. update-v86.js no longer
needs to patch sources at build time — it just builds whatever's checked
out and copies the result.

Gone: the fallback-to-copy.sh path, the skew-day check, the structural
regex patches for load_file/exportSymbol/fetch-bind, the phantom-slave
guard (both are in the branch), the --js-only flag. If you don't have
cargo/clang/java/closure, the script fails loudly — no silent fallbacks.

Added: sanity checks against the installed libv86.js for the invariants
our SMB integration and parcel-build shim depend on, so if upstream
changes something load-bearing we see it as a WARN at update time
instead of a runtime failure.

Tested end-to-end: 5/5 sanity checks, fresh boot SUCCESS in 32s.

* docs and skills: capture SMB/v86/testing knowledge from the session

- docs/smb-share.md: user-facing SMB integration overview (how to mount in
  Win95, what's implemented, what's not). Points at the protocol-level
  README inside src/renderer/smb/ for wire-level gotchas.
- .claude/skills/probe-win95: how to boot and test the VM without a human.
  Env vars, file locations, failure modes, the XT scancode keyboard trick,
  bisect rules of thumb.
- .claude/skills/update-v86: how to pull upstream v86 changes, what the
  five sanity-check WARNs mean, how to retire the fork branches when the
  PRs merge upstream.

.gitignore narrowed to exclude only the runtime dirs (scheduled_tasks.lock,
worktrees) instead of the whole .claude/ tree, so skills can be committed.
This commit is contained in:
Felix Rieseberg
2026-04-11 09:33:51 -07:00
committed by GitHub
parent 2ef06eb412
commit 89c0a8575d
6 changed files with 433 additions and 168 deletions

47
docs/smb-share.md Normal file
View File

@@ -0,0 +1,47 @@
# Host folder over SMB
Windows 95 can mount a host folder as a network drive. The server lives in
`src/renderer/smb/` — ~1500 lines, zero dependencies, read-only. Defaults to
`~/Downloads`, configurable in Settings.
## Inside Win95
- **Browse:** Start → Run → `\\HOST\HOST`
- **Map a letter:** in Explorer, Tools → Map Network Drive → `Z:`
`\\HOST\HOST` → ☑ Reconnect at logon
- **Batch shortcut:** the share root exposes a virtual `_MAPZ.BAT` that runs
`NET USE Z: \\HOST\HOST`. Double-click once, or copy it to
`C:\WINDOWS\STARTM~1\PROGRAMS\STARTUP` to reconnect every boot.
NetBIOS over TCP/IP must be enabled (Control Panel → Network → TCP/IP
properties → NetBIOS tab). This is baked into the default state image.
## Architecture
One SMB session per `TCPConnection`, hooked off v86's network adapter. The
server speaks SMB1 (LANMAN2.1 dialect) because that's what Win95 negotiates.
Full breakdown in `src/renderer/smb/README.md` — that file has the protocol
gotchas learned during implementation (NT dialect trap, NetBIOS name
null-termination, 8.3 `~N` mapping, RAP descriptor parsing).
**Security:** read-only, symlink-aware path traversal guard, share path
validated in main-process IPC. Not exposed until `smbSharePath` is set in
settings or `WIN95_SMB_SHARE=...` is in the env.
## Tests
```sh
npx tsc --ignoreConfig --module commonjs --target es2020 --esModuleInterop \
--moduleResolution bundler --outDir /tmp/smb-test --skipLibCheck \
src/renderer/smb/*.ts && node /tmp/smb-test/test-standalone.js
```
35 protocol tests, full round-trips with real file I/O. No Electron needed.
## What's not implemented
- Writes (read-only by design, but OPEN is easy to extend)
- Long filenames via TRANS2 (we serve 8.3 through the legacy SEARCH path,
which is enough for Win95 Explorer but loses the original casing/length)
- Multiple shares — everything is one share named `HOST`
- Authentication — guest access only