Embed the LineSweeper bundle
LineSweeper can run inside a page you own. Build Labrador with wasm-release, then take the
folder out/build/wasm-release/web-dist/linesweeper/. Its index.html is a working host you
can serve as it is, or replace with your own page. This guide is the public contract of that
bundle; Build for the browser
describes the same canvas and callbacks for your own game’s module.
Build the bundle
Section titled “Build the bundle”The bundle is built with the engine, by the engine’s own wasm-release preset, so it needs
Emscripten as Build for the browser installs it, and
an x64 Native Tools Command Prompt where emsdk_env.bat has run:
C:\dev\emsdk\emsdk_env.bat-
Go to the engine’s folder. For a Git clone of Labrador, made as Build Labrador shows:
Terminal window cd /d C:\dev\LabradorA starter project has the engine in
external\labrador, and builds the bundle there too:Terminal window cd /d C:\dev\mygame\external\labradorbut that copy has no
.gitfolder, so its bundle records its commit asunknown, and the check in Check the bundle refuses it. It plays the same, and is fine for trying a host page on your own machine. A bundle you put on a site should come from a Git clone, whose check names the exact commit it was built from. -
Configure and build
wasm-release:Terminal window cmake --preset wasm-releasecmake --build --preset wasm-releaseThe configure prints a
CMake Warningthat this version of CMakedoes not support emscripten shared librariesthree times, which does not matter here, as in Build for the browser, and ends:Output -- Configuring done (7.5s)-- Generating done (0.3s)-- Build files have been written to: C:/dev/mygame/external/labrador/out/build/wasm-releasewith
C:/dev/Labrador/out/build/wasm-releasein a clone. If it stops withinclude could not find requested file:,emsdk_env.bathas not run in this prompt: run the line above the steps, then configure again.The build has 296 steps and builds the engine, every sample and their tests. On a fast desktop with Emscripten’s libraries already built, the configure took 10 seconds and the build about 40; a first configure on a new machine can take up to a quarter of an hour, as Build for the browser says. The folder
out\build\wasm-releasetakes 33 MB. One step of the build is the bundle, which prints each file with its size raw and under Brotli, and the commit:Output [261/296] Bundling LineSweeper for a host pageNOTICE.txt 104616 bytes, 13037 under Brotliindex.html 18145 bytes, 5136 under Brotlilinesweeper.js 120545 bytes, 27753 under Brotlilinesweeper.wasm 426100 bytes, 132288 under Brotliposter.png 15063 bytes, 10896 under Brotlifrom 7ae6dbe3278f44ce7dc23b8b72237b82b7c2feffThe step number and the commit differ from build to build.
from unknownis the starter project’s copy, andwith uncommitted changesafter the commit means the clone has changes that commit does not hold.ctest --preset wasm-releasethen runs the engine’s tests in the browser build, one of which loads this bundle’s page, plays it and quits it; it needs a Chromium browser, as Run the samples says. -
Copy it to a folder of your own. The build empties
out\build\wasm-release\web-dist\linesweeperand writes it again on every build, so anything you add there, such as a host page, is deleted by the next one. Copy the six files out:Terminal window if exist C:\dev\ls-host rmdir /s /q C:\dev\ls-hostxcopy out\build\wasm-release\web-dist\linesweeper C:\dev\ls-host\ /E /I /QThe first line deletes the copy you made last time, if there is one; check the path before you run it.
xcopyprints6 File(s) copied. Work on your host page inC:\dev\ls-host, and run these two lines again to take a newer build.
In an iframe
Section titled “In an iframe”An iframe may load the bundle’s example page from another origin. Keyboard input reaches it after a click into the game; the Play button supplies that click. Focus moving to the embedding page pauses LineSweeper, and clicking its canvas gives the game the keyboard again. Without fullscreen delegation the example hides its Full screen button. A host that wants to offer it can use:
<iframe title="LineSweeper" src="https://your-game.example/linesweeper/" width="960" height="720" allow="fullscreen; gamepad; autoplay"></iframe>The host’s Permissions Policy can impose further restrictions. Those tokens do not grant a connected pad, audible playback or automatic fullscreen; fullscreen still starts from the page’s button click. The maintained Chromium regression checks two local origins, including host/frame focus, quit/replay and loader-failure recovery. It does not qualify an external hosting service, Firefox/Safari iframe behavior, real pads or headed fullscreen/Escape. Keep saved data’s origin and browser partitioning in mind if a game adds storage; LineSweeper saves nothing. An itch.io guide and precompressed bundle output remain outside this checked route.
The factory
Section titled “The factory”createLineSweeper is the default ES-module export of linesweeper.js. Import that default,
then call it with the instance’s Module options. The call creates a fresh game instance and
returns a promise for its initialized module. It does not wait for the game to quit. The loader
fetches linesweeper.wasm from beside linesweeper.js, so keep the two together.
Module.canvas is required: pass the actual canvas element, already attached to the page.
Give it a CSS size, tabindex="0" so it can take keyboard focus, and touch-action: none so
touching the game does not scroll the page. The engine sizes the drawing buffer to that CSS box
and the device pixel ratio. Focus the canvas when play starts.
The four callbacks are optional. Their names are exact and case sensitive: a misspelling
produces no warning, and a value that is not a function is ignored. They are read from the
instance’s Module when due.
| Callback | When the instance calls it |
|---|---|
onQuit() |
The game quits, after its frame loop is cancelled and its window’s input and page listeners are removed. The instance releases its states, audio and graphics on a later task. LineSweeper reaches this through the pause menu’s QUIT row. |
onError(message) |
The entry point reports a startup exception, or a frame or input handler fails. message is a string also written to the console. A caught frame or input failure stops the loop and window listeners before the callback. |
onContextLost() |
At the first begin_frame that observes a lost WebGL2 context, once per loss. The canvas is blank while graphics are unavailable. |
onContextRestored() |
At begin_frame, after the renderer and game resources are rebuilt, so that frame can draw again. Loss is reported first even if both browser events arrive between frames. |
Catch import and factory-promise failures as well: a missing script, failed fetch or WebAssembly
compilation failure can happen before the engine can call onError. A startup callback can run
before the factory promise settles. Context restoration has no deadline; keep a loss message
visible until restoration or a new page load.
A host page to copy
Section titled “A host page to copy”Save this as host.html in C:\dev\ls-host, beside the bundle’s files from
Copy it to a folder of your own, not in the build folder, which the next
build empties. These two lines make the empty file, if it is not there yet, and open it:
if not exist C:\dev\ls-host\host.html type nul > C:\dev\ls-host\host.htmlnotepad C:\dev\ls-host\host.htmlPaste the HTML at the end of this section into Notepad, then save and close it. Then serve that
folder over HTTP with the Python that came with Emscripten, from the prompt where
emsdk_env.bat ran:
start "LineSweeper server" "%EMSDK_PYTHON%" -m http.server 8000 --bind 127.0.0.1 --directory C:\dev\ls-hostand open http://127.0.0.1:8000/host.html. The page shows a Play LineSweeper button, the
status line and a Third-party notices link; the server’s window, its messages and how to stop
it are as in Serve it and open it. Play imports
the loader on the first click and starts each game on a fresh canvas. Escape opens the pause menu; choose QUIT to
return to the page. The example is for desktop keyboard play; the bundle’s supplied index.html
also has a poster, controls, accessibility information and the current phone gate.
<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>My LineSweeper host</title><style> #stage { width: min(100%, 1280px); aspect-ratio: 16 / 9; } canvas { display: block; width: 100%; height: 100%; touch-action: none; }</style><button id="play">Play LineSweeper</button><p id="status" role="status">Escape opens the pause menu; choose QUIT to finish.</p><div id="stage"></div><p><a href="./NOTICE.txt">Third-party notices</a></p><script type="module"> const play = document.getElementById('play'); const status = document.getElementById('status'); const stage = document.getElementById('stage'); let createLineSweeper;
play.addEventListener('click', async () => { play.disabled = true; status.textContent = 'Loading LineSweeper…'; let canvas; let ended = false; const finish = (message) => { ended = true; canvas?.remove(); status.textContent = message; play.disabled = false; play.textContent = 'Play again'; play.focus(); }; try { createLineSweeper ??= (await import('./linesweeper.js')).default; canvas = document.createElement('canvas'); canvas.tabIndex = 0; canvas.setAttribute('aria-label', 'LineSweeper'); canvas.addEventListener('contextmenu', (event) => event.preventDefault()); stage.append(canvas); canvas.focus(); await createLineSweeper({ canvas, onQuit: () => finish('Thanks for playing.'), onError: (message) => finish('LineSweeper stopped: ' + message), onContextLost: () => { status.textContent = 'Graphics are unavailable; waiting for restoration.'; }, onContextRestored: () => { status.textContent = 'Escape opens the pause menu; choose QUIT to finish.'; }, }); if (!ended) { status.textContent = 'Escape opens the pause menu; choose QUIT to finish.'; canvas.focus(); } } catch (error) { finish('LineSweeper could not start: ' + String(error)); } });</script></html>A running instance stops through its own quit. The instance the factory resolves has
_linesweeper_quit(), which makes the same quit as the pause menu’s QUIT row: onQuit follows
synchronously, before the call returns. Nothing else stops it. Removing its canvas or changing Module.canvas leaves its
loop and listeners running. Keep that canvas attached until onQuit, or the stopped game’s
onError, then remove it. Quit stops the loop and listeners, and on a later task the static
Application destroys its states and releases its services, Web Audio and the WebGL2 context
included. Play again uses a new factory call and a new canvas; dropping the old canvas lets the
finished instance be collected. Importing the loader can be reused. See the
complete example host
for the bundle’s presentation and failure UI.
Files and build record
Section titled “Files and build record”The bundle contains these six files. Copy them together, including the full notices.
| File | Purpose |
|---|---|
linesweeper.js |
The ES-module loader and default factory export. |
linesweeper.wasm |
The engine, game and embedded content. |
index.html |
The example host page, with Play and Play again. |
poster.png |
The example page’s game poster. |
NOTICE.txt |
Attribution and full licence texts for the engine, content and linked toolchain libraries. Keep its link on your host page. |
BUILD.json |
The bundle’s source identity, supplied build type, toolchain version and file measurements. |
BUILD.json has the following fields:
| Field | Meaning |
|---|---|
commit |
The full Git revision at packaging time, or unknown if the source checkout cannot be identified. |
dirty |
true for tracked local changes, false for a clean checkout, or null if Git identity is unavailable. Untracked and ignored files do not affect it. |
build_type |
The build type CMake supplied, such as Release or Debug. |
emscripten |
The version read from the Emscripten install that bundles the game. |
files |
An object keyed by each bundled file’s name, excluding BUILD.json itself. Each entry has bytes (raw size), brotli (size compressed at Brotli quality 11) and sha256 (the file’s SHA-256). These are measurements; no compressed copies are included. |
This record describes the checkout when packaging runs; it cannot prove the sources or flags used by an older module. Build immediately before packaging, check the record and preserve it with the release. A dirty or Debug bundle is for development.
Check the bundle
Section titled “Check the bundle”Before copying a LineSweeper bundle to a host, check it. Run this from the Labrador clone’s
folder, C:\dev\Labrador, in the prompt where you loaded Emscripten’s environment:
"%EMSDK_NODE%" tools\web_bundle\bundle.mjs --verify out\build\wasm-release\web-dist\linesweeperThe check reads the folder without changing it, and takes under a second. A bundle that passes prints one line, with the commit it was built from:
Verified clean Release LineSweeper bundle from 7ae6dbe3278f44ce7dc23b8b72237b82b7c2feffCompare that commit with the one you mean to put on the site. The commit the clone is at now is what this prints:
git rev-parse HEADIf they differ, the clone has moved since the bundle was built: build again, then check again.
To check the copy you will upload instead, give its folder, C:\dev\ls-host, in place of the
build folder. It passes until you add host.html to it; then the check reports that file, as
below, and a host page of your own belongs beside the copy you upload, not inside the folder you
check.
A bundle that fails prints bundle: verification failed: and the rule it broke, and nothing
after it:
| The rest of the line | What it means, and what to do |
|---|---|
commit must be a full Git revision, not unknown |
The engine it was built from has no .git folder, as in a starter project’s external\labrador. Build it from a Git clone. |
dirty must be false |
The clone had changes that its commit does not hold when the bundle was built; the build printed with uncommitted changes. Commit them, or undo them with git restore ., and build again. |
build_type must be Release |
The folder is from a Debug build, such as wasm-debug’s. Build wasm-release and check its folder. |
unrecorded bundle entry: host.html |
The folder has a file the bundle did not write, here a host page saved into it. Check the build folder, or a copy without your own files. |
index.html: SHA-256 does not match BUILD.json |
A file was changed after the build, here index.html. Build again rather than editing the bundle’s files. |
ENOENT: no such file or directory, lstat '...\BUILD.json' |
There is no bundle at that path: a misspelt folder, or a preset that was never built. |
Error: Cannot find module 'C:\dev\tools\web_bundle\bundle.mjs', with a list of Node’s own
files under it, means the prompt is not in the clone’s folder: run cd /d C:\dev\Labrador first.
The port record, section 7.1
states every verification rule and its provenance limits. Verification does not upload the bundle.
What the host sends
Section titled “What the host sends”Follow Put your game on a web host for MIME types, compression, CSP and
caching. LineSweeper has the same requirements: serve .wasm as application/wasm, use HTTP or
HTTPS, and include 'wasm-unsafe-eval' if you set a script-src Content Security Policy. This
single-threaded bundle needs no COOP or COEP headers. The example’s inline module also needs the
policy’s allowance for that script.
For long caching, put linesweeper.js and linesweeper.wasm together in a folder named for
their content hash, change the import to that folder, and serve them with
Cache-Control: public, max-age=31536000, immutable. Serve the host page with no-cache, so a
new build points to a new folder. Keep the notices and build record with the release. The
hosting guide’s caching rules explain the revalidation alternative.
What has been checked
Section titled “What has been checked”On 31 October 2026, wasm-release was configured and built as Build the bundle
says, with Emscripten 6.0.12, in a local Git clone of this repository at its last commit and in
the external\labrador of a starter project made from a starter ZIP of this tree; the bundle
step printed the lines quoted, from unknown in the starter. The check passed in the clone and
gave the commit message in the starter. The copy with xcopy printed 6 File(s) copied, and
the copy passed the check until host.html was saved in it. host.html saved in the build
folder was gone after the next build. An empty line added to the clone’s README.md gave
with uncommitted changes and dirty must be false, and undoing it and building again passed.
The missing-module and ENOENT messages were made in the wrong folder and with an unbuilt
preset; the build_type and SHA-256 rows are the tool’s own messages, which its tests check.
C:\dev\ls-host was served with Emscripten’s Python: host.html, linesweeper.js,
linesweeper.wasm (as application/wasm) and NOTICE.txt were each fetched with a 200, and
headless Edge showed the Play button, the status line and the notices link. The game was not
played from that copy on that day.
A second agent then followed the page as worded, in a fresh starter’s external\labrador and in
a local Git clone at the same commit. Configure took 8 seconds and the build 33, the bundle’s
file sizes matched those quoted, the starter’s bundle was refused with commit must be a full Git revision, not unknown, and the clone’s passed with the commit git rev-parse HEAD printed.
xcopy’s count, the unrecorded bundle entry: host.html refusal, the emptied build folder, the
dirty case and its recovery, and the missing-module and ENOENT messages matched, and every file
of the served copy returned 200. It found that this section named no command to make and open
host.html, and Notepad asks whether to create a file that is not there; the two lines above
were added, and run in an empty folder, where they made an empty host.html and, run again,
left it as it was. It did not play the game from host.html either, or run
ctest --preset wasm-release.
A review in a third fresh starter’s external\labrador repeated the configure, build, check and
copy: the configure printed the shared-libraries warning three times and the last lines quoted,
the build ran 296 steps with the bundle’s lines and from unknown, the check refused it with the
commit’s rule, xcopy printed 6 File(s) copied, and the build folder took 33 MB. The same
configure in a prompt where emsdk_env.bat had not run stopped with include could not find requested file:.
On 28 October 2026 the HTML example above was saved outside the engine checkout, beside a
locally built Release loader and module. Headless Chrome loaded it over HTTP, drew the game,
quit through the pause menu to onQuit, and started and quit a second instance on a fresh
canvas, with no console errors or warnings. This verifies the host example locally; it is not
a deployment, Safari, physical-controller or real-phone check. The bundle’s phone gate remains
in place until the recorded iPhone and host-layout acceptance is complete.
Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.