### Running Browservice Proxy on Linux and Windows

Source: https://context7.com/ttalvitie/browservice/llms.txt

Basic commands to start the Browservice proxy server. Includes options for accepting external connections and installing fonts.

```bash
# Linux: download AppImage, make executable, and run
chmod +x browservice-0.9.12.2-x86_64.AppImage
./browservice-0.9.12.2-x86_64.AppImage
```

```bash
# Linux: accept connections from other machines (WARNING: see security notes in README)
./browservice-0.9.12.2-x86_64.AppImage --vice-opt-http-listen-addr=0.0.0.0:8080
```

```bash
# Linux: install optional Verdana font for best UI appearance
./browservice-0.9.12.2-x86_64.AppImage --install-verdana
```

```bash
# Windows
browservice.exe --vice-opt-http-listen-addr=0.0.0.0:8080
```

```bash
# Show all available options
./browservice-0.9.12.2-x86_64.AppImage --help
```

```bash
# Show version information
./browservice-0.9.12.2-x86_64.AppImage --version
# Output: Browservice 0.9.12.2, built with CEF <version>
#         Vice plugin retrojsvice.so: <version>
```

--------------------------------

### Vice Plugin API: Initialize and Start Context

Source: https://context7.com/ttalvitie/browservice/llms.txt

Demonstrates initializing a vice plugin context with specific options and starting it with a set of callbacks. Ensure API version compatibility before proceeding.

```c
#include "vice_plugin_api.h"
#include <stdio.h>
#include <stdint.h>

// Step 1: Verify API version compatibility
if (!vicePluginAPI_isAPIVersionSupported(2000000)) {
    fprintf(stderr, "Plugin does not support API version 2000000\n");
    return 1;
}

// Step 2: (optional) Register custom log and panic callbacks
vicePluginAPI_setGlobalLogCallback(
    2000000,
    [](void* data, VicePluginAPI_LogLevel level, const char* loc, const char* msg) {
        fprintf(stderr, "[%d] %s: %s\n", level, loc, msg);
    },
    NULL,
    NULL
);

// Step 3: Initialize a plugin context with options
const char* optNames[]  = { "http-listen-addr", "http-auth" };
const char* optValues[] = { "0.0.0.0:8080",     "admin:pass" };
char* initErrorMsg = NULL;
VicePluginAPI_Context* ctx = vicePluginAPI_initContext(
    2000000,
    optNames, optValues, 2,
    "MyBrowserApp",
    &initErrorMsg
);
if (!ctx) {
    fprintf(stderr, "Failed to init plugin context: %s\n", initErrorMsg);
    vicePluginAPI_free(initErrorMsg);
    return 1;
}

// Step 4: Start the context with callbacks
VicePluginAPI_Callbacks cbs = {0};
cbs.eventNotify       = [](void* d) { /* signal main loop */ };
cbs.shutdownComplete  = [](void* d) { /* mark done */ };
cbs.createWindow      = [](void* d, char** msg) -> uint64_t { return 1; };
cbs.closeWindow       = [](void* d, uint64_t w) { };
cbs.resizeWindow      = [](void* d, uint64_t w, size_t wd, size_t ht) { };
cbs.fetchWindowImage  = [](void* d, uint64_t w, void(*put)(void*,const uint8_t*,size_t,size_t,size_t), void* pd) {
    // supply a 24-bit RGB image; put() must be called exactly once
    put(pd, myRGBBuffer, 1024, 768, 1024);
};
cbs.mouseDown         = [](void* d, uint64_t w, int x, int y, int btn) { };
cbs.keyDown           = [](void* d, uint64_t w, int key) { };
// ... populate all other required callback fields ...

vicePluginAPI_start(ctx, cbs, /*callbackData=*/NULL);

// Step 5: Main event loop — pump events whenever eventNotify fires
while (running) {
    waitForEventNotify();
    vicePluginAPI_pumpEvents(ctx);  // may call callbacks directly
}

// Step 6: Shut down gracefully
vicePluginAPI_shutdown(ctx);
waitForShutdownComplete();         // wait for shutdownComplete callback
vicePluginAPI_destroyContext(ctx);
```

--------------------------------

### Start Browservice Proxy

Source: https://github.com/ttalvitie/browservice/blob/master/BUILD.md

Starts the Browservice proxy executable. This command assumes the build process has completed successfully.

```bash
release/bin/browservice
```

--------------------------------

### Install vcpkg Packages

Source: https://github.com/ttalvitie/browservice/blob/master/winbuild/README.md

Installs required vcpkg packages for both 32-bit and 64-bit Windows builds. Remove irrelevant targets if needed.

```bash
vcpkg install openssl:x86-windows openssl:x64-windows
vcpkg install pango:x86-windows pango:x64-windows poco[netssl]:x86-windows poco[netssl]:x64-windows libjpeg-turbo:x86-windows libjpeg-turbo:x64-windows
```

--------------------------------

### Vice Plugin API Context Lifecycle Example

Source: https://context7.com/ttalvitie/browservice/llms.txt

This C code example demonstrates the typical lifecycle of a vice plugin context, from initialization to shutdown.

```APIDOC
## Vice Plugin API - Context Lifecycle

### Description
This section details the process of integrating a host program with a vice plugin using the C API. It covers essential steps such as verifying API version compatibility, registering callbacks, initializing the plugin context with specific options, starting the context, managing the main event loop, and gracefully shutting down the plugin.

### API Version Check

```c
#include "vice_plugin_api.h"
#include <stdio.h>

// Step 1: Verify API version compatibility
if (!vicePluginAPI_isAPIVersionSupported(2000000)) {
    fprintf(stderr, "Plugin does not support API version 2000000\n");
    return 1;
}
```

### Custom Callbacks (Optional)

```c
// Step 2: (optional) Register custom log and panic callbacks
vicePluginAPI_setGlobalLogCallback(
    2000000,
    [](void* data, VicePluginAPI_LogLevel level, const char* loc, const char* msg) {
        fprintf(stderr, "[%d] %s: %s\n", level, loc, msg);
    },
    NULL,
    NULL
);
```

### Context Initialization

```c
#include <stdint.h> // Required for uint64_t

// Step 3: Initialize a plugin context with options
const char* optNames[]  = { "http-listen-addr", "http-auth" };
const char* optValues[] = { "0.0.0.0:8080",     "admin:pass" };
char* initErrorMsg = NULL;
VicePluginAPI_Context* ctx = vicePluginAPI_initContext(
    2000000,
    optNames, optValues, 2,
    "MyBrowserApp",
    &initErrorMsg
);
if (!ctx) {
    fprintf(stderr, "Failed to init plugin context: %s\n", initErrorMsg);
    vicePluginAPI_free(initErrorMsg); // Free the error message string
    return 1;
}
```

### Starting the Context and Callbacks

```c
// Step 4: Start the context with callbacks
VicePluginAPI_Callbacks cbs = {0};
cbs.eventNotify       = [](void* d) { /* signal main loop */ };
cbs.shutdownComplete  = [](void* d) { /* mark done */ };
cbs.createWindow      = [](void* d, char** msg) -> uint64_t { return 1; };
cbs.closeWindow       = [](void* d, uint64_t w) { };
cbs.resizeWindow      = [](void* d, uint64_t w, size_t wd, size_t ht) { };
cbs.fetchWindowImage  = [](void* d, uint64_t w, void(*put)(void*,const uint8_t*,size_t,size_t,size_t), void* pd) {
    // supply a 24-bit RGB image; put() must be called exactly once
    put(pd, myRGBBuffer, 1024, 768, 1024);
};
cbs.mouseDown         = [](void* d, uint64_t w, int x, int y, int btn) { };
cbs.keyDown           = [](void* d, uint64_t w, int key) { };
// ... populate all other required callback fields ...

vicePluginAPI_start(ctx, cbs, /*callbackData=*/NULL);
```

### Main Event Loop

```c
// Step 5: Main event loop — pump events whenever eventNotify fires
while (running) {
    waitForEventNotify();
    vicePluginAPI_pumpEvents(ctx);  // may call callbacks directly
}
```

### Shutdown Sequence

```c
// Step 6: Shut down gracefully
vicePluginAPI_shutdown(ctx);
waitForShutdownComplete();         // wait for shutdownComplete callback
vicePluginAPI_destroyContext(ctx);
```

### Notes
- The API version `2000000` is the current stable version.
- Ensure all required fields in `VicePluginAPI_Callbacks` are populated.
- The `vicePluginAPI_free` function should be used to free memory allocated by the API, such as `initErrorMsg`.
```

--------------------------------

### Run Browservice Proxy (Linux)

Source: https://github.com/ttalvitie/browservice/blob/master/README.md

Start the Browservice proxy server as a normal user. Do not use root privileges.

```bash
./browservice-RELEASE-ARCH.AppImage
```

--------------------------------

### Start Python HTTP Server

Source: https://github.com/ttalvitie/browservice/blob/master/test/README.md

Run this command in the directory containing your HTTP files to start a local server. It listens on all interfaces on port 8000.

```shell
python3 -m http.server
```

--------------------------------

### Get Browservice Help Information

Source: https://github.com/ttalvitie/browservice/blob/master/README.md

Display a list of all available command-line options for Browservice. This is useful for discovering and utilizing advanced configurations.

```bash
# Linux
./browservice-RELEASE-ARCH.AppImage --help
```

```bash
# Windows
browservice.exe --help
```

--------------------------------

### Install Verdana Font for Browservice

Source: https://github.com/ttalvitie/browservice/blob/master/README.md

Install the Verdana font for the Browservice GUI. This command should be run from the directory containing the AppImage. Type `yes` to accept the license agreement when prompted.

```bash
./browservice-RELEASE-ARCH.AppImage --install-verdana
```

--------------------------------

### Install Browservice Dependencies on Arch Linux

Source: https://github.com/ttalvitie/browservice/blob/master/BUILD.md

Installs necessary packages for Browservice on Arch Linux, including MS core fonts from the AUR. This process involves cloning the AUR snapshot, building, and installing the package.

```bash
sudo pacman -S wget cmake make gcc pkgconf poco pango libjpeg-turbo libxcb libx11 python xorg-server-xvfb xorg-xauth fakeroot at-spi2-atk alsa-lib nss libcups libxrandr libxcursor libxss libxcomposite libxkbcommon gtk3

# Install MS core fonts from AUR
wget https://aur.archlinux.org/cgit/aur.git/snapshot/ttf-ms-fonts.tar.gz
tar xf ttf-ms-fonts.tar.gz
pushd ttf-ms-fonts
makepkg -si
popd
rm -r ttf-ms-fonts ttf-ms-fonts.tar.gz
```

--------------------------------

### Install Browservice Dependencies on Fedora

Source: https://github.com/ttalvitie/browservice/blob/master/BUILD.md

Installs required packages for Browservice on Fedora 33, including MS core fonts via RPM.

```bash
sudo dnf install wget tar bzip2 cmake make g++ pkg-config poco-devel libjpeg-turbo-devel pango-devel Xvfb xauth at-spi2-atk alsa-lib libXScrnSaver libXrandr libgbm libXcomposite libXcursor curl cabextract xorg-x11-font-utils nss cups-libs libatomic gtk3
sudo rpm -i https://downloads.sourceforge.net/project/mscorefonts2/rpms/msttcore-fonts-installer-2.6-1.noarch.rpm
```

--------------------------------

### Install Build Dependencies on Ubuntu/Debian

Source: https://context7.com/ttalvitie/browservice/llms.txt

Installs necessary packages for building CEF on Ubuntu/Debian systems. Ensure your system is up-to-date before running.

```bash
sudo apt install wget cmake make g++ pkg-config libxcb1-dev libx11-dev \
    libpoco-dev libjpeg-dev zlib1g-dev libpango1.0-dev libpangoft2-1.0-0 \
    ttf-mscorefonts-installer xvfb xauth libatk-bridge2.0-0 libasound2 \
    libgbm1 libxi6 libcups2 libnss3 libxcursor1 libxrandr2 libxcomposite1 \
    libxss1 libxkbcommon0 libgtk-3-0
```

--------------------------------

### Setup CEF Distribution

Source: https://github.com/ttalvitie/browservice/blob/master/BUILD.md

Extracts the CEF distribution tarball and builds its DLL wrapper library. Replace `patched_cef_x86_64.tar.bz2` with the actual path to your CEF tarball.

```bash
./setup_cef.sh patched_cef_x86_64.tar.bz2
```

--------------------------------

### Install Browservice Dependencies on Ubuntu/Debian

Source: https://github.com/ttalvitie/browservice/blob/master/BUILD.md

Installs necessary packages for Browservice on Ubuntu 18.04/20.04, Debian 10, and Raspberry Pi OS. Ensure 'contrib' is added to APT sources for ttf-mscorefonts-installer if needed.

```bash
sudo apt install wget cmake make g++ pkg-config libxcb1-dev libx11-dev libpoco-dev libjpeg-dev zlib1g-dev libpango1.0-dev libpangoft2-1.0-0 ttf-mscorefonts-installer xvfb xauth libatk-bridge2.0-0 libasound2 libgbm1 libxi6 libcups2 libnss3 libxcursor1 libxrandr2 libxcomposite1 libxss1 libxkbcommon0 libgtk-3-0
```

--------------------------------

### Window Load Initialization

Source: https://github.com/ttalvitie/browservice/blob/master/viceplugins/retrojsvice/html/main.html

Entry point for the script. Detects browser quirks, initializes image elements, registers event handlers, and starts image loading upon window load.

```javascript
window.onload = function() {
 detectBrowserQuirks();
 imgElems[0] = document.images[0];
 imgElems[1] = document.images[1];
 registerEventHandlers();
 startImgLoad();
};
```

--------------------------------

### Browservice Navigation URLs

Source: https://context7.com/ttalvitie/browservice/llms.txt

Examples of URLs used to interact with the Browservice proxy. Use these to open new windows, navigate to specific sites on startup, or redirect existing windows.

```shell
# Open a new Browservice window at the proxy default start page:
http://192.168.1.10:8080/
```

```shell
# Navigate the Browservice browser to a specific URL on first open:
http://192.168.1.10:8080/goto/https://example.com
```

```shell
# Navigate an already-open Browservice window to a new URL
# (append goto/URL to the existing window address in the client browser):
http://192.168.1.10:8080/1/qu7cHJCHqtYeHjasBedM3b42tlS4nEOM/goto/https://github.com
```

--------------------------------

### URINavigation Extension

Source: https://context7.com/ttalvitie/browservice/llms.txt

Enables plugins to navigate windows to specific URIs. It provides callbacks for creating new windows with a URI and navigating existing windows to a URI. This extension must be enabled after initContext and before start.

```APIDOC
## URINavigation Extension

### Description
Allows plugins to control window navigation to specific URIs.

### Callbacks
- `createWindowWithURI`: Called when a new window should be opened at a given URI. Returns a new window handle.
- `navigateWindowToURI`: Called when an existing window should navigate to a specified URI.

### Enable Function
`vicePluginAPI_URINavigation_enable(ctx, uriCbs)`

### Usage Notes
Must be called after `initContext` and before `start`.
```

--------------------------------

### Initiate and Cancel File Uploads with Vice Plugin API

Source: https://context7.com/ttalvitie/browservice/llms.txt

Start a file upload process, which prompts the user to select a file. The upload can be programmatically cancelled. The plugin will call a callback with the selected file path or a cancellation notification.

```c
// Start file upload mode; plugin shows an upload dialog to user
int started = vicePluginAPI_startFileUpload(ctx, /*window=*/1);
if (!started) {
    fprintf(stderr, "Plugin does not support file uploads\n");
}
// Plugin calls uploadFile callback with path when user selects a file,
// or cancelFileUpload callback if user dismisses the dialog.
// To cancel programmatically:
vicePluginAPI_cancelFileUpload(ctx, 1);
```

--------------------------------

### Build Patched CEF using Docker

Source: https://github.com/ttalvitie/browservice/blob/master/BUILD.md

Use this script to build a patched CEF version compatible with the current Browservice code. Ensure you have Docker installed and sufficient disk space and memory. The build can take a significant amount of time.

```bash
# Clone the Browservice code repository
git clone https://github.com/ttalvitie/browservice.git

# Create the cefbuild Docker image
cd browservice/tools/linux_cef_build_docker_image/
sudo docker build -t cefbuild .

# Prepare a build directory
cd ..
mkdir build
chmod 777 build
cp build_patched_cef.py build/

# Build CEF (this takes a lot of time; run in screen if you are behind an unreliable SSH connection)
# This command creates a x86_64 build; replace x86_64 by aarch64 for ARM64 and armhf for 32-bit ARM
# This will build a CEF version that is compatible with the Browservice code in the currently checked out commit
# (The version is overridable using the command line arguments of build_patched_cef.py)
sudo docker run -v "${PWD}/build":/home/appuser cefbuild python3 /home/appuser/build_patched_cef.py /home/appuser/build /home/appuser/patched_cef_x86_64.tar.bz2 x86_64

# Copy the built patched CEF distribution away from the build directory; we will need it when building Browservice
# (Again replace x86_64 by aarch64 or armhf if appropriate)
cp build/patched_cef_x86_64.tar.bz2 .

# Remove the build directory
sudo rm -r build
```

--------------------------------

### Building Browservice from Source (Linux)

Source: https://context7.com/ttalvitie/browservice/llms.txt

Commands to clone the Browservice repository and navigate into the project directory on Linux.

```bash
# Clone the repository
git clone https://github.com/ttalvitie/browservice.git
cd browservice
```

--------------------------------

### Make AppImage Executable

Source: https://github.com/ttalvitie/browservice/blob/master/README.md

Make the downloaded AppImage file executable before running it. Replace `RELEASE` and `ARCH` with the actual values from the filename.

```bash
chmod +x browservice-RELEASE-ARCH.AppImage
```

--------------------------------

### Browservice Command-Line Configuration Options

Source: https://context7.com/ttalvitie/browservice/llms.txt

Configure Browservice behavior using command-line arguments. Options prefixed with `--vice-opt-` are passed to the vice plugin.

```bash
# Persist cookies and cache across sessions (disables incognito mode)
./browservice --data-dir=/home/user/.browservice/cefdata
```

```bash
# Set a custom start page for every new browser window
./browservice --start-page=https://example.com
```

```bash
# Limit concurrent browser windows (default: 32)
./browservice --window-limit=5
```

```bash
# Override the User-Agent string sent by the embedded Chromium browser
./browservice --user-agent="Mozilla/5.0 (compatible; MyBrowser/1.0)"
```

```bash
# Pass extra arguments directly to Chromium (e.g. use desktop OpenGL for better video performance)
./browservice --chromium-args=use-gl=desktop
```

```bash
# Disable the control bar entirely (useful for kiosk setups)
./browservice --show-control-bar=no
```

```bash
# Show soft Back/Forward/Refresh/Home buttons inside the browser area
./browservice --show-soft-navigation-buttons=yes
```

```bash
# Set initial zoom factor for all new windows (e.g. 1.5 = 150%)
./browservice --initial-zoom=1.5
```

```bash
# Set font rendering mode: options include no-antialias, antialias,
# antialias-subpixel-rgb, antialias-subpixel-bgr, antialias-subpixel-vrgb,
# antialias-subpixel-vbgr, system
./browservice --browser-font-render-mode=antialias-subpixel-rgb
```

```bash
# Add SSL/TLS certificate check exceptions for specific domains
./browservice --certificate-check-exceptions=internal.corp,dev.local
```

```bash
# Block file:// URI scheme access (enabled by default as a security measure)
./browservice --block-file-scheme=yes
```

```bash
# Select a different vice plugin shared library
./browservice --vice-plugin=/path/to/custom_vice_plugin.so
```

```bash
# Linux only: share existing X session instead of using a dedicated Xvfb
./browservice --use-dedicated-xvfb=no
```

--------------------------------

### Query Vice Plugin API Option Documentation

Source: https://context7.com/ttalvitie/browservice/llms.txt

Retrieves documentation for all configuration options supported by the Vice plugin for a given API version. The callback function processes each option's name, value specification, description, and default value.

```c
// Enumerate all options supported by the vice plugin for a given API version
vicePluginAPI_getOptionDocs(
    2000000,
    [](void* data, const char* name, const char* valSpec,
       const char* desc, const char* defaultValStr) {
        printf("  --vice-opt-%s=%s\n", name, valSpec);
        printf("      %s [%s]\n", desc, defaultValStr);
    },
    NULL  // callback data
);
// Example output:
//   --vice-opt-http-listen-addr=IP:PORT
//       bind address and port for the HTTP server [default: 127.0.0.1:8080]
//   --vice-opt-http-auth=USER:PASS
//       if nonempty, require HTTP basic auth [default empty]
//   --vice-opt-default-quality=QUALITY
//       default image quality, 10-100 for JPEG, 101 for PNG [default: 80]
```

--------------------------------

### Fix FUSE Missing Error in AppImage

Source: https://github.com/ttalvitie/browservice/blob/master/README.md

This error indicates that FUSE is not installed, which is required for mounting AppImages. Install FUSE using your distribution's package manager or extract the AppImage contents to run Browservice without root privileges.

```bash
fuse: failed to exec fusermount: No such file or directory

Cannot mount AppImage, please check your FUSE setup.
You might still be able to extract the contents of this AppImage
if you run it with the --appimage-extract option.
See https://github.com/AppImage/AppImageKit/wiki/FUSE
for more information
open dir error: No such file or directory
```

--------------------------------

### Query Option Documentation

Source: https://context7.com/ttalvitie/browservice/llms.txt

Retrieves documentation for all configuration options supported by the vice plugin for a given API version. The results are provided via a callback function.

```APIDOC
## Query Option Documentation

### Function
`vicePluginAPI_getOptionDocs(apiVersion, callback, callbackData)`

### Parameters
- `apiVersion` (int): The API version to query documentation for.
- `callback` (function pointer): A function called for each option with parameters:
  - `data`: User-provided data passed to `vicePluginAPI_getOptionDocs`.
  - `name` (const char*): The name of the option.
  - `valSpec` (const char*): A string specifying the expected value format.
  - `desc` (const char*): A description of the option.
  - `defaultValStr` (const char*): The default value of the option as a string.
- `callbackData` (void*): User-defined data to be passed to the callback.
```

--------------------------------

### Initialize Browservice Testbed Variables and Counter

Source: https://github.com/ttalvitie/browservice/blob/master/test/page1.html

Sets up global variables for timeouts and an interval counter that updates the DOM every second. Ensure an element with id 'counter' exists in the HTML.

```javascript
var iframeLoadNowTimeoutFunc;
var imageReloadTimeoutFunc;
var imagePostLoadTimeoutFunc = function() {};
var hackInputFocusTimeoutFunc;
window.onload = function() {
  var seconds = 0;
  var counter = document.getElementById("counter");
  setInterval(function() {
    ++seconds;
    counter.innerText = seconds + " second" + (seconds == 1 ? "" : "s")
  }, 1000)
}
```

--------------------------------

### WindowTitle Extension

Source: https://context7.com/ttalvitie/browservice/llms.txt

Enables plugins to query and track changes to window titles. It provides a callback to get the current window title and a notification for title changes.

```APIDOC
## WindowTitle Extension

### Description
Allows plugins to query and track window title changes.

### Callbacks
- `getWindowTitle`: Called to retrieve the title of a specific window. The plugin must return a `vicePluginAPI_malloc`-allocated string or `NULL`.

### Enable Function
`vicePluginAPI_WindowTitle_enable(ctx, titleCbs)`

### Notification Function
`vicePluginAPI_WindowTitle_notifyWindowTitleChanged(ctx, window)`

### Usage Notes
`getWindowTitle` should return a plugin-allocated string that will be freed by the caller.
```

--------------------------------

### Query and Change Window Quality Settings

Source: https://context7.com/ttalvitie/browservice/llms.txt

Query if a window supports quality selection and change the quality setting. The qualityList is newline-delimited and contains short ASCII strings. Ensure the quality index is valid.

```c
// Query whether the plugin provides a quality selector widget for a window
char* qualityList = NULL;
size_t currentQuality = 0;
if (vicePluginAPI_windowQualitySelectorQuery(ctx, 1, &qualityList, &currentQuality)) {
    // qualityList = "Bad\nOK\nHD\n"  (newline-delimited, 1-3 ASCII chars each)
    printf("Quality options: %s  Current: %zu\n", qualityList, currentQuality);
    vicePluginAPI_free(qualityList);
    // Notify plugin when user selects a different quality (0-based index)
    vicePluginAPI_windowQualityChanged(ctx, 1, /*qualityIdx=*/2);  // select "HD"
}
```

--------------------------------

### Troubleshoot ttf-mscorefonts-installer on Ubuntu

Source: https://github.com/ttalvitie/browservice/blob/master/BUILD.md

Provides steps to resolve silent failures of ttf-mscorefonts-installer on Ubuntu by using a Debian package. This ensures correct UI text rendering.

```bash
sudo apt remove ttf-mscorefonts-installer
wget https://www.nic.funet.fi/debian/pool/contrib/m/msttcorefonts/ttf-mscorefonts-installer_3.7_all.deb
sudo dpkg -i ttf-mscorefonts-installer_3.7_all.deb
```

--------------------------------

### Google Sign-In Workaround with Browservice

Source: https://context7.com/ttalvitie/browservice/llms.txt

Command-line steps to perform a Google sign-in workaround using a special user agent. This involves two steps: signing in with the specific user agent and then restarting with the preferred user agent, leveraging persisted session cookies.

```bash
# Step 1: Sign in with user agent set to the Google accounts URL
./browservice --user-agent="https://accounts.google.com" \
              --data-dir=/home/user/.browservice/cefdata

# Step 2: After signing in successfully, restart with your preferred user agent
# (session cookies are persisted in --data-dir and will continue to work)
./browservice --data-dir=/home/user/.browservice/cefdata
```

--------------------------------

### Build AppImage

Source: https://github.com/ttalvitie/browservice/blob/master/BUILD.md

Builds the AppImage for Browservice using a provided script. Requires specifying architecture, Git branch/commit/tag, CEF tarball path, and output filename.

```bash
tools/build_appimage.sh <arch> <git_ref> <cef_tarball_path> <output_filename>
```

--------------------------------

### Run Browservice on Windows

Source: https://github.com/ttalvitie/browservice/blob/master/README.md

Execute the Browservice application on Windows. This can be done via the command prompt or by directly clicking the executable.

```bash
browservice.exe
```

--------------------------------

### Vice Plugin HTTP Listen Address and Authentication

Source: https://context7.com/ttalvitie/browservice/llms.txt

Configure the Retrojsvice plugin's HTTP server, including listen address, authentication, and image quality.

```bash
# Bind to a specific IP and port (default: 127.0.0.1:8080)
./browservice --vice-opt-http-listen-addr=192.168.1.10:8080
```

```bash
# Enable HTTP Basic Auth to require a password
./browservice --vice-opt-http-auth=admin:s3cr3tpassword
```

```bash
# Set default image quality: 10-100 for JPEG quality, 101 for PNG
./browservice --vice-opt-default-quality=75
```

```bash
# Show all vice plugin options
./browservice --help
# (The help output includes a section "Supported options for the vice plugin")
```

--------------------------------

### Extract AppImage and Run Browservice

Source: https://github.com/ttalvitie/browservice/blob/master/README.md

Use this command to extract the contents of an AppImage into a directory. This is a workaround for issues like 'exec format error' or 'SUID sandbox helper not found' that prevent the AppImage from running directly. After extraction, you can run Browservice from the extracted AppDir.

```bash
# Extract the AppImage into directory 'squashfs-root'
./browservice-RELEASE-ARCH.AppImage --appimage-extract

# Give the directory a better name
mv squashfs-root browservice-RELEASE-ARCH.AppDir

# Start Browservice
browservice-RELEASE-ARCH.AppDir/AppRun
```

--------------------------------

### HTML Structure for Clipboard Interaction

Source: https://github.com/ttalvitie/browservice/blob/master/viceplugins/retrojsvice/html/clipboard.html

Sets up a basic HTML page with a textarea for input and buttons for clipboard actions. Focuses the textarea on page load.

```html
<!DOCTYPE html>
<html>
<head>
<title>Clipboard</title>
<style>
body { overflow: hidden; }
textarea { position: absolute; top: 0px; left: 0px; width: 400px; height: 260px; }
input { position: absolute; top: 260px; height: 40px; width: 200px; }
.get { left: 0px; }
.set { left: 200px; }
</style>
</head>
<body>
<form>
<textarea></textarea>
<input class="get" type="button" value="Get Text">
<input class="set" type="button" value="Set Text">
</form>
<script>
window.onload = function() {
  document.forms[0].elements[0].focus();
  document.forms[0].elements[0].select();
};
</script>
</body>
</html>
```

--------------------------------

### Configure CMake for 64-bit Build

Source: https://github.com/ttalvitie/browservice/blob/master/winbuild/README.md

Configures the build environment for a 64-bit Browservice build using CMake and Visual Studio 17 generator.

```bash
cmake -G "Visual Studio 17" -A x64 ..

```

--------------------------------

### URINavigation Extension for Vice Plugin API

Source: https://context7.com/ttalvitie/browservice/llms.txt

Enables plugins to handle URI navigation requests, including opening new windows and navigating existing ones. Ensure the extension is supported before use.

```c
// --- URINavigation extension //
// Allows plugin to navigate windows to specific URIs
if (vicePluginAPI_isExtensionSupported(2000000, "URINavigation")) {
    VicePluginAPI_URINavigation_Callbacks uriCbs;
    // Called when a new window should open at a given URI
    uriCbs.createWindowWithURI = [](void* d, char** msg, const char* uri) -> uint64_t {
        printf("New window requested for URI: %s\n", uri);
        return 42;  // return new window handle
    };
    // Called when an existing window should navigate to a URI
    uriCbs.navigateWindowToURI = [](void* d, uint64_t win, const char* uri) {
        printf("Window %llu navigating to: %s\n", win, uri);
    };
    // Must be called after initContext and BEFORE start
    vicePluginAPI_URINavigation_enable(ctx, uriCbs);
}
```

--------------------------------

### JavaScript Redirect for Download

Source: https://github.com/ttalvitie/browservice/blob/master/viceplugins/retrojsvice/html/download_iframe.html

This JavaScript code executes when the window loads, redirecting the user to the specified download URL. Ensure the URL parameters are correctly substituted.

```javascript
%-programName-% window.onload = function() { window.location.href = "% -pathPrefix-%/download/%-downloadIdx-%/%-fileName-%"; };
```

--------------------------------

### Vice Plugin API Memory Management

Source: https://context7.com/ttalvitie/browservice/llms.txt

Demonstrates proper memory management for strings and buffers within the Vice Plugin API. Use `vicePluginAPI_malloc` for allocations that will be passed back to the plugin and `vicePluginAPI_free` to release them. Standard `free()` should not be used.

```c
// Get version string — caller must free with vicePluginAPI_free
char* version = vicePluginAPI_createVersionString();
printf("Plugin version: %s\n", version);
vicePluginAPI_free(version);

// Get credits string — caller must free with vicePluginAPI_free
char* credits = vicePluginAPI_createCreditsString();
printf("Credits:\n%s\n", credits);
vicePluginAPI_free(credits);

// Allocate memory on the plugin heap (for strings passed back to the plugin)
char* myBuf = (char*)vicePluginAPI_malloc(256);
snprintf(myBuf, 256, "value");
// Plugin will call vicePluginAPI_free(myBuf) when done

// NULL-safe: vicePluginAPI_free(NULL) is a no-op
vicePluginAPI_free(NULL);
```

--------------------------------

### Generate HTML C++ File

Source: https://github.com/ttalvitie/browservice/blob/master/winbuild/README.md

Generates the HTML template C++ file from the viceplugins\retrojsvice directory. Ensure you are in the correct directory before running.

```bash
mkdir gen
python gen_html_cpp.py > gen\html.cpp
```

--------------------------------

### PluginNavigationControlSupportQuery Extension

Source: https://context7.com/ttalvitie/browservice/llms.txt

Allows plugins to indicate whether they provide their own navigation controls (Back, Forward, Refresh). If the plugin does not provide these, the host application should display its own.

```APIDOC
## PluginNavigationControlSupportQuery Extension

### Description
Queries whether the plugin offers its own navigation controls.

### Query Function
`vicePluginAPI_PluginNavigationControlSupportQuery_query(ctx)`

### Return Value
- `0`: Host app should show its own navigation buttons.
- Non-zero: Plugin provides its own navigation controls.
```

--------------------------------

### Set SUID Bit for Chrome Sandbox

Source: https://github.com/ttalvitie/browservice/blob/master/README.md

This command sequence extracts the AppImage, sets the correct ownership and permissions for the 'chrome-sandbox' executable, and then runs Browservice. This is an alternative fix for the 'SUID sandbox helper not found' error if enabling user namespaces is not possible.

```bash
# Extract the AppImage into directory 'squashfs-root'
./browservice-RELEASE-ARCH.AppImage --appimage-extract

# Give the directory a better name
mv squashfs-root browservice-RELEASE-ARCH.AppDir

# Set proper permissions for chrome-sandbox as root
sudo chown root:root browservice-RELEASE-ARCH.AppDir/opt/browservice/chrome-sandbox
sudo chmod 4755 browservice-RELEASE-ARCH.AppDir/opt/browservice/chrome-sandbox

# Start Browservice
browservice-RELEASE-ARCH.AppDir/AppRun
```

--------------------------------

### Configure Browservice Listen Address

Source: https://github.com/ttalvitie/browservice/blob/master/README.md

Adjust the network interface and port Browservice listens on. Use '0.0.0.0' to accept connections on all interfaces. Be aware of security implications when binding to external interfaces.

```bash
# Linux:
./browservice-RELEASE-ARCH.AppImage --vice-opt-http-listen-addr=0.0.0.0:8080
```

```bash
# Windows:
browservice.exe --vice-opt-http-listen-addr=0.0.0.0:8080
```

--------------------------------

### PluginNavigationControlSupportQuery Extension for Vice Plugin API

Source: https://context7.com/ttalvitie/browservice/llms.txt

Queries whether a plugin provides its own navigation controls (Back, Forward, Refresh). If the plugin does not, the host application should display its own.

```c
// --- PluginNavigationControlSupportQuery extension //
// Query whether the plugin provides its own Back/Forward/Refresh buttons
if (vicePluginAPI_isExtensionSupported(2000000, "PluginNavigationControlSupportQuery")) {
    int hasNavControls = vicePluginAPI_PluginNavigationControlSupportQuery_query(ctx);
    // If hasNavControls == 0, the host app should show its own navigation buttons
}
```

--------------------------------

### Configure CMake for 32-bit Build

Source: https://github.com/ttalvitie/browservice/blob/master/winbuild/README.md

Configures the build environment for a 32-bit Browservice build using CMake and Visual Studio 17 generator.

```bash
cmake -G "Visual Studio 17" -A Win32 ..

```

--------------------------------

### Window Management Functions

Source: https://context7.com/ttalvitie/browservice/llms.txt

Functions for managing windows, including notifications, creation, closing, and cursor settings.

```APIDOC
## Window Management Functions

### Description
Functions for managing windows, including notifications, creation, closing, and cursor settings.

### Functions

- **vicePluginAPI_notifyWindowViewChanged(ctx, window)**
  - Notifies the plugin that the view image for a specific window has changed.

- **vicePluginAPI_createPopupWindow(ctx, parentWindow, newPopupHandle, &denyMsg)**
  - Creates a popup window initiated by the program.
  - Returns 1 if allowed, 0 if denied. `denyMsg` contains the reason for denial if denied.

- **vicePluginAPI_closeWindow(ctx, window)**
  - Closes a specified window.

- **vicePluginAPI_setWindowCursor(ctx, window, cursorType)**
  - Changes the displayed mouse cursor for a window.
  - `cursorType` can be VICE_PLUGIN_API_MOUSE_CURSOR_NORMAL, VICE_PLUGIN_API_MOUSE_CURSOR_HAND, or VICE_PLUGIN_API_MOUSE_CURSOR_TEXT.

- **vicePluginAPI_windowQualitySelectorQuery(ctx, window, &qualityList, &currentQuality)**
  - Queries whether the plugin provides a quality selector widget for a window.
  - If true, `qualityList` will contain newline-delimited quality options and `currentQuality` will be the index of the current quality.

- **vicePluginAPI_windowQualityChanged(ctx, window, qualityIdx)**
  - Notifies the plugin when the user selects a different quality setting for a window.
  - `qualityIdx` is the 0-based index of the selected quality.
```

--------------------------------

### State and Event Queue Management

Source: https://github.com/ttalvitie/browservice/blob/master/viceplugins/retrojsvice/html/main.html

JavaScript variables and functions for managing the application state, including shutdown status, event queue, and mouse coordinates.

```javascript
// State variables
var shutdown = false;
var eventQueue = new Array();
var eventQueueStartIdx = 0;
var mouseMoved = false;
var mouseX = 0;
var mouseY = 0;
```

--------------------------------

### Enable User Namespaces for SUID Sandbox

Source: https://github.com/ttalvitie/browservice/blob/master/README.md

This command enables unprivileged user namespaces, which is a prerequisite for the SUID sandbox helper to function correctly. This is a preferred fix for the 'SUID sandbox helper not found' error when user namespaces are disabled.

```bash
sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
```

--------------------------------

### Enable Unprivileged User Clone

Source: https://github.com/ttalvitie/browservice/blob/master/README.md

On some Debian-based distributions, unprivileged user namespaces might be completely disabled. This command enables them by setting the 'kernel.unprivileged_userns_clone' sysctl parameter. This is an alternative to enabling user namespaces when the first method is not applicable.

```bash
sysctl -w kernel.unprivileged_userns_clone=1
```

--------------------------------

### Compile Release Build of Browservice

Source: https://github.com/ttalvitie/browservice/blob/master/BUILD.md

Compiles a release build of Browservice. Adjust the `-j` argument to control the number of parallel compile jobs.

```bash
make -j5 release
```

--------------------------------

### Manage Browser Windows with Vice Plugin API

Source: https://context7.com/ttalvitie/browservice/llms.txt

Use these functions to control browser windows, such as notifying about view changes, creating popups, closing windows, and setting cursors. Ensure context is valid before calling.

```c
// Notify the plugin that the view image for window 1 has changed;
// the plugin will call fetchWindowImage to retrieve the updated frame.
vicePluginAPI_notifyWindowViewChanged(ctx, /*window=*/1);
```

```c
// Program-initiated popup window creation (parentWindow=1, newPopupHandle=2)
char* denyMsg = NULL;
int allowed = vicePluginAPI_createPopupWindow(ctx, 1, 2, &denyMsg);
if (!allowed) {
    fprintf(stderr, "Popup denied: %s\n", denyMsg);
    vicePluginAPI_free(denyMsg);
}
```

```c
// Program-initiated window close
vicePluginAPI_closeWindow(ctx, /*window=*/1);
```

```c
// Change the displayed mouse cursor for a window
vicePluginAPI_setWindowCursor(ctx, 1, VICE_PLUGIN_API_MOUSE_CURSOR_HAND);
// Available cursors: NORMAL, HAND, TEXT
```

--------------------------------

### Set SUID Permissions for Chromium Sandbox

Source: https://context7.com/ttalvitie/browservice/llms.txt

Sets the SUID permissions for the Chromium sandbox helper binary. This is a security-sensitive operation and requires root privileges.

```bash
sudo chown root:root release/bin/chrome-sandbox
sudo chmod 4755 release/bin/chrome-sandbox
```

--------------------------------

### JavaScript for Initial Focus and Selection

Source: https://github.com/ttalvitie/browservice/blob/master/viceplugins/retrojsvice/html/upload.html

Sets the initial focus and selects the content of the first form element when the page loads. Ensure the form and its elements are correctly structured.

```javascript
window.onload = function() {
  document.forms[0].elements[0].focus();
  document.forms[0].elements[0].select();
};
```

--------------------------------

### Build Patched CEF using Docker

Source: https://context7.com/ttalvitie/browservice/llms.txt

Builds a patched CEF tarball using Docker. Ensure you have sufficient RAM and disk space. This process can take several hours.

```bash
cd tools
mkdir build && chmod 777 build
cp build_patched_cef.py build/
sudo docker build -t cefbuild linux_cef_build_docker_image/
sudo docker run -v "${PWD}/build":/home/appuser cefbuild \
    python3 /home/appuser/build_patched_cef.py \
    /home/appuser/build /home/appuser/patched_cef_x86_64.tar.bz2 x86_64
cp build/patched_cef_x86_64.tar.bz2 ..
cd ..
```

--------------------------------

### Browservice Keyboard Shortcuts

Source: https://context7.com/ttalvitie/browservice/llms.txt

List of keyboard shortcuts available within the Browservice browser view for common actions like copy/paste, find, address bar focus, zoom, and reloading.

```shell
# Keyboard shortcuts supported inside the Browservice browser view:
# Ctrl+C / Ctrl+V     — copy/paste within Browservice windows
# Ctrl+F              — open Find bar (or Ctrl+Shift+F if browser captures Ctrl+F)
# Ctrl+L              — focus address bar
# Ctrl+K / Ctrl+J     — zoom in / zoom out
# Ctrl+M              — zoom reset
# F5 / Ctrl+R         — reload
# Backspace           — back   (Shift+Backspace = forward)
# PgUp / PgDown / Home / End — scroll
```

--------------------------------

### Navigate Back and Redirect on Load

Source: https://github.com/ttalvitie/browservice/blob/master/viceplugins/retrojsvice/html/next.html

Executes JavaScript on page load to go back one history entry and then redirect to a specified path after a short delay. Useful for implementing 'back' functionality with a fallback redirect.

```javascript
window.onload = function() { setTimeout("window.history.back(); setTimeout(\"window.location.href = \\\
```

--------------------------------

### Registering Mouse and Window Event Handlers in JavaScript

Source: https://github.com/ttalvitie/browservice/blob/master/viceplugins/retrojsvice/html/main.html

Sets up event listeners for various user interactions including mouse clicks, double clicks, movement, and mouse wheel scrolling. It ensures events are properly processed and default actions are prevented.

```javascript
function registerEventHandlers() {
 imgElems[0].onload = function() {
 imgLoadHandler(0);
 };
 imgElems[1].onload = function() {
 imgLoadHandler(1);
 };
 window.onresize = newEventNotify;
 document.onmousedown = function(event) {
 if(!event) event = window.event;
 updateMousePos(event);
 var button = event.button | 0;
 if(button >= 0 && button <= 2) {
 if(leftMouseButtonIs1 && button == 1) {
 button = 0;
 }
 sanitizeModifiers(event, function() { putEvent("MDN_" + mouseX + "_" + mouseY + "_" + button); });
 }
 window.focus();
 preventDefault(event);
 };
 document.onmouseup = function(event) {
 if(!event) event = window.event;
 updateMousePos(event);
 var button = event.button | 0;
 if(button >= 0 && button <= 2) {
 if(leftMouseButtonIs1 && button == 1) {
 button = 0;
 }
 putEvent("MUP_" + mouseX + "_" + mouseY + "_" + button);
 }
 preventDefault(event);
 };
 document.ondblclick = function(event) {
 if(!event) event = window.event;
 updateMousePos(event);
 putEvent("MDBL_" + mouseX + "_" + mouseY);
 preventDefault(event);
 };
 document.onmousemove = function(event) {
 if(!event) event = window.event;
 updateMousePos(event);
 if(!mouseMoved) {
 mouseMoved = true;
 newEventNotify();
 }
 };
 if(useOnDOMMouseScroll) {
 document.addEventListener( "DOMMouseScroll", function(event) {
 var delta = -120 * (event.detail | 0);
 putEvent("MWH_" + mouseX + "_" + mouseY + "_" + delta);
 event.preventDefault();
 }, false );
 } else if(useOnMouseWheel) {
 document.onmousewheel = function(event) {
 if(!event) event = window.event;
 putEvent("MWH_" + mouseX + "_" + mouseY + "_" + (event.wheelDelta | 0));
 };
 } else {
 document.onwheel = function(event) {
 var delta = 0;
 if(
```

--------------------------------

### Set SUID Permissions for chrome-sandbox

Source: https://github.com/ttalvitie/browservice/blob/master/BUILD.md

Sets the SUID permissions for the `chrome-sandbox` binary, which is required to enable Chromium's sandbox features. This command should be run with root privileges.

```bash
sudo chown root:root release/bin/chrome-sandbox && sudo chmod 4755 release/bin/chrome-sandbox
```

--------------------------------

### ZoomInput Extension for Vice Plugin API

Source: https://context7.com/ttalvitie/browservice/llms.txt

Enables plugins to send zoom commands (e.g., from keyboard shortcuts) to control the zoom level of a window. Supported commands include zoom in, zoom out, and reset.

```c
// --- ZoomInput extension //
// Allows plugin to send zoom commands (e.g., from keyboard shortcuts)
if (vicePluginAPI_isExtensionSupported(2000000, "ZoomInput")) {
    VicePluginAPI_ZoomInput_Callbacks zoomCbs;
    zoomCbs.zoomCommand = [](void* d, uint64_t win, VicePluginAPI_ZoomInput_Command cmd) {
        switch (cmd) {
            case VICE_PLUGIN_API_ZOOM_INPUT_COMMAND_ZOOM_IN:    /* zoom in  */ break;
            case VICE_PLUGIN_API_ZOOM_INPUT_COMMAND_ZOOM_OUT:   /* zoom out */ break;
            case VICE_PLUGIN_API_ZOOM_INPUT_COMMAND_ZOOM_RESET: /* reset    */ break;
        }
    };
    vicePluginAPI_ZoomInput_enable(ctx, zoomCbs);
}
```