From 03b3aa0cfaa22b53c8a554e93965378bb96d77a2 Mon Sep 17 00:00:00 2001
From: Yumeng Xiao <yumeng.xiao@outlook.com>
Date: Mon, 18 May 2026 11:33:42 -0400
Subject: [PATCH] HTML5: document host-set Module opt-outs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

dmloader.js now respects six host-set properties on the global
Module object when they're declared before <script src="dmloader.js">
loads (defold/defold#12396). Document the full surface — pthread,
WebGL2, context attrs, extension filter, button strip, context-loss
recovery — in the HTML5 manual under a new "Host-set Module
properties" subsection, between Engine arguments and Query
arguments. Includes the example shape, the per-property reference
table, and the two important notes (let-vs-var binding, strict
sentinel checks).
---
 docs/en/manuals/html5.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docs/en/manuals/html5.md b/docs/en/manuals/html5.md
index ed1f0ed9..7979a980 100644
--- a/docs/en/manuals/html5.md
+++ b/docs/en/manuals/html5.md
@@ -284,6 +284,44 @@ print(foo2) -- bar2
 ```
 
 
+### Host-set Module properties
+
+Embedding hosts can fine-tune the loader's behaviour by pre-setting properties on the global `Module` object *before* the `<script src="dmloader.js">` tag runs. This is the standard Emscripten pattern; `dmloader.js` captures each host-set value before its own `var Module = {...}` redefinition discards the global. Default behaviour is byte-identical when nothing is pre-set.
+
+```html
+<script>
+var Module = {
+    isWASMPthreadSupported: false,
+    isWebGL2Supported: false,
+    webGLContextAttributes: { preserveDrawingBuffer: true },
+    webGLExtensionFilter: function (name) {
+        return name.toLowerCase().includes("compressed_texture");
+    },
+    showButtonStrip: false,
+    autoReloadOnWebGLContextRestore: true
+};
+</script>
+<script src="dmloader.js"></script>
+```
+
+| Property | Type | Effect |
+| --- | --- | --- |
+| `isWASMPthreadSupported` | `=== false` | Force the single-threaded WASM variant. Useful when the page passes the `crossOriginIsolated` + `SharedArrayBuffer` probe but still can't construct same-origin Workers (e.g. a WebView wrapper serving the bundle from a custom URL scheme — Chromium rejects `new Worker('myscheme://...')` with `SecurityError: cannot be accessed from origin 'null'`). |
+| `isWebGL2Supported` | `=== false` | Downgrade `getContext('webgl2')` to `'webgl'`. Useful when the embedded GLES driver advertises WebGL2 but trips inside the engine's VAO / instancing init. |
+| `webGLContextAttributes` | `Object` | Merged (`Object.assign`) into the attrs argument of the WebGL context creation. Notably useful for forcing `preserveDrawingBuffer:true` when the host compositor is flaky and `eglSwapBuffers` may fail between renders. |
+| `webGLExtensionFilter` | `(name) => boolean` | Strip names from `getSupportedExtensions` / `getExtension`. Returning `true` for a name removes it. Useful when the driver falsely advertises compressed-texture / float-texture / depth-texture extensions then rejects the actual upload. |
+| `showButtonStrip` | `=== false` | Hide the engine_template footer (`.buttons-background`). [project setting]`html5.show_fullscreen_button = 0` + `html5.show_made_with_defold = 0` suppresses the inner anchors but leaves a 42 px white bar behind; this opt-out finishes the job for hosts that want a true-fullscreen canvas. |
+| `autoReloadOnWebGLContextRestore` | `=== true` | Attach `webglcontextlost` / `webglcontextrestored` listeners to the canvas. `preventDefault()` on lost asks the browser to restore; on restored, `location.reload()` so the engine boots cleanly. The player lands on the title screen and resumes from autosave. |
+
+::: important
+Use a `var` declaration or `window.Module = {...}`. Top-level `let Module = ...` creates a script-scoped binding that the loader's global `var Module` can't see — the host-set values will be invisible to the captures.
+:::
+
+::: important
+The checks are strict — only the literal sentinel triggers the opt-out (`=== false` for the booleans, `=== true` for `autoReloadOnWebGLContextRestore`, a `function` typeof for the filter, a truthy object for the attrs). Truthy/falsy values like `0`, `null`, `""`, or `undefined` are ignored.
+:::
+
+
 ### Query arguments in the URL
 
 You can pass arguments as part of the query parameters in the page URL and read these at runtime: