# Rendering support

An Al-Amr Environment is an engine-neutral web destination. It may use the
DOM, Canvas 2D, WebGL, WebGPU, WASM, or any browser-capable engine, including
Three/R3F, Babylon, PlayCanvas, Phaser, Pixi, Unity Web, or Godot Web. The
public Environment manifest deliberately has no `engine` or `renderer` field.

This page describes only the optional official R3F rendering profile,
`al-amr.r3f-webgpu@1`. A local package opts into that profile when its own name
is `@al-amr/r3f` or `@react-three/fiber`, or when it declares either marker in
any dependency section. That local authoring metadata scopes the renderer
policy; it does not change the public Environment contract. Generic
Environment conformance remains separate and engine-neutral.

## Plugin compatibility is scoped

A Plugin release may expose several frontend adapters. Compatibility is decided
for one immutable Plugin release, one adapter selected by the Environment's
composition plan, and verified capability evidence for one exact Environment
revision. R3F is the recommended official 3D profile, not a requirement for
either an Environment or a Plugin.

An R3F-only adapter on a generic host returns
`ALAMR_PLUGIN_HOST_RUNTIME_INCOMPATIBLE` with bounded alternatives: choose a
compatible Plugin, add a verified adapter, or build a new integration. That
result rejects only the Plugin composition; it never invalidates the generic
Environment. Missing, stale, publisher-claimed, conflicting, or unknown runtime
evidence is `unknown`, never compatible. A real-host support claim still
requires the exact packaged artifact to run in the packaged Desktop host; a
Node fixture consumer is not that evidence.

Within this profile, support is defined by capability, never by a browser-name
allowlist: a device is supported when the page runs in a secure (HTTPS)
context, the renderer actually initializes on WebGPU or WebGL2, and the first
frame renders without errors. Every Environment that selects the profile tries
WebGPU first and falls back to WebGL2 automatically — authors do not construct
or select the backend themselves. If the time-bounded WebGPU check cannot
obtain an adapter, startup continues directly on WebGL2 instead of waiting
indefinitely. A slow device is still supported; the world lowers its quality
tier instead of refusing to start. Environments using another engine define
their own rendering support and fallback behavior within the same host and
security contracts.

## Browsers tested for this profile

| Browser                                                    | WebGPU             | WebGL2 fallback | Status                                                                 |
| ---------------------------------------------------------- | ------------------ | --------------- | ---------------------------------------------------------------------- |
| Chrome and Edge, current stable and one major version back | Yes                | Yes             | Fully tested; best experience                                          |
| Safari 26 and newer                                        | Yes                | Yes             | Tested                                                                 |
| Firefox                                                    | Platform-dependent | Yes             | WebGPU where the platform provides it, otherwise the WebGL2 fallback   |
| Other modern browsers                                      | Varies             | Usually         | Capability-based: supported when WebGPU or WebGL2 actually initializes |

A browser or device with neither WebGPU nor WebGL2 — including WebGL1-only
systems — cannot run this profile's 3D world and receives the unsupported page
described below. That does not make the device incapable of running a generic
DOM or other engine-neutral Environment. Keeping the browser updated matters:
WebGPU availability and stability improve with every release.

## When a device is unsupported

An Environment using this profile reaches the unsupported page only when no
working profile graphics path exists:

- the page is not served from a secure (HTTPS) context
  (`insecure_context`);
- graphics hardware acceleration is disabled or unavailable, so neither
  WebGPU nor WebGL2 can start (`hardware_acceleration_unavailable`);
- WebGPU and the WebGL2 fallback both fail to initialize
  (`webgpu_init_failed`, `webgl2_unavailable`, `webgl2_init_failed`,
  `renderer_initialization_failed`, `renderer_unknown`);
- the graphics device was lost — for example after a driver reset — and the
  automatic bounded recovery did not succeed (`device_lost_unrecovered`).

## The unsupported page

The profile's unsupported page is a plain DOM page: no 3D canvas, Plugins, or
presence connection ever mount on it, and it is safe to refresh. It is
right-to-left aware, bilingual (Persian and English), and shows:

- a short explanation of what happened;
- the recovery steps listed below;
- **Retry** — runs the full detection again in the default WebGPU-first mode;
- **Try compatibility mode** — pins the WebGL2 backend and starts in the
  lowest quality tier; when this succeeds, the choice is remembered on this
  device for future visits;
- a copyable reason code from the table below — include it when asking for
  help.

## Reason codes

| Reason code                         | What it means                                     | What to try                                                               |
| ----------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------- |
| `insecure_context`                  | The page was not opened in a secure context.      | Open the `https://` address (localhost is allowed for local development). |
| `webgpu_init_failed`                | WebGPU initialization failed on this device.      | Update the browser, then try compatibility mode.                          |
| `webgl2_unavailable`                | WebGL2 is not available in this browser.          | Enable hardware acceleration and update the browser.                      |
| `webgl2_init_failed`                | The WebGL2 compatibility fallback also failed.    | Update the graphics driver and operating system.                          |
| `hardware_acceleration_unavailable` | Hardware acceleration is disabled or unavailable. | Enable hardware acceleration in the browser settings, then relaunch.      |
| `device_lost_unrecovered`           | The graphics device was lost and recovery failed. | Retry; update the graphics driver if it repeats.                          |
| `renderer_initialization_failed`    | The rendering engine failed to initialize.        | Retry, then compatibility mode; update browser and driver.                |
| `renderer_unknown`                  | The engine stopped with an unclassified error.    | Retry; report the code if it persists.                                    |

## What to try first

1. Use the latest version of Chrome for the best experience.
2. Enable hardware acceleration in your browser settings, then relaunch the
   browser.
3. Update your browser, operating system, and graphics driver.
4. If the world still does not start, use **Try compatibility mode** on the
   unsupported page, or append `?al-amr-rendering=force-webgl2` to the URL.

These steps mirror the guidance shown on the unsupported page itself.

## Privacy

The profile's rendering diagnostics are privacy-safe. When something goes
wrong, the platform may record only which backend was selected (WebGPU or
WebGL2), whether the fallback was used, the quality tier, a coarse
initialization-duration bucket, the stable reason code, and whether recovery
succeeded. The platform never collects or displays your GPU vendor or model,
unmasked renderer strings, VRAM size, raw adapter information, raw driver
errors, or shader sources. The platform-wide rules are in
[Trust and security](/docs/security); the technical renderer contract is in
[Rendering runtime](/docs/architecture/rendering-runtime).