Feature/avalonia browser automation (#192)

* Move AutomatedStartupHandler from DebugAdapter to Systems library to be reusable from all host apps that is started with parameters for automation purposes.

* Implement query parameters for Avalonia Browser app for automated startup and scripts.

* Update Avalonia Browser automation doc.

* Fix bug in Avalonia Log header not being updated and cleared correctly.

* Automatically show ROM acknowledgement dialog when starting C64 from Avalonia Browser query parameters.

* Preserve Lua MoonSharp library from AOT trimming to make it more compatible with running in Browser/WebAssembly.

* Remove non-ascii characters from .lua scripts

* Fix Avalonia Browser script editor dialog height

* Add links to start screen

Author: highbyte

docs/tools/scripting/configuration.md

@@ -1,6 +1,6 @@
 # Configuration
 
-Scripting is configured in `appsettings.json` under the `"Highbyte.DotNet6502.Scripting"` section:
+On desktop targets, scripting is configured in `appsettings.json` under the `"Highbyte.DotNet6502.Scripting"` section. On the Avalonia Browser app, the same section is persisted in browser `localStorage` by the settings UI.
 
 ```json
 "Highbyte.DotNet6502.Scripting": {
@@ -14,7 +14,8 @@ Scripting is configured in `appsettings.json` under the `"Highbyte.DotNet6502.Sc
     "AllowHttpRequests": true,
     "AllowStore": true,
     "StoreSubDirectory": ".store",
-    "AllowTcpClient": false
+    "AllowTcpClient": false,
+    "AllowUrlScripts": false
 }
 ```
 
@@ -32,3 +33,4 @@ Scripting is configured in `appsettings.json` under the `"Highbyte.DotNet6502.Sc
 | `AllowStore` | bool | `true` | Whether the `store` global is available to Lua scripts. Provides a cross-platform key/value store. On desktop, backed by files in `StoreSubDirectory`. In browser, backed by `localStorage`. Default is `true`. |
 | `StoreSubDirectory` | string | `".store"` | Subdirectory within `ScriptDirectory` used for the filesystem store backend (desktop only). Default is `".store"`. |
 | `AllowTcpClient` | bool | `false` | Whether the `tcp` global is available to Lua scripts. Desktop only — forced `false` in browser/WASM builds. Default is `false`. |
+| `AllowUrlScripts` | bool | `false` | Browser-only. When `true`, the Avalonia Browser app honours the `script` and `scriptUrl` URL query parameters at startup. Disabled by default because a crafted link could otherwise execute Lua against the user's emulator session and `localStorage`. Takes effect on the next page load. |

docs/web-apps/avalonia-browser.md

@@ -42,6 +42,84 @@ To self-host, see [Run from command line](#run-from-command-line) below.
 
 The browser app supports the same Lua scripting API as the Avalonia Desktop app, except for filesystem and TCP access (the browser sandbox does not allow them; the key/value store falls back to `localStorage`). For the full guide, see [Tools / Scripting](../tools/scripting/overview.md).
 
+### URL query parameters
+
+The Avalonia Browser app supports URL-driven startup automation. This is the browser counterpart to the Avalonia Desktop app's [CLI arguments](../desktop-apps/avalonia-desktop.md#cli-arguments): instead of passing `--system` or `--script`, you encode the request in the page URL query string.
+
+Query parameter names are case-insensitive. Boolean flags treat an empty value, `1`, `true`, and `yes` as true.
+
+| Query parameter | Purpose | Notes |
+| --- | --- | --- |
+| `system` | Pre-select a system such as `C64` or `Generic`. | Mirrors desktop `--system`. |
+| `systemVariant` | Pre-select a system variant. | Requires `system`. Mirrors desktop `--systemVariant`. |
+| `start` | Auto-start the selected system. | Requires `system`. Mirrors desktop `--start`. |
+| `waitForSystemReady` | Wait until the system reports ready. | Requires `system` and `start`. Mirrors desktop `--waitForSystemReady`. |
+| `loadPrgUrl` | Fetch a `.prg` over HTTP and load it into memory. | Requires `system` and `start`. Browser equivalent of desktop `--loadPrg`, but uses a URL instead of a local file path. Relative URLs are resolved from the app origin. |
+| `runLoadedProgram` | Start executing the loaded PRG from its load address. | Requires `loadPrgUrl`. Mirrors desktop `--runLoadedProgram`. |
+| `basicText` | Paste inline C64 BASIC source text into the running C64. | Base64url-encoded UTF-8 text. Requires `system=C64`, `start`, and `waitForSystemReady`. Mutually exclusive with `loadPrgUrl` and `runLoadedProgram`. |
+| `basicUrl` | Fetch C64 BASIC source text over HTTP and paste it into the running C64. | Same semantics as `basicText`, but uses a text file URL instead of embedding the source in the query string. |
+| `runBasic` | Queue `RUN` after BASIC source has been pasted. | Requires `basicText` or `basicUrl`. |
+| `script` | Run an inline Lua script supplied as base64url-encoded UTF-8 text. | Browser only. Mutually exclusive with all system-driven parameters below. Disabled by default; gated by `Scripting.AllowUrlScripts`. |
+| `scriptUrl` | Fetch a Lua script from a relative or absolute URL and run it. | Same behavior as `script`, but avoids URL-length limits. Disabled by default; gated by `Scripting.AllowUrlScripts`. |
+
+Validation rules are intentionally forgiving: invalid combinations are ignored and the normal UI still loads.
+
+When a URL starts `system=C64` and the app does not yet have the required C64 ROMs, the browser startup flow prompts the user to acknowledge the ROM download terms and can download the ROMs before continuing. This lets first-run automation links work without opening the C64 config dialog first.
+
+1. `systemVariant` requires `system`.
+2. `start` and `waitForSystemReady` require `system`.
+3. `waitForSystemReady` requires `start`.
+4. `loadPrgUrl` requires `system` and `start`.
+5. `runLoadedProgram` requires `loadPrgUrl`.
+6. `basicText` and `basicUrl` are mutually exclusive.
+7. `basicText` and `basicUrl` require `system=C64`, `start`, and `waitForSystemReady`.
+8. `basicText` and `basicUrl` are mutually exclusive with `loadPrgUrl` and `runLoadedProgram`.
+9. `runBasic` requires `basicText` or `basicUrl`.
+10. `script` and `scriptUrl` are mutually exclusive.
+11. `script` and `scriptUrl` are also mutually exclusive with `system`, `start`, `waitForSystemReady`, `loadPrgUrl`, `runLoadedProgram`, `basicText`, `basicUrl`, and `runBasic`.
+
+Examples:
+
+```text
+# Start C64 PAL and wait until the machine is ready
+?system=C64&systemVariant=PAL&start=1&waitForSystemReady=1
+
+# Load and run a bundled PRG
+?system=C64&start=1&waitForSystemReady=1&loadPrgUrl=prg/c64/smooth_scroller_and_raster.prg&runLoadedProgram=1
+
+# Paste BASIC source from a browser-served text file and run it
+?system=C64&start=1&waitForSystemReady=1&basicUrl=basic/c64/hello-world.bas&runBasic=1
+
+# Paste the same BASIC source inline and run it
+?system=C64&start=1&waitForSystemReady=1&basicText=MTAgYzE9NzpjMj0xNAoyMCBjPWMxCjMwIGlmIGM9YzEgdGhlbiBjPWMyIDogZ290byA1MAo0MCBpZiBjPWMyIHRoZW4gYz1jMQo1MCBwb2tlIDUzMjgwLGMKNjAgcHJpbnQgImhlbGxvIHdvcmxkISIKNzAgZm9yIGk9MSB0byAxNTA6bmV4dAo4MCBnb3RvIDMwCg&runBasic=1
+
+# Run an inline Lua script (base64url for: log.info('hello'))
+?script=bG9nLmluZm8oJ2hlbGxvJyk
+
+# Run a Lua script fetched over HTTP
+?scriptUrl=scripts/example_emulator_control.lua
+```
+
+The browser app ships the `basicUrl` sample above as `basic/c64/hello-world.bas`, containing:
+
+```basic
+10 c1=7:c2=14
+20 c=c1
+30 if c=c1 then c=c2 : goto 50
+40 if c=c2 then c=c1
+50 poke 53280,c
+60 print "hello world!"
+70 for i=1 to 150:next
+80 goto 30
+```
+
+Important differences from desktop automation:
+
+- `loadPrgUrl`, `basicUrl`, and `scriptUrl` use browser HTTP fetch semantics, so normal browser origin and CORS rules apply.
+- `basicText` and `basicUrl` are C64-only and use the normal keyboard paste path after BASIC is ready; `runBasic=1` simply appends `RUN` and Return after the pasted source.
+- URL-driven Lua is **disabled by default**. Enable **Allow URL-driven scripts (script / scriptUrl query params)** in the browser app's general settings, save, then reload the page.
+- URL-driven scripts do not behave exactly like desktop `--script`: the browser app still selects the configured default system first, then enables the injected script. The script can still take over by calling APIs such as `emu.select(...)` and `emu.start()`.
+
 ## How to run locally for development
 
 For development system requirements, see [Development](../home/development.md).

docs/web-apps/overview.md

@@ -15,6 +15,6 @@ The two apps share the same emulator core — they differ in UI/rendering tech.
 
 - Lua TCP client (`tcp` global) is unavailable — `System.Net.Sockets.TcpClient` is not supported in WebAssembly.
 - Lua filesystem access (`file` / `emu.load`) is sandboxed; the key/value `store` falls back to `localStorage`.
-- No CLI arguments, no VS Code debug adapter, no remote control endpoint — those are desktop-only features. See [Tools](../tools/overview.md) for the full list of integrations.
+- No CLI arguments, no VS Code debug adapter, no remote control endpoint — those are desktop-only features. The Avalonia Browser app does support URL query parameters for automated startup and script injection; see [Avalonia Browser app](avalonia-browser.md#url-query-parameters).
 
 For general project limitations, see [Limitations](../home/limitations.md).

resources/scripts/desktop/example_c64_screenshot.lua

@@ -23,7 +23,7 @@
 --   emu.screenshot(filename, quality) -> saves as JPEG (determined by .jpg/.jpeg extension),
 --                                        quality 1-100 (default 90)
 
--- ── Step 1: Ensure C64 is selected and running ───────────────────────────────
+-- == Step 1: Ensure C64 is selected and running ========================
 
 if emu.selected_system() ~= "C64" then
     log.info("[screenshot] Selecting C64 system...")
@@ -42,7 +42,7 @@ end
 
 log.info("[screenshot] C64 is running. Waiting for BASIC to start...")
 
--- ── Step 2: Wait for BASIC to initialize ─────────────────────────────────────
+-- == Step 2: Wait for BASIC to initialize ==============================
 --
 -- c64.basic_started() checks the TXTAB pointer ($002B-$002C) to detect
 -- whether the BASIC interpreter has initialized and the READY. prompt is up.
@@ -66,7 +66,7 @@ emu.frameadvance()
 
 log.info("[screenshot] BASIC ready. Taking screenshot...")
 
--- ── Step 3: Take the screenshot ───────────────────────────────────────────────
+-- == Step 3: Take the screenshot =======================================
 --
 -- The file path is relative to the scripting base directory.
 -- The screenshots/ subdirectory is created automatically if it does not exist.
@@ -75,7 +75,7 @@ local filename = "screenshots/c64_basic_ready.png"
 emu.screenshot(filename)
 log.info("[screenshot] Saved: " .. filename)
 
--- ── Step 4: Quit if running headless ─────────────────────────────────────────
+-- == Step 4: Quit if running headless ==================================
 --
 -- In headless mode the process has nothing left to do after the screenshot,
 -- so quit cleanly. In desktop/browser mode the emulator keeps running.

resources/scripts/desktop/example_file_io.lua

@@ -41,7 +41,7 @@ local log_file = "frame_log.csv"
 file.write(log_file, "frame,pc,a,x,y\n")
 log.info("Logging CPU state every 60 frames to " .. log_file)
 
--- ---- Binary load example (commented out — requires a PRG file in the scripts directory) ----
+-- ---- Binary load example (commented out - requires a PRG file in the scripts directory) ----
 -- emu.load("my_program.prg")           -- auto-detects load address from 2-byte PRG header
 -- emu.load("raw_data.bin", 0xC000)     -- loads raw binary at address $C000 (no header)
 

resources/scripts/desktop/example_tcp_client.lua

@@ -19,7 +19,7 @@ local PORT = 9000
 local CONNECT_TIMEOUT_MS = 3000
 
 -- Helper: encode a little-endian 4-byte length prefix.
--- Returns a 1-indexed Lua table of 4 numbers (0-255), e.g. encode_u32_le(5) → {5, 0, 0, 0}.
+-- Returns a 1-indexed Lua table of 4 numbers (0-255), e.g. encode_u32_le(5) -> {5, 0, 0, 0}.
 --
 -- Why a number table instead of a Lua string?
 -- In standard Lua, strings are byte arrays and can hold arbitrary binary data.
@@ -30,8 +30,8 @@ local CONNECT_TIMEOUT_MS = 3000
 --
 -- Note: MoonSharp implements Lua 5.2. Lua 5.3 bitwise operators (&, |, >>, <<) are NOT
 -- supported. Use integer arithmetic instead:
---   n & 0xFF       → n % 256
---   (n >> 8) & 0xFF → math.floor(n / 256) % 256   (etc.)
+--   n & 0xFF       -> n % 256
+--   (n >> 8) & 0xFF -> math.floor(n / 256) % 256   (etc.)
 local function encode_u32_le(n)
     return {
         n % 256,                          -- byte 0 (least significant)

resources/scripts/shared/example_c64_basic_readwrite.lua

@@ -35,20 +35,20 @@ end
 
 log.info("BASIC ready. Typing BASIC program...")
 
--- ── Step 3: Type a 2-line BASIC program ──────────────────────────────────────
+-- == Step 3: Type a 2-line BASIC program ===============================
 --
 -- c64.print_text() queues text into the C64 keyboard buffer exactly as if the
 -- user typed it. Each line must end with "\n" (mapped to C64 Return key).
 -- BASIC tokenizes keywords (print, goto) as each line is confirmed with Return.
--- Note: input must be lowercase — the C64 keyboard uses PETSCII where lowercase
+-- Note: input must be lowercase - the C64 keyboard uses PETSCII where lowercase
 -- letters map to uppercase display characters (the C64's default text mode).
 
 local PROGRAM_LINE1 = "10 print \"hello from lua\""
 local PROGRAM_LINE2 = "20 goto 10"
 
 c64.print_text(PROGRAM_LINE1 .. "\n" .. PROGRAM_LINE2 .. "\n")
 
--- ── Step 4: Wait for the C64 to process the input ────────────────────────────
+-- == Step 4: Wait for the C64 to process the input =====================
 --
 -- The keyboard buffer drains at most one character per frame. The two lines
 -- total ~35 characters; 120 frames (~2.4 s at 50 fps PAL) gives ample margin.
@@ -59,13 +59,13 @@ for _ = 1, 120 do
     emu.frameadvance()
 end
 
--- ── Step 5: Read the program back from memory ────────────────────────────────
+-- == Step 5: Read the program back from memory =========================
 
 local source = c64.get_basic_source()
 log.info("Retrieved BASIC source:")
 log.info(source)
 
--- ── Step 6: Check that both lines round-tripped correctly ────────────────────
+-- == Step 6: Check that both lines round-tripped correctly =============
 
 local ok1 = string.find(source, "10") ~= nil and string.find(source, "PRINT") ~= nil  -- tokenizer uppercases keywords
 local ok2 = string.find(source, "20") ~= nil and string.find(source, "GOTO") ~= nil   -- tokenizer uppercases keywords

resources/scripts/shared/example_c64_cli_demo.lua

@@ -19,7 +19,7 @@
 --   4. Restore the default border color
 --   5. Type "HELLO!" at a human-like typing speed
 
--- ── Step 1: Ensure C64 is running ────────────────────────────────────────────
+-- == Step 1: Ensure C64 is running =====================================
 
 if emu.selected_system() ~= "C64" then
     log.info("[demo] Selecting C64 system...")
@@ -34,7 +34,7 @@ end
 -- Validate config before attempting to start
 local ok, errors = emu.config_valid()
 if not ok then
-    log.error("[demo] C64 system config is invalid — cannot start.")
+    log.error("[demo] C64 system config is invalid - cannot start.")
     for _, e in ipairs(errors) do
         log.error("[demo]   " .. e)
     end
@@ -53,16 +53,16 @@ end
 
 log.info("[demo] C64 is running. Waiting for BASIC READY prompt...")
 
--- ── Step 2: Wait for BASIC to initialize ─────────────────────────────────────
+-- == Step 2: Wait for BASIC to initialize ==============================
 while not c64.basic_started() do
     emu.frameadvance()
 end
 
 log.info("[demo] BASIC READY detected. Cycling border color for 2 seconds...")
 
--- ── Step 3: Cycle border color (~2 seconds at C64 PAL 50 fps ≈ 100 frames) ──
+-- == Step 3: Cycle border color (~2 seconds at C64 PAL 50 fps ~= 100 frames) ==
 --
--- C64 border color register: $D020 (bits 3–0, 16 colors 0–15)
+-- C64 border color register: $D020 (bits 3-0, 16 colors 0-15)
 
 local BORDER_REG = 0xD020
 local border_start = emu.time()
@@ -73,24 +73,24 @@ while emu.time() - border_start < 2.0 do
     emu.frameadvance()
 end
 
--- ── Step 4: Restore default border (C64 default: light blue = 14) ─────────
+-- == Step 4: Restore default border (C64 default: light blue = 14) ====
 
 mem.write(BORDER_REG, 14)
 log.info('[demo] Border cycling done. Typing "HELLO!" ...')
 
--- ── Step 5: Type "HELLO!" at human-like speed ────────────────────────────────
+-- == Step 5: Type "HELLO!" at human-like speed =========================
 --
--- C64 BASIC starts in uppercase mode, so h–o produce uppercase letters on screen.
+-- C64 BASIC starts in uppercase mode, so h-o produce uppercase letters on screen.
 -- '!' on C64 keyboard = lshift + 1.
 --
 -- Input injection pattern: input.key_press() must be called every frame to keep
 -- a key held (ClearScriptInput fires at the start of each frame). So we loop for
 -- hold_frames, pressing the key each iteration, then wait gap_frames with no press.
 --
 -- Timing at 50 fps (PAL C64):
---   hold_frames = 4  →  ~80 ms per key
---   gap_frames  = 6  →  ~120 ms between keys
---   Total per keystroke ≈ 200 ms  →  ~5 characters/second
+--   hold_frames = 4  -> ~80 ms per key
+--   gap_frames  = 6  -> ~120 ms between keys
+--   Total per keystroke ~= 200 ms -> ~5 characters/second
 
 local HOLD_FRAMES = 4
 local GAP_FRAMES  = 6
@@ -111,6 +111,6 @@ type_key("e")
 type_key("l")
 type_key("l")
 type_key("o")
-type_key("1", true)   -- lshift + 1  →  '!'
+type_key("1", true)   -- lshift + 1 -> '!'
 
 log.info('[demo] Done. "HELLO!" typed.')

resources/scripts/shared/example_c64_load_d64.lua

@@ -3,7 +3,7 @@
 -- emulated DiskDrive 1541 via c64.load_d64().
 --
 -- The path supports ~ (home directory) on Mac/Linux and %USERPROFILE% on
--- Windows — expansion is handled automatically by the engine.
+-- Windows - expansion is handled automatically by the engine.
 --
 -- After a successful load the directory listing command is typed automatically.
 
@@ -32,7 +32,7 @@ end
 
 log.info("BASIC ready. Loading disk image...")
 
--- ── Load the disk image ───────────────────────────────────────────────────────
+-- == Load the disk image ===============================================
 --
 -- Adjust the path below to point at an actual .d64 file on your system.
 -- ~ is expanded to the current user's home directory on Mac/Linux;

resources/scripts/shared/example_emulator_control.lua

@@ -29,7 +29,7 @@
 --   on_system_selected(name)    -- system selection changed
 --   on_variant_selected(name)   -- system variant changed
 
--- ── State-change event hooks ──────────────────────────────────────────
+-- == State-change event hooks ==========================================
 
 function on_started()
     log.info("[event] Emulator started")
@@ -51,7 +51,7 @@ function on_variant_selected(name)
     log.info(string.format("[event] Variant selected: %s", name))
 end
 
--- ── Top-level init ────────────────────────────────────────────────────
+-- == Top-level init ====================================================
 
 local function list_systems()
     local systems = emu.systems()
@@ -70,7 +70,7 @@ log.info(string.format(
     list_systems()
 ))
 
--- ── Main loop (uses emu.yield to keep ticking while paused) ───────────
+-- == Main loop (uses emu.yield to keep ticking while paused) ===========
 
 log.info(string.format("Script start"))
 
@@ -92,7 +92,7 @@ while true do
 
     -- Pause at frame 300 (~5 seconds on C64), then resume after 3 seconds
     if not pause_demo_done and frame >= 300 and emu.state() == "running" then
-        log.info("Frame 300 reached — requesting pause")
+        log.info("Frame 300 reached - requesting pause")
         emu.pause()
         paused_at_time = emu.time()
     end