# Examples/Web — raylib-cs in the browser (WebAssembly)

A small browser app that runs raylib examples in the browser via WebAssembly, with a dropdown to
switch between them. It exists to **prove the `Raylib-cs` NuGet package's `browser-wasm` support
works end-to-end**: the package's `buildTransitive/Raylib-cs.targets` automatically links the
shipped `runtimes/browser-wasm/native/raylib.a` (and adds `-sUSE_GLFW=3`) into the .NET wasm
runtime. The browser host lives in `Examples/Web`, while `Examples.csproj` remains the single
examples project.

The browser-wasm configuration is enabled only when publishing `Examples` with
`RuntimeIdentifier=browser-wasm`, so normal solution builds do not require the `wasm-tools`
workload.

## Prerequisites

- .NET 10 SDK
- `dotnet workload install wasm-tools`
- The `Raylib-cs` package matching `$(RaylibCsVersion)` (see `Directory.Build.props`) — from
  nuget.org, or built locally into the repo's `./nuget` feed (`dotnet pack Raylib-cs -c Release --output nuget`).

## Build

```bash
dotnet publish Examples -f net10.0 -r browser-wasm -c Release
# -> Examples/bin/Release/net10.0/browser-wasm/AppBundle/
```

### Toolchain caveat

If the link step fails with:

```
wasm-opt: Unknown option '--enable-bulk-memory-opt'
```

your installed `wasm-tools` workload (Binaryen) is out of sync with the SDK — emscripten passes a
feature flag the bundled `wasm-opt` doesn't understand (commonly caused by a stale workload band
or a conflicting system EMSDK on PATH/`$EMSDK`). Proper fix:

```bash
dotnet workload update
```

`Examples.csproj` defaults browser-wasm publishes to unoptimized native linking so the standard
publish command works on affected local toolchains. A fully optimized publish can override those
MSBuild properties after updating the workload/toolchain.

## Run

WebAssembly must be served over HTTP (not `file://`):

```bash
dotnet serve -d Examples/bin/Release/net10.0/browser-wasm/AppBundle    # dotnet tool install -g dotnet-serve
# or:  npx http-server Examples/bin/Release/net10.0/browser-wasm/AppBundle
```

Open the printed URL and use the **Example** dropdown to switch examples.

## Canvas scaling modes

The browser host keeps raylib's internal render buffer fixed to `800x450` and applies display
scaling in CSS. Use the **Scale** dropdown (or `?scale=` query param) to choose behavior:

- `native` (default): exact `800x450` CSS pixels (1x), no resizing.
- `integer`: largest whole-number multiple that fits the viewport, centered with letterboxing.
  Best for pixel-perfect presentation.
- `fit`: fills available viewport while preserving aspect ratio (can be fractional, less crisp on
  some DPI/zoom combinations).

Scaling is computed in **device pixels first** and then converted back to CSS pixels using current
`devicePixelRatio`, which decouples the modes from needing a specific browser zoom level on
125%/150% OS scale displays.

`main.js` also shows runtime diagnostics in the status bar (`DPR`, CSS size, backing size, scale)
to help debug OS scaling / browser zoom behavior across monitors.

### Manual validation matrix (expected behavior)

- OS scale `100%`, browser zoom `100%`: `integer` should appear crisp and stable (`Scale 1.00` or
  higher if viewport allows).
- OS scale `125%` and `150%`, browser zoom `100%`: `integer` should stay crisp (no subpixel CSS
  scaling); perceived physical size changes with OS scale are expected.
- Browser zoom `80%`, `100%`, `125%`: `integer` should continue using whole-number scaling;
  `fit` may show softening at non-integer effective scales.
- `native` mode should always report `CSS 800x450` and `Scale 1.00`.
- During window resize, there should be no frame-by-frame jitter because scale updates run on
  resize/mode changes, not per animation frame.

## How it works

A browser can't run raylib's blocking `while (!WindowShouldClose())` loop (it would freeze the
page), so frames are driven from JavaScript:

- `Host.Main()` calls `InitWindow` once and selects the default example (`main.js` runs it via
  `runMain()`).
- `main.js` binds the page `<canvas>` to the runtime, then calls `Host.UpdateFrame()` every
  `requestAnimationFrame` tick. `UpdateFrame`, `SetExample`, and `GetExampleNames` are `[JSExport]`.
- Each base example implements `IExample` (`Init` / `Update` / `Unload`) in `#if BROWSER` partials.
  The host owns the window;
  examples never call `InitWindow`/`CloseWindow`.

## Adding more examples

For a new desktop example (`../Core/...`, `../Shaders/...`, etc.), add a browser partial
(`*.Browser.cs`) that implements `IExample` and mirrors the split of its monolithic `Main`:

```
Main() { <setup>; while(!WindowShouldClose()){ <body> } <cleanup> }
  ->  Init()  { <setup, minus InitWindow/SetTargetFPS> }   // loop-spanning locals become fields
      Update(){ <body> }                                   // keep BeginDrawing..EndDrawing
      Unload(){ <cleanup, minus CloseWindow> }
```

Then add `new YourExample()` to the `Examples` list in `Host.cs`.

Examples that load files (`resources/...`) also need those assets in the wasm virtual filesystem.
`Examples.csproj` bundles `../resources/` into the browser app when publishing with
`RuntimeIdentifier=browser-wasm`.