---
paths:
  - "Modules/Blacklight/WebGL2/**"
  - "Modules/Blacklight/Testbed/WebGL2/**"
  - "Modules/Glass/Glass.Testbed/WebGL2/**"
---

# WASM/browser projects

Applies to `Blacklight.WebGL2`, `ShaderTranspiler`, `Blacklight.WebGL2.Testbed` and `Glass.Testbed.WebGL2`. They
build through `build.py` like everything else, but their live dev server (`.claude\launch.json`) runs `dotnet watch
run --non-interactive` directly.

## Run `dotnet` from the project's own directory

Never run a bare `dotnet` command from the repo root. The SDK pin (`global.json`) resolves from the working directory
upward only, there's none at the repo root, and this machine has several SDKs. From the root, `dotnet` silently picks
the newest SDK instead of the project's. `.claude\launch.json` shows the pattern.

## `dotnet watch`

- `--non-interactive` is required. Without it, an edit that edit-and-continue can't patch (a "rude edit", such as a
  `const` initializer) waits forever on a `y/n/a/v` prompt nobody can answer. With it, a rude edit restarts the app.
- A C# method-body edit patches in place with no refresh. An edit in `Program.Main()` warns, but still lands, since
  dotnet-watch refreshes the page and reruns `Main` (about 6s).
- A JS edit in `wwwroot` triggers no reload at all, so refresh by hand. The WebGL2 interop `.js` first needs a
  Release rebuild of `Blacklight.WebGL2` before its copy in `wwwroot` changes.
- In a testbed, prefer `static readonly` to `const` for anything tuned live, since changing a `const` is a rude edit.

## AOT and the trimmer only run on Publish

`Microsoft.NET.Sdk.WebAssembly` AOT-compiles only during `dotnet publish`, never during build, run or `dotnet watch`.
Those run the Mono interpreter, an order of magnitude slower.

The testbeds set `RunAOTCompilation` only while publishing, on purpose. It forces a native relink that adds about 35s
to every Release build, even one where nothing changed. Gate it on `'$(_IsPublishing)' == 'true' or
'$(WasmBuildingForNestedPublish)' == 'true'`.

For a real AOT build, run `python -u Scripts/build.py --command publish --project <Name> --configuration release
--no-interactive`. Publishing the WASM app takes several minutes. The output lands in
`Junk\<Name>\<configuration>\publish\wwwroot`. Serve it with a static HTTP server (not `file://`, and not `dotnet
watch run`, which is always interpreted) to measure AOT performance.

## Screenshots

The browser testbeds are the exception to "don't screenshot a GUI": they render in the Browser pane, where a
screenshot is of that page.