# three-live-authoring

Adopt this skill: https://proskills.md/skills/other/google-three-live-skills-three-live-authoring

Page: https://proskills.md/skills/other/google-three-live-skills-three-live-authoring
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/three-live-authoring/SKILL.md
size: 26595
sha: 36f125e6e1dd2d6bc63842bb883ca6ce4bd60d26
upstream: https://github.com/google/three-live/blob/main/skills/three-live-authoring/SKILL.md

```text
---
name: three-live-authoring
description: >-
  Builds interactive 3D viewers, procedural Three.js scenes, AR product
  configurators, and 6DoF WebXR, Android XR, and iOS/visionOS spatial computing
  apps using <three-live> and <xr-live>. Use when creating or editing
  <three-live> or <xr-live> HTML elements, writing <script type="text/three">
  procedural scenes, configuring userData.xr spatial traits or
  userData.interactivity behavior graphs, building <div slot="spatial"> 3D HTML
  cards, or integrating native Android (Filament / Jetpack XR SceneCore) and
  iOS/visionOS (RealityKit) spatial views.
---

# Authoring 3D & Spatial Apps with `<three-live>` and `<xr-live>`

`<three-live>` and `<xr-live>` compile declarative HTML and sandboxed Three.js scripts (`<script type="text/three">`) into WebGL2/WebXR on the web, Google Filament & Jetpack XR SceneCore on Android, and Apple RealityKit & Quick Look on iOS/visionOS.

## 1. Choose the Right Component & Bundle

- **Use `<three-live>` (`three-live.min.js` or `three-live-full.min.js`)** when you need:
    -   A 3D `.glb` / `.usdz` model viewer (`<model-viewer>` drop-in
        replacement) with built-in `EXT_meshopt_compression` decoding and
        `KHR_materials_variants` (`variant-name`)
    -   A procedural Three.js scene (including 2D `Shape`/`ExtrudeGeometry`,
        3D `SweepGeometry`/`HelixGeometry`/`LoftGeometry` sweeps, coils, and
        lofted vessels, `THREE.CSG` Booleans, 3D `TextGeometry`, optional a la
        carte domain kits
        `THREE.Mechanical`, `THREE.Architecture`, `THREE.Industrial`,
        `THREE.Science`, and `THREE.Electronics` via `three-live-kits.min.js` or
        `three-live-kit-<domain>.min.js`, and `THREE.InstancedMesh` GPU
        instancing) with
        orbit controls and 1-tap mobile AR handoff (`ar`)
    -   PBR Next materials (clearcoat, transmission, dispersion, iridescence,
        sheen, volume), 5 filmic/commerce tone-mapping modes
        (`tone-mapping="neutral|aces|agx|reinhard|none"`), HDR emissive `bloom`,
        silhouette `outline`, `.hdr` environment lighting, ground contact
        shadows, multi-light depth shadow maps (`shadow-maps="auto|pcf|off"`,
        `light.castShadow`, `mesh.castShadow`, `mesh.receiveShadow`), loop-free
        `THREE.TSL` procedural node materials (`three-live-tsl.min.js` /
        `MeshStandardNodeMaterial` + `el.setMaterialUniform()`), skeletal
        animations & 2-bone/FABRIK `ik`, or 2D screen-space hotspots
        (`slot="hotspot-*"`)
- **Use `<xr-live>` (`xr-live-full.min.js`)** when you need:
    - 6DoF WebXR (`xr-mode="ar"` / `"vr"` / `"auto"`) or desktop 6DoF simulation (`xr-simulator="living-room"`)
    -   Declarative spatial manipulation traits (`grab`, `scale`, `billboard`,
        `follow`, `anchor`, `physics`, `orbit`, `handles`, `dimensions`,
        `snapTo`, `snapSocket`, `gaze`, `explode`, `navigable`, `sync`, `bloom`,
        `outline`, `ik`, `text`, `splat`, `audioEmitter`)
    - True 3D raycastable HTML/CSS spatial cards (`<div slot="spatial">`)
    -   Real-world depth occlusion & heightfield physics
        (`xr-depth="occlusion-physics"`), 25-joint hand gesture recognition
        (`xr-hands="gestures"`), spatial 3D painting (`spatial-paint`),
        depth-colliding particles (`particles`), 3D Gaussian Splats with 3D
        covariance & SH degree 1–3 (`splatUrl` / `splat`), world plane/reticle
        understanding (`world-understanding`), multimodal Gemini Live
        (`connectGeminiLive()` / `holdToAsk`), 3D CAD dimension callouts & tape
        measure (`spatial-measure`), magnetic socket/grid snapping
        (`magnetic-snap`), hands-free eye/head gaze dwell (`gaze-dwell`),
        multi-part exploded views & section clipping (`explode` /
        `section-plane`), `#xr-state` & `XRAnchor` persistence
        (`persistent-anchors`), parabolic XR locomotion (`locomotion`), or
        multi-user co-presence & WebRTC voice signaling (`shared-room` +
        `shared-room-voice`; your app owns the `RTCPeerConnection`).
-   **Add `xr-live-sim.min.js` (included in `xr-live-full.min.js`)** when the
    scene is an interactive simulation: a game, training drill, or safety
    walkthrough with a controllable character (`character`), steering agents
    (`agent`), integrity and hits (`integrity`, `hit-zones`), trigger zones
    (`zone`), spawners (`spawner`), objectives and scoring (`objective`,
    `scenario-timer`, `target-score`, `attempts`), or procedural audio cues
    (`audioCues`, `synth-audio`). Use neutral names: `integrity` (not health),
    `group` (not team).

---

## 2. Critical Rules That Prevent Broken Scenes

1. **Include `allow-client-scripts` whenever using inline `<script type="text/three">` or `executeScript()`:**
   - `<three-live>` and `<xr-live>` reject inline client scripts unless `allow-client-scripts` is present on the host element.
   - Server-hosted scripts loaded via `script-src="/path/to/scene.js"` do not require `allow-client-scripts`.
2. **Use the pre-defined `THREE` and `scene` globals inside `<script type="text/three">`:**
   - Do **not** `import * as THREE from 'three'`, do **not** create a `new THREE.WebGLRenderer()`, and do **not** call `document.body.appendChild(...)` inside `<script type="text/three">`. The script runs inside an isolated Web Worker (or Rust Boa sandbox) with zero DOM access and populates the global `scene` directly (`scene.add(mesh)`).
3. **Never use `GLTFLoader` or `TextureLoader` inside `<script type="text/three">`:**
   - Network APIs (`fetch`, `XMLHttpRequest`) are revoked inside the procedural sandbox. Load `.glb` assets declaratively via `<three-live src="model.glb">` or `<xr-anchor src="model.glb">`.
4. **Prefer `mesh.userData.xr = { ... }` over legacy `userData.xrTraits`:**
   - The structured `userData.xr` object supports all core and extended spatial traits and exports cleanly to `.glb` (`extras.xr` + `ANDROID_xr_scenecore`) and `.usdz` (`customData.xr`).
5. **Always name interactive meshes (`mesh.name = '...'`):**
   - `meshclick` events, `selected-mesh`, `userData.xr.orbit.target`, `userData.interactivity` target references, `holdToAsk` prompts, and WebMCP `place_xr_object_at_gaze` all identify nodes by `mesh.name`.
6.  **Use loop-free `THREE.MeshStandardNodeMaterial` + `THREE.TSL` for
    procedural shaders (never `ShaderMaterial` or `TSL.Loop`):**
    -   Load `three-live-tsl.min.js` (or `three-live-full.min.js` /
        `xr-live-full.min.js`) and assign `colorNode`, `opacityNode`,
        `emissiveNode`, `roughnessNode`, `metalnessNode`, `normalScaleNode`,
        `bumpNode`, or `positionNode` using `THREE.TSL` (`uv`, `time`,
        `positionLocal`, `positionWorld`, `normalLocal`, `normalWorld`,
        `viewDirection`, `uniform(val, name)`, `fresnel`, `simplexNoise2D/3D`,
        `voronoi2D`, `checker`, `triplanar`, `hueShift`, `bumpFromHeight`,
        `remap`). Keep graphs acyclic (`<= 128` nodes, `<= 16` uniforms) and
        avoid fragment-only ops (`viewDirection`, `fresnel`, `bumpFromHeight`)
        inside `positionNode` (`TL501`–`TL504`).

---

## 3. Canonical `userData.xr` Trait Quick Reference

Attach `userData.xr` to any `THREE.Mesh` or `THREE.Group` inside `<script type="text/three">`:

Trait Key                | Accepted Values                                                                                                                                                                                                                                                                                                       | Behavior
:----------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------
`grab`                   | `'1-hand' \| '2-hand' \| true`                                                                                                                                                                                                                                                                                        | Enables 6DoF pinch / controller trigger grabbing (`true` defaults to `'2-hand'`).
`scale`                  | `{ min?: number, max?: number } \| true`                                                                                                                                                                                                                                                                              | Two-hand pinch-to-scale clamped to `[min, max]` (default `0.05`–`5.0`).
`billboard`              | `'capsule' \| 'cylindrical' \| 'spherical' \| true`                                                                                                                                                                                                                                                                   | Faces the active viewer camera (`'capsule'` / `'cylindrical'` yaw-only; `'spherical'` full 3D).
`follow`                 | `'head' \| 'hand-left' \| 'hand-right'` **or** `{ mode, lazy, distance, deadzoneDeg, stiffness, height, faceUser, snapOnStart }`                                                                                                                                                                                      | String values use eager spring follow; object values activate lazy follow with angular deadzone + critically damped spring.
`anchor`                 | `'floor' \| 'wall' \| 'ceiling' \| 'table' \| 'horizontal' \| 'vertical'` **or** `{ target?, id?, persist? }`                                                                                                                                                                                                         | Snaps node to detected real-world planes or simulated surfaces; `persist: true` saves user-moved transforms across reloads and `#xr-state` URLs.
`physics` / `rigidBody`  | `'dynamic' \| 'static' \| 'kinematic' \| true` **or** `{ body?, shape?: 'auto' \| 'box' \| 'sphere' \| 'cylinder', mass?, restitution?, friction?, linearDamping?, angularDamping?, gravityScale?, velocity?, angularVelocity?, lockRotation? }`                                                                      | Steps 60 Hz deterministic Sequential Impulse rigid-body physics (gravity, restitution bounce, friction, stacking, sleeping, character push, projectile knockback, and depth heightfield collisions); emits `xrcollision` and `xrsleep`.
`orbit`                  | `{ target: [x,y,z] \| 'nodeName', radius, speed, height, phase, faceCenter }`                                                                                                                                                                                                                                         | Orbits around a 3D point or named target mesh at `speed` rad/s.
`handles`                | `{ rotateAxis?: 'y' \| 'none', minScale?: number, maxScale?: number } \| true`                                                                                                                                                                                                                                        | Spawns 4 top-corner uniform-scale handles and a bottom pedestal yaw-rotation bar; emits `xr-handles-change`.
`dimensions`             | `{ unit?: 'auto' \| 'm' \| 'cm' \| 'mm' \| 'in' \| 'ft-in', axes?: Array<'x' \| 'y' \| 'z'>, color?: string, showOnSelect?: boolean } \| true`                                                                                                                                                                        | Renders live `W × H × D` bounding-box dimension guide bars and 3D vector-glyph labels (`spatial-measure`).
`snapTo`                 | `{ grid?: number \| [x,y,z], angleDeg?: number, surface?: 'none' \| 'floor' \| 'wall' \| 'ceiling' \| 'any', socketTag?: string, radius?: number } \| true`                                                                                                                                                           | Snaps grabbed meshes to matching `snapSocket` anchors (`1.25×` breakaway hysteresis), grids, surfaces, and yaw angles (`magnetic-snap`).
`snapSocket`             | `string` **or** `{ tag: string, radius?: number, alignRotation?: boolean, highlightColor?: string }`                                                                                                                                                                                                                  | Marks a node as a magnetic snap target socket with a pulsing proximity ring (`magnetic-snap`).
`gaze`                   | `{ dwellMs?: number, action?: 'select' \| 'ask', repeat?: boolean } \| true`                                                                                                                                                                                                                                          | Opts mesh into hands-free eye/head gaze dwell (`250..10000ms`, default `1200ms`), routing to `meshclick` or `gemini-live` (`gaze-dwell`).
`explode`                | `{ direction?: [x,y,z], distance?: number, layer?: number, leaderLine?: boolean } \| boolean`                                                                                                                                                                                                                         | Configures per-part explosion vector, distance, staggered `layer` (`1..10`), and dashed leader lines (`exploded-view`); `false` pins base parts.
`navigable`              | `boolean \| 'walkable' \| 'blocked'`                                                                                                                                                                                                                                                                                  | Marks floor/deck meshes as valid (`'walkable'`) or blocked landing surfaces for parabolic XR teleportation (`spatial-locomotion`).
`sync`                   | `boolean`                                                                                                                                                                                                                                                                                                             | Controls whether user manipulations sync across peers in `shared-room` (defaults to `true` on grabbable nodes).
`particles`              | `{ preset: 'rain' \| 'snow' \| 'sparks' \| 'confetti', count?: number, area?: [x,y,z], speed?: number }`                                                                                                                                                                                                              | Emits up to `2,000` depth-colliding particles inside `area`.
`holdToAsk`              | `{ prompt?: string, holdMs?: number } \| true`                                                                                                                                                                                                                                                                        | Press-and-hold on the mesh starts speech recognition and queries Gemini Live; emits `xr-hold-to-ask`.
`worldUnderstanding`     | `{ planes?: boolean, meshes?: boolean, reticle?: boolean, objects?: boolean }`                                                                                                                                                                                                                                        | Enables WebXR plane/mesh detection and gaze surface reticle (`__xr_reticle__`).
`splatUrl`               | `'https://.../scene.splat'` or `'.spz'`                                                                                                                                                                                                                                                                               | Streams and depth-sorts 3D Gaussian Splats (`.splat` or Niantic `.spz` v2/v3 with 3D covariance + SH degree 1–3).
`splat`                  | `{ url: string, shDegree?: 0 \| 1 \| 2 \| 3, maxSplats?: number }`                                                                                                                                                                                                                                                    | Structured 3D Gaussian Splat trait controlling Spherical Harmonics degree (`0..3`) and splat cap.
`bloom`                  | `{ strength?: number, threshold?: number, radius?: number } \| boolean \| number`                                                                                                                                                                                                                                     | Enables HDR emissive bloom on the scene/node (`strength` in `[0, 5]`, `threshold` in `[0, 2]`, `radius` in `[0, 1]`).
`outline`                | `{ color?: string, thickness?: number } \| boolean \| string`                                                                                                                                                                                                                                                         | Renders an inverted-hull or screen-space silhouette outline (`thickness` in `[0.002, 0.25]`) around the node.
`ik`                     | `{ root: string, mid?: string, effector: string, target: string \| [x, y, z], pole?: string \| [x, y, z], solver?: 'two-bone' \| 'fabrik', iterations?: number, tolerance?: number, weight?: number }`                                                                                                                | Solves analytical 2-bone (`root` → `mid` → `effector`) or FABRIK inverse kinematics toward `target` (and optional `pole`, alias `poleTarget`).
`lod`                    | `boolean \| number[] \| { distances?: number[], ratios?: number[], levels?: Array<{ distance: number, ratio?: number, node?: string }>, cullDistance?: number, hysteresis?: number }`                                                                                                                                 | Distance-based Level-of-Detail switching with hysteresis, far-distance culling, and automatic vertex-clustering decimation (also `new THREE.LOD()`).
`text`                   | `{ text: string, size?: number, depth?: number, bevelEnabled?: boolean, bevelThickness?: number, bevelSize?: number }`                                                                                                                                                                                                | Extruded 3D vector text metadata exported to glTF `extras.xr.text` and USDZ `customData.xr`.
`audioEmitter` / `audio` | `'hum' \| 'reactor' \| 'wind' \| 'beacon' \| 'geiger' \| 'chimeLoop' \| 'machinery' \| 'water'` or `'https://.../sound.mp3'` or `{ preset?, src?, volume?, loop?, autoplay?, playOnSelect?, distanceModel?, refDistance?, maxDistance?, rolloffFactor?, coneInnerAngle?, coneOuterAngle?, coneOuterGain?, pitchHz? }` | Attaches a 3D positional and directional spatial audio emitter (`spatial-audio`), exporting `KHR_audio_emitter` and USDZ `SpatialAudio`.
`character`              | `true \| 'third-person' \| 'first-person' \| 'top-down' \| 'fixed'` **or** `{ speed, jumpVelocity, radius, height, cameraMode, clips }`                                                                                                                                                                               | (`xr-live-sim`) Keyboard, gamepad, or touch-joystick character that slides along `collidable` nodes.
`agent`                  | `'patrol' \| 'chase' \| 'flee' \| 'follow' \| 'wander'` **or** `{ mode, target, speed, sightRadius, waypoints }`                                                                                                                                                                                                      | (`xr-live-sim`) Steering agent; `target: 'user'` means the character, else the viewer.
`integrity`              | `number` **or** `{ max, group, showBar, scoreValue, contactAmount, hideOnDepleted }`                                                                                                                                                                                                                                  | (`xr-live-sim`) Takes hits from other groups; emits `xrhit` and `xrdepleted`.
`zone`                   | `'box' \| 'sphere'` **or** `{ shape, size, radius, watchGroups, color }`                                                                                                                                                                                                                                              | (`xr-live-sim`) Emits `xrzoneenter` / `xrzoneexit` for characters, agents, and integrity nodes.
`spawner`                | `'TemplateName'` **or** `{ template, intervalSec, maxActive, totalCount, spawnRadius }`                                                                                                                                                                                                                               | (`xr-live-sim`) Clones a hidden template node; emits `xrspawn`.
`objective`              | `'pickup' \| 'checkpoint' \| 'key' \| 'time-bonus' \| 'restore'` **or** `{ type, amount, order, required, radius, respawnSec }`                                                                                                                                                                                       | (`xr-live-sim`) Completed by proximity to the character, or by tap without one; `order > 0` enforces sequence.
`audioCues`              | `{ onTap?, onObjective?, onHit?, onDepleted?, onZoneEnter?, onZoneExit?, onSpawn?, onJump?, onLand? }` (cue names such as `'confirm'`, `'alarm'`)                                                                                                                                                                     | (`xr-live-sim`) Procedural cues with `synth-audio`; separate from the file-based `audio` trait.
`collidable`             | `true`                                                                                                                                                                                                                                                                                                                | (`xr-live-sim`) Wall or floor for characters and agents.
`pointerEvents`          | `'none'`                                                                                                                                                                                                                                                                                                              | Excludes the mesh from raycast picking so rays pass through to objects behind it.

---

## 4. Progressive Disclosure References

Read these reference files when you need detailed schemas, copy-pasteable recipes, or debugging steps:

-   **[`references/xr-traits-and-plugins.md`](references/xr-traits-and-plugins.md)**:
    Complete attribute tables, clamping ranges, DOM events,
    `userData.interactivity` (`KHR_interactivity`) actions, all 15 spatial
    plugin controllers, the 6 `xr-live-sim` simulation plugins, Gemini Live API,
    and WebMCP tool schemas.
-   **[`references/recipes.md`](references/recipes.md)**: 10 production-ready,
    copy-pasteable code templates (E-commerce configurator, Physics ballpit &
    spatial HTML UI, manipulation handles & lazy HUD, Gemini Live + World
    Understanding, Spatial Paint + Particles + Gaussian Splats, Native
    Android/iOS integration, CAD Exploded View + Measure + Gaze Dwell, Magnetic
    Snapping + Persistent `#xr-state` + Locomotion, Multi-User `shared-room`
    Co-Presence, and an `xr-live-sim` training drill).
-   **[`references/debugging-and-csp.md`](references/debugging-and-csp.md)**:
    Diagnosing blank scenes, inspecting `THREE.getAuthorWarnings()`, running
    closed-loop `three-live-cli validate --json` / `render --view=quad` /
    `sim --json` checks (`TL100–TL402`), configuring Worker/iframe sandboxes &
    `connect-src wss:` under strict CSP / Trusted Types, and verifying bundle
    budgets.

--------------------------------------------------------------------------------

## 5. Closed-Loop CLI Verification (`three-live-cli`)

Always verify authored `.js`, `.html`, or `.glb` scenes headlessly using
`three-live-cli`:

1.  **Validate & Spatial Lint:** `three-live-cli validate scene.js --json` — fix
    all `TL100–TL402` errors and spatial warnings (`inFrustum`,
    `screenCoveragePct`, `grounded`, broken target references) before rendering.
2.  **Render 4-Up Quad Contact Sheet:** `three-live-cli render scene.js -o
    preview.png --view=quad --grid --annotations` — inspect perspective camera
    framing (`CAMERA`), front/right elevation (`FRONT`, `RIGHT`), and top-down
    layout (`TOP`) with `1 m` gridlines and AABB labels.
3.  **Match a Reference (when given a photo, mockup, sketch, or blueprint):**
    `three-live-cli render scene.js -o compare.png --reference=ref.jpg
    --view=camera` (or `--view=front|right|top` for blueprints) — iterate until
    `silhouetteIou >= 0.85` and `|aspectError| < 0.05` when `silhouetteReliable`
    is true, otherwise compare the aligned OVERLAY panel.
4.  **Simulate Interactivity & Temporal Motion:** `three-live-cli render
    scene.js -o anim.png --frames=4 --duration=2.0 --trigger-select=<node>` or
    `three-live-cli sim scene.js --duration=5.0 --actions='[...]' --json`. For
    games, play the level closed-loop with
    `three-live-cli gym reset scene.js --session ep.json` and
    `three-live-cli gym step --session ep.json --actions='[...]'` (or the
    `three_live_gym_*` MCP tools) to check it is winnable.
```

## File: skills/three-live-authoring/references/debugging-and-csp.md
size: 8910
sha: e329d7ccebaad734445a41902c9623193ecdd09a
upstream: https://github.com/google/three-live/blob/main/skills/three-live-authoring/references/debugging-and-csp.md

````text
# Debugging, Sandboxing & CSP Guide (`<three-live>` & `<xr-live>`)

## 1. Why Nothing Renders (Top 4 Causes)

1. **Missing `allow-client-scripts` attribute:**
   - **Symptom:** `<three-live>` or `<xr-live>` with an inline `<script type="text/three">` stays blank and dispatches an `error` event with `CLIENT_SCRIPTS_DISABLED_ERROR`.
   - **Fix:** Add `allow-client-scripts` to the element (`<three-live allow-client-scripts ...>`) or set `ThreeLiveElement.allowClientScripts = true` before connecting.
2. **Bundler moved the Worker engine asset (`sandboxEngineSrc`):**
   - **Symptom:** When bundling with Vite, Webpack, or Rollup instead of loading `/dist/three-live.min.js` via `<script>`, the sandbox Worker cannot auto-detect the IIFE bundle URL and fails closed.
   - **Fix:** Explicitly point `ThreeLiveElement.sandboxEngineSrc` at the IIFE `.min.js` bundle:
     
     ```js
     import { ThreeLiveElement } from 'three-live';
     ThreeLiveElement.sandboxEngineSrc =
       new URL('three-live/dist/three-live.min.js', import.meta.url).href;
     ```
3. **Strict Host CSP (`require-trusted-types-for 'script'` or blocked `blob:` Workers):**
   - **Symptom:** The host page's Content Security Policy blocks Worker creation or script evaluation.
   - **Fix:** Set `sandbox="iframe"` on the element and configure `ThreeLiveElement.sandboxIframeSrc` to point at `three-live-sandbox.html`, which runs inside an opaque-origin `<iframe sandbox="allow-scripts">`.
4. **Calling `new THREE.GLTFLoader()` or `fetch()` inside `<script type="text/three">`:**
   - **Symptom:** External model does not appear because `fetch` and `XMLHttpRequest` are permanently revoked inside the sandbox Worker.
   - **Fix:** Use `<three-live src="/path/to/model.glb">` or `<xr-anchor src="/path/to/model.glb">`.

---

## 2. Inspecting Permissive Fallback Warnings (`THREE.getAuthorWarnings()`)

When an LLM-generated `<script type="text/three">` uses unsupported Three.js classes (`ShaderMaterial`, `SpotLight`, `IcosahedronGeometry`, `CapsuleGeometry`, or unknown `THREE.*` constructors), `three-author` downgrades them gracefully instead of crashing.

To inspect which fallbacks were triggered during a scene compilation:

```js
// Inside <script type="text/three"> or unit tests:
const warnings = THREE.getAuthorWarnings();
console.log('Author warnings:', warnings);
THREE.clearAuthorWarnings();
```

---

## 3. Enforced Sandbox Quotas

Every procedural compilation (`toCanvas3D()`, `toGLB()`, `toUSDZ()`) runs `SceneQuotaValidator` with these defaults:

- **Max Script Size:** `1,048,576` bytes (`1 MiB`)
- **Max Meshes:** `1,000`
- **Max Vertices:** `100,000`
- **Max Indices:** `300,000`
- **Max Textures:** `16` (max dimension `2048×2048`)
- **Execution Watchdog:** `3,000 ms` wall-clock timeout (`250 ms` CPU ceiling inside Rust Boa compiler)
- **Max Concurrent Sandbox Workers:** `32`

--------------------------------------------------------------------------------

## 4. Network CSP & Plugin Security Quotas (`gemini-live`, `shared-room`, `persistent-anchors`)

-   **Host `connect-src` for Live Relays:** The procedural
    `<script type="text/three">` Worker always runs with network access revoked
    (`connect-src 'none'`). Host-level plugins (`connectGeminiLive()` and
    `shared-room="wss://..."`) connect from the main thread and enforce `wss://`
    (or loopback `ws://localhost` / `ws://127.0.0.1` / `ws://[::1]`). If your
    page serves a strict Content Security Policy and uses remote WebSocket
    relays, allow your relay origin in `connect-src` (e.g.
    `connect-src 'self' wss://your-relay.example.com`). Same-origin
    `shared-room="room-id"` uses `BroadcastChannel` and needs no `connect-src`
    allowance.
-   **Persistence & Co-Presence Caps:**
    -   `persistent-anchors`: `MAX_PERSISTED_NODES = 128`,
        `MAX_HASH_BYTES = 8192` (`#xr-state` tokens larger than `8 KB` or
        containing prototype-pollution keys are rejected).
    -   `shared-room`: `MAX_PEERS = 16`, `MAX_PAYLOAD_BYTES = 16384` (`16 KB`),
        `MAX_REMOTE_STROKES = 64`, `POSE_TICK_INTERVAL_MS = 50` (`20 Hz`),
        `SOFT_LOCK_TTL_MS = 2000`.

--------------------------------------------------------------------------------

## 5. Closed-Loop CLI Diagnostics (`TL100–TL402`), Headless Contact Sheets & Scenario Simulation

Use `three-live-cli` to verify `.js`, `.html`, and `.glb` scenes without a
browser:

```bash
# 1. Validate syntax, schema, HTML attributes, and 3D spatial layout
three-live-cli validate scene.js --json

# 2. Render a 2x2 quad contact sheet (Camera, Front, Right, Top) with 1m grid & AABB labels
three-live-cli render scene.js -o preview.png --view=quad --grid --annotations

# 3. Render a 4-frame temporal filmstrip or animated GIF with KHR_interactivity onSelect trigger
three-live-cli render scene.js -o anim.png --frames=4 --duration=2.0 --trigger-select=crystal

# 4. Run a 60Hz deterministic scenario simulation
three-live-cli sim scene.js --duration=5.0 \
  --actions='[{"at":0.2,"type":"select","target":"crystal"},{"at":0.5,"type":"moveCharacter","direction":[0,0,-1],"duration":1.5}]' \
  --json
```

### Diagnostic Code Table (`TL100–TL402`)

Code    | Severity  | Condition                                                          | Actionable Fix
:------ | :-------- | :----------------------------------------------------------------- | :-------------
`TL100` | `error`   | Syntax error, runtime exception, or quota exceeded                 | Check `line`/`column` in JSON output and fix JS syntax or reduce vertex/mesh count.
`TL101` | `warning` | `ShaderMaterial` / `RawShaderMaterial` fallback                    | Replace with `THREE.MeshStandardMaterial` or `THREE.MeshPhysicalMaterial`.
`TL102` | `warning` | Polyhedron/Tube geometry fallback                                  | Use `SphereGeometry`, `CylinderGeometry`, `ExtrudeGeometry`, `LatheGeometry`, or `THREE.CSG`.
`TL103` | `warning` | `THREE.GLTFLoader` / `TextureLoader` / `fetch`                     | Load external `.glb` via `<three-live src="model.glb">` or `<xr-anchor src="model.glb">`.
`TL104` | `info`    | `requestAnimationFrame` in static export                           | Use `userData.xr.orbit` or `userData.interactivity` so motion survives `.glb`/`.usdz` export.
`TL105` | `warning` | Unknown `THREE.*` constructor/method                               | Remove unsupported Three.js helper call.
`TL201` | `warning` | Unknown `userData.xr` or `userData.interactivity` key              | Apply the Levenshtein suggestion in `suggestion` (e.g. `grabbable` -> `grab`).
`TL202` | `warning` | Out-of-range numeric trait clamped                                 | Keep `gaze.dwellMs` in `[200, 10000]`, `bloom.strength` in `[0, 5]`, `outline.thickness` in `[0.002, 0.25]`.
`TL203` | `error`   | Unsafe media/live/room URL or anchor ID                            | Use `https://` (or clean relative paths) for media, `wss://` for relays, and alphanumeric anchor IDs.
`TL204` | `error`   | Broken target node reference                                       | Ensure `orbit.target`, `ik.*`, `spawner.template`, and `interactivity.*.target` match an existing `mesh.name`.
`TL205` | `warning` | Unnamed interactive/spatial mesh                                   | Set a unique `mesh.name = "..."` before attaching `userData.xr` or `userData.interactivity`.
`TL301` | `error`   | Empty scene (`meshCount == 0`)                                     | Call `scene.add(mesh)` with at least one non-empty geometry.
`TL302` | `warning` | Camera inside mesh AABB                                            | Move camera outside `summary.worldBounds` or shrink the enclosing mesh.
`TL303` | `warning` | Mesh outside camera frustum or extreme framing                     | Reposition the mesh or adjust camera `position` / `lookAt` so `screenCoveragePct` is between `5%` and `85%`.
`TL304` | `warning` | Extreme scene scale (`< 0.01 m` or `> 200 m`)                      | Author dimensions in meters (`1 unit = 1 meter`); scale millimeter meshes by `0.001`.
`TL305` | `warning` | Unlit metallic PBR material                                        | Add a `DirectionalLight` / `AmbientLight` or set `environment` on `<three-live>`.
`TL306` | `warning` | Co-located sibling meshes (`> 80%` overlap)                        | Offset sibling positions or use `THREE.CSG.subtract(a, b)` for boolean cutouts.
`TL307` | `info`    | Floating or buried scene / character                               | Align `min.y` to `0.0` (`mesh.position.y = height / 2`) so AR/VR placement sits on the floor.
`TL401` | `error`   | Inline `<script type="text/three">` without `allow-client-scripts` | Add `allow-client-scripts` to `<three-live>` or `<xr-live>`.
`TL402` | `warning` | `<xr-live>` feature used on `<three-live>`                         | Upgrade the tag from `<three-live>` to `<xr-live>` and load `xr-live.min.js`.
````

## File: skills/three-live-authoring/references/recipes.md
size: 20795
sha: 84af27c9f71bf7173719bb03431c59ca1e2edaad
upstream: https://github.com/google/three-live/blob/main/skills/three-live-authoring/references/recipes.md

````text
# Copy-Paste Recipes for `<three-live>` and `<xr-live>`

All 9 recipes below use features available in the repository today and work
without external build steps.

---

## Recipe 1: Interactive 3D Product Configurator (`<three-live>` + `KHR_interactivity` + Hotspots)

```html
<script type="module" src="/dist/three-live-full.min.js"></script>

<three-live
  allow-client-scripts
  camera-controls
  auto-rotate
  ar
  shadow-intensity="0.8"
  shadow-softness="0.6"
  tone-mapping="neutral"
  style="width: 100%; height: 520px; display: block;">

  <script type="text/three">
    const pedestal = new THREE.Mesh(
      new THREE.CylinderGeometry(0.55, 0.65, 0.14, 48),
      new THREE.MeshStandardMaterial({ color: 0x1e293b, metalness: 0.7, roughness: 0.25 })
    );
    pedestal.name = 'pedestal';
    pedestal.position.set(0, -0.35, 0);
    scene.add(pedestal);

    const watchCase = new THREE.Mesh(
      new THREE.TorusGeometry(0.32, 0.09, 32, 64),
      new THREE.MeshStandardMaterial({ color: 0x38bdf8, metalness: 0.85, roughness: 0.15 })
    );
    watchCase.name = 'watch-case';
    watchCase.position.set(0, 0.15, 0);
    // Compile-to-GLB KHR_interactivity behavior on click/tap:
    watchCase.userData.interactivity = {
      onSelect: [
        {
          action: 'cycleMaterialColor',
          colors: [
            [0.22, 0.74, 0.97, 1.0],
            [0.96, 0.62, 0.04, 1.0],
            [0.66, 0.33, 0.97, 1.0]
          ],
          duration: 0.3
        },
        {
          action: 'toggleTransform',
          property: 'scale',
          from: [1, 1, 1],
          to: [1.18, 1.18, 1.18],
          duration: 0.25
        }
      ]
    };
    scene.add(watchCase);

    const keyLight = new THREE.DirectionalLight(0xffffff, 2.2);
    keyLight.position.set(2, 4, 3);
    scene.add(keyLight);
    scene.add(new THREE.AmbientLight(0xffffff, 0.6));
  </script>

  <button slot="hotspot-case" data-position="0 0.45 0.1" data-normal="0 1 0">
    Tap Ring to Cycle Finish
  </button>
</three-live>
```

---

## Recipe 2: Spatial UI Card & Depth-Physics Ballpit (`<xr-live>`)

```html
<script type="module" src="/dist/xr-live-full.min.js"></script>

<xr-live
  allow-client-scripts
  xr-mode="ar"
  xr-depth="occlusion-physics"
  xr-hands="gestures"
  xr-simulator="living-room"
  sound-feedback
  camera-controls
  style="width: 100%; height: 600px; display: block;">

  <script type="text/three">
    const palette = [0x38bdf8, 0xf43f5e, 0x22c55e, 0xeab308, 0xa855f7];
    for (let i = 0; i < 12; i++) {
      const ball = new THREE.Mesh(
        new THREE.SphereGeometry(0.08, 24, 24),
        new THREE.MeshStandardMaterial({
          color: palette[i % palette.length],
          metalness: 0.2,
          roughness: 0.25
        })
      );
      ball.name = `ball-${i}`;
      ball.position.set((i % 4 - 1.5) * 0.22, 1.3 + Math.floor(i / 4) * 0.22, -1.1);
      ball.userData.xr = {
        grab: '1-hand',
        physics: 'dynamic',
        restitution: 0.78
      };
      scene.add(ball);
    }

    const light = new THREE.DirectionalLight(0xffffff, 2.0);
    light.position.set(1, 3, 2);
    scene.add(light);
  </script>

  <div slot="spatial" data-position="0.55 1.25 -1.1" data-xr-traits="grab billboard">
    <div style="padding: 16px; background: #0f172a; color: #f8fafc; border-radius: 14px; width: 220px;">
      <h4 style="margin: 0 0 8px;">Physics Controls</h4>
      <p style="margin: 0 0 12px; font-size: 13px;">Grab spheres or bounce them off real-world surfaces.</p>
      <button onclick="document.querySelector('xr-live').transitionToVR({ durationMs: 400 })">
        Toggle VR Environment
      </button>
    </div>
  </div>
</xr-live>
```

---

## Recipe 3: Precision Manipulation Handles, Lazy Head-Follow HUD & Orbiting Satellites

```html
<script type="module" src="/dist/xr-live-full.min.js"></script>

<xr-live
  allow-client-scripts
  xr-simulator="office"
  camera-controls
  style="width: 100%; height: 560px; display: block;">

  <script type="text/three">
    // Centerpiece with 4 corner scale handles + pedestal yaw rotation bar
    const sculpture = new THREE.Mesh(
      new THREE.TorusKnotGeometry(0.22, 0.07, 64, 16),
      new THREE.MeshStandardMaterial({ color: 0x6366f1, metalness: 0.7, roughness: 0.2 })
    );
    sculpture.name = 'sculpture';
    sculpture.position.set(0, 0.9, -1.2);
    sculpture.userData.xr = {
      grab: '2-hand',
      handles: { rotateAxis: 'y', minScale: 0.4, maxScale: 2.5 }
    };
    scene.add(sculpture);

    // Satellite orbiting the named 'sculpture' node
    const orbiter = new THREE.Mesh(
      new THREE.SphereGeometry(0.05, 24, 24),
      new THREE.MeshStandardMaterial({ color: 0x38bdf8, emissive: 0x0284c7 })
    );
    orbiter.name = 'orbiter';
    orbiter.userData.xr = {
      orbit: { target: 'sculpture', radius: 0.45, speed: 1.2, height: 0.08, faceCenter: true }
    };
    scene.add(orbiter);

    // Lazy head-follow status pill with 18-degree angular deadzone
    const hudPill = new THREE.Mesh(
      new THREE.BoxGeometry(0.28, 0.08, 0.02),
      new THREE.MeshStandardMaterial({ color: 0x0f172a, roughness: 0.4 })
    );
    hudPill.name = 'hud-pill';
    hudPill.userData.xr = {
      follow: {
        mode: 'head',
        lazy: true,
        distance: 1.1,
        deadzoneDeg: 18,
        stiffness: 6,
        height: -0.22,
        faceUser: true
      }
    };
    scene.add(hudPill);
  </script>
</xr-live>
```

---

## Recipe 4: Multimodal Gemini Live Assistant + Hold-to-Ask + World Understanding

```html
<script type="module">
  import '/dist/xr-live-full.min.js';
  import { connectGeminiLive } from '/dist/xr-live-spatial.min.js';

  const xr = document.getElementById('gemini-xr');

  xr.addEventListener('xr-transcription', (e) => {
    console.log(`[${e.detail.speaker}] ${e.detail.text}`);
  });

  xr.addEventListener('xr-object-detected', (e) => {
    console.log(`Located ${e.detail.label} at`, e.detail.position);
  });

  // Connect only after user gesture (never on page load):
  document.getElementById('connect-btn').addEventListener('click', () => {
    connectGeminiLive(xr, {
      url: 'wss://your-proxy.example.com/gemini-live',
      frameIntervalMs: 1000,
      streamAudio: true,
      playAudio: true,
      detectObjects: true
    });
  });
</script>

<button id="connect-btn">Start Gemini Live Session</button>

<xr-live
  id="gemini-xr"
  allow-client-scripts
  world-understanding="planes reticle"
  xr-depth="occlusion"
  camera-controls
  style="width: 100%; height: 560px; display: block;">
  <script type="text/three">
    const artifact = new THREE.Mesh(
      new THREE.CylinderGeometry(0.18, 0.22, 0.4, 32),
      new THREE.MeshStandardMaterial({ color: 0xf59e0b, metalness: 0.6, roughness: 0.3 })
    );
    artifact.name = 'turbine-core';
    artifact.position.set(0, 1.0, -1.0);
    artifact.userData.xr = {
      grab: '1-hand',
      holdToAsk: {
        prompt: 'Explain the role of this turbine core and inspect its orientation.',
        holdMs: 600
      }
    };
    scene.add(artifact);
  </script>
</xr-live>
```

---

## Recipe 5: 3D Spatial Paint, Depth Particles & Gaussian Splats

```html
<script type="module" src="/dist/xr-live-full.min.js"></script>

<xr-live
  allow-client-scripts
  spatial-paint="#38bdf8"
  xr-depth="occlusion"
  xr-simulator="tabletop"
  camera-controls
  style="width: 100%; height: 560px; display: block;">

  <script type="text/three">
    // Depth-colliding snow emitter volume
    const snowVolume = new THREE.Mesh(
      new THREE.BoxGeometry(0.01, 0.01, 0.01),
      new THREE.MeshBasicMaterial({ color: 0xffffff })
    );
    snowVolume.name = 'snow-emitter';
    snowVolume.position.set(0, 1.4, -1.2);
    snowVolume.userData.xr = {
      particles: { preset: 'snow', count: 500, area: [2.5, 2.0, 2.5], speed: 0.9 }
    };
    scene.add(snowVolume);

    // 3D Gaussian Splat node (.splat or .spz)
    const splatAnchor = new THREE.Group();
    splatAnchor.name = 'garden-splat';
    splatAnchor.position.set(0, 0.8, -1.2);
    splatAnchor.userData.xr = {
      grab: '2-hand',
      splatUrl: 'https://example.com/assets/bonsai.spz'
    };
    scene.add(splatAnchor);
  </script>
</xr-live>
```

---

## Recipe 6: Native Android (Kotlin) & iOS/visionOS (Swift) Integration

### Android (Google Filament + Jetpack XR SceneCore)

```kotlin
import com.google.threelive.ThreeLiveRuntimeSession
import com.google.threelive.XRLiveSceneCoreHelper
import com.google.threelive.filament.ThreeLiveFilament

// 1. Install the Filament renderer once at startup
ThreeLiveFilament.install()

// 2. Compile procedural Three.js and step XR traits / handles / particles natively
val session = ThreeLiveRuntimeSession.fromScript(scriptSource)
session.stepFrame(dtSeconds = 1f / 60f)

// 3. Or attach traits directly to an Android XR SceneCore entity from GLB bytes
XRLiveSceneCoreHelper.attachTraitsFromGlb(xrSession, rootEntity, glbByteBuffer)
```

### iOS & visionOS (Apple RealityKit)

```swift
import ThreeLiveCompiler
import RealityKit

@MainActor
func mountSpatialScene(script: String, in arView: ARView) async throws {
    let entity = try await RealityKitHelper.loadEntity(from: script)
    XRLiveRealityKit.installTraits(on: entity, in: arView)
}
```

--------------------------------------------------------------------------------

## Recipe 7: CAD Exploded View, Cross-Section Slicer, 3D Dimensions & Gaze Dwell

```html
<script type="module" src="/dist/xr-live-full.min.js"></script>

<xr-live
  allow-client-scripts
  explode="0.55"
  explode-mode="axial-y"
  section-plane="interactive"
  spatial-measure="all"
  measure-unit="mm"
  gaze-dwell="auto"
  dwell-time="950"
  camera-controls
  style="width: 100%; height: 560px; display: block;">
  <script type="text/three">
    const base = new THREE.Mesh(
      new THREE.CylinderGeometry(0.26, 0.3, 0.14, 36),
      new THREE.MeshStandardMaterial({ color: 0x334155, metalness: 0.8, roughness: 0.25 })
    );
    base.name = 'housing-base';
    base.position.set(0, 0.75, -1.1);
    base.userData.xr = {
      explode: false,
      dimensions: { unit: 'mm', axes: ['x', 'y', 'z'], color: '#38bdf8' }
    };
    scene.add(base);

    const shroud = new THREE.Mesh(
      new THREE.CylinderGeometry(0.24, 0.26, 0.14, 36),
      new THREE.MeshStandardMaterial({ color: 0x38bdf8, metalness: 0.65, roughness: 0.2 })
    );
    shroud.name = 'upper-shroud';
    shroud.position.set(0, 0.92, -1.1);
    shroud.userData.xr = {
      explode: { direction: [0, 1, 0], distance: 0.38, layer: 2, leaderLine: true },
      gaze: { dwellMs: 900, action: 'select' }
    };
    scene.add(shroud);

    scene.add(new THREE.DirectionalLight(0xffffff, 2.2));
  </script>
</xr-live>
```

--------------------------------------------------------------------------------

## Recipe 8: Magnetic Socket Snapping, `#xr-state` URL Persistence & XR Locomotion

```html
<script type="module" src="/dist/xr-live-full.min.js"></script>

<xr-live
  allow-client-scripts
  magnetic-snap="all"
  snap-grid="0.05"
  snap-angle="15"
  persistent-anchors="workbench"
  persist-url-hash
  locomotion="teleport snap-turn"
  snap-turn-deg="30"
  xr-simulator="office"
  camera-controls
  style="width: 100%; height: 560px; display: block;">
  <script type="text/three">
    const floor = new THREE.Mesh(
      new THREE.PlaneGeometry(4, 4),
      new THREE.MeshStandardMaterial({ color: 0x0f172a, roughness: 0.9 })
    );
    floor.name = 'walkable-floor';
    floor.rotation.x = -Math.PI / 2;
    floor.userData.xr = { navigable: 'walkable' };
    scene.add(floor);

    const socketPedestal = new THREE.Mesh(
      new THREE.CylinderGeometry(0.16, 0.18, 0.04, 32),
      new THREE.MeshStandardMaterial({ color: 0x1e293b })
    );
    socketPedestal.name = 'dock-socket';
    socketPedestal.position.set(0, 0.8, -1.1);
    socketPedestal.userData.xr = {
      snapSocket: { tag: 'bay-a', radius: 0.18, alignRotation: true, highlightColor: '#22c55e' }
    };
    scene.add(socketPedestal);

    const moduleCube = new THREE.Mesh(
      new THREE.BoxGeometry(0.18, 0.18, 0.18),
      new THREE.MeshStandardMaterial({ color: 0x6366f1, metalness: 0.5, roughness: 0.25 })
    );
    moduleCube.name = 'snap-module';
    moduleCube.position.set(0.35, 0.9, -1.1);
    moduleCube.userData.xr = {
      grab: '1-hand',
      snapTo: { socketTag: 'bay-a', radius: 0.18, grid: 0.05, angleDeg: 15 },
      anchor: { id: 'snap-module', persist: true }
    };
    scene.add(moduleCube);

    scene.add(new THREE.DirectionalLight(0xffffff, 2.0));
  </script>
</xr-live>
```

--------------------------------------------------------------------------------

## Recipe 9: Zero-Backend Multi-User Co-Presence & Shared Spatial Paint (`shared-room`)

```html
<script type="module" src="/dist/xr-live-full.min.js"></script>

<xr-live
  allow-client-scripts
  shared-room="studio-room-1"
  peer-name="Designer"
  peer-color="#38bdf8"
  spatial-paint="#38bdf8"
  camera-controls
  style="width: 100%; height: 560px; display: block;">
  <script type="text/three">
    const artifact = new THREE.Mesh(
      new THREE.TorusKnotGeometry(0.18, 0.055, 64, 16),
      new THREE.MeshStandardMaterial({ color: 0xa855f7, metalness: 0.65, roughness: 0.2 })
    );
    artifact.name = 'shared-artifact';
    artifact.position.set(0, 1.0, -1.1);
    artifact.userData.xr = {
      grab: '2-hand',
      handles: { rotateAxis: 'y', minScale: 0.4, maxScale: 2.5 },
      sync: true
    };
    scene.add(artifact);

    scene.add(new THREE.DirectionalLight(0xffffff, 2.2));
  </script>
</xr-live>
```

--------------------------------------------------------------------------------

## Recipe 10: Timed Training Drill with a Safety Zone (`xr-live-sim`)

Ordered task steps, a countdown, and an alarm zone around a robot cell. Load
`xr-live-sim.min.js` (or use `xr-live-full.min.js`). Taps complete steps in
order; out-of-order taps play an `error` cue.

```html
<!-- Load after xr-live.min.js; xr-live-full.min.js already includes it. -->
<script src="/dist/xr-live-sim.min.js"></script>

<xr-live
  id="drill"
  allow-client-scripts
  objectives
  scenario-timer="60"
  synth-audio
  style="width: 100%; height: 520px; display: block;">
  <script type="text/three">
    const mat = (color) => new THREE.MeshStandardMaterial({ color, roughness: 0.4 });

    // Ordered, required task steps (tap them in sequence)
    ['Step_1_Valve', 'Step_2_Filter', 'Step_3_Cap'].forEach((name, i) => {
      const part = new THREE.Mesh(new THREE.BoxGeometry(0.2, 0.2, 0.2), mat(0x38bdf8));
      part.name = name;
      part.position.set(i * 0.4 - 0.4, 1.0, -1.0);
      part.userData.xr = {
        objective: { type: 'checkpoint', order: i + 1, required: true, amount: 10 },
        audioCues: { onObjective: 'confirm' }
      };
      scene.add(part);
    });

    // Robot cell: alarm while the AGV is inside
    const cell = new THREE.Mesh(
      new THREE.BoxGeometry(1.2, 1, 1.2),
      new THREE.MeshStandardMaterial({ color: 0xef4444, transparent: true, opacity: 0.15 })
    );
    cell.name = 'Robot_Cell';
    cell.position.set(1.4, 0.5, -2);
    cell.userData.xr = {
      zone: { shape: 'box', size: [1.2, 1, 1.2], color: '#ef4444', watchGroups: ['agent'] },
      audioCues: { onZoneEnter: 'alarm' }
    };
    scene.add(cell);

    // AGV patrolling through the cell
    const agv = new THREE.Mesh(new THREE.BoxGeometry(0.4, 0.2, 0.6), mat(0xf59e0b));
    agv.name = 'AGV';
    agv.position.set(-1.5, 0.1, -2);
    agv.userData.xr = {
      agent: { mode: 'patrol', speed: 0.8, waypoints: [[-1.5, 0.1, -2], [2.5, 0.1, -2]] }
    };
    scene.add(agv);

    scene.add(new THREE.DirectionalLight(0xffffff, 2.2));
    scene.add(new THREE.AmbientLight(0xffffff, 0.6));
  </script>
</xr-live>

<script>
  const drill = document.getElementById('drill');
  drill.addEventListener('xrobjective', (e) => {
    if (e.detail.outOfOrder) console.warn('Out of order:', e.detail.nodeId);
  });
  drill.addEventListener('xrzoneenter', (e) => {
    console.log(e.detail.nodeId, 'entered', e.detail.zoneId);
  });
  drill.addEventListener('xrscenarioend', (e) => {
    console.log('Outcome:', e.detail.outcome, 'in', e.detail.elapsedSec, 's');
  });
</script>
```

--------------------------------------------------------------------------------

## Recipe 11: Procedural CAD Extrusion, CSG Booleans, 3D Text & GPU Instancing (`<three-live>`)

```html
<script type="module" src="/dist/three-live.min.js"></script>

<three-live
  allow-client-scripts
  camera-controls
  auto-rotate
  ar
  tone-mapping="aces"
  bloom="1.2"
  outline="#38bdf8 0.025"
  style="width: 100%; height: 520px; display: block;">
  <script type="text/three">
    const profile = new THREE.Shape();
    profile.absarc(0, 0, 0.55, 0, Math.PI * 2, false);
    const hole = new THREE.Path();
    hole.absarc(0, 0, 0.22, 0, Math.PI * 2, true);
    profile.holes.push(hole);

    const steel = new THREE.MeshStandardMaterial({ color: 0x94a3b8, metalness: 0.78, roughness: 0.24 });
    const rawFlange = new THREE.Mesh(
      new THREE.ExtrudeGeometry(profile, { depth: 0.16, bevelEnabled: true, bevelThickness: 0.02, bevelSize: 0.015 }),
      steel
    );
    rawFlange.rotation.x = -Math.PI / 2;

    const slotCutter = new THREE.Mesh(new THREE.BoxGeometry(1.3, 0.14, 0.16), steel);
    slotCutter.position.set(0, 0.12, 0);
    const machined = THREE.CSG.subtract(rawFlange, slotCutter);
    machined.name = 'machined-flange';
    machined.userData.xr = { outline: { color: '#38bdf8', thickness: 0.02 } };
    scene.add(machined);

    const label = new THREE.Mesh(
      new THREE.TextGeometry('CAD R1', { size: 0.14, depth: 0.035, bevelEnabled: true }),
      new THREE.MeshStandardMaterial({ color: 0xf8fafc, emissive: 0x0ea5e9, emissiveIntensity: 0.45 })
    );
    label.position.set(-0.32, 0.28, 0);
    scene.add(label);

    const bolts = new THREE.InstancedMesh(
      new THREE.CylinderGeometry(0.035, 0.035, 0.22, 16),
      new THREE.MeshStandardMaterial({ color: 0xf59e0b, metalness: 0.9, roughness: 0.15 }),
      12
    );
    const m = new THREE.Matrix4();
    const p = new THREE.Vector3();
    const q = new THREE.Quaternion();
    const s = new THREE.Vector3(1, 1, 1);
    for (let i = 0; i < 12; i++) {
      const a = (i / 12) * Math.PI * 2;
      p.set(Math.cos(a) * 0.39, 0.09, Math.sin(a) * 0.39);
      m.compose(p, q, s);
      bolts.setMatrixAt(i, m);
    }
    scene.add(bolts);

    scene.add(new THREE.DirectionalLight(0xffffff, 2.4));
    scene.add(new THREE.AmbientLight(0xffffff, 0.6));
  </script>
</three-live>
```

--------------------------------------------------------------------------------

## Recipe 12: Articulated Robotic Arm with 2-Bone / FABRIK IK & Voice Signaling (`<xr-live>`)

```html
<script type="module" src="/dist/xr-live-full.min.js"></script>

<xr-live
  allow-client-scripts
  bloom="1.3"
  outline="#38bdf8 0.025"
  tone-mapping="agx"
  shared-room="robotics-cell"
  shared-room-voice
  camera-controls
  style="width: 100%; height: 540px; display: block;">
  <script type="text/three">
    const armMat = new THREE.MeshStandardMaterial({ color: 0x64748b, metalness: 0.8, roughness: 0.25 });
    const shoulder = new THREE.Group();
    shoulder.name = 'Shoulder';
    shoulder.position.set(0, 0.75, -1.1);
    const upper = new THREE.Mesh(new THREE.BoxGeometry(0.08, 0.08, 0.32), armMat);
    upper.position.set(0, 0, 0.16);
    shoulder.add(upper);

    const forearm = new THREE.Group();
    forearm.name = 'Forearm';
    forearm.position.set(0, 0, 0.32);
    const lower = new THREE.Mesh(new THREE.BoxGeometry(0.065, 0.065, 0.28), armMat);
    lower.position.set(0, 0, 0.14);
    forearm.add(lower);
    shoulder.add(forearm);

    const wrist = new THREE.Mesh(
      new THREE.SphereGeometry(0.055, 20, 20),
      new THREE.MeshStandardMaterial({ color: 0x38bdf8, emissive: 0x0284c7, emissiveIntensity: 0.6 })
    );
    wrist.name = 'WristEffector';
    wrist.position.set(0, 0, 0.28);
    wrist.userData.xr = {
      ik: { root: 'Shoulder', mid: 'Forearm', effector: 'WristEffector', target: 'GripperTarget', pole: 'ElbowPole' }
    };
    forearm.add(wrist);
    scene.add(shoulder);

    const pole = new THREE.Group();
    pole.name = 'ElbowPole';
    pole.position.set(0, 1.35, -0.95);
    scene.add(pole);

    const target = new THREE.Mesh(
      new THREE.SphereGeometry(0.065, 24, 24),
      new THREE.MeshStandardMaterial({ color: 0x22c55e, emissive: 0x16a34a, emissiveIntensity: 0.8 })
    );
    target.name = 'GripperTarget';
    target.position.set(0.22, 1.02, -0.78);
    target.userData.xr = { grab: '1-hand', outline: { color: '#22c55e', thickness: 0.025 } };
    scene.add(target);

    scene.add(new THREE.DirectionalLight(0xffffff, 2.2));
  </script>
</xr-live>
```
````

## File: skills/three-live-authoring/references/xr-traits-and-plugins.md
size: 26256
sha: 21dff42ec00a6e3ad44b3d29c2deb16a9272e97e
upstream: https://github.com/google/three-live/blob/main/skills/three-live-authoring/references/xr-traits-and-plugins.md

````text
# `<three-live>` & `<xr-live>` Complete Traits, Plugins & Events Reference

## 1. `<xr-live>` Host Attributes

`<xr-live>` inherits every `<three-live>` attribute (`src`, `ios-src`, `poster`, `scale`, `camera-orbit`, `camera-target`, `min-camera-orbit`, `max-camera-orbit`, `field-of-view`, `selected-mesh`, `camera-controls`, `ar`, `ar-modes`, `ar-scale`, `ar-placement`, `script-src`, `sandbox`, `allow-client-scripts`, `exposure`, `environment-image`, `skybox-image`, `shadow-intensity`, `shadow-softness`, `tone-mapping`, `autoplay`, `animation-name`, `auto-rotate`) and adds:

Attribute             | Values                                                                                         | Default     | Description
:-------------------- | :--------------------------------------------------------------------------------------------- | :---------- | :----------
`xr-mode`             | `'ar' \| 'vr' \| 'inline' \| 'auto'`                                                           | `'auto'`    | Target WebXR session mode.
`xr-depth`            | `'occlusion' \| 'occlusion-physics' \| 'mesh' \| 'none'`                                       | `'none'`    | Hardware depth occlusion and analytical heightfield physics collision.
`xr-hands`            | `'gestures' \| 'joints' \| 'pinch' \| 'none'`                                                  | `'none'`    | 25-joint `XRHand` tracking and gesture classification (`pinch`, `grab`, `point`, `palm-up`).
`xr-simulator`        | `'living-room' \| 'office' \| 'tabletop' \| 'none'`                                            | `'none'`    | Enables the desktop 6DoF keyboard/mouse simulator with room floor/table planes.
`xr-profile`          | `'quest3' \| 'android-xr' \| 'visionos' \| 'auto'`                                             | `'auto'`    | Target hardware profile hint.
`sound-feedback`      | boolean attribute                                                                              | `false`     | Plays procedural Web Audio earcons (`grab`, `release`, `bounce`, `hover`) on interaction.
`world-understanding` | `'' \| 'planes' \| 'planes reticle' \| 'false'`                                                | —           | Activates `xr-live-world-understanding` plane/mesh tracking and optional gaze reticle.
`spatial-paint`       | `'' \| '#rrggbb' \| 'false'`                                                                   | —           | Activates `xr-live-spatial-paint`; pinching in empty space extrudes Catmull-Rom 3D tube strokes.
`spatial-measure`     | `'' \| 'bounds' \| 'tape' \| 'all' \| 'none'`                                                  | —           | Activates `xr-live-spatial-measure` 3D dimension callouts and/or interactive AR tape measure.
`measure-unit`        | `'auto' \| 'm' \| 'cm' \| 'mm' \| 'in' \| 'ft-in'`                                             | `'auto'`    | Default display unit for `spatial-measure`.
`magnetic-snap`       | `'' \| 'grid' \| 'surface' \| 'sockets' \| 'all' \| 'none'`                                    | —           | Activates `xr-live-magnetic-snap` socket, grid, surface, and yaw snapping.
`snap-grid`           | `number` or `'gx gy gz'` (meters)                                                              | —           | Default Cartesian snap grid spacing in meters.
`snap-angle`          | `number` (`0..180` degrees)                                                                    | `0`         | Default rotational yaw snap increment in degrees.
`gaze-dwell`          | `'' \| 'auto' \| 'false' \| 'none'`                                                            | —           | Activates `xr-live-gaze-dwell` hands-free eye/head gaze reticle and radial dwell selection.
`dwell-time`          | `number` (`250..10000` ms)                                                                     | `1200`      | Default dwell duration in milliseconds for `gaze-dwell`.
`explode`             | `number` (`0..1`)                                                                              | `0`         | Normalized multi-part assembly explosion factor (`xr-live-exploded-view`).
`explode-mode`        | `'radial' \| 'axial-x' \| 'axial-y' \| 'axial-z' \| 'hierarchical'`                            | `'radial'`  | Automatic explosion vector strategy when parts omit `userData.xr.explode.direction`.
`explode-scale`       | `number`                                                                                       | `1.0`       | Multiplier applied to per-part explosion distances.
`section-plane`       | `'none' \| 'x:<d>' \| 'y:<d>' \| 'z:<d>' \| '-x:<d>' \| '-y:<d>' \| '-z:<d>' \| 'interactive'` | `'none'`    | Real-time GPU cross-section clipping plane in scene (model) space (`d` in meters; the cut follows the model through AR placement and turntable rotation) with optional draggable gizmo frame.
`persistent-anchors`  | `''` or `string` (namespace)                                                                   | —           | Activates `xr-live-persistent-anchors` cross-session transform persistence (`xr-live:anchors:<ns>`).
`persist-url-hash`    | boolean attribute                                                                              | `false`     | Encodes persisted node poses into `#xr-state=<base64url>` (`<= 8192` bytes) for link sharing.
`locomotion`          | `'' \| 'teleport' \| 'snap-turn' \| 'smooth' \| 'teleport snap-turn' \| 'none'`                | —           | Activates `xr-live-spatial-locomotion` parabolic teleportation, snap-turns, or smooth glide.
`snap-turn-deg`       | `number` (degrees)                                                                             | `30`        | Horizontal thumbstick snap-turn increment in degrees.
`comfort-vignette`    | boolean attribute                                                                              | `true`      | Shows a `120ms` peripheral FOV comfort vignette during teleports and snap-turns.
`shared-room`         | `'<room-id>'` or `'wss://...'`                                                                 | —           | Joins a multi-user room via `BroadcastChannel("xr-live:room:<id>")` or a `wss://` relay (`xr-live-shared-room`).
`shared-room-voice`   | boolean attribute                                                                              | `false`     | Opts in to voice **signaling** in `shared-room`: relays WebRTC offer/answer/ICE messages (`peerrtcsignal` event, `broadcastRtcSignal()`) and computes per-peer `voiceGain` (`computeSpatialVoiceGain`). Your app owns `getUserMedia`, `RTCPeerConnection`, and audio playback.
`peer-name`           | `string` (max `32` chars)                                                                      | —           | Local peer display name broadcast in `shared-room`.
`peer-color`          | `'#rrggbb'`                                                                                    | `'#38bdf8'` | Local peer 3D visor & laser ray tint color in `shared-room`.
`bloom`               | `boolean \| string`                                                                            | —           | Enables HDR emissive bloom (`bloom`, `bloom="1.4"`, or `bloom="strength:1.2 threshold:0.75 radius:0.5"`).
`outline`             | `boolean \| string`                                                                            | —           | Enables silhouette outlines on `selected-mesh` or nodes with `userData.xr.outline` (`outline="#38bdf8 0.03"`).
`variant-name`        | `string`                                                                                       | —           | Selects active `KHR_materials_variants` colorway name (`viewer.variantName` / `viewer.availableVariants`).
`webmcp`              | boolean attribute                                                                              | `false`     | Registers `inspect_xr_scene`, `place_xr_object_at_gaze`, and `capture_xr_view` on `navigator.modelContext`.
`webmcp-allow-depth`  | boolean attribute                                                                              | `false`     | Opt-in gate allowing `capture_xr_view` to include the 8×8 metric `depthGridMeters` array.
`webmcp-omit-pose`    | boolean attribute                                                                              | `false`     | When present, `inspect_xr_scene` omits `headPosition` entirely.

---

## 2. Canonical `userData.xr` Normalization & Clamping Rules

Defined in `three-live/src/xr-trait-schema.ts`:

### `follow` (`LazyFollowOptions`)

```ts
mesh.userData.xr = {
  follow: {
    mode: 'head',        // 'head' | 'hand-left' | 'hand-right' (default: 'head')
    lazy: true,          // false uses eager spring; true uses angular deadzone + critically damped spring
    distance: 1.0,       // [0.1, 10.0] meters (default: 1.0 for 'head', 0.15 for hands)
    deadzoneDeg: 15,     // [0, 90] degrees (default: 15 for 'head', 0 for hands)
    stiffness: 6,        // [0.5, 40] angular frequency omega (default: 6)
    height: -0.1,        // [-2.0, 2.0] vertical offset in meters (default: -0.1 for 'head', 0.12 for hands)
    faceUser: true,      // boolean (default: true)
    snapOnStart: true,   // boolean (default: true)
  },
};
```

### `orbit` (`OrbitOptions`)

```ts
mesh.userData.xr = {
  orbit: {
    target: 'sun',       // [x, y, z] finite tuple OR target mesh name (max 256 chars; default: [0, 0, 0])
    radius: 0.5,         // [0.01, 50] meters (default: 0.5)
    speed: 0.5,          // [-20, 20] radians/sec (default: 0.5)
    height: 0.0,         // [-10, 10] meters vertical offset from target (default: 0)
    phase: 0.0,          // [-1e6, 1e6] initial angle in radians (default: 0)
    faceCenter: false,   // boolean (default: false)
  },
};
```

### `handles` (`HandlesOptions`)

```ts
mesh.userData.xr = {
  handles: {
    rotateAxis: 'y',     // 'y' | 'none' (default: 'y')
    minScale: 0.1,       // [0.001, 1000] (default: 0.1)
    maxScale: 10.0,      // [minScale, 1000] (default: max(minScale, 10))
  },
};
```

### `particles` (`ParticleOptions`)

```ts
mesh.userData.xr = {
  particles: {
    preset: 'rain',      // 'rain' | 'snow' | 'sparks' | 'confetti' (default: 'rain')
    count: 600,          // [1, 2000] (defaults: rain=600, snow=400, sparks=300, confetti=300)
    area: [2, 2, 2],     // number or [x, y, z], each axis clamped to [0.05, 50] meters (default: [2, 2, 2])
    speed: 1.0,          // [0.05, 10] speed multiplier (default: 1.0)
  },
};
```

### `holdToAsk` (`HoldToAskOptions`)

```ts
mesh.userData.xr = {
  holdToAsk: {
    prompt: 'What is this?', // max 4000 chars (default: 'What is this?')
    holdMs: 600,             // [100, 5000] ms press-and-hold threshold (default: 600)
  },
};
```

### `dimensions` (`DimensionsOptions`)

```ts
mesh.userData.xr = {
  dimensions: {
    enabled: true,           // false disables (default: true)
    unit: 'auto',            // 'auto' | 'm' | 'cm' | 'mm' | 'in' | 'ft-in' (default: 'auto')
    axes: ['x', 'y', 'z'],   // subset of ['x', 'y', 'z'] or string 'xyz' (default: ['x', 'y', 'z'])
    color: '#38bdf8',        // sanitized #rgb / #rrggbb hex color (default: '#38bdf8')
    showOnSelect: false,     // when true, only displays callouts while selected (default: false)
  },
};
```

### `snapTo` & `snapSocket` (`SnapToOptions` / `SnapSocketOptions`)

```ts
// On the movable / grabbable part:
part.userData.xr = {
  grab: '1-hand',
  snapTo: {
    grid: [0.05, 0.05, 0.05], // number or [gx, gy, gz] clamped to [0.001, 100] m (default: null)
    angleDeg: 15,             // [0, 180] yaw snap increment in degrees (default: 0)
    surface: 'floor',         // 'none' | 'floor' | 'wall' | 'ceiling' | 'any' (default: 'none')
    socketTag: 'module-bay',  // max 128 chars matching a snapSocket.tag (default: '')
    radius: 0.15,             // [0.01, 2.0] m capture radius; 1.25x breakaway hysteresis (default: 0.15)
  },
};

// On the stationary target socket:
dock.userData.xr = {
  snapSocket: {
    tag: 'module-bay',        // required non-empty tag (max 128 chars)
    radius: 0.15,             // [0.01, 2.0] m capture radius; 1.5x pulsing preview ring (default: 0.15)
    alignRotation: true,      // slerps snapped part to socket orientation (default: true)
    highlightColor: '#22c55e',// sanitized hex color for preview ring (default: '#22c55e')
  },
};
```

### `gaze` (`GazeOptions`)

```ts
mesh.userData.xr = {
  gaze: {
    enabled: true,           // false disables (default: true)
    dwellMs: 1200,           // [250, 10000] ms after 150ms grace delay (default: 1200)
    repeat: false,           // when true, re-arms continuously while gazing (default: false)
    action: 'select',        // 'select' (fires meshclick + KHR_interactivity) | 'ask' (queries Gemini Live)
  },
};
```

### `explode` (`ExplodeOptions`)

```ts
mesh.userData.xr = {
  explode: {
    enabled: true,           // false pins a base/chassis mesh at rest (default: true)
    direction: [0, 1, 0],    // normalized [x, y, z] unit vector, or null to use explode-mode
    distance: 0.35,          // [0, 10] meters at explode="1" (default: 0.35)
    layer: 2,                // integer [1, 10] — outer layers separate earlier in staggered mode (default: 1)
    leaderLine: true,        // renders dashed 3D leader line back to rest position (default: true)
  },
};
```

### `anchor` Persistence (`AnchorPersistOptions`), `navigable`, & `sync`

```ts
mesh.userData.xr = {
  anchor: {
    target: 'table',         // optional: 'floor' | 'wall' | 'ceiling' | 'table' | 'horizontal' | 'vertical'
    id: 'turntable-1',       // sanitized key (max 128 chars; rejects __proto__/constructor/prototype)
    persist: true,           // persists across #xr-state URL hash, localStorage, and WebXR XRAnchor
  },
  navigable: 'walkable',     // true | 'walkable' | false | 'blocked' (spatial-locomotion)
  sync: true,                // boolean (shared-room; defaults to true on grabbable nodes)
};
```

### `bloom`, `outline`, `ik`, `splat`, & `text` (`BloomTraitOptions` / `OutlineTraitOptions` / `IKTraitOptions` / `SplatTraitOptions` / `TextTraitOptions`)

```ts
mesh.userData.xr = {
  bloom: {
    strength: 1.2,           // [0, 5] HDR bloom intensity (default: 1.0)
    threshold: 0.8,          // [0, 2] luminance threshold (default: 0.8)
    radius: 0.5,             // [0, 1] blur radius (default: 0.5)
  },
  outline: {
    color: '#38bdf8',        // sanitized #rgb / #rrggbb hex color (default: '#38bdf8')
    thickness: 0.03,         // [0.002, 0.25] outline width (default: 0.03)
  },
  ik: {
    root: 'Shoulder',        // required chain root node name
    mid: 'Forearm',          // optional middle joint (enables the two-bone solver)
    effector: 'WristEffector', // required end-effector node name
    target: 'GripperTarget', // required node name, 'head' / 'hand-left' / 'hand-right', or [x, y, z]
    pole: 'ElbowPole',       // optional pole node name or [x, y, z] (alias: poleTarget)
    solver: 'two-bone',      // 'two-bone' | 'fabrik' (default: 'two-bone' with mid, else 'fabrik')
    iterations: 8,           // integer [1, 32] for FABRIK (default: 8)
    tolerance: 0.001,        // [1e-5, 0.1] convergence tolerance in meters (default: 0.001)
    weight: 1,               // [0, 1] blend toward the solved pose (default: 1)
  },
  splat: {
    url: '/assets/room.spz', // safe https:// or clean relative .splat/.spz URL
    shDegree: 3,             // 0 | 1 | 2 | 3 Spherical Harmonics degree (default: 3)
    maxSplats: 500000,       // [1, 1000000] splat cap
  },
  text: {
    text: 'STAGE 1',         // max 256 chars
    size: 0.2,               // [0.01, 20] glyph height in meters (default: 0.2)
    depth: 0.04,             // [0.001, 10] extrusion depth in meters (default: 0.04)
    bevelEnabled: true,
    bevelThickness: 0.008,
    bevelSize: 0.006,
  },
};
```

---

## 3. Declarative `KHR_interactivity` Authoring (`userData.interactivity`)

Any mesh or group inside `<script type="text/three">` can declare interactive state machines compiled into standard Khronos `KHR_interactivity` graphs (`three-live/src/interactivity-compiler.ts`):

- **Triggers:**
  - `onSelect`: Fired when clicked/tapped or pinched in XR (`pointer/onSelect`).
  - `onHoverIn` / `onHoverOut`: Fired on pointer/ray hover enter and exit.
  - `onStart`: Fired automatically when the scene loads (`event/onStart`).
  - `onReceive`: `{ [eventName: string]: Action | Action[] }` — reacts to custom events sent by `sendEvent`.
- **Actions (single object or array executed in sequence):**
  - `{ action: 'toggleTransform', property: 'translation' | 'rotation' | 'scale', to: number[], from?: number[], duration?: number }`
  - `{ action: 'interpolate', target?: string, property: 'translation' | 'rotation' | 'scale' | 'baseColorFactor' | 'metallicFactor' | 'roughnessFactor' | 'emissiveFactor', to: number | number[], duration?: number }`
  - `{ action: 'setProperty', target?: string, property: string, value: any }`
  - `{ action: 'toggleVisibility', target?: string }`
  - `{ action: 'cycleMaterialColor', colors: Array<[number, number, number, number?]>, duration?: number }`
  - `{ action: 'playAnimation', animation?: number }` / `{ action: 'stopAnimation' }`
  - `{ action: 'sendEvent', event: string, values?: Record<string, any> }`

---

## 4. Programmatic Plugin Controllers (`xr-live/spatial`)

When importing from `xr-live/spatial` (or using `xr-live-spatial.min.js` /
`xr-live-full.min.js`):

- **Gemini Live (`gemini-live.ts`):**

    ```ts
    import { connectGeminiLive } from 'xr-live/spatial';

    const live = connectGeminiLive(xrElement, {
      url: 'wss://your-backend.example.com/gemini-live', // wss:// required (or ws://localhost)
      model: 'models/gemini-2.0-flash-exp',
      systemInstruction: 'You are a spatial assistant.',
      frameIntervalMs: 1000,   // clamped to [250, 60000] ms
      streamAudio: true,       // streams 16 kHz PCM mic chunks
      playAudio: true,         // plays streamed 24 kHz PCM model audio
      speakReplies: false,     // SpeechSynthesis fallback
      detectObjects: true,     // auto-registers report_objects tool -> xr-object-detected events
    });
    ```
- **Spatial Paint (`spatial-paint.ts`):**

    ```ts
    import { getSpatialPaintController } from 'xr-live/spatial';

    const paint = getSpatialPaintController(xrElement);
    paint.color = [0.22, 0.74, 0.97, 1.0];
    paint.radius = 0.008;
    paint.undo(xrElement.viewer);
    paint.clear(xrElement.viewer);
    ```
- **World Understanding (`world-understanding.ts`):**

    ```ts
    import { detectObjects, parseDetections, XRTapeMeasure } from 'xr-live/spatial';

    const detections = parseDetections('[{"label":"chair","box":[200,300,800,700]}]');
    const located3D = detectObjects(xrElement, detections);
    ```
-   **Spatial Measure, Exploded View, Persistent Anchors, Locomotion & Shared
    Room:**

    ```ts
    import {
      getSpatialMeasureController,
      getMagneticSnapController,
      getGazeDwellController,
      getExplodedViewController,
      getPersistentAnchorsController,
      getSpatialLocomotionController,
      getSharedRoomController,
    } from 'xr-live/spatial';

    xrElement.setExplode(0.65);                     // Smoothly animate exploded-view [0..1]
    xrElement.clearMeasurements();                  // Clear locked 3D tape-measure segments
    const token = xrElement.exportAnchorState();    // Base64url layout snapshot (<= 8 KB)
    xrElement.importAnchorState(token);             // Restore layout snapshot programmatically
    xrElement.teleportTo([0, 0, -1.5]);             // Teleport viewer rig + emit xrteleport
    const peers = xrElement.getSharedPeers();       // Active RemotePeerState[] in shared-room
    ```

---

## 5. DOM Events Summary

Event Name                         | Dispatched By                | `event.detail` Payload
:--------------------------------- | :--------------------------- | :---------------------
`load`                             | `<three-live>` / `<xr-live>` | `{ model: GLBData }`
`error`                            | `<three-live>` / `<xr-live>` | `{ error: Error }`
`meshclick`                        | `<three-live>` / `<xr-live>` | `{ meshName, hitPoint, normal, distance }`
`camera-change`                    | `<three-live>` / `<xr-live>` | `{ theta, phi, distance }`
`ar-status`                        | `<three-live>` / `<xr-live>` | `{ status: 'session-started' \| 'not-presenting' \| 'failed', error? }`
`interactivityEvent`               | `KHR_interactivity` VM       | `{ id: string, values: Record<string, any> }`
`xr-select-start` / `move` / `end` | `XRInputManager`             | `{ hand: 'left' \| 'right' \| 'screen', pivotPosition, quaternion, rayOrigin, rayDirection, hit }`
`xr-handles-change`                | `manipulation-handles`       | `{ mesh, scale: number, yawDeg: number }`
`xr-object-detected`               | `world-understanding`        | `{ label: string, position: [number, number, number], distanceMeters: number, source: 'plane' \| 'depth' \| 'fallback' }`
`xr-transcription`                 | `gemini-live`                | `{ speaker: 'user' \| 'model', text: string, isFinal: boolean }`
`xr-hold-to-ask-listening`         | `gemini-live`                | `{ mesh: string }`
`xr-hold-to-ask`                   | `gemini-live`                | `{ mesh: string, transcript: string, prompt: string }`
`xr-gemini-interrupted`            | `gemini-live`                | `{}`
`xr-paint-stroke`                  | `spatial-paint`              | `{ index: number, points: number, lengthMeters: number }`
`measurecomplete`                  | `spatial-measure`            | `{ start: [x,y,z], end: [x,y,z], distanceMeters: number, formatted: string }`
`xrsnap`                           | `magnetic-snap`              | `{ node, socket, position: [x,y,z], quaternion: [x,y,z,w], mode: 'socket' \| 'grid' \| 'surface' \| 'angle' }`
`xrunsnap`                         | `magnetic-snap`              | `{ node, socket }`
`gazeenter` / `gazeleave`          | `gaze-dwell`                 | `{ node, point: [x,y,z] }` / `{ node }`
`gazedwell`                        | `gaze-dwell`                 | `{ node, point: [x,y,z], action: 'select' \| 'ask' }`
`explodechange`                    | `exploded-view`              | `{ factor: number, source: 'attribute' \| 'gesture' \| 'api' \| 'peer' }`
`anchorsrestored`                  | `persistent-anchors`         | `{ count: number, source: 'xr-anchor' \| 'storage' \| 'url-hash' }`
`xrteleport`                       | `spatial-locomotion`         | `{ from: [x,y,z], to: [x,y,z], yawDeg: number }`
`peerjoin` / `peerleave`           | `shared-room`                | `{ peerId: string, name: string, color: string }`
`peergrabconflict`                 | `shared-room`                | `{ peerId: string, nodeId: string }`
`peersync`                         | `shared-room`                | `{ peerId: string, nodeId: string }`
`characterjump` / `characterland`  | `xr-live-sim`                | `{ nodeId, position }` / `{ nodeId, fallSpeed }`
`agentstatechange` / `agentreach`  | `xr-live-sim`                | `{ nodeId, state, targetId }` / `{ agentId, targetId, position }`
`xrhit` / `xrdepleted`             | `xr-live-sim`                | `{ targetId, sourceId, amount, remaining, point }` / `{ targetId, group, scoreValue }`
`xrzoneenter` / `xrzoneexit`       | `xr-live-sim`                | `{ zoneId, nodeId, group }`
`xrspawn`                          | `xr-live-sim`                | `{ spawnerId, instanceId, index }`
`xrobjective`                      | `xr-live-sim`                | `{ nodeId, tag, type, amount, totalScore, remainingRequired, outOfOrder }`
`xrscorechange`                    | `xr-live-sim`                | `{ score, delta, attemptsLeft, timeRemaining }`
`xrscenarioend`                    | `xr-live-sim`                | `{ outcome: 'pass' \| 'fail' \| 'timeout', finalScore, elapsedSec }`
`xr-webmcp-capture`                | `xr-extras` (WebMCP)         | Fired when `capture_xr_view` captures a frame (`data-xr-webmcp-indicator="active"`).

--------------------------------------------------------------------------------

## 6. Simulation Plugins (`xr-live-sim`)

Load `xr-live-sim.min.js` (global `XRSim`, included in `xr-live-full.min.js`) or
import `xr-live/sim`. Systems step at a fixed 60 Hz (at most 5 steps per frame);
at most 128 spawned instances exist per scene.

Trait clamping (defaults in parentheses):

-   **`character`:** `speed` 0.1–20 (4), `runMultiplier` 1–4 (1.6),
    `jumpVelocity` 0–30 (5.5), `gravity` 0–50 (15), `radius` 0.05–5 (0.35),
    `height` ≥ 2 × radius (1.4), `cameraMode` (`third-person`), `cameraDistance`
    0.5–50 (3.5), `cameraHeight` −10–50 (1.8).
-   **`agent`:** `mode` (`wander`), `speed` 0.1–20 (2), `turnSpeed` 0.1–50 (6),
    `sightRadius` 0–100 (6), `stopDistance` 0.01–10 (0.6), `separationRadius`
    0–10 (0.8), up to 32 `waypoints`. `chase`, `flee`, and `follow` default
    `target` to `'user'`.
-   **`integrity`:** `max` 1–1e6 (100), `group` (`neutral`), `cooldownMs`
    0–10000 (250), `hideOnDepleted` (true), `scoreValue`, `contactAmount` (0).
-   **`zone`:** `shape` (`box`), `size` 0.01–1000 (1), `radius` (0.5), up to 16
    `watchGroups` (empty watches every tracked node).
-   **`spawner`:** `intervalSec` 0.05–3600 (3), `maxActive` 1–32 (8),
    `totalCount` (0 = unlimited), `spawnRadius` 0–100 (0).
-   **`objective`:** `type` (`pickup`), `amount` (10), `radius` 0.05–50 (0.65),
    `order` 0–1000 (0), `respawnSec` 0–3600 (0). Only pickups spin and bob by
    default.
-   **`audioCues`:** event-to-cue map, `pitchJitter` 0–0.5 (0.08), `volume` 0–1
    (1), `spatial` (true).

Host attributes: `character-controller`, `character-speed`, `character-jump`,
`touch-joystick`, `steering-agents`, `hit-zones`, `fire-rate`,
`projectile-speed`, `projectile-gravity`, `hit-amount`, `objectives`,
`scenario-timer`, `target-score`, `attempts`, `sim-hud`, `synth-audio`, and
`synth-volume`. `XRSim.resetSimScenario(element)` restarts the scenario.
````

## File: README.md
upstream: https://github.com/google/three-live/blob/main/README.md

````text
<!--
Copyright 2026 Google LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

> **Disclaimer:** This is not an officially supported Google product.

<div align="center">

# Three-Live

**AI-First Native 3D, CAD & Spatial Computing:** On-device JIT compiler turning live, AI-generated **Three.js** into native **Android (Google Filament & Jetpack XR)**, **iOS & visionOS (Apple RealityKit)**, and **WebXR**.

[![CI](https://github.com/google/three-live/actions/workflows/ci.yml/badge.svg)](https://github.com/google/three-live/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/google/three-live?include_prereleases&label=Release)](https://github.com/google/three-live/releases)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

**[🧭 Why Three-Live?](docs/why-three-live.md)** •
**[⚡ Quickstarts (Android • iOS • CLI • Web)](#quickstarts)** •
**[📦 Install (JitPack • SwiftPM • Cargo • npm)](#install-packages-and-bundles)** •
**[▶ Live 3D Studio](https://google.github.io/three-live/three/)** •
**[🧩 Domain Kits Catalog](https://google.github.io/three-live/kits/)** •
**[🥽 Live Spatial XR Studio](https://google.github.io/three-live/xr/)** •
**[📚 Docs](#documentation-guide)**

</div>

**iOS & visionOS · RealityKit** | **Android XR · Google Filament**
:-----------------------------: | :------------------------------:
![iOS RealityKit Demo][ios-gif] | ![Android XR Demo][android-gif]

[ios-gif]: examples/assets/slide-product-ios.gif
[android-gif]: examples/assets/slide-xr-android.gif

LLMs and developers excel at writing concise **Three.js** code—not hundreds of
lines of platform-specific native 3D, shader, and AR boilerplate. **Three-Live**
compiles standard Three.js (`THREE.Mesh`, `THREE.CSG`, `userData.xr`,
`KHR_interactivity`) on-device in a sandboxed Rust VM and renders natively in
**Google Filament and Jetpack XR SceneCore on Android**, **Apple RealityKit and
Quick Look on iOS and visionOS**, **headless 4-up PNG contact sheets
(`three-live-cli`)** for AI coding agents, and **WebGL2 / WebXR** on the Web.

--------------------------------------------------------------------------------

## Quickstarts

### 1. Run Three.js natively on Android (Google Filament & Jetpack XR SceneCore)

Compile standard Three.js code over zero-copy JNI and drive native **Google
Filament** rendering, **60 Hz physics**, and **Jetpack XR SceneCore** spatial
entities:

```kotlin
import com.google.threelive.FilamentHelper
import com.google.threelive.XRLiveRuntimeSession
import com.google.threelive.XRLiveSceneCoreHelper

val threeJsCode = """
  const core = new THREE.Mesh(
    new THREE.IcosahedronGeometry(0.55, 3),
    new THREE.MeshStandardMaterial({ color: 0x38bdf8, metalness: 0.85, roughness: 0.15 })
  );
  core.userData.xr = { grab: '2-hand', orbit: { speed: -0.4 } };
  scene.add(core);
""".trimIndent()

// Compile Three.js to a zero-copy GLB ByteBuffer and load directly into Google Filament
val holder = FilamentHelper.loadModelZeroCopy(threeJsCode) { buffer ->
    assetLoader.createAssetFromBinary(buffer)
}

// Step live KHR_interactivity graphs, 60 Hz rigid-body physics, and spatial traits per frame
val runtime = XRLiveRuntimeSession.fromGlb(holder.byteBuffer)
runtime.step(dtSeconds = 1.0 / 60.0)

// Or attach interactive spatial traits (grab, scale, billboard, anchor) in Android XR SceneCore
XRLiveSceneCoreHelper.attachTraitsFromGlb(xrSession, entity, holder.byteBuffer)
```

### 2. Run Three.js natively on iOS, macOS, and visionOS (Apple RealityKit)

Compile the exact same Three.js code into **Apple RealityKit** (`ARView` /
`RealityView`) or `.usdz`:

```swift
import ThreeLiveCompiler
import RealityKit

@MainActor
func loadSpatialScene(from threeJsCode: String, into arView: ARView) async throws -> XRLiveRealityKitSession? {
    let glb = try ThreeCompiler.compileToGLB(script: threeJsCode)
    let entity = try await RealityKitHelper.loadEntity(fromGLB: glb)
    XRLiveRealityKit.installTraits(on: entity, in: arView)

    // Bind live KHR_interactivity, 60 Hz physics, and spatial traits to RealityKit SceneEvents.Update
    let session = XRLiveRealityKitSession(glbData: glb, root: entity)
    session?.installInputTargets()
    session?.start()
    return session
}
```

### 3. Verify & compile Three.js headlessly for AI agents (`three-live-cli` & MCP server)

Render a 4-up orthographic/camera contact sheet (zero GPU required), run the
spatial linter for JSON frustum/overlap telemetry, compile `scene.js` to `.glb`
/ `.usdz`, generate a scene from a reference image (`from-image`), or attach
`three-live-cli mcp` as a zero-dependency **Model Context Protocol (MCP)** stdio
server (`three_live_validate`, `three_live_render`, `three_live_convert`,
`three_live_from_image`, `three_live_bake_textures`, `three_live_sim`,
`three_live_link`, and the `three_live_gym_reset` / `three_live_gym_step` /
`three_live_gym_close` agent gym) in Gemini CLI, Google Antigravity, Claude
Code, or any MCP client. The agent gym lets an agent play a scene step by step
(act, observe, react) to check a level is winnable; "gym" is the
reinforcement-learning term for such a reset/step environment, and no ML is
involved. Not using MCP? `three-live-cli gym reset level.js --session ep.json`
and `three-live-cli gym step --session ep.json --actions '[...]'` do the same,
one command per step. `three-live-cli link scene.js --qr` prints a playground
link (and a terminal QR code) that opens the scene on a phone, one tap from AR.
Building from a photo, mockup, sketch, or blueprint? Pass `--reference` (or
`reference` in MCP) to get a side-by-side + aligned-overlay + silhouette-diff
sheet with IoU and proportion guidance, or run `from-image` to synthesize and
verify a procedural Three.js scene directly from an image:

```bash
$ npx three-live-cli render scene.js --view=quad --grid --annotations -o contact_sheet.png
$ npx three-live-cli render scene.js --reference=blueprint.png --view=front -o compare.png
$ npx three-live-cli from-image photo.jpg -o scene.js --visual-turns 2 --render compare.png
$ npx three-live-cli validate scene.js --json
$ npx three-live-cli link scene.js --qr
$ npx three-live-cli convert scene.js -o model.usdz
$ npx three-live-cli textures bake scene.js -o scene.textures.json   # AI textures (needs THREE_LIVE_AI_IMAGE_ENDPOINT)
$ npx three-live-cli convert scene.js --texture-pack scene.textures.json -o model.glb

# Or register the built-in MCP server for closed-loop visual + spatial AI verification:
$ claude mcp add three-live -- npx -y -p three-live three-live-cli mcp
```

### 4. Run on the Web (`<three-live>` and `<xr-live>`)

On the web, `<three-live>` (`< 31 KB gz` viewer, `< 78 KB gz` with the live
Three.js compiler) and `<xr-live>` (`< 90 KB gz`) render the same Three.js
scenes in WebGL2 and 6DoF WebXR with 1-tap mobile AR handoff:

```js
// Standard Three.js scene (runs identically in Android, iOS, CLI, and Web)
const mesh = new THREE.Mesh(
  new THREE.TorusKnotGeometry(0.4, 0.14, 64, 16),
  new THREE.MeshStandardMaterial({ color: 0x38bdf8, metalness: 0.8, roughness: 0.15 })
);
mesh.userData.xr = { grab: '1-hand', billboard: 'capsule' };
scene.add(mesh);
```

Add `three-live-ai.min.js` (`< 33 KB gz`; built into the full bundles) to let
users reshape a scene with **any LLM**: every edit is compiled in the sandbox
first, auto-repaired once on failure, and only then hot-swapped, so a bad
generation never breaks the live scene.

```html
<three-live allow-client-scripts
    ai-endpo
````
