Engine WebView

Engine: WebView

Sucrose.Live.WebView is Sucrose's evergreen-browser engine, built on Microsoft Edge WebView2 (Chromium). It is the most versatile engine: it can render all five browser-capable types — Gif, Url, Web, Video, and YouTube. It is the everything-capable alternative to the default CefSharp browser engine and, together with CefSharp, is one of the two engines that can deliver Sucrose's audio-reactive and system-status JavaScript APIs to Web wallpapers. This page covers the technology, supported types, the WebView2 runtime requirement and auto-download, environment options, browser arguments, local file serving, the JS bridge, and the customization panel.

Table of contents

• At a glance
• Technology
• Supported wallpaper types
• Runtime requirement and auto-download
• Environment options
• Browser arguments
• Local file serving
• JavaScript bridge: audio and system data
• Customization panel
• Strengths and limitations
• See also

At a glance

Property	Value
Assembly	Sucrose.Live.WebView.exe
Tech	Microsoft Edge WebView2 (Chromium, evergreen runtime)
Supported types	Gif, Url, Web, Video, YouTube
Default for	(none — CefSharp is the default browser engine)
Preprocessor symbols	ENGINE, LIVE_WEBVIEW
Runtime requirement	WebView2 runtime ≥ 131.0.2903.70 (auto-download offered)
Local serving	file:///
Interactivity	Yes (uses RawInput.Sharp)
Audio/system-data injection	Yes (Web type)
Properties panel	PropertiesType.WebView (Gif/Video/YouTube), else Base

Technology

WebView2 hosts the same Chromium engine that ships with Microsoft Edge, drawing through the evergreen, system-updated runtime rather than a bundled Chromium. Its user-data folder is %AppData%\<App>\Cache\WebView2.

Supported wallpaper types

WebView renders all of Gif, Url, Web, Video, and YouTube — every browser-capable type. It does not render the Application type (that is Aurora-only). This makes WebView the most versatile single engine in Sucrose. See Type Gif, Type Url, Type Web, Type Video, and Type YouTube.

Runtime requirement and auto-download

The pre-launch Check queries CoreWebView2Environment.GetAvailableBrowserVersionString(). If the WebView2 runtime is missing or older than 131.0.2903.70, it shows a dialog with four options:

Option	Behavior
Continue	Proceed anyway
Download	Fetch the WebView2 bootstrapper from SMMRU.WebView2 and silently install it (Downloader)
Remember	Snooze the prompt for 1 day (WebViewTime)
Close	Exit the engine

See Runtime Dependencies and System Requirements.

Environment options

The engine constructs CoreWebView2EnvironmentOptions with:

• Language = Culture — the current Sucrose UI culture.
• AreBrowserExtensionsEnabled = false.
• ScrollBarStyle = FluentOverlay.

The user-data folder is %AppData%\<App>\Cache\WebView2.

Browser arguments

Command-line arguments come from the engine setting WebArguments (defaults in Internal.WebArguments). Key default flags include:

--disable-gpu-compositing
--multi-threaded-message-loop
--no-sandbox
--autoplay-policy=no-user-gesture-required
--enable-media-stream
--enable-accelerated-video-decode
--allow-file-access-from-files
--disable-features=...   (a long list: OutOfBlinkCors, IsolateOrigins, autoplay bypass, etc.)

Two settings modify the arguments at launch:

Setting	Effect
HardwareAcceleration ON	adds --enable-gpu and --enable-gpu-vsync
HardwareAcceleration OFF	adds --disable-gpu and --disable-gpu-vsync
DeveloperPort (Developer Mode)	adds --remote-debugging-port=N, --remote-allow-origins=*, and msEdgeDevTools remote debugging

See Settings Wallpaper and Settings Other for these toggles.

Local file serving

WebView serves a local web theme directly from disk using a file:/// URL of the form:

file:///{LibraryLocation}/{Selected}/

(This is the key behavioral difference from CefSharp, which serves the theme over a local HTTP server instead.)

JavaScript bridge: audio and system data

WebView is one of the two engines (the other is CefSharp) that deliver Sucrose's live-data JavaScript APIs to Web-type wallpapers:

• The theme ships a SucroseCompatible.json (class Sucrose.Shared.Theme.Helper.Compatible) declaring the JS callbacks it wants — for example SystemAudio, SystemMemory, SystemNetwork, SystemBattery, etc.
• If SystemAudio is declared, the engine flips Backgroundog's AudioRequired flag and starts a communication channel (CommunicationType: Pipe, Signal, or Transmission). Backgroundog produces the audio/system data and pushes messages; WebView receives them and calls CoreWebView2.ExecuteScriptAsync(...) with the theme's JS callbacks (Helper/Web.cs::StartCompatible).
• Customization controls are pushed via a property file watcher (Sucrose.Shared.Engine/Helper/Properties.cs): when the Portal/Property tool writes new property values, the engine re-injects them using the JS template SucrosePropertyListener('{0}', {1});.

See Create Audio API, Create System API, Create JS Bridge, Create Property Listener Filters, and Create Web Architecture.

Customization panel

The Properties panel type is set by Helper/Properties.cs: for Gif/Video/YouTube types it is PropertiesType.WebView; otherwise it is Base. The WebProperties JSON exposes CSS-style filters:

Control	Notes
scale (zoom)	—
saturate	—
hue-rotate	—
brightness	—
contrast	—
blur	—
grayscale	—
sepia	—
invert	—
mirror	Dropdown
animation	Flat / Flip / Pulse / Shake / Bounce / Wiggle
playbackRate	—
muted	Toggle
caption	Toggle

See Customizing Wallpaper and Property Service.

Strengths and limitations

Strengths

• The most versatile engine — renders every browser-capable type (Gif, Url, Web, Video, YouTube).
• Uses the evergreen, system-updated Chromium runtime, so it stays current with the OS.
• Full support for audio-reactive and system-status Web wallpapers.
• Interactive (mouse/keyboard via RawInput.Sharp).

Limitations

• Requires the WebView2 runtime (≥ 131.0.2903.70); offers an auto-download if missing.
• Cannot render the Application type.
• Browser overhead is higher than the native MpvPlayer for plain Gif/Video playback.

See also

• Engine CefSharp
• Engines Overview
• Engine Comparison
• Type Web
• Type YouTube
• Create Web Architecture
• Runtime Dependencies