Skip to content

Review fixes for the HTML5 runtime - #1

Closed
utkarshdalal wants to merge 37 commits into
jeremybernstein:jb/html5-containerfrom
utkarshdalal:html5-runtime-review-fixes
Closed

utkarshdalal wants to merge 37 commits into
jeremybernstein:jb/html5-containerfrom
utkarshdalal:html5-runtime-review-fixes

Conversation

@utkarshdalal

@utkarshdalal utkarshdalal commented Nov 12, 2026 •

Copy link
Copy Markdown

Hey Jeremy, these came out of testing utkarshdalal#1570 on an Odin 3 with OMORI and reading through the branch. One commit per item, so take or drop them individually.

  • Move the CrashHandler fixes out. The three CrashHandler / CrashFingerprint commits are reverted here and opened unchanged, with you as author, as CrashHandler: install once and dispatch each crash once utkarshdalal/GameNative#2410 against master.
  • Submodule note in the README. The workflows already fetch the leveldb and snappy-java submodules, so only the build steps needed a git submodule update --init --recursive line.
  • Runtime routing off the main thread. resolveRuntime answers wine without reading any container config when there is no html5 container on disk. The game page, its menu options, Open Container, preLaunchApp and applyToContainerGated resolve it on IO. The game page re-resolves when the runtime changes; applyToContainerGated now emits the flip event on a first opt-in too.
  • reclaimWineStorage checks the runtime itself, so it is a no-op for a wine container whatever the caller.
  • R8 keep rules for snappy. Keeps Snappy$XerialSnappy, which leveldb loads by name, and SnappyNative's native methods plus throw_error, which the JNI side calls by name. IQ80Snappy is not kept because org.iq80.snappy is compile-only.
  • Config import keeps the runtime. A best-config map (import, server config, support suggestion) can no longer switch a container to or from html5; that stays with the opt-in and its fingerprint check. An imported html5 block now only carries user settings (input map, language, gestures, touch mode, overlay, render scale) onto this device's existing sidecar. The id, install path, engine/layout, fingerprint, controls profile and decrypt key stay local.
  • Reset to defaults keeps an html5 game html5. Reset now uses the html5 variant and runs the opt-in before writing the wine container, like applyGatedVariant. It carries over the decrypt key, the greenworks flag and the controls profile id, and runs on IO. Without the carry-over, OMORI's key would only come back on a launch where Steam has the launch arguments in memory.
  • No remote documents in the game WebView. Main-frame navigations away from the game's *.localhost origin are blocked; an http(s) link the player taps opens in the browser. Every html document the interceptors serve gets a CSP limiting frame-src / object-src / form-action to self, data: and blob:. That covers iframes, which never reach shouldOverrideUrlLoading for http(s). XHR, fetch, WebSocket and media are untouched, and nothing in the shims or packs loads a remote document.
  • Session telemetry. HTML5 sessions send game_exited with game name/store, runtime=webview, session length and session id. With usage analytics on, it also sends the engine pack, WebView package/version and whether the renderer died. Wine-only fields are left out. No fps: the HUD counter only runs while the HUD is on and keeps no session stats. The wine event gets runtime=wine. game_runtime_switched (usage analytics only) fires on an actual change, with trigger hint, container_dialog or opfs_unsupported.
  • On-screen controls start from the default wine layout. New html5 profiles copy their elements from the profile the wine path falls back to. The pack's gamepad->key synthesis is applied to the copied bindings, so electron keeps its keyboard mapping and rmmv its Start/Select keys. Elements the html5 path can't deliver are skipped, and the per-pack overlay assets are gone. Back already opens the quick menu, so there is no menu button.
  • No Controller tab for html5 in Edit Container. Both entries already live in the in-game quick menu, and the launch path creates the controls profile on first run.

Verified: :app:compileModernDebugKotlin passes. :app:testModernDebugUnitTest for app.gamenative.html5.*, app.gamenative.runtime.*, ContainerUtils*, the best-config/community/support-suggestion/optimize-lever tests and ContainerStorageManagerTest: 1256 tests, 0 failures, 9 skipped. That includes new tests for the import merge, the variant rule, the reset carry-over, the document-origin check and the layout seed.

Left to you: moving the submodule URLs under the org, rebasing onto master, and the PR description.

jeremybernstein and others added 30 commits November 12, 2026 08:47
Every PluviaApp boot wrapped the previous default handler, so the chain
grew per boot, and a failed crash-file save handed the crash to the next
handler before uncaughtException did again, doubling dispatch per link.
A single very long line makes some patterns backtrack quadratically;
onlyTheTailIsRead feeds one 256 KB line and ran for minutes.
…cratch

vendors iq80 leveldb 0.12 (Apache-2.0, github.com/dain/leveldb -- final release, unmaintained)
as the :iq80-leveldb gradle module. needed pure-Java because the IndexedDB rewrite uses a custom
Java comparator (idb_cmp1), which native leveldb JNI ports can't take.

sole patch vs upstream: Table.uncompressedScratch was a shared static ByteBuffer used as the snappy
decompression target, guarded in MMapTable/FileChannelTable.readBlock by synchronized(MMapTable.class)
/(FileChannelTable.class) -- different monitors over the same buffer. a reader thread and iq80's
background-compaction thread decompress into it concurrently → corrupted blocks → silently dropped
records under load. made it a per-thread ThreadLocal and dropped the now-useless class locks.

vendored as source (not a prebuilt jar / jitpack artifact) so it builds reproducibly from source.
see iq80-leveldb/NOTICE.md.
- iq80 leveldb 0.12 + snappy-java 1.1.10.8 for chromium localStorage transcode
- androidx.webkit 1.15.0 for WebView host
- AGP-strips-snappy-natives workaround: extract Linux/android-* .so from jar,
  relocate to lib/<abi>/, register as jniLibs srcDir
- FeatureGate.HTML5_RUNTIME flag -- single switch to gate the new path
…ound

WineRuntime vs WebViewRuntime split. Container.runtime defaults to wine
(back-compat). LibraryItem badge surfaces runtime. MainActivity / PluviaApp
suspend the active WebView on background to match Wine semantics
(isOverlayPaused flag covers menu-up-while-backgrounded case).
WebView-based runtime host with profile registry, asar handling,
shim infrastructure (common host-side JS), and pack abstraction layer.
Includes the case-insensitive fs bridge, leveldb health checks,
port-stripped URI handling, ZipAssetInterceptor with disk fallback,
Crashpad cleanup, uninstall hygiene, and storage-move sidecar
synchronization.
Engine detection (RPG Maker MV/MZ, Construct 2/3, Construct-on-NW.js,
GameMaker, Godot HTML5, NW.js, Electron, TyranoScript). Confidence
scoring with alternates and Candidate routing. Handles asar packaging,
sub-engine routing, NW.js single-exe bundles, unpacked package.nw
layouts, and Tyrano-on-Electron.
…ge ↔ gog fs

Bidirectional save sync between chromium WebView origin storage
(LocalStorage, IndexedDB blobs, OPFS) and the canonical wine save
locations under drive_c/users/. Steam UFS uses SteamCloud batch
protocol; GOG fs uses Heroic-compatible protocol; pack:nwjs Impact
storage adapter uses dual-write fs+leveldb. Includes leveldb-rewrite
v2.1 (idb_cmp1 + .ldb/.sst handling), opfs-mirror with BC-gated
worker hydration for cross-device restore, per-title forceMechanism
override, Crashpad/sync-file filter, and debug-menu Clear Steam Cloud
RPC for testing.
Html5InputBridge unifies controller/touch/keyboard routing into the
WebView. Gamepad emits W3C-standard 4 axes (no trigger entries) with
prototype-walk-safe button shim. Touchscreen-mode parity with master
QuickMenu. Kbd-on-gamepad swallow keeps Impact-engine input device
detection on gamepad. Process polyfill (execPath/__dirname/__filename)
and NW.js Node surface (events module, process.arch, module stub) for
require() compatibility.
Per-engine pack JSONs declare overrides (saves mechanism, shims,
patches, input spec); ProfileRegistry hoist applied cross-pack
defaults to host code so packs only carry overrides. Per-engine
shim JS handles engine-specific quirks (Impact storage adapter for
NW.js, RMMV plugin patches for Galv/Hime/Olivia/YEP, TyranoScript
tpatch overlay + bgmaudio race guard + measurement-based centering,
GMS canvas viewport cap, Electron AMD/UMD pollution unblock, etc.).
…ne Storage

- Library: html5 game badges, runtime-aware launch buttons, opt-in service
- Container config dialog: offers the html5 variant only when the install fingerprints as html5 (wine stays
  the default, nothing flips on its own); gates wine-only knobs for html5; adds gesture settings
- Launch re-fingerprints html5 containers when the install dir changes, so an update that swaps the engine is picked up
- Downloads & Storage: Reclaim Wine Storage action (surgical wipe of system dirs in drive_c, preserves saves)
- Settings: HUD config wiring, gesture config persistence, performance HUD additions
- PrefManager, AndroidEvent additions for html5 lifecycle signals
Html5Runtime runs html5 process setup on first html5 use (pre-launch
sync, WebView launch, a runtime flip), never at app start: Chromium
version gate, loopback port, leveldb health + crashpad cleanup (deferred
when another WebView already ran this session), save-sync subscription.
LevelDbRewriter sets snappy-java use.systemlib before any snappy class
loads. SteamService exposes steamCloudHandler() for the savesync
GreenworksCloudClient. WebViewContainer + runtime tests cover container
JSON round-trip and dispatch.
structural cleanups to the pack/engine/runtime plumbing -- no behavior change
(modern + legacy unit tests + full assemble green). five threads:

- declarative pack-shim registration: placement moves into the pack JSON
  (packShimPlacement: none/append/prepend); shim id+asset+url derived by
  convention (pack:foo -> html5/shims/packs/foo.js). the five per-pack if-blocks
  in resolveShimUrls collapse to one generic block. ProfileSchemaTest gains a
  disk-backed guard loading the shipped pack JSONs through the real resolver.

- ShimBundles convention: deriveShimPath also covers base shims
  (<id> -> html5/shims/<id>.js), dropping 28 const-triplets + map entries; only
  irregular ids (steamworks-noop->steamworks.js, nw-noop, greenworks-noop,
  js-yaml.min.js) keep explicit entries. ShimBundlesConventionTest locks it.

- typed engine-pack ids: EnginePackId consts replace scattered "pack:X" string
  literals (signatures + host/savesync comparisons) so a typo is a compile error.

- centralized container-id prefixes: GameSource owns the prefix scheme
  (containerPrefix + matches/idOf/fromContainerId/idPart); the hand-rolled
  appId.startsWith("STEAM_") / removePrefix calls across services + save-sync +
  install + ContainerUtils route through it -- the prefix strings live once.

- declarative viewport: EngineProfile.wideViewport (c3 + electron) replaces the
  per-engine useWideViewPort/loadWithOverviewMode string checks in WebViewScreen.

a new pack now touches ~one place: the EngineSignature object + packs/<id>.json
(+ shim JS if any); ShimBundles/resolveShimUrls need no edits.
covers html5/webview, save-sync, perf-hud, render-scale, reclaim-storage,
and debug cloud strings added by this branch. format specifiers (%n$x) and
%% literals preserved, apostrophes escaped per aapt2, brand/tech terms
(HTML5/WebView/Chromium/Wine/Steam/etc.) left untranslated.
terra-engine shaders exceed the vendor GLES 256-vector vertex uniform cap;
the android ANGLE override (ANGLE-on-Vulkan, cap 1024) is the only unblock.
suggest it via snackbar when launching a terra title without it -- gated to
WebView >= 118 (passthrough-decoder default flip, ui/gl/gl_features.cc
bisect; below that the override is inert, device-confirmed on WV109).
…inary

the *.log gitignore rule silently dropped leveldb write-ahead logs (000003.log)
-- the actual IndexedDB/LocalStorage records. fixtures parsed locally (files left
from capture) but a fresh CI checkout got them empty -> 0 keys -> 5 savesync tests
failed only on CI. force-add the 4 data files, negate *.log under leveldb fixture
dirs, and mark the fixture tree binary so EOL normalization can't corrupt CURRENT.
godot web (emscripten single-threaded) runs quit/teardown synchronously
on the renderer's only thread, then the canvas wedges permanently --
process doesn't die so onRenderProcessGone never fires and the user is
stuck on a dead frame. detect Main::cleanup()'s 'at exit' shutdown burst
in the console (nondeterministic which line flushes before the wedge, so
match the shared 'at exit' substring) and navigateBack to library, which
runs the existing teardown + outbound save-sync.
…PI channels

source language from the wine Container (the container-config dialog's source of
truth) instead of the WebViewContainer sidecar, which never carried it and silently
defaulted to english. fixes both navigator.language and the new Steam getCurrentGame-
Language / getCurrentUILanguage bridge (greenworks.js + steamworks.js). adds resolver
bcp47->goldberg inverse map + tests.
…ot / offline)

OMORI's AES decrypt key is a Steam launch arg (--<32hex>) that PICS only caches in-memory,
so a cold boot / offline launch had no key and .OMORI/.KEL passed through as ciphertext
(needed Steam contacted once per session). persist it on the html5 container instead:

- WebViewContainer gains a non-user-facing decryptionKey field (no config UI surfaces it,
  unlike wine's execArgs -- a --<32hex> blob can't be mistaken for garbage and cleared).
- loadByAppId seeds it write-once from the live PICS arg (without the transient language
  field, which is re-derived from wine each launch and not persisted).
- Html5PackSetup reads container.decryptionKey for both the AES key and nw.App.argv;
  drops the now-dead appId param from rememberHtml5PackSetup.

storing it on the container avoids a Room schema / parse-version bump and keeps it per-install.
back-compat: absent key decodes to "".
…ldb scratch

rmmv saves via Node fs only when our shim wins the StorageManager.isLocalMode
override (Utils.isNwjs is kept false so YEP_CoreEngine.initNwjs survives). a build
where the override misses -- web build, late/replaced StorageManager, RMMZ forage
-- saves to chromium leveldb instead. so the substrate can't be pinned statically
per pack or per title without shipping a release for every new title.

route at runtime: fs.js calls __gnFsBridge.markFsSaveMode() the instant it forces
isLocalMode=true, marking the container fs-authoritative at boot, BEFORE the first
write. the first sync boundary then reroutes to FsBridge and never uploads chromium
scratch. titles that never confirm local-mode keep the leveldb sync. self-selecting,
zero per-title config. (the lazy marker only tripped on the first fs write, so a
boot-scratch-then-exit session uploaded leveldb -- the original Look Outside leak.)

on the fsbridge outbound reroute, scrub the wine-side chromium leveldb staging
(Local Storage/leveldb, IndexedDB/<origin>.indexeddb.{leveldb,blob}) so prior or
degenerate-session scratch is tombstoned by the next UFS pass and can't be re-pulled
on a future misclassify. the resolver always builds these as leaf dirs distinct from
userDataRoot, so .rpgsave is never touched (guarded by a safety-invariant test).

also correct the stale "fsbridge is the universal default" comments: leveldb is the
static default; fs routing is the runtime decision.
…me flag

CrossCode saves to cc.save (fs) -- its chromium-LS is empty on both stores, so the
old "dual-write" rationale was wrong. but the chromium profile still matters on GOG:
GOG/Galaxy cloud mirrors the WHOLE chromium User Data dir (Sync Data, Web Data, Local
Storage, ...), so if the device scrubs the leveldb it churns against the PC (device
deletes -> PC re-uploads). keep the profile syncing on GOG_1252295864 for parity.

Steam CrossCode (STEAM_368340) syncs ONLY cc.save -- no chromium profile in its UFS
patterns -- so it rides the fs-authoritative fsbridge reroute like any fs title.

rename the confusing bypassFsBridgeReroute flag to syncChromiumProfile: same polarity
(true = keep the profile syncing), names the effect instead of the plumbing.
…ixes

The fix commits underneath this branch are the runtime-neutral halves of fixes
this work surfaced; they are split out for separate review and merge. This adds
what HTML5 needs on top of them:

- SteamService: steamCloudHandler() for GreenworksCloudClient,
  getLaunchArgumentsForOs, fetchUserStatsForApp for Html5AchievementSeed, and
  the chromiumProfileSync parameter on the sync and closeApp paths
- GOGCloudSavesManager / GOGService: the chromium-internal denylist call and
  mirror-delete, both gated on chromiumProfileSync so the Wine path is unchanged
- InputControlsView: Html5BindingSink plus the touchpadView/xServer null guards
  the WebView path needs, since neither exists there
- on-screen sticks send a zero axis value as a release instead of a press. The
  HTML5 sink reads a press with offset 0 as a digital tap (full deflection), so
  a stick held near centre stuck at full down/left. On Wine the axis is 0 either
  way.

Keeping these separate means the base commits can merge upstream on their own,
after which this branch rebases and they drop out by patch-id.
These three commits are unrelated to the HTML5 runtime and are proposed
separately against master.
resolveRuntime returns wine without reading any container config when no
html5 container exists. The game page, its menu options, Open Container,
preLaunchApp and applyToContainerGated now resolve the runtime on IO; the
game page re-resolves it when applyToContainerGated reports a runtime
change, which now includes a first opt-in.
The wipe of drive_c/windows and Program Files was only guarded by the
storage dialog; it now checks the container's runtime before deleting.
A best-config map (import, server config, support suggestion) no longer
switches a container to or from the html5 variant; that stays with the
opt-in path and its fingerprint check. An imported html5 block now only
carries user settings onto this device's existing sidecar, keeping its
id, install path and layout, fingerprint, controls profile and decrypt
key; without a local sidecar it is dropped.
Utkarsh Dalal added 5 commits November 12, 2026 20:38
Reset applied the global defaults, whose variant is never html5, so the
game flipped to wine outside applyToContainerGated and then got a fresh
html5 sidecar anyway. An html5 game now resets with the html5 variant,
re-runs the opt-in before the wine container is written, and keeps the
decrypt key, the greenworks save route and the controls profile. The
reset runs on IO.
The JS bridges are exposed to every frame, so a document from outside the
game's loopback origin must never load. Main-frame navigations elsewhere
are blocked; an http(s) link the player taps opens in the browser.
Every html document the interceptors serve carries a CSP limiting frames,
objects and form targets to the game origin, data: and blob:, which covers
subframes that never reach shouldOverrideUrlLoading. XHR, fetch,
WebSocket and media requests are unchanged.
An html5 session now sends game_exited when its screen tears down, with
the game identity, runtime, session length and session id like the wine
event, plus the engine pack, system WebView package and version and
whether the renderer died when usage analytics is on. Wine-only fields
are left out. The wine game_exited gains runtime=wine.

game_runtime_switched (usage analytics only) fires when the runtime
actually changes: the game-page hint, the container dialog, or the
launch falling back to wine without OPFS support.
A new html5 controls profile now copies its on-screen elements from the
profile the wine path falls back to, so the layout looks the same in both
runtimes. The pack's gamepad->key synthesis is applied to the copied
bindings, as it already is for the physical controller, which keeps
electron's keyboard mapping and rmmv's Start/Select keys. Elements the
html5 input path can't deliver are left out. The per-pack overlay assets
are gone; back still opens the quick menu, so no extra menu button.
…5 games

Its two entries, physical controller mapping and touch gestures, are in
the in-game quick menu for html5 sessions exactly as for wine, and the
launch path already creates the controls profile on first run. Removes
the composables, the edited-state flag only the tab set, and their
strings in every locale.
@coderabbitai

coderabbitai Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: a2ebbbf1-2765-4ba9-bf89-a7f943717988

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Utkarsh Dalal added 2 commits November 12, 2026 20:52
… itself

Robolectric tests run on a bare Application, so the html5-containers root
was empty and every opt-in fixture failed to write its sidecar.
@utkarshdalal
utkarshdalal marked this pull request as ready for review November 12, 2026 15:27
@jeremybernstein

Copy link
Copy Markdown
Owner

thank you, merged

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants