xb-add-world-sensing

name	xb-add-world-sensing
description	Connect physical-world sensing to XR Blocks application state. Use when adding planes, scene meshes, depth, occlusion, world collision evidence, object or human recognition, face tracking, segmentation, or agent-facing scene context.

Add world sensing

Build a complete sensing behavior: evidence enters the app, becomes current state, and produces an observable reaction.

1. Write the sensor contract

Name the physical or scene signal, cadence, observable reaction, data freshness, permissions, target runtime, and behavior for unsupported, denied, warming-up, empty, stale, and failed states.

Read references/branches.md, select the narrowest branch that supplies the signal, and read only that branch's manual and example.

Complete this step when one named signal maps to one reaction and every absence state maps to an explicit application state.

2. Prove the selected branch

Verify each planned symbol in ../../src/xrblocks.ts and its implementation. Inspect the linked current manual, template, or sample. Record the exact option, permission, WebXR session feature, optional dependency, simulator fidelity, and real-device check before editing application code.

Complete this step when every input has current source or executable evidence and the target runtime is explicit.

3. Connect evidence to app state

Configure the branch before xb.init(options) and keep application behavior in an xb.Script. Let XR Blocks own sensor and render update loops. For explicit detection, prevent uncontrolled concurrent requests and display pending state. For continuous detectors, use start(client) and stop(client) with the same client object.

Convert success into the requested reaction. Convert empty arrays, null, missing sensor data, denied permission, rejected session startup, and stale observations into the contract's absence state. Clear previous output when it is no longer current.

Complete this step when fresh evidence changes observable state and missing or stale evidence clears or replaces it deterministically.

4. Preserve targeting and placement ownership

Use the interaction pipeline's resolved hit for ray-based placement. A reticle displays that hit; it does not own target data. Use xb.world.placeOnHorizontalSurface() for one-time surface placement. Use the Placement manual for continuous follow/face/orbit behavior and its manipulation rebasing.

Complete this step when the sensor, interaction resolver, reticle, and placed object each have one clear responsibility.

5. Prove and hand off sensing

Build or type-check the app and start the exact simulator route when available. Confirm options, imports, permissions, detector ownership, freshness, result mapping, absence states, and cleanup. Add deterministic simulator ground truth only when the branch supports it.

Give separate simulator and device instructions when their evidence differs. Name the signal to present, expected reaction, empty result, stale clearing, permissions, and synthetic versus native evidence.

Finish when successful, empty, denied, unsupported, failed, and stale states have reproducible checks for the selected branch.