diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..4d4382aa3
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,201 @@
+# AGENTS.md — Contributing demos to the Babylon.js website
+
+This file tells automated agents (and humans) how to add or change demos on the
+Babylon.js website. Read it before touching anything under `src/compiledDemos/`,
+`src/pureCompiledDemos/`, or `static/Demos/`.
+
+## The one hard rule: no UMD demos
+
+**Every demo on the website MUST use the ES6 `@babylonjs/*` packages. UMD is not
+allowed.**
+
+- ❌ Do **not** add a demo that loads Babylon from a UMD/CDN script tag, e.g.
+ `` or any
+ `BABYLON.*` global usage.
+- ❌ Do **not** add a demo to `static/Demos/`. That folder is the legacy UMD tree
+ and is being removed. Nothing new goes there.
+- ✅ Add demos as ES6 TypeScript that imports named symbols from
+ `@babylonjs/core` (and sibling packages), bundled by Vite.
+
+If you are porting a legacy `static/Demos//` demo, you replace every
+`BABYLON.*` global with an explicit ES6 import and delete the legacy folder once
+the port is verified.
+
+## Two flavors, add BOTH
+
+Every demo exists in two forms. When you add or port a demo, add it in **both**:
+
+1. **Compiled demo** — `src/compiledDemos//`. Imports from the standard
+ deep ESM paths such as `@babylonjs/core/Engines/engine`. Built to
+ `build/Demos//` and served at `/Demos//`.
+2. **Pure demo** — `src/pureCompiledDemos//`. Imports from the tree-shaken
+ `@babylonjs/core/pure` barrel and calls the explicit `Register*()` side-effect
+ functions it needs. Built to `build/PureDemos//` and served at
+ `/PureDemos//`.
+
+The pure flavor exists to prove the demo works against the side-effect-free
+barrel. If a feature cannot be expressed in pure form, say so explicitly in the
+PR/commit rather than silently skipping it.
+
+## File layout per demo
+
+```text
+src/compiledDemos//
+ index.html # canvas shell; copy an existing demo's index.html, change
+ main.ts # 5-line wrapper that calls runDemo({ createScene })
+ scene.ts # the actual scene factory — the only file with real logic
+
+src/pureCompiledDemos/<Slug>/
+ index.html # same shell
+ main.ts # same wrapper, imports ../shared/demoRunner (the pure one)
+ scene.ts # same scene, but imports from @babylonjs/core/pure
+```
+
+`main.ts` is always:
+
+```ts
+import { runDemo } from "../shared/demoRunner";
+import { createMyScene } from "./scene";
+
+runDemo({ createScene: createMyScene });
+```
+
+`scene.ts` exports a factory. It may return `Scene` or `Promise<Scene>` (use the
+Promise form for demos that load assets):
+
+```ts
+export function createMyScene(engine: Engine, canvas: HTMLCanvasElement): Scene {
+ const scene = new Scene(engine);
+ // ...build the scene...
+ return scene;
+}
+```
+
+`index.html` is identical across demos except the `<title>`. Copy it from a
+neighboring demo (for example `src/compiledDemos/Fog/index.html`). It must keep
+the `#renderCanvas` element, the `#enableDebug`/`#fullscreen` buttons, the
+`<a id="sourceLink" href="./source/">Source</a>` link, and
+`<script type="module" src="./main.ts"></script>`.
+
+## Imports: compiled vs pure
+
+Compiled (`src/compiledDemos`) — deep named imports plus side-effect imports for
+prototype-augmented APIs:
+
+```ts
+import { Engine } from "@babylonjs/core/Engines/engine";
+import { Scene } from "@babylonjs/core/scene";
+import { StandardMaterial } from "@babylonjs/core/Materials/standardMaterial";
+import "@babylonjs/core/Loading/Plugins/babylonFileLoader"; // side effect: .babylon loader
+```
+
+Pure (`src/pureCompiledDemos`) — import everything from the `pure` barrel and
+register side effects with the matching `Register*()` call. Shared registrations
+(StandardMaterial, dynamic/read texture, cube texture, depth renderer, outline)
+already live in `src/pureCompiledDemos/shared/demoRunner.ts`; only add
+registrations specific to your demo in your `scene.ts`.
+
+```ts
+import type { Engine, Scene } from "@babylonjs/core/pure";
+import { StandardMaterial, RegisterBabylonFileLoader } from "@babylonjs/core/pure";
+
+RegisterBabylonFileLoader(); // pure equivalent of the side-effect import above
+```
+
+> **Critical (pure only):** if `Engine`/`Scene` (or any symbol) are used **only as
+> types**, import them with `import type`. Importing them as values and silencing
+> the unused-var lint with `void Engine;` makes the bundler emit
+> `init_engine_pure()` / `init_scene_pure()` calls **without importing them**,
+> which fails at runtime with `ReferenceError: init_engine_pure is not defined`.
+> Keep genuine value imports (e.g. `ShadowGenerator` used with `instanceof`) in a
+> separate, non-`type` import statement.
+
+Common compiled side-effect → pure registration pairs:
+
+| Feature | Compiled side-effect import | Pure registration |
+| --- | --- | --- |
+| `.babylon` file loading | `@babylonjs/core/Loading/Plugins/babylonFileLoader` | `RegisterBabylonFileLoader()` |
+| StandardMaterial | `@babylonjs/core/Materials/standardMaterial` | `RegisterStandardMaterial()` |
+| MultiMaterial | `@babylonjs/core/Materials/multiMaterial` | `RegisterMultiMaterial()` |
+| Fresnel parameters | `@babylonjs/core/Materials/fresnelParameters` | `RegisterFresnelParameters()` |
+| Loading screen | `@babylonjs/core/Loading/loadingScreen` | `RegisterLoadingScreen()` |
+| Universal/Arc cameras | `@babylonjs/core/Cameras/universalCamera` (etc.) | `RegisterUniversalCamera()` / `RegisterArcRotateCamera()` |
+| Lights (dir/point/spot/hemi) | imported transitively | `RegisterDirectionalLight()` / `RegisterPointLight()` / `RegisterSpotLight()` / `RegisterHemisphericLight()` |
+| Dynamic texture | `@babylonjs/core/Engines/Extensions/engine.dynamicTexture` | `RegisterEnginesExtensionsEngineDynamicTexture()` |
+| Cube texture / skybox | `@babylonjs/core/Engines/Extensions/engine.cubeTexture` | `RegisterAbstractEngineCubeTexture()` + `RegisterEnginesExtensionsEngineCubeTexture()` |
+| Render target / shadow map | `@babylonjs/core/Engines/Extensions/engine.renderTarget` | `RegisterEnginesExtensionsEngineRenderTarget()` + `RegisterEnginesExtensionsEngineRenderTargetTexture()` + `RegisterRenderTargetTexture()` |
+| Shadow generator | `@babylonjs/core/Lights/Shadows/shadowGeneratorSceneComponent` + `import { ShadowGenerator }` | `RegisterShadowGeneratorSceneComponent(ShadowGenerator)` (also needs render-target + light regs above) |
+| Mesh actions | `@babylonjs/core/Actions/directActions` + `directAudioActions` + `interpolateValueAction` | `RegisterDirectActions()` + `RegisterDirectAudioActions()` + `RegisterInterpolateValueAction()` |
+| Depth renderer | `@babylonjs/core/Rendering/depthRendererSceneComponent` | `RegisterDepthRendererSceneComponent(DepthRenderer)` |
+| Outline renderer | `@babylonjs/core/Rendering/outlineRenderer` | `RegisterOutlineRenderer()` |
+
+The shared `demoRunner.ts` (compiled and pure) already registers the common ones:
+loading screen, standard/multi-material, fresnel, dynamic/read/cube texture, depth
+renderer, outline, universal/arc cameras, and the four common light types. Only add
+registrations specific to your demo (e.g. shadow-map render targets, actions) in
+your own `scene.ts`.
+
+If a registration is missing in pure mode the symptom is usually a silent no-op
+(textures never become ready, a scene component is a stub). When in doubt, search
+`node_modules/@babylonjs/core/**/pure.d.ts` for the matching `Register*` export.
+
+## Assets
+
+- Keep asset URLs rooted at stable public paths. Legacy `.babylon` scenes and
+ textures live under `static/Scenes/<Name>/` and are served from `/Scenes/...`.
+- Do not enable `engine.enableOfflineSupport`; it triggers `.manifest` requests
+ that fail the smoke test. The shared `demoRunner` already creates the engine
+ for you, so just don't turn offline support on.
+
+## Manifests
+
+Register the compiled demo in `src/compiledDemos/manifest.json` and the pure demo
+in `src/pureCompiledDemos/manifest.json`:
+
+```json
+{
+ "slug": "<Slug>",
+ "title": "Babylon.js - <Name> demo",
+ "legacyPath": "static/Demos/<Slug>",
+ "sourceFiles": ["main.ts", "scene.ts"],
+ "renderCheck": { "timeoutMs": 20000, "minimumColoredSamples": 120 }
+}
+```
+
+- `sourceFiles` are the files shown on the generated `/Demos/<Slug>/source/` page.
+- `renderCheck.timeoutMs` should be generous for asset-loading demos (30–60s).
+- `minimumColoredSamples` is the blank-canvas guard; lower it for sparse scenes
+ (for example `Lines` uses 10).
+
+## Removing the legacy UMD demo
+
+Once the ES6 compiled + pure versions are verified, delete the legacy folder
+`static/Demos/<Slug>/`. Do not leave a UMD copy behind — the website must not
+ship any UMD demos.
+
+## Validate before you are done
+
+From the repo root:
+
+```bash
+npm run demos:format:write # apply prettier
+npm run build # site + compiled demos + pure demos
+npm run demos:smoke # browser smoke: console/page/request errors
+npm run demos:pure:smoke # same for /PureDemos/
+```
+
+For full validation (typecheck + render/pixel checks) run `npm run demos:ci` and
+`npm run demos:pure:ci`. The smoke test loads each demo in headless Chromium,
+waits for `window.__babylonDemoReady`, and fails on any console error, page
+error, or failed network request. A demo is not "done" until both smoke tests
+pass with no scene-related console errors.
+
+## Checklist
+
+- [ ] No `BABYLON.*` globals, no UMD/CDN script tags anywhere.
+- [ ] `src/compiledDemos/<Slug>/` added (index.html, main.ts, scene.ts).
+- [ ] `src/pureCompiledDemos/<Slug>/` added, importing from `@babylonjs/core/pure`.
+- [ ] Both manifests updated.
+- [ ] Legacy `static/Demos/<Slug>/` deleted.
+- [ ] `npm run build` succeeds.
+- [ ] `npm run demos:smoke` and `npm run demos:pure:smoke` pass with no errors.
diff --git a/docs/compiled-demos.md b/docs/compiled-demos.md
index be1a6ac73..6f17b42ba 100644
--- a/docs/compiled-demos.md
+++ b/docs/compiled-demos.md
@@ -264,6 +264,12 @@ Each demo page should include a small source link at the bottom of the viewport:
## Adding A Demo
+> Demos on the website must use the ES6 `@babylonjs/*` packages. UMD/CDN demos
+> are not allowed and nothing new should be added to `static/Demos/`. Every demo
+> is added in both compiled (`src/compiledDemos/`) and pure
+> (`src/pureCompiledDemos/`) form. See [AGENTS.md](../AGENTS.md) for the full
+> policy and the compiled→pure registration map.
+
1. Create `src/compiledDemos/<Slug>/index.html`, `main.ts`, and `scene.ts`.
2. Export a scene factory from `scene.ts`:
diff --git a/package-lock.json b/package-lock.json
index 3fb074a90..7bbb61cf3 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -15,10 +15,14 @@
"devDependencies": {
"@babylonjs/core": "^9.9.1",
"@babylonjs/gui": "^9.9.1",
+ "@babylonjs/havok": "^1.3.12",
"@babylonjs/inspector": "^9.9.1",
"@babylonjs/loaders": "^9.9.1",
"@babylonjs/materials": "^9.9.1",
+ "@babylonjs/procedural-textures": "^9.11.0",
"@eslint/js": "^10.0.1",
+ "@types/earcut": "^3.0.0",
+ "earcut": "^3.0.2",
"eslint": "^10.3.0",
"globals": "^17.6.0",
"playwright": "^1.59.1",
@@ -257,6 +261,16 @@
"@types/react-dom": ">=16.0.9"
}
},
+ "node_modules/@babylonjs/havok": {
+ "version": "1.3.12",
+ "resolved": "https://registry.npmjs.org/@babylonjs/havok/-/havok-1.3.12.tgz",
+ "integrity": "sha512-KR5Z7DBkVEgdvHLMDh2VWe/nHvUG8+MdLBiAE0iM19KIHAPqPRVITPAZKx4SQusK5nqm4ZXDcKv5OYtViIxLzA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@types/emscripten": "^1.39.6"
+ }
+ },
"node_modules/@babylonjs/inspector": {
"version": "9.9.1",
"resolved": "https://registry.npmjs.org/@babylonjs/inspector/-/inspector-9.9.1.tgz",
@@ -304,6 +318,16 @@
"@babylonjs/core": "^9.0.0"
}
},
+ "node_modules/@babylonjs/procedural-textures": {
+ "version": "9.11.0",
+ "resolved": "https://registry.npmjs.org/@babylonjs/procedural-textures/-/procedural-textures-9.11.0.tgz",
+ "integrity": "sha512-fezdsmU6wfVTQ/r22h4D1wSFoGNk9aQt3m5liL+K6KaPEnPRdBZtEfRiaKURyMOQddoeHBDDyj4zpm1NVHmGpQ==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "peerDependencies": {
+ "@babylonjs/core": "^9.0.0"
+ }
+ },
"node_modules/@babylonjs/serializers": {
"version": "9.5.2",
"resolved": "https://registry.npmjs.org/@babylonjs/serializers/-/serializers-9.5.2.tgz",
@@ -3114,6 +3138,20 @@
"tslib": "^2.4.0"
}
},
+ "node_modules/@types/earcut": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/@types/earcut/-/earcut-3.0.0.tgz",
+ "integrity": "sha512-k/9fOUGO39yd2sCjrbAJvGDEQvRwRnQIZlBz43roGwUZo5SHAmyVvSFyaVVZkicRVCaDXPKlbxrUcBuJoSWunQ==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/@types/emscripten": {
+ "version": "1.41.5",
+ "resolved": "https://registry.npmjs.org/@types/emscripten/-/emscripten-1.41.5.tgz",
+ "integrity": "sha512-cMQm7pxu6BxtHyqJ7mQZ2kXWV5SLmugybFdHCBbJ5eHzOo6VhBckEgAT3//rP5FwPHNPeEiq4SmQ5ucBwsOo4Q==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/@types/esrecurse": {
"version": "4.3.1",
"resolved": "https://registry.npmjs.org/@types/esrecurse/-/esrecurse-4.3.1.tgz",
@@ -3825,6 +3863,13 @@
"url": "https://github.com/fb55/domutils?sponsor=1"
}
},
+ "node_modules/earcut": {
+ "version": "3.0.2",
+ "resolved": "https://registry.npmjs.org/earcut/-/earcut-3.0.2.tgz",
+ "integrity": "sha512-X7hshQbLyMJ/3RPhyObLARM2sNxxmRALLKx1+NVFFnQ9gKzmCrxm9+uLIAdBcvc8FNLpctqlQ2V6AE92Ol9UDQ==",
+ "dev": true,
+ "license": "ISC"
+ },
"node_modules/ee-first": {
"version": "1.1.1",
"resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz",
diff --git a/package.json b/package.json
index beb0ab29a..3dc8cad08 100644
--- a/package.json
+++ b/package.json
@@ -36,10 +36,14 @@
"devDependencies": {
"@babylonjs/core": "^9.9.1",
"@babylonjs/gui": "^9.9.1",
+ "@babylonjs/havok": "^1.3.12",
"@babylonjs/inspector": "^9.9.1",
"@babylonjs/loaders": "^9.9.1",
"@babylonjs/materials": "^9.9.1",
+ "@babylonjs/procedural-textures": "^9.11.0",
"@eslint/js": "^10.0.1",
+ "@types/earcut": "^3.0.0",
+ "earcut": "^3.0.2",
"eslint": "^10.3.0",
"globals": "^17.6.0",
"playwright": "^1.59.1",
diff --git a/scripts/demos/check-smoke.mjs b/scripts/demos/check-smoke.mjs
index 8d6d5dc79..fd95180d5 100644
--- a/scripts/demos/check-smoke.mjs
+++ b/scripts/demos/check-smoke.mjs
@@ -27,6 +27,8 @@ const contentTypes = new Map([
[".webp", "image/webp"],
[".hdr", "application/octet-stream"],
[".wasm", "application/wasm"],
+ [".mp4", "video/mp4"],
+ [".webm", "video/webm"],
]);
function escapeAzureDevOpsMessage(message) {
@@ -82,8 +84,33 @@ const server = http.createServer(async (request, response) => {
}
const body = await fs.readFile(filePath);
+ const contentType = contentTypes.get(path.extname(filePath).toLowerCase()) || "application/octet-stream";
+
+ // Support HTTP Range requests so that <video>/<audio> elements (which
+ // request partial content) load correctly instead of being aborted.
+ const rangeHeader = request.headers.range;
+ if (rangeHeader) {
+ const match = /^bytes=(\d*)-(\d*)$/.exec(rangeHeader);
+ if (match) {
+ const start = match[1] ? Number.parseInt(match[1], 10) : 0;
+ const end = match[2] ? Number.parseInt(match[2], 10) : body.length - 1;
+ if (start <= end && end < body.length) {
+ response.writeHead(206, {
+ "content-type": contentType,
+ "content-range": `bytes ${start}-${end}/${body.length}`,
+ "accept-ranges": "bytes",
+ "content-length": end - start + 1,
+ });
+ response.end(body.subarray(start, end + 1));
+ return;
+ }
+ }
+ }
+
response.writeHead(200, {
- "content-type": contentTypes.get(path.extname(filePath).toLowerCase()) || "application/octet-stream",
+ "content-type": contentType,
+ "accept-ranges": "bytes",
+ "content-length": body.length,
});
response.end(body);
} catch {
diff --git a/src/compiledDemos/Actions/index.html b/src/compiledDemos/Actions/index.html
new file mode 100644
index 000000000..28ae0e5f4
--- /dev/null
+++ b/src/compiledDemos/Actions/index.html
@@ -0,0 +1,105 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
+ <title>Babylon.js - Actions demo
+
+
+
+
+