feat(examples): Add depth occlusion demo

Summary:
Add example app demonstrating depth-based occlusion in AR. Creates
occludable spheres, cubes, and cylinders that are hidden when passing
behind real-world surfaces. Includes distance-grabbable interaction
so objects can be moved to test occlusion from different positions.

Reviewed By: cabanier

Differential Revision: D93502318

fbshipit-source-id: 4adcd6b8f1283d7b6ab36638c35e7ef7418a509b

Author: zjm-meta

examples/depth-occlusion/.gitignore

@@ -0,0 +1,61 @@
+# Dependencies
+node_modules/
+.pnpm-debug.log*
+
+# Build outputs
+dist/
+*.tsbuildinfo
+
+# Environment files
+.env
+.env.local
+.env.production
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Coverage directory used by tools like istanbul
+coverage/
+*.lcov
+
+# Temporary files
+.tmp/
+.temp/
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Local SSL certificates (auto-generated)
+.cert/
+
+# Meta Spatial Editor exports
+public/gltf/generated/
+public/glxf/
+public/ui/

examples/depth-occlusion/README.md

@@ -0,0 +1,137 @@
+# Depth Occlusion Example
+
+This example demonstrates depth-based occlusion in the Immersive Web SDK (IWSDK). Virtual objects are hidden when they pass behind real-world surfaces, creating a more realistic AR experience.
+
+## What This Example Shows
+
+- **Depth Sensing**: Configuring WebXR depth sensing with GPU-optimized float32 depth data
+- **Depth Occlusion**: Using the `DepthOccludable` component to automatically occlude virtual objects behind real-world geometry
+- **DepthSensingSystem**: Registering and configuring the system that drives depth data retrieval and occlusion rendering
+- **Interactive Objects**: Combining occlusion with distance grabbing and spatial anchors
+
+### What's in the Example
+
+The example creates three occludable primitives in an AR scene:
+
+1. **Red sphere** at `(0, 0.8, -0.8)` with `DepthOccludable`
+2. **Green cube** at `(-0.4, 0.8, -0.6)` with `DepthOccludable`
+3. **Blue cylinder** at `(0.4, 0.8, -0.6)` without `DepthOccludable` (for comparison)
+
+All objects are distance-grabbable and anchored, so you can move them around and observe occlusion in action. The `OcclusionDemoSystem` also applies a gentle rotation animation to occludable entities.
+
+## Project Structure
+
+```
+depth-occlusion/
+├── src/
+│   └── index.js          # OcclusionDemoSystem and world setup
+├── index.html            # HTML entry point
+├── vite.config.js        # Vite configuration with HTTPS
+└── package.json          # Dependencies
+```
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 20.19.0+ and pnpm
+- An AR-capable device with depth sensing support (e.g., Meta Quest 3)
+
+### Installation
+
+```bash
+cd depth-occlusion
+pnpm install
+```
+
+### Development
+
+```bash
+# Start development server with HTTPS
+pnpm dev
+
+# Build for production
+pnpm build
+
+# Preview production build
+pnpm preview
+```
+
+## How It Works
+
+### 1. Configure Depth Sensing
+
+Enable depth sensing in the WebXR session features:
+
+```javascript
+World.create(document.getElementById('scene-container'), {
+  xr: {
+    sessionMode: SessionMode.ImmersiveAR,
+    referenceSpace: ReferenceSpaceType.Unbounded,
+    features: {
+      depthSensing: {
+        required: true,
+        usage: 'gpu-optimized',
+        format: 'float32',
+      },
+      hitTest: { required: true },
+      anchors: { required: true },
+      unbounded: { required: true },
+    },
+  },
+  features: {
+    grabbing: true,
+  },
+});
+```
+
+### 2. Register the DepthSensingSystem
+
+```javascript
+world.registerSystem(DepthSensingSystem, {
+  enabled: true,
+  enableDepthTexture: true,
+  enableOcclusion: true,
+  useFloat32: true,
+});
+world.registerComponent(DepthOccludable);
+```
+
+### 3. Mark Entities as Occludable
+
+Add the `DepthOccludable` component to any entity that should be hidden behind real-world surfaces:
+
+```javascript
+const entity = world.createTransformEntity(mesh);
+entity.addComponent(DepthOccludable);
+```
+
+The `DepthSensingSystem` automatically injects occlusion shader code into the entity's materials when the component is added, and removes it when the component is removed. No manual shader setup is required.
+
+### Depth Sensing Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | boolean | `true` | Enable/disable the depth sensing system |
+| `enableDepthTexture` | boolean | `true` | Enable depth texture generation |
+| `enableOcclusion` | boolean | `true` | Enable occlusion rendering |
+| `useFloat32` | boolean | `true` | Use float32 depth values (vs luminance-alpha) |
+
+### Depth Sensing Modes
+
+The `depthSensing.usage` field controls how depth data is accessed:
+
+- **`gpu-optimized`**: Depth data stays on the GPU as a texture array. Lower latency, preferred for occlusion.
+- **`cpu-optimized`**: Depth data is copied to CPU memory as a `DataTexture`. Useful if you need to read depth values on the CPU.
+
+## Testing on Device
+
+1. Start the dev server: `pnpm dev`
+2. On your Quest device, open the browser and navigate to `https://YOUR_LOCAL_IP:8081`
+3. Accept the self-signed certificate warning
+4. Enter AR mode
+5. Move the virtual objects behind real-world surfaces to see occlusion
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

examples/depth-occlusion/index.html

@@ -0,0 +1,22 @@
+<!-- 
+  Copyright (c) Meta Platforms, Inc. and affiliates.
+
+  This source code is licensed under the MIT license found in the
+  LICENSE file in the root directory of this source tree.
+-->
+
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1, shrink-to-fit=no"
+    />
+    <title>Depth Occlusion Demo</title>
+  </head>
+  <body style="margin: 0">
+    <div id="scene-container"></div>
+    <script type="module" src="/src/index.js"></script>
+  </body>
+</html>

examples/depth-occlusion/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@iwsdk/depth-occlusion",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "fresh:install": "npx rimraf package-lock.json node_modules && npm install",
+    "fresh:ci": "npx rimraf node_modules && npm ci",
+    "fresh:dev": "npm run fresh:install && npm run dev",
+    "fresh:build": "npm run fresh:install && npm run build"
+  },
+  "dependencies": {
+    "@iwsdk/core": "file:../../packages/core/iwsdk-core.tgz",
+    "patch-package": "^8.0.1",
+    "three": "npm:super-three@0.181.0"
+  },
+  "devDependencies": {
+    "@iwsdk/vite-plugin-gltf-optimizer": "file:../../packages/vite-plugin-gltf-optimizer/iwsdk-vite-plugin-gltf-optimizer.tgz",
+    "@iwsdk/vite-plugin-iwer": "file:../../packages/vite-plugin-iwer/iwsdk-vite-plugin-iwer.tgz",
+    "@iwsdk/vite-plugin-metaspatial": "file:../../packages/vite-plugin-metaspatial/iwsdk-vite-plugin-metaspatial.tgz",
+    "@iwsdk/vite-plugin-uikitml": "file:../../packages/vite-plugin-uikitml/iwsdk-vite-plugin-uikitml.tgz",
+    "vite": "^7.1.4",
+    "vite-plugin-mkcert": "^1.17.0"
+  }
+}