jsbeeb 1.1.1

package/Dockerfile

@@ -0,0 +1,22 @@
+# NOTE: We create a temporary Docker container to build the webapp in, then copy
+# the generated distributable files to the final Docker image. This keeps the
+# final image tidy (since it doesn't contain any generated temporary artifacts),
+# and its size to a minimum.
+# NOTE: The version of Node must be kept in sync with what's in package.json.
+FROM node:22-alpine AS build
+
+# build the webapp
+WORKDIR /app/
+COPY package.json .
+RUN npm install
+COPY . .
+RUN npm run build
+
+# create the final Docker image
+# NOTE: The webapp is just a bunch of static files, so all we need is something to serve them.
+FROM nginx:1.27-alpine
+COPY docker/nginx-default.conf /etc/nginx/conf.d/default.conf
+COPY --from=build /app/dist /app
+
+EXPOSE 80
+CMD [ "nginx", "-g", "daemon off;" ]

package/Makefile

@@ -0,0 +1,30 @@
+NPM_UP_TO_DATE:=.npm-up-to-date
+NODE=node
+NPM=npm
+
+.PHONY: all
+all: test
+
+npm: $(NPM_UP_TO_DATE)
+
+.PHONY: npm
+test: npm
+	$(NPM) test
+
+$(NPM_UP_TO_DATE): package.json
+	$(NPM) install
+	touch $(NPM_UP_TO_DATE)
+
+HASH := $(shell git rev-parse HEAD)
+
+.PHONY: dist
+dist: npm
+	npm run build
+
+.PHONY: clean
+clean:
+	@rm -rf dist out
+
+.PHONY: spotless
+spotless: clean
+	@rm -f $(NPM_UP_TO_DATE)

package/README.md

@@ -0,0 +1,259 @@
+[![jsbeeb tests](https://github.com/mattgodbolt/jsbeeb/actions/workflows/test-and-deploy.yml/badge.svg)](https://github.com/mattgodbolt/jsbeeb/actions/workflows/test-and-deploy.yml)
+
+# jsbeeb - JavaScript BBC Micro Emulator
+
+[![jsbeeb](public/images/jsbeeb-example.png)](https://bbc.xania.org/)
+
+A BBC Micro emulator written in JavaScript and running in modern browsers. Emulates a 32K BBC B (with sideways RAM)
+and a 128K BBC Master, along with a number of different peripherals.
+
+## Table of Contents
+
+- [Keyboard Mappings](#keyboard-mappings)
+- [Getting Set Up to Run Locally](#getting-set-up-to-run-locally)
+- [Running as a Desktop Application](#running-as-a-desktop-application)
+- [URL Parameters](#url-parameters)
+- [Patches](#patches)
+- [Loading BASIC Files from GitHub Gists](#loading-basic-files-from-github-gists)
+- [Things Left to Do](#things-left-to-do)
+- [Tests](#tests)
+- [Thanks](#thanks)
+- [More Information](#more-information)
+- [License](#license)
+- [Contact](#contact)
+
+## Keyboard Mappings
+
+The BBC had a somewhat different-looking keyboard to a modern PC, and so it's useful to know some of the mappings:
+
+- BBC `F0` is `F10`
+- BBC `Break` key is `F12`
+- BBC `*` is on `"` (if it doesn't work for you try shift-2)
+
+To play right now, visit [https://bbc.xania.org/](https://bbc.xania.org/). To load the default disc image (Elite in this
+case), press shift-F12 (which is shift-Break on the BBC).
+
+### Joystick Support
+
+jsbeeb supports both USB/Bluetooth gamepads and mouse-based analogue joystick emulation. Note that BBC Micro joysticks use inverted axes:
+
+- X-axis: Left = 65535, Right = 0
+- Y-axis: Up = 65535, Down = 0
+
+## Getting Set Up to Run Locally
+
+### Prerequisites
+
+- Node.js (https://nodejs.org/)
+- npm (comes with Node.js)
+
+### Installation
+
+1. Clone the repository:
+   ```sh
+   git clone https://github.com/mattgodbolt/jsbeeb.git
+   cd jsbeeb
+   ```
+2. Install dependencies:
+   ```sh
+   npm install
+   ```
+3. Start the local webserver:
+   ```sh
+   npm start
+   ```
+4. Visit `http://localhost:5173/` in your browser.
+
+jsbeeb uses Node.js and vite to afford simple and standard web development tooling and third-party library access
+without lots of painful copy/paste or wheel-reinventing, as well as the ability to better run tests, and "pack" up the
+site to make it smaller and faster to load when it's deployed to [https://bbc.xania.org](https://bbc.xania.org).
+
+## Running as a Desktop Application
+
+jsbeeb can also run as a standalone desktop application using Electron:
+
+### Running in Development
+
+```sh
+npm run electron
+```
+
+This automatically builds the latest code before launching Electron.
+
+### Building Distributable Packages
+
+To build packages for Linux distribution:
+
+```sh
+npm run build
+npm run electron:build
+```
+
+This creates two package formats in `out/dist/`:
+
+- **Debian/Ubuntu**: `.deb` package
+- **Fedora/RHEL**: `.rpm` package
+
+**Why no Snap packages?** electron-builder's snap support uses the outdated `gnome-3-28-1804` platform (Ubuntu 18.04), which causes GPU driver incompatibilities on modern systems, resulting in MESA loader failures and segfaults. While we were able to work around the initial Wayland issues (electron-builder sets `DISABLE_WAYLAND=1` by default, fixed with `allowNativeWayland: true`), the GPU problems proved insurmountable. The snap builder hasn't been updated to support modern bases like `core22` or `core24`. The `.deb` package works perfectly on all Debian-based systems.
+
+**Note for Ubuntu/Debian users:** If you encounter RPM build errors, you may need to use the system FPM package manager instead of electron-builder's bundled version. First, install the required dependencies:
+
+```sh
+sudo apt-get install ruby rubygems build-essential
+sudo gem install fpm
+```
+
+Then build with:
+
+```sh
+USE_SYSTEM_FPM=true npm run electron:build
+```
+
+### Installing the Packaged Application
+
+**Debian/Ubuntu:**
+
+```sh
+sudo apt install ./out/dist/jsbeeb_1.0.1_amd64.deb
+```
+
+**Fedora/RHEL/CentOS:**
+
+```sh
+sudo rpm -i out/dist/jsbeeb-1.0.1.x86_64.rpm
+```
+
+**Note:** Electron support was re-enabled in November 2024 after being disabled during the ESM migration in 2021. It now works with Electron 28+ which added full ES Modules support.
+
+## URL Parameters
+
+- `autoboot` - fakes a shift break
+- `disc1=XXX` - loads disc XXX (from the `discs/` directory) into drive 1
+- `disc2=XXX` - as above
+- `disc1=local:YYY` - creates a local disk YYY which will be kept in browser local storage
+- `disc1=sth:ZZZ` - loads disc ZZZ from the Stairway to Hell archive
+- `tape=XXX` - loads tape XXX (from the `tapes/` directory)
+- `tape=sth:ZZZ` - loads tape ZZZ from the Stairway to Hell archive
+- `patch=P` - applies a memory patch `P`. See below.
+- `loadBasic=X` - loads 'X' (a resource on the webserver) as text, tokenises it and puts it in `PAGE` as if you'd typed
+  it in to the emulator
+- `embedBasic=X` - loads 'X' (a URI-encoded string) as text, tokenises it and puts it in `PAGE` as if you'd typed it in
+  to the emulator
+- `autorun` - types `*TAPE` then `*/` to run from tape. In conjunction with `loadBasic` it types `RUN`.
+- `autochain` - types `*TAPE` then `CH.""` to run from tape.
+- `autotype` - types whatever you put after. e.g. `&autotype=PRINT"Matt is cool"%0a` (return is URI escaped to `%0a`)
+- `embed` - Remove the margins around the screen, hide most navigation entries and make the page background
+  transparent (intended for use when running within an iframe in a third-party site).
+- `cpuMultiplier=X` speeds up the CPU by a factor of `X`. May be fractional or below one to slow the CPU down. NB disc
+  loads become unreliable with a too-slow CPU, and running too fast might cause the browser to hang.
+- `sbLeft` / `sbRight` / `sbBottom` - a URL to place left of, right of, or below the cub monitor. The left and right
+  should be around 648 high and the bottom image should be around 896 wide. Left and right wider than 300 will run into
+  problems on smaller screens; bottom taller than 100 or so similarly.
+- `videoCyclesBatch` - the number of video cycles to batch up before running the video emulation. Defaults to zero:
+  anything higher leads to emulation inaccuracies. Useful for showing why accuracy is important, even if less efficient.
+- `rom` - load the given URL or path as an extra ROM. If a URL is provided, that URL must allow cross-site requests.
+  Doesn't support the sth: pseudo URL unlike `disc` and `tape`, but if given a ZIP file will attempt to use the `.rom`
+  file assumed to be within.
+- (mostly internal use) `logFdcCommands`, `logFdcStateChanges` - turn on logging in the disc controller.
+- `audioDebug=true` turns on some audio debug graphs.
+
+## Patches
+
+Patches can be applied by making a `patch=P` URL parameter. `P` is a sequence of semicolon-separated patches of the form
+`@XXXX,YYYY:ZZZZZ,...` where the `@XXXX` specifies a PC address to breakpoint, the `YYYY` is the address to patch and
+the `ZZZZ` is the data to write at address `YYYY`. The `@` part is optional, but is handy to ensure the code you want to
+patch has actually loaded. For example: `patch=@31a6,0769:6e4c4d48465a` which is a patch for the default Elite image.
+Once the PC has reached `$31a6`, the bytes at `0769` are replaced with `6e4c4d48465a`.
+
+## Loading BASIC Files from GitHub Gists
+
+1. Create a gist with your code. https://gist.github.com/ - here's
+   an [example](https://gist.github.com/mattgodbolt/fc8d6f3d6e5e015dce399013719c8341)
+2. Get the "Raw" link by clicking "raw" and copying the URL. In the case above
+   that's: https://gist.githubusercontent.com/mattgodbolt/fc8d6f3d6e5e015dce399013719c8341/raw/bd5cb4314bfc3ee4330783ecf82cb329a36b915c/foo.bas
+3. Add that after "https://bbc.xania.org/?autorun&loadBasic=" or similar, for
+   example, [this link](https://bbc.xania.org/?loadBasic=https://gist.githubusercontent.com/mattgodbolt/fc8d6f3d6e5e015dce399013719c8341/raw/bd5cb4314bfc3ee4330783ecf82cb329a36b915c/foo.bas&autorun)
+
+Note that every update you make means you need to make a new raw link.
+
+## Things Left to Do
+
+If you're looking to help:
+
+- Testing
+  - Play lots of games and report issues either on [GitHub](https://github.com/mattgodbolt/jsbeeb/issues) or by email (
+    matt@godbolt.org).
+- Core
+  - Save state ability
+    - Once we have this I'd love to get some "reverse step" debugging support
+  - Get the "boo" of the boot "boo-beep" working (disabled currently as the JavaScript startup makes the sound
+    dreadfully choppy on Chrome at least).
+- Save disc support
+  - Local discs need to be made more workable and need an "export" feature
+  - Multiple discs need a UI
+- `git grep -i todo`
+- Optimisation
+  - While every attempt to make things fast has been made, I'm sure there's some more clever things that can be done
+    without compromising emulation accuracy
+
+## Tests
+
+For general correctness, there are several tests in the `tests` directory, including:
+
+- Klaus Dormann's exhaustive [test of all documented opcodes](https://github.com/Klaus2m5/6502_65C02_functional_tests)
+  for 6502 and 65C12. This is brought in as a git submodule from a forked version of Klaus's original as it needed a few
+  tweaks to get 65C12 working.
+- hoglet's Binary Coded Decimal tests.
+- @dp111's [timing tests](https://github.com/dp111/6502Timing). Also brought in as a git submodule.
+- A public domain Commodore 64 6502 test suite which tests every 6502 opcode (documented or otherwise) for every
+  possible input and flags condition.
+- Some tests by @scarybeasts testing VIA and 65C12 functionality.
+
+For timing correctness, we have:
+
+- A timing test program written by Rich. It has been run on a real live BBC B and the results are in the directory. An
+  SSD of the same tests is in the `discs/` directory.
+- Some of Kevin Edwards' protection systems (stripped of the games themselves). These are extremely timing- and
+  correctness-sensitive when it comes to the timers and interrupts of the BBC.
+- Some 65C12-specific read-modify-write tests written by Ed Spittles.
+
+Tests can be run automatically if you have `node` installed - just run `make` and it'll ensure the relevant libraries
+are installed, then it'll run the tests. Please note it can take a while to run the whole test suite.
+
+## Thanks
+
+jsbeeb was heavily based on Sarah Walker's C [B-Em emulator](https://github.com/stardot/b-em) -- thanks to her for her
+hard work and for open sourcing her code. B-em is now being maintained by a group of enthusiasts - thanks to them too!
+
+Huge thanks to Richard Talbot-Watkins for his advice and help along the way in fathoming out the instruction timings,
+interrupt fun, video code rewrite and for being such a good pal all these many years!
+
+Thanks to [Michael Borcherds](https://twitter.com/mike_geogebra) for his help; improving the keyboard layouts and
+handling in JavaScript, reporting issues, chasing down game bugs and much more.
+
+Thanks to [David Banks](https://github.com/hoglet67) (hoglet) for his help in testing the gnarly BCD flag behaviour on
+real live BBCs.
+
+Cheers to [Ed Spittles](https://github.com/BigEd) for testing various interrupt timing code on a real BBC.
+
+Thanks to Chris Jordan for his thorough testing, bug reports, ideas and help.
+
+A lot of the early development used the amazing [Visual 6502](http://visual6502.org/) as reference for intra-instruction
+timings. Amazing stuff.
+
+Special shout out to the users of the [6502 Forums](http://forum.6502.org/)
+
+## More Information
+
+I've written a lot about how the innards work on [my blog](http://xania.org) in
+the [emulation](http://xania.org/Emulation-archive) section. I gave a presentation on how it all fits together at work,
+and posted the [video up on YouTube](https://www.youtube.com/watch?v=37jyHQT7fXQ). I have another presentation at
+[ABug](https://www.youtube.com/watch?v=ABmwJXMLzYM).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contact
+
+For support or questions, please contact Matt Godbolt at matt@godbolt.org.

package/docker/nginx-default.conf

@@ -0,0 +1,10 @@
+server {
+
+    server_name localhost ;
+    listen 80 ;
+
+    location / {
+        root /app ;
+    }
+
+}

package/docs/pal-comb-filter-research.md

@@ -0,0 +1,129 @@
+# Authentic PAL TV Comb Filter Research
+
+## Sources
+
+1. **Watkinson "Engineer's Guide to Decoding & Encoding"** (pages 37-39)
+2. **Jim Easterbrook PAL Decoder Page** (https://www.jim-easterbrook.me.uk/pal/)
+3. **Web search**: PAL television patents and implementations from 1980s
+
+## What Real PAL TVs Used
+
+### 2H Delay Line Comb Filters
+
+**Implementation:**
+
+- Used "64 microsecond quartz delay line" (2 line periods for PAL)
+- Delays of **2H** (two horizontal line periods) for PAL
+- Contrast with NTSC which uses 1H delays
+
+**Why 2H for PAL?**
+
+- PAL subcarrier: 283.75 cycles per line (fractional 0.75)
+- 2H spacing = 1.5 cycles = 540° = **180° phase shift** (mod 360°)
+- This ensures chroma signals are in opposite phase and cancel when added
+- V-switch state is SAME on lines N and N±2 (both inverted or both non-inverted)
+
+**From Watkinson (page 38):**
+
+> "The delays needed are of one line period [for NTSC]. The configuration for PAL is shown in b) in which the delays need to be of two line periods."
+
+### Complementary Decoder Approach
+
+**From Jim Easterbrook:**
+
+> "Some form of filter is used to extract the modulated chrominance from a PAL signal. Subtracting this chrominance from a suitably delayed PAL signal then yields luminance"
+
+This is the **complementary decoder** principle:
+
+1. Extract chroma from composite using a filter
+2. Subtract extracted chroma from **delayed** composite to get luma
+3. The decoder is "complementary" because chroma + luma = original PAL signal
+
+**Important Note:**
+
+> "Decoders like this are not widely used, as better subjective results can be obtained by using separate filters for chrominance and luminance, each optimised to give the best looking signals."
+
+**This explains our findings!**
+
+- Notch filter (complementary approach) is simpler but not what most TVs used
+- Real TVs used separate optimized filters for chroma and luma
+
+### Simple Line Comb for Luma (Most Common Approach)
+
+**From Watkinson Figure 3.4.2b:**
+
+- PAL comb uses 2H delays
+- **Simple averaging:** Add current line + line delayed by 2H
+- This is a LOWPASS filter for luma
+- Chroma cancels due to 180° phase inversion
+- Luma adds (in phase)
+
+**Coefficients:**
+
+- Simplest form: `luma = 0.5 * current + 0.5 * delayed_2H`
+- 3-tap variation: `luma = 0.25 * prev_2H + 0.5 * current + 0.25 * next_2H`
+
+### Tradeoffs and Limitations
+
+**From Watkinson (page 38-39):**
+
+> "Quite a lot of vertical luminance resolution is being lost, and becoming cross luminance, particularly in PAL."
+
+**The fundamental tradeoff:**
+
+- **More averaging** (comb filter) → Less cross-color, more vertical blur
+- **Less averaging** (notch filter) → Sharper, but more cross-color/cross-luma artifacts
+
+**Bandpass Comb Variation:**
+
+> "Some of this resolution loss can be overcome by restricting the combing to a bandpass region"
+
+This means applying the comb filter only to mid-frequencies where chroma lives, preserving low-frequency luma detail. However:
+
+> "Although the full luminance bandwidth is available, this is restricted to picture detail having vertical edges. Man-made subjects such as buildings give good results, but more natural scenes containing diagonal edges are less successful."
+
+### BBC Transform Decoder (Advanced)
+
+**Not a comb filter!** Uses Fourier transforms:
+
+> "Each frequency in the block is compared with its reflection about the colour sub-carrier frequency, and if the magnitudes are too dissimilar the pair of frequencies is rejected."
+
+This is much more sophisticated than simple comb filters and not what consumer TVs used.
+
+## Summary for Implementation
+
+### What Consumer PAL TVs Actually Did:
+
+1. **Most common:** Simple 2H comb filter for luma
+   - Average current line with line ±2H away
+   - Coefficients: 0.5 + 0.5 (or 0.25 + 0.5 + 0.25 for 3-tap)
+   - Accept vertical blur as tradeoff for reduced color artifacts
+
+2. **Some higher-end:** Separate optimized filters
+   - Not pure complementary decoder
+   - Custom filters for chroma and luma
+   - Try to balance sharpness vs artifacts
+
+3. **Not common:** Pure notch/complementary decoders
+   - Simpler but gave worse subjective results
+   - Used in some early/cheap implementations
+
+### What We Should Simulate:
+
+**Option 1: Authentic simple comb (most TVs)**
+
+- Use 2H comb with equal weighting: `luma = 0.5 * current + 0.5 * delayed_2H`
+- Accept some vertical blur (that's what real TVs had!)
+- Minimal checkerboard/cross-color
+
+**Option 2: Notch filter (current implementation)**
+
+- Sharper than real TVs
+- But with FIR_GAIN = 2.0, no checkerboard
+- Arguably "better" than real hardware, but less authentic
+
+**Recommendation:**
+Implement the simple 2H comb as an option so users can choose between:
+
+- "Sharp mode" (notch filter - better than real hardware)
+- "Authentic mode" (2H comb - what TVs actually did, with appropriate blur)