@vincentt-xr/sdk 2.0.0-alpha.1 → 2.0.0-alpha.3

package/GROUNDING.md

@@ -10,7 +10,8 @@ or spelunk `node_modules` for the API.
 The API is split into task-domain entry points. Import each symbol from the door
 this reference shows for it; the imports here are literal.
 
-- `@vincentt-xr/sdk` — **core**: providers, scene, screen-space layout, `TextLabel`, `Panel`, `SpriteAnimation`, `VideoBackground`, `AspectRatioContainer`, capture/share (`useMediaRecorder`, `dataURLtoFile`), audio.
+- `@vincentt-xr/sdk` — **core**: providers, scene, screen-space layout, runtime renderers (`Transform3D`, `MeshRenderer`, `SceneObjectRenderer`), `TextLabel`, `Panel`, `SpriteAnimation`, `VideoBackground`, `AspectRatioContainer`, capture/share (`useFrameCapture`, `useMediaRecorder`, `dataURLtoFile`), audio.
+- `@vincentt-xr/sdk/scene-object` — **public authoring state**: scene-object/component types, factories, selectors, and immutable store operations.
 - `@vincentt-xr/sdk/tracking` — **trackers**: face/hand/gesture/body/segmentation, `TrackingAnchor`, `GestureTrigger`, the bare `FaceMesh`, `useFaceResults`.
 - `@vincentt-xr/sdk/face-effects` — **face deep**: FaceMesh material config, retouch, canonical mesh, head-binding.
 - `@vincentt-xr/sdk/low-level` — **escape hatch**: raw model-node reads, selector hooks, custom-tracker plumbing. Reach here only when core + tracking can't express it.
@@ -24,6 +25,50 @@ logic is R3F `useFrame`; per-mount setup is `useEffect`.
 > patterns) into the project's `GROUNDING.md`. Edit the SDK API here, in the repo
 > that owns the API.
 
+### Internal source layout
+
+The public import doors above are stable. Internal files are organized by domain
+so shared behavior stays reusable instead of duplicated in large components:
+
+- `lib/components/ScreenImage/` — thin `ScreenImage.tsx` orchestrator plus
+  reusable body, frame, transform-frame, material, matcap, shader, source, and
+  helper modules.
+- `lib/components/ScreenText/` — thin `ScreenText.tsx` orchestrator plus
+  reusable body, transform-frame, constants, mapping, and helper modules.
+- `lib/components/TextLabel/` — low-level canvas text renderer split into
+  texture building, layout, style, hooks, and body modules.
+- `lib/components/XRViewport/` — thin viewport orchestrator plus reusable
+  provider, stage, overlays, media, control, sizing, slot, and layout modules.
+- `lib/components/Screen2D/` — shared screen-transform interaction/frame helpers
+  used by screen-space authoring components.
+- `lib/debug-ui/screen-text-settings/` — panel orchestrator plus reusable
+  sections, controls, settings, styles, transform helpers, and types.
+- `lib/render/` — render-group, render-pass, and layer-stack internals.
+- `lib/hand/`, `lib/screen-image/`, and `lib/screen-text/` — domain-level
+  primitives, presets, settings, and tests that used to live flat in `lib/`.
+
+When adding features, keep public exports at the documented import doors and put
+implementation details in the matching domain folder. Do not reintroduce
+component-local duplicate shader, transform, text-rendering, or settings logic.
+
+### Example asset layout
+
+Example-app assets are organized by purpose, not by whichever page first needed
+them:
+
+- `example/src/assets/media/images/` — reusable still textures and sample images.
+- `example/src/assets/media/images/people/` — face/body tracking sample stills.
+- `example/src/assets/media/images/screenshots/` — screenshot reference images.
+- `example/src/assets/media/videos/` — sample MP4/WebM sources.
+- `example/src/assets/media/gifs/` — animated GIF source files.
+- `example/src/assets/media/sequences/<demo>/` — ordered image-sequence frames.
+- `example/src/assets/models/` — GLB files used by example 3D scenes.
+- `example/src/assets/face-effects/` — domain-owned face-effect assets.
+
+Do not flatten all example assets into the root. Do not add new `utils/` media
+folders. Compression is a separate visual/behavior review because it can change
+tracking fixtures and texture output.
+
 ---
 
 ## Screen-space layout (the primary tool)
@@ -94,6 +139,89 @@ authoring prefer `position`, `size`, and `rotation`. `anchors` still exist as
 the lower-level layout escape hatch. If no source is provided, it renders the
 SDK-owned square default image.
 
+### `<ScreenShape>` — editable vector primitives
+
+Use `ScreenShape` for circles, ellipses, rectangles, rounded rectangles, regular
+polygons, stars, and lines. Do not generate raster image assets for these basic
+shapes. Placement and drag editing use the shared `ScreenTransform` settings.
+Circles, regular polygons, and stars preserve equal axes inside non-square
+transforms; ellipses and rectangles fill the transform.
+
+```tsx
+import { ScreenShape, ScreenSpaceUI } from "@vincentt-xr/sdk";
+
+<ScreenSpaceUI>
+  <ScreenShape
+    transform={{ position: { x: 0, y: 0 }, size: { width: 220, height: 220 } }}
+    settings={{
+      kind: "star",
+      fillColor: "#ffd54a",
+      strokeColor: "#ffffff",
+      strokeWidth: 4,
+      sides: 5,
+      innerRadiusRatio: 0.45,
+    }}
+  />
+</ScreenSpaceUI>;
+```
+
+Scene objects pair `ScreenTransform` with `ScreenShape`. Import scene-object
+factories from `@vincentt-xr/sdk/scene-object` and the live
+`ScreenShapeSettingsPanel` from `@vincentt-xr/sdk/debug-ui`.
+
+Settings: `kind`; `fillMode`, `fillColor`, `fillOpacity`; `strokeColor`,
+`strokeOpacity`, `strokeWidth`, `dashed`; `cornerRadius` for rounded rectangles;
+`sides` for polygons/stars; `innerRadiusRatio` for stars; and normalized
+`lineStart`/`lineEnd` `{ x, y }` coordinates for lines.
+
+Set `fillMode: "gradient"` and provide `gradient: { type, stops, angle, center,
+radius }`. Types are `linear`, `radial`, and `angular` (conic). A gradient accepts
+2–8 `{ offset, color }` stops. `ScreenGradientMaterial` is a separate reusable
+component exported from core; its settings panel is exported from debug-ui.
+
+Set `fillMode: "glass"` and provide `glass: { tint, opacity, frost, highlight }`
+for lightweight translucent glass. `ScreenGlassMaterial` is a separate reusable
+component. It is a stylized overlay material, not backdrop blur/refraction.
+
+### Shared material primitives
+
+Import shared material primitives from `@vincentt-xr/sdk` only:
+
+```tsx
+import {
+  DEFAULT_MATERIAL_FILL,
+  MaterialFill,
+  MeshMaterial,
+  createTwoStopGradient,
+  type MaterialFillSettings,
+  type MeshMaterialSettings,
+} from "@vincentt-xr/sdk";
+```
+
+Use `MaterialFill` when a component needs the same solid/gradient/texture fill
+system as `ScreenShape` and FaceMesh masks. `MaterialFillSettings.source` is
+`"solid" | "gradient" | "texture"`; pass `color`, `opacity`, optional
+`textureUrl`, and optional `gradient`.
+
+```tsx
+const fill: MaterialFillSettings = {
+  ...DEFAULT_MATERIAL_FILL,
+  source: "gradient",
+  color: "#38bdf8",
+  opacity: 0.8,
+  gradient: createTwoStopGradient("#38bdf8"),
+};
+
+<mesh>
+  <planeGeometry args={[1, 1]} />
+  <MaterialFill settings={fill} />
+</mesh>;
+```
+
+Use `MeshMaterial` for serialized mesh material settings shared by
+`MeshRenderer`; do not re-create local `<meshBasicMaterial>` /
+`<meshStandardMaterial>` branches in scene-object components.
+
 ```tsx
 import { ScreenImage, ScreenSpaceUI } from "@vincentt-xr/sdk";
 
@@ -121,7 +249,7 @@ import { ScreenImage, ScreenSpaceUI } from "@vincentt-xr/sdk";
 
 Props:
 
-- `source`: `{ kind: "default" }`, `{ kind: "image", src }`, or `{ kind: "texture", texture }`.
+- `source`: `{ kind: "default" }`, `{ kind: "image", src }`, `{ kind: "gif", src }`, or `{ kind: "texture", texture }`.
 - `src`: shorthand for `{ kind: "image", src }`.
 - `fit`: `"stretch" | "contain" | "cover"`; default `"contain"`.
 - `coordinateSpace`: `"normalized" | "canvas"`; default `"normalized"`.
@@ -147,9 +275,16 @@ Settings:
   position, size, rotation, pivot, render order, overlay/depth behavior, and visibility.
 - `DEFAULT_SCREEN_IMAGE_SETTINGS.image`: source kind, src, fit, opacity, color,
   flips, transparency, and alpha test.
-- `sourceKind` includes future media categories (`video`, `sequence`, `gif`),
-  but the current component implementation supports `default`, static `image`,
-  and already-loaded Three `texture`.
+- GIF URLs are decoded inside `ScreenImage` into a canvas texture. The decoder
+  preserves the GIF canvas size, frame delays, optimized partial-frame
+  compositing, and disposal rules before fitting the texture to the authored
+  rectangle. GIF playback streams into one working canvas buffer plus an
+  optional restore buffer; it does not retain every decoded full frame. Sources
+  over 5 MB, 1,000,000 decoded pixels, or 180 frames are rejected with a warning
+  and fall back to the default texture. Keep authored GIFs around 3-5 MB for
+  mobile AR.
+- Video and image-sequence providers resolve their media to a live
+  `THREE.Texture` and pass it as `kind: "texture"`.
 
 Use `<ScreenImage>` instead of hand-authoring `<ScreenTransform>` + `<mesh>`
 when the object is conceptually a 2D screen image. Use the lower-level mesh path
@@ -168,6 +303,31 @@ including `name`, `kind: "screenImage"`, `transform`, `image`, `material`, and
 `screenSpaceUI`. The `transform` includes `coordinateSpace` and `canvasSize`.
 Use that payload as the handoff from human layout tuning back to code.
 
+### ScreenImage contract for every caller
+
+`ScreenImage` is the canonical screen-image object in SDK and client apps. Any
+debug panel, hierarchy row, editor, or runtime controller that targets one must
+operate on the same mounted object state:
+
+- Keep one source of truth for `transform`, source/material settings, and
+  visibility. Panel edits must immediately update the rendered object.
+- Always wire `onScreenTransformChange` for inspector or editor usage. It is the
+  real drag/place path; do not implement a panel-only shadow transform.
+- Use `coordinateSpace="canvas"` plus `canvasSize` for authoring tools, then
+  map canvas values to `position`/`size`; never treat design pixels as world
+  units. `fit`/`stretchMode` changes content fitting, not the object's bounds.
+- Source replacement must preserve the object identity when possible, stop and
+  dispose the previous owned provider, and keep the current transform/material
+  settings. Dynamic video/canvas textures must continue marking fitted clones
+  for GPU upload.
+- Respect capability-gated controls: static images expose image/material
+  controls only; animated providers expose only controls they support. Loading,
+  error, retry, pause, ended, and cleanup state must be visible to diagnostics.
+- `visible`, `overlay`, `renderOrder`, `transparent`, `alphaTest`, blend mode,
+  opacity, tint, flips, pivot, rotation, size, and position are all part of the
+  live object contract and must remain synchronized from SDK or client entry
+  points.
+
 ### `<SpriteAnimation sheet={{ url, cols, rows, frames, fps }}>` — Animated transparent overlay
 
 The primitive for an animated transparent overlay (a frame border, a gesture-instruction graphic, an animated sticker). One transparent WebP atlas of `cols`×`rows` cells; the first `frames` play left-to-right, top-to-bottom at `fps`. It is a single static GPU texture with a per-frame UV offset — no video decode — so it works in every native and in-app browser and costs ~zero heat.
@@ -232,9 +392,190 @@ For local tuning, import `FaceWarp3DSettingsPanel` from
 `@vincentt-xr/sdk/debug-ui`. It is a draggable debug panel and should not
 be included in the final production scene.
 
+### `FaceMeshRenderer` — scene-object live 3D face mesh
+
+Use `FaceMeshRenderer` for the standard SDK face-mesh scene-object component.
+It owns face tracking internally through `FaceTracker`, reads live landmarks,
+deforms the canonical face mesh, and renders through normal face-mesh material
+settings. Prefer this over direct `CanonicalFaceMeshRenderer` in new
+scene-object/editor integrations.
+
+Import runtime/material symbols from `@vincentt-xr/sdk/face-effects`:
+
+```tsx
+import {
+  DEFAULT_FACE_MESH_RENDERER,
+  DEFAULT_FACE_MESH_TRANSFORM,
+  FACE_MESH_MATERIAL_TYPES,
+  FACE_MESH_SIDES,
+  FaceMeshRenderer,
+  mapFaceMeshRendererSettingsToProps,
+  resolveFaceMeshRendererSettings,
+  type FaceMeshRendererSettings,
+} from "@vincentt-xr/sdk/face-effects";
+```
+
+Import scene-object defaults and store helpers from
+`@vincentt-xr/sdk/scene-object`:
+
+```tsx
+import {
+  createDefaultComponent,
+  createDefaultFaceMeshRendererSettings,
+  DEFAULT_RENDER_GROUP_IDS,
+  type RenderGroupSceneObjectStore,
+} from "@vincentt-xr/sdk/scene-object";
+```
+
+`FaceMeshRendererSettings` is the serialized component settings contract:
+`enabled`, `faceIndex`, `targetFps`, `showLeftEyeGeometry`,
+`showRightEyeGeometry`, `showMouthGeometry`, `showNoseGeometry`,
+`showOverlayMask`, `showMouthMask`, `showLeftEyeMask`, `showRightEyeMask`,
+`showNoseMask`, `externalMeshUrl`, `externalScale`, `materialType`,
+`shaderPreset`, `textureMap`, `alphaMap`, `alphaOpacity`, `side`, `blendMode`,
+`blendOpacity`, `baseColor`, `opacity`, `compositeShading`,
+`maskTextureSource`, `maskSourceUrl`, `maskColor`, `maskOpacity`,
+`faceTextureUrl`, `faceTextureStyle2Url`, `faceAlphaMaskUrl`, and
+`renderOrder`.
+
+`maskTextureSource` is `"solid" | "gradient" | "imageUrl" | "mediaUrl"`.
+Solid and gradient masks use `maskColor`; image/media masks use
+`maskSourceUrl`. `maskOpacity` is always `0..1`.
+
+`materialType: "shader"` has three shader presets: `"basicShader"`,
+`"originalFace"`, and `"composite"`. Use
+`resolveFaceMeshRendererSettings(current, patch)` when editing settings so
+shader/material/texture state stays synchronized. Selecting composite applies
+the SDK composite defaults (`textureMap: "canonical"`, hard-light blend,
+`blendOpacity: 0.85`, `compositeShading: true`) instead of silently falling
+back to original-face rendering.
+
+`externalMeshUrl` is for canonical-compatible OBJ assets that match the
+renderer's live landmark deformation path. Third-party Face Mesh OBJ files are
+reference assets only until the SDK has an explicit topology mapper from those
+vertices to the 468 tracked face landmarks. Do not bundle OBJ/FBX/PNG reference
+files in `lib/` or examples unless runtime code consumes them correctly.
+
+Do not add settings that are not runtime-effective. Skull/ear geometry,
+expression multiplier, and UV1 mapping require parser/runtime support before
+they become public SDK settings.
+
+Scene-object example:
+
+```tsx
+const objectId = "face-mesh";
+const transform = createDefaultComponent("Transform", objectId);
+transform.settings.position.y = DEFAULT_FACE_MESH_TRANSFORM.position.y;
+
+const faceMesh = createDefaultComponent("FaceMeshRenderer", objectId);
+faceMesh.settings = {
+  ...createDefaultFaceMeshRendererSettings(),
+  materialType: FACE_MESH_MATERIAL_TYPES.wireframe,
+  side: FACE_MESH_SIDES.double,
+  baseColor: "#00e5ff",
+  opacity: 0.82,
+} satisfies FaceMeshRendererSettings;
+
+const store: RenderGroupSceneObjectStore = {
+  objects: {
+    [objectId]: {
+      id: objectId,
+      name: "Face Mesh",
+      enabled: true,
+      renderGroupId: DEFAULT_RENDER_GROUP_IDS.scene3d,
+      componentIds: [transform.id, faceMesh.id],
+    },
+  },
+  components: {
+    [transform.id]: transform,
+    [faceMesh.id]: faceMesh,
+  },
+  renderGroups: {
+    [DEFAULT_RENDER_GROUP_IDS.scene3d]: {
+      id: DEFAULT_RENDER_GROUP_IDS.scene3d,
+      name: "3D Scene",
+      domain: "scene3d",
+      enabled: true,
+      objectIds: [objectId],
+    },
+  },
+  renderGroupOrder: [DEFAULT_RENDER_GROUP_IDS.scene3d],
+};
+```
+
+When `SceneObjectRenderer` sees both `Transform` and `FaceMeshRenderer` on the
+same object, it passes the authored `Transform` into `FaceMeshRenderer`.
+FaceMesh does not use normal world-space `Transform3D` semantics. It applies
+the supported Transform values in MediaPipe landmark space before camera
+projection; it must never wrap the already-projected mesh in a parent
+`Transform3D`, because that causes depth-dependent screen skew.
+
+Supported FaceMesh Transform values are position and uniform scale only.
+Rotation and non-uniform scale are ignored by the runtime until the SDK has a
+real object-space face solve. Authored `position.y` is Y-up, but MediaPipe image
+space is Y-down, so the renderer subtracts Y while adding X/Z.
+
+This is the SDK's strict FaceMesh contract: FaceInfo/FaceBinding pose first,
+FaceMesh deformation in face landmark space, supported authored Transform in
+that space, then world/camera projection.
+`DEFAULT_FACE_MESH_TRANSFORM` starts from `DEFAULT_TRANSFORM_3D` and sets
+`position.y` to `0.001` as an intentional FaceMesh authoring bias, not as a
+projection correction. Author a Transform with `position.y = 0` to opt out.
+
+`mapFaceMeshRendererSettingsToProps(settings)` maps serialized
+`FaceMeshRendererSettings` to low-level `CanonicalFaceMeshRendererProps`.
+Use it only when bridging custom runtime code; ordinary scene-object rendering
+should use `SceneObjectRenderer`.
+
+`CanonicalFaceMeshRenderer` remains exported from `@vincentt-xr/sdk/face-effects`
+for backwards compatibility and low-level experiments, but new editor and
+scene-object work should use `FaceMeshRenderer`.
+
+### `FaceRetouch` — legacy landmark skin retouch
+
+Use `FaceRetouch` from `@vincentt-xr/sdk/face-effects` for the legacy
+landmark-masked skin retouch shader. The public controls are intentionally
+minimal:
+
+```tsx
+import {
+  FaceRetouch,
+  patchFaceRetouchControls,
+  resolveFaceRetouchControls,
+  type FaceRetouchControls,
+} from "@vincentt-xr/sdk/face-effects";
+import { FaceRetouchSettingsPanel } from "@vincentt-xr/sdk/debug-ui";
+
+const [controls, setControls] = useState(() => resolveFaceRetouchControls());
+
+const updateControls = (next: Partial<FaceRetouchControls>) => {
+  setControls((current) => patchFaceRetouchControls(current, next));
+};
+
+<FaceRetouch {...controls} />;
+<FaceRetouchSettingsPanel value={controls} onChange={updateControls} />;
+```
+
+`FaceRetouchControls` has only `skinSmoothing`, `skinRealism`,
+`blemishReduction`, and `previewMask`. Do not invent provider, quality,
+redness, teeth, eye, or blur controls for this component.
+
+For multiple people, render one `FaceRetouch` per face:
+
+```tsx
+<FaceRetouch {...controls} faceIndex={0} numFaces={2} />
+<FaceRetouch {...controls} faceIndex={1} numFaces={2} />
+```
+
+`numFaces` defaults to at least `faceIndex + 1`. `clipMinX` and `clipMaxX` are
+optional horizontal UV clipping props in `0..1` space, useful for split-screen
+comparison demos.
+
 ### `<FaceTracker>` — Face tracking (468 landmarks)
 
-Detects faces and provides face transform to children via context. Supports `faceIndex` (default 0) and `scaleWithFace`.
+Detects faces and provides face transform to children via context. Supports
+`faceIndex` (default `0`), `scaleWithFace`, and `followFaceRoll` (default
+`true`; set `false` to keep children upright while the head tilts).
 
 ```tsx
 import { FaceTracker, TrackingAnchor } from "@vincentt-xr/sdk/tracking";
@@ -249,6 +590,274 @@ import { FaceTracker, TrackingAnchor } from "@vincentt-xr/sdk/tracking";
 </FaceTracker>;
 ```
 
+### `FaceInfo` — face-driven effect logic
+
+Use `FaceInfo` for head-pose, expression, landmark, bounds, and face-scale logic.
+Do not read raw MediaPipe results or repeat landmark indices unless the facade
+does not expose data required by a research/debugging tool.
+
+```tsx
+import { hasFaceExpression, useFaceInfo } from "@vincentt-xr/sdk/tracking";
+
+function FaceLogic() {
+  const face = useFaceInfo({ active: true });
+  if (!face) return null;
+
+  const mouthOpen = hasFaceExpression(face, "jawOpen");
+  const lookingLeft = face.pose.rotation.y > 0.2;
+  return <group visible={mouthOpen} rotation-y={lookingLeft ? 0.2 : 0} />;
+}
+```
+
+| Field           | Coordinate contract                                              |
+| --------------- | ---------------------------------------------------------------- |
+| `index`         | Current result-array index; not a persistent identity            |
+| `landmarks`     | MediaPipe normalized tracker-input coordinates, top-left origin  |
+| `bounds`        | Normalized tracker-input bounds, top-left origin                 |
+| `pose.position` | Existing face-tracker Three.js world position                    |
+| `pose.rotation` | Radians: X pitch (+up), Y yaw (+left), Z roll                    |
+| `pose.scale`    | Smoothed uniform sizing heuristic used by face anchors/occluders |
+| `eyeDistance`   | Outer-eye distance in normalized tracker-input coordinates       |
+| `blendshapes`   | MediaPipe category names and scores in `[0, 1]`                  |
+
+`useFaceInfo({ faceIndex })` is the normal single-face React reader.
+`useFaceInfos({ numFaces })` publishes all current faces. Both acquire the shared
+face model through the SDK registry and use the existing throttle/empty-frame
+hold lifecycle; do not mount a separate result polling loop. Call them inside
+`XRProvider` and the R3F Canvas. Options are `active`, `numFaces`, `targetFps`,
+`throttleMs`, and `holdMs`; `useFaceInfo` additionally accepts `faceIndex`.
+
+```tsx
+function MultiFaceLogic() {
+  const faces = useFaceInfos({ numFaces: 3 });
+  return <group visible={faces.some((face) => hasFaceExpression(face, "jawOpen"))} />;
+}
+```
+
+For `useFrame` code that already has a low-level face node, call
+`getFaceInfo(node, faceIndex, target)`. Create `target` once with
+`createFaceInfoTarget()` and reuse it to avoid per-frame allocations. Use
+`getFaceInfo` and `createFaceInfoTarget` from `@vincentt-xr/sdk/low-level`; they
+are node-in escape hatches, not the normal React API. Use `getFaceBlendshape`
+and `hasFaceExpression`; absent scores resolve to `0`, and the default expression
+threshold is `DEFAULT_FACE_EXPRESSION_THRESHOLD`. Bind the R3F camera once with
+`node.setCamera(camera, faceIndex)` before reading pose; the React hooks do this
+automatically.
+
+All supported expression names are typed by `FaceBlendshapeName` and listed in
+the greppable `FACE_BLENDSHAPE_NAMES` constant exported from
+`@vincentt-xr/sdk/tracking`. This includes `eyeBlinkLeft`, `eyeBlinkRight`,
+`eyeWideLeft`, `eyeWideRight`, and `jawOpen`; do not guess string names.
+
+Use `normalizedToScreenPixels` with the tracker input/display viewport size to
+display a face landmark in Screen Image/Text/Shape coordinates. The tracker
+input is already the SDK feed; do not apply media cover/mirroring a second time.
+Never mutate or mirror `FaceInfo.landmarks` in place, manually project them,
+infer a persistent face ID, or copy numeric landmark indices/thresholds into
+application code.
+
+```ts
+const nose = normalizedToScreenPixels({
+  point: face.landmarks[FACE_LANDMARK_INDICES["face.noseTip"]],
+  viewportSize,
+});
+```
+
+Effect House mapping: `FaceInfo.landmarks` replaces `pointsArray`, `bounds`
+replaces `rect`, `pose.rotation` provides pitch/yaw/roll, and `eyeDistance` is
+named the same. Use Face Actions below for the semantic `FaceAction` role.
+Vincentt uses MediaPipe's face topology and top-left origin; it is not a
+106-point or bottom-left-compatible alias.
+
+Run the example route `/face-info` to verify all landmarks, live bounds, nose
+position, pose, eye distance, and `jawOpen` using `ScreenShape`, `ScreenText`,
+and `Axes`.
+
+### `useFaceDetection()` — face presence lifecycle and count
+
+Import `useFaceDetection` from `@vincentt-xr/sdk/tracking` when logic needs face
+detected/lost edges, selected-face presence, or the current face count. It wraps
+the shared `useFaceInfos` reader and does not start another model.
+
+```tsx
+const detection = useFaceDetection({ faceIndex: 0, numFaces: 5 });
+
+if (detection.justDetected) showEffect();
+if (detection.detected) updateEffect(detection.face);
+if (detection.justLost) hideEffect();
+```
+
+| Visual-scripting term                 | SDK field                            |
+| ------------------------------------- | ------------------------------------ |
+| Face Detection Begin / face appeared  | `justDetected`, `phase === "begin"`  |
+| Face Detection Stay / face present    | `detected`, `phase === "stay"`       |
+| Face Detection End / face disappeared | `justLost`, `phase === "end"`        |
+| Face Detection None / no face         | `!detected`, `phase === "none"`      |
+| Face Count / number of faces          | `faceCount` and `faces.length`       |
+| Which Face / selected face            | `faceIndex` option and `face` result |
+
+The full result is `face`, `faces`, `faceCount`, `detected`, `justDetected`,
+`justLost`, and `phase`. Options are the normal `useFaceInfos` options plus
+`faceIndex`: `active`, `numFaces`, `targetFps`, `throttleMs`, and `holdMs`.
+Default `holdMs: 250` prevents a transient missed frame from firing `end`; use
+`holdMs: 0` only when immediate disappearance is required. Do not compare raw
+result arrays or build a local previous-frame ref. The verified
+`/face-detection` page tests five selectable face slots and all four phases; its
+real-camera lifecycle flow passed on 26 July 2026.
+
+### Reusable normalized and face image crops
+
+Import `drawNormalizedCrop` from `@vincentt-xr/sdk` for any normalized image
+region. Import `drawFaceCrop` from `@vincentt-xr/sdk/tracking` when the bounds
+come from `FaceInfo`. Both preserve the requested output pixel aspect ratio,
+clamp at source edges, and draw into a caller-owned canvas without starting a
+tracker or allocating per call.
+
+```ts
+const cropCanvas = document.createElement("canvas");
+
+const drawn = drawFaceCrop({
+  source: video,
+  face,
+  canvas: cropCanvas,
+  outputSize: { width: 224, height: 224 },
+  padding: 0.2,
+});
+```
+
+Bounds use normalized tracker-input/source coordinates with a top-left origin.
+`padding` is the fraction of detected width/height added on each side. The face
+helper defaults to `0.2`; the generic helper defaults to `0`. The functions do
+not mirror, classify, upload, or retain pixels. A `false` result means the
+source dimensions, bounds, output dimensions, or canvas context were unusable.
+Reuse one canvas on frame-driven paths. Face attribute expression should feed
+this crop into its independent image classifier; never derive emotion labels
+from `FaceInfo.blendshapes`.
+
+### Face Actions — semantic face effect logic
+
+Import `FACE_ACTION_NAMES`, `DEFAULT_FACE_ACTION_OPTIONS`,
+`getFaceActionValue`, `hasFaceAction`, and `useFaceAction` from
+`@vincentt-xr/sdk/tracking`. They derive from caller-owned `FaceInfo`; they do
+not start a second tracker.
+
+```tsx
+const face = useFaceInfo();
+const blink = useFaceAction(face, "eyeBlink");
+
+useEffect(() => {
+  if (blink.justStarted) capturePhoto();
+}, [blink.justStarted]);
+
+const mouthAmount = face ? getFaceActionValue(face, "mouthOpen") : 0;
+```
+
+| Action                                                        | Source and direction              | Default start / release / hold |
+| ------------------------------------------------------------- | --------------------------------- | ------------------------------ |
+| `browRaise`                                                   | max brow-up blendshape            | `0.45 / 0.30 / 50 ms`          |
+| `eyeBlink`, `eyeBlinkLeft`, `eyeBlinkRight`, `eyeBlinkEither` | typed eye-blink blendshapes       | `0.55 / 0.40 / 50 ms`          |
+| `mouthOpen`                                                   | `jawOpen`                         | `0.45 / 0.30 / 50 ms`          |
+| `mouthPout`                                                   | `mouthPucker`                     | `0.50 / 0.35 / 50 ms`          |
+| `headUp`, `headDown`                                          | positive/negative pitch magnitude | `10° / 6° / 80 ms`             |
+| `headTurnLeft`, `headTurnRight`                               | positive/negative yaw magnitude   | `10° / 6° / 80 ms`             |
+| `headTiltLeft`, `headTiltRight`                               | positive/negative roll magnitude  | `10° / 6° / 80 ms`             |
+
+Blendshape values are `[0, 1]`; head values and thresholds are radians. Left
+and up use the SDK-positive pose convention. Directional actions always return
+a non-negative magnitude. Pass `neutralRotation: { ...face.pose.rotation }`
+captured from an explicit user calibration gesture when the resting pose should
+be treated as zero. Without it, head actions use zero rotation.
+
+Use `getFaceActionValue` for continuous animation, `hasFaceAction` for a simple
+level check, and `useFaceAction` for `active`, `justStarted`, `justEnded`, and
+`phase: "begin" | "stay" | "end" | "none"`
+with SDK hysteresis and hold timing. Do not guess blendshape strings, flip pose
+signs, or rebuild local debounce/hysteresis logic. For multiple faces, select
+one with `useFaceInfo({ faceIndex })`, or call
+`getStrongestFaceAction(faces, action)` for an "any face" effect, then pass its
+`face` into `useFaceAction`. The strongest selector is one pass and starts no
+additional reader.
+
+Effect House-style physical movement maps as follows: left/right/both/either
+blink → `eyeBlinkLeft` / `eyeBlinkRight` / `eyeBlink` / `eyeBlinkEither`;
+mouth open → `mouthOpen`; pout → `mouthPout`; eyebrow movement → `browRaise`.
+Semantic blink left/right is viewer-facing and therefore swaps MediaPipe's raw
+anatomical-side blendshape names. Never swap `FaceInfo.blendshapes` itself.
+Every detected movement emits at least one `stay` frame after `begin` before
+`end`.
+These are observable movements, not image classification. Do not infer
+`happy`, `sad`, `angry`, `fear`, `disgust`, `surprise`, or `neutral` from local
+threshold combinations. Use the separate Face Attribute Expression API below.
+
+Run `/face-actions` to inspect every live value, set neutral pose, tune the
+selected action, and repeat the all-actions checklist. All actions and the
+default thresholds were verified with the real-camera page on 26 July 2026.
+Run the verified `/facial-movement-expression` page to test the Effect
+House-compatible physical movement subset, phase edges, fixed-face or
+strongest-face selection, and the image classifier. Its complete real-camera
+flow passed on 26 July 2026.
+
+### Face Attribute Expression — image-based classification
+
+Import `useFaceAttributeExpression`, `FACE_ATTRIBUTE_EXPRESSION_NAMES`, and
+their types from `@vincentt-xr/sdk/tracking`. Pass caller-owned `FaceInfo`; the
+hook reuses the shared session input frame, crops that face, and lazy-loads the
+OpenCV MobileFaceNet INT8 ONNX classifier. It does not create another face
+reader or detector.
+
+```tsx
+const face = useFaceInfo();
+const attribute = useFaceAttributeExpression(face, {
+  targetFps: 5,
+  minConfidence: 0.55,
+});
+
+if (attribute.status === "ready") {
+  const { expression, confidence, scores } = attribute.result;
+}
+```
+
+The lifecycle is `idle | loading | ready | error`. Ready results contain
+`expression`, `confidence`, and `scores`. `expression` can be `angry`,
+`disgust`, `fear`, `happy`, `neutral`, `sad`,
+`surprise`, or `unknown`. `scores` contains only the seven real model classes;
+there is no fabricated `unknown` score. `unknown` is the low-confidence fallback
+below `minConfidence`. Default `targetFps` is `5`; the model is about 1.36 MB,
+loads outside the main bundle, and is SHA-384 verified. ONNX Runtime's WASM
+worker files load from the jsDelivr package path that matches the active
+`onnxruntime-web` runtime version, not through the consuming app's bundler. The
+runtime files are fetched from jsDelivr without SDK-managed SRI because ONNX
+Runtime resolves its own WASM assets.
+
+For best threaded SIMD performance, production pages that run expression
+classification should be cross-origin isolated
+(`Cross-Origin-Opener-Policy: same-origin` and
+`Cross-Origin-Embedder-Policy: require-corp`) so `SharedArrayBuffer` is
+available. Without those headers, ONNX Runtime falls back to single-threaded
+WASM.
+
+`modelUrl` overrides must accept float32 NCHW `[1, 3, 112, 112]`, with planar
+RGB normalized to `[-1, 1]`, and return seven logits ordered `angry`, `disgust`,
+`fear`, `happy`, `neutral`, `sad`, `surprise`. Do not assume an arbitrary
+MobileFaceNet ONNX model is compatible. Failed loads are removed from the
+session cache so a remounted consumer can retry.
+
+This is a visual-expression estimate, not ground-truth emotion, intent,
+identity, or mental state. Never replace it with blendshape heuristics. Run the
+verified `/facial-movement-expression` page to inspect every live model score.
+
+### `<Axes>` — generic 3D orientation gizmo
+
+Use `Axes` to visualize any 3D pose. X is red, Y is green, and Z is blue. Keep
+tracking separate: bind a face, hand, or object pose through standard Three.js
+`position` and `rotation` props.
+
+```tsx
+import { Axes } from "@vincentt-xr/sdk";
+
+<Axes size={0.38} position={pose.position} rotation={pose.rotation} />;
+```
+
 ### `<FaceTracker.Mesh />` / `<FaceMesh>` — Deforming 468-point face mesh
 
 For masks, makeup, and full-face decoration that deforms with skin.
@@ -353,6 +962,12 @@ Every tracker takes an `active` prop (default `true`). Set `active={false}` and
 
 When several consumers share one model, it runs while **any** of them is active. `active` gates whether the model runs; `perf.targetFps` (below) caps how often it runs while active — use both. `<Segmentation>` also takes `active` (distinct from its `visible` prop, which only gates mask exposure while inference keeps running).
 
+Session lifecycle preserves that ownership state: `session.stop()` pauses every
+tracker without releasing its MediaPipe resources, and the next `session.start()`
+resumes only models that still have at least one active owner. Static-image
+detection pulses use the same suspension path, so source switches do not
+accidentally reactivate an `active={false}` tracker.
+
 ### `perf` — cap inference rate + camera resolution
 
 Set `perf` on `<XRProvider>` to trade tracking fidelity for lower load and heat. This is the single biggest lever if the device runs hot.
@@ -378,6 +993,11 @@ Per-tracker override beats the session default:
 
 The base template ships `perf={{ targetFps: 24, camRes: 720 }}` by default — good for both dev laptops and end-user phones. Don't lower it further without a reason; don't remove it to "get full quality" unless you know the target device can take the heat.
 
+SDK-owned tracker, occluder, and canonical-face assets are SHA-384 verified
+against hashes pinned in the package. A missing hash for
+`https://cdn.vincentt.studio` fails closed; custom consumer-owned asset URLs
+remain best-effort and warn when no pinned hash exists.
+
 ---
 
 ## Reading tracker state
@@ -386,9 +1006,11 @@ The base template ships `perf={{ targetFps: 24, camRes: 720 }}` by default — g
 
 Wraps children; the child's world position is updated to the tracked landmark each frame. Use for all decoration that simply follows a face/hand/body point.
 
-Valid targets:
+Valid targets are centralized in `FACE_TARGETS`; use that exported list for
+editor dropdowns instead of copying it. Left/right mean the tracked person's
+perspective.
 
-- **Face:** `face.forehead`, `face.noseTip`, `face.chin`, `face.leftEyeOuter`, `face.rightEyeOuter`, `face.leftCheek`, `face.rightCheek`, `face.mouthCenter`
+- **Face binding presets:** `face.center`, `face.forehead`, `face.noseTip`, `face.chin`, `face.leftEye`, `face.rightEye`, `face.leftEyeOuter`, `face.rightEyeOuter`, `face.leftCheek`, `face.rightCheek`, `face.mouthCenter`, `face.leftEarlobe`, `face.rightEarlobe`, `face.custom`
 - **Hand:** `hand.wrist`, `hand.thumbTip`, `hand.indexTip`, `hand.middleTip`, `hand.ringTip`, `hand.pinkyTip`, `hand.indexBase`, `hand.middleBase`, `hand.ringBase`, `hand.pinkyBase`
 - **Body:** `body.head`, `body.neck`, `body.leftShoulder`, `body.rightShoulder`, `body.leftElbow`, `body.rightElbow`, `body.leftWrist`, `body.rightWrist`, `body.leftHip`, `body.rightHip`, `body.leftKnee`, `body.rightKnee`, `body.leftAnkle`, `body.rightAnkle`
 
@@ -403,6 +1025,32 @@ Valid targets:
 </FaceTracker>
 ```
 
+`face.center` is the general default. Eye targets are composite eye centers;
+`*EyeOuter` targets are exact outer-corner landmarks. Earlobe targets are the
+nearest stable MediaPipe face-oval points, not anatomical earlobe detections.
+All Effect House `FaceBindingAnchorType` names therefore have a Vincentt
+equivalent, but their numeric canonical-mesh coordinates are not compatible.
+
+For `face.custom`, pass normalized face-local coordinates. The origin is face
+center; X runs from person's left `-1` to right `+1`, Y from chin `-1` to
+forehead `+1`, and positive Z comes toward the camera.
+
+```tsx
+<FaceTracker>
+  <TrackingAnchor target="face.custom" customAnchorPoint={{ x: 0.7, y: 0.2, z: 0 }} smoothing={15}>
+    <mesh />
+  </TrackingAnchor>
+</FaceTracker>
+```
+
+Scene objects use the same `TrackingAnchor` component settings. A 2D null with
+`ScreenTransform` + `TrackingAnchor` projects the preset into SDK design pixels,
+so all child Screen Shapes move as one group. Use `/face-binding-anchors` to
+test every preset on the editable `rose null`; the inspector target options
+come directly from `FACE_TARGETS`. Toggle `Follow Face Roll` to rotate the
+attachment with head tilt. The example hierarchy intentionally shows only the
+combined root object.
+
 **`smoothing` — smooth motion from throttled inference.** Inference is throttled (the `perf` API caps it at 24fps by default) while rendering runs at 60-120fps, so a raw anchor holds then jumps on each new sample — visible stepping under head/hand movement. A plain lerp only hides it at rest; under motion it still steps. Pass `smoothing` (`~15` is a good default) and the anchor runs a **One Euro filter** — the standard adaptive low-pass for interactive tracking: it smooths hard when the landmark moves slowly (kills jitter) and loosens as it speeds up (kills lag), and never extrapolates so it can't overshoot or wobble. Higher `smoothing` is snappier (less lag, slightly more jitter); lower is smoother. It snaps (resets the filter) on first placement and on re-acquire, so it never slides in from a stale position. `0` (default) keeps the raw snap. Rotation is not smoothed. Prefer this over a hand-rolled `useFrame` lerp — a hand-rolled lerp reintroduces the stepping.
 
 ```tsx
@@ -471,10 +1119,116 @@ import { GestureTracker, GestureTrigger } from "@vincentt-xr/sdk/tracking";
 
 In a v2-template project this is already mounted in `src/App.tsx` — do NOT add a second one there. Mentioned here because `customBackground` is how you do background replacement: pair it with `<Segmentation type="portrait" />` and pass the segmentation mask texture as `segmentationMask`.
 
+`VideoBackground` is a flat camera-background component: its material keeps
+`depthTest={false}` and `depthWrite={false}`. Editor-style 3D viewports that
+treat the camera feed as a real scene plane should render a separate editor
+video plane instead of changing `VideoBackground` semantics.
+
 ---
 
 ## Mesh primitives and textures
 
+`ScreenImage` keeps fitted clones synchronized for dynamic video and canvas textures.
+
+### Texture Types API usage
+
+`ScreenImage` is the common render target for static and animated texture sources. Use
+the normal runtime import for rendering:
+
+```tsx
+import { ScreenImage, ScreenSpaceUI } from "@vincentt-xr/sdk";
+
+<ScreenSpaceUI>
+  <ScreenImage
+    source={{ kind: "image", src: imageUrl }}
+    materialType="unlit"
+    stretchMode="fit"
+    transparent
+  />
+</ScreenSpaceUI>;
+```
+
+Supported source behavior:
+
+- Image: static URL texture. No playback controls.
+- Runtime texture: pass `{ kind: "texture", texture }` when supplying an existing `THREE.Texture`.
+- Video: use a managed `THREE.VideoTexture`; support play/pause, restart, frame stepping, playback rate, forward, and reverse stepping. Negative `playbackRate` is not used.
+- GIF: pass `{ kind: "gif", src }` to `ScreenImage`. The SDK decodes frames into
+  a canvas texture, preserves dimensions and per-frame delays, coalesces
+  optimized partial frames, and applies disposal rules before fitting.
+- Image sequence: draw loaded frames into a canvas texture using FPS and frame state.
+
+Animated sources support forward, reverse, ping-pong, random, looping, finite loop
+counts, pause/resume at current frame, restart, frame status, and ended state where
+the source supports it. Static image sources must not expose animation controls.
+
+ScreenImage inspector rules:
+
+- `ScreenImageSettingsPanel` must read/write the same scene-object state used by the rendered `ScreenImage`.
+- Transform drag/place must be wired through `onScreenTransformChange`.
+- Use `mapScreenImageSettingsToProps` to convert inspector canvas coordinates into render props.
+- Do not pass inspector pixel dimensions directly as world-space `ScreenImage` dimensions.
+- Dynamic canvas/video texture updates must mark fitted texture clones for GPU upload.
+
+Low-level texture integration imports from `@vincentt-xr/sdk/low-level`:
+
+```ts
+import {
+  BasicAnimatedTextureController,
+  createTextureSourceResolver,
+  gifTextureSourceProvider,
+  getPlaybackFrame,
+  getSequenceFrame,
+  type AnimatedTextureController,
+  type AnimatedTexturePlayMode,
+  type GifTextureSource,
+  type ResolvedTextureSource,
+  type TextureSourceResolver,
+  type TextureSourceProvider,
+} from "@vincentt-xr/sdk/low-level";
+```
+
+Controller lifecycle is: `play()`, `pause()`, `restart()`, optional `seek()`,
+`setPlayMode("forward" | "reverse" | "ping-pong" | "random")`,
+`setLoop(enabled, count)`, `subscribe(listener)`, then `dispose()`. Read
+`getSnapshot()` for state, frame/time, duration, frame count, loop, and errors;
+check `capabilities` before rendering a control.
+
+`gifTextureSourceProvider` is the built-in GIF resolver provider used by
+`ScreenImage`. It returns a `ResolvedTextureSource` with a
+`BasicAnimatedTextureController` and streams playback through a bounded canvas
+buffer instead of retaining all decoded frames. Custom resolver users can compose
+it directly when they need controller access for pause, restart, forward playback,
+loop, typed events, and ownership-safe disposal. Because GIF playback is streamed
+instead of full-frame cached, seeking and random/reverse/ping-pong playback are
+not advertised capabilities. Loop restart clears the streamed working buffer
+before frame 0 so optimized partial-frame GIFs do not carry stale pixels across
+cycles.
+
+Frame helpers are also available from the same `/low-level` door:
+`getPlaybackFrame(tick, frameCount, mode, loop, loopCount)` handles forward,
+reverse, ping-pong, random, loop, and ended math; `getSequenceFrame(elapsedSeconds,
+fps, frameCount)` maps elapsed time to a bounded sequence index.
+
+Event compatibility: subscribe with `controller.on(type, listener)` and remove
+with the returned disposer or `off()`. Supported event types are
+`KeyFrameInSecond`, `Pause`, `PlayBegin`, `PlayEnd`, `Resume`, and `Stop`.
+Event snapshots include the current frame/time, playback state, loop settings,
+and optional duration/frame count. Use capability checks before exposing an
+event-driven control.
+
+Consumer example: `docs/texture-api-consumer.md`.
+
+Browser verification checklist: Chrome/Android (autoplay requires muted media),
+Safari/iOS (inline video requires `playsInline` and user-gesture fallback), and
+background tabs (timers may throttle; frame state must remain bounded). Validate
+source switching, pause-at-current-frame, loop-off ending, reverse/ping-pong,
+stretch modes, drag/place transforms, and unmount cleanup in each target.
+
+`ResolvedTextureSource` owns a texture, optional controller, metadata, and
+ownership-safe `dispose()`. Abort stale loads, stop timers/RAF, remove media
+listeners, and never dispose externally owned textures.
+
 Use R3F intrinsic `<mesh>`, `<group>`, `<planeGeometry>`, `<meshBasicMaterial>`, etc. Load image textures with drei's `useTexture`.
 
 **Always name your meshes** (`name="myLabel"`). Names enable runtime lookup AND visual-feedback editing by the editor.
@@ -494,6 +1248,292 @@ const tex = useTexture("https://cdn.../badge.webp");
 
 ---
 
+## Scene-object runtime and authoring state
+
+Runtime components import from `@vincentt-xr/sdk`. Scene-object data and store
+operations import from `@vincentt-xr/sdk/scene-object`. DOM editors import from
+`@vincentt-xr/sdk/debug-ui`.
+
+### `<Transform3D value={settings}>` and `<MeshRenderer value={settings}>`
+
+`Transform3D` applies position, rotation (degrees), scale, visibility, and optional
+Drei transform controls to its children. `MeshRenderer` renders a cube, sphere,
+plane, or first-pass GLTF/GLB asset with basic/standard material settings.
+
+```tsx
+import {
+  DEFAULT_MESH_RENDERER,
+  DEFAULT_TRANSFORM_3D,
+  MeshRenderer,
+  Transform3D,
+} from "@vincentt-xr/sdk";
+
+<Transform3D
+  value={{
+    ...DEFAULT_TRANSFORM_3D,
+    position: { x: 0, y: 0, z: -1 },
+    showTransformControls: true,
+  }}
+  onChange={setTransform}
+>
+  <MeshRenderer
+    value={{
+      ...DEFAULT_MESH_RENDERER,
+      material: { ...DEFAULT_MESH_RENDERER.material, color: "#38bdf8" },
+    }}
+  />
+</Transform3D>;
+```
+
+`Transform3DProps` is `{ value, onChange?, children }`.
+`MeshRendererProps` is `{ value, renderOrder? }`. `renderOrder` is applied to the
+renderable mesh itself. Disabled or invisible settings render nothing.
+
+`MeshRendererSettings` fields:
+
+- `enabled`, `visible`: gate rendering.
+- `mesh`: `"cube" | "sphere" | "plane"` for primitive fallback.
+- `assetUrl?`: optional GLTF/GLB URL. When present, the asset renders instead of
+  the primitive mesh.
+- `assetNodeName?`: optional object name inside the loaded GLTF scene. When
+  missing or unresolved, the whole cloned scene renders.
+- `assetAnimation?`: optional animation clip name to play. Use `"all"` to play
+  every clip; otherwise provide the exact clip name.
+- `material.type`: `"standard" | "basic"`.
+- `material.color`, `opacity`, `wireframe`, `roughness`, `metalness`: material
+  overrides. Wireframe belongs to material state, not geometry state.
+- `material.renderState?`: optional advanced draw behavior:
+  - `depthTest`, `depthWrite`, `colorWrite`: booleans. `colorWrite` is the
+    all-channel write gate.
+  - `colorMask`: `{ r, g, b, a }` per-channel color write gates. This is
+    applied as scoped WebGL color-mask state for each mesh draw and restored
+    after the object renders.
+  - `depthFunc`: `"never" | "less" | "equal" | "lessEqual" | "greater" |
+"notEqual" | "greaterEqual" | "always"`.
+  - `cullMode`: `"back" | "front" | "off"`. The default `"back"` maps to
+    Three.js `FrontSide`; `"off"` maps to `DoubleSide`.
+  - `blendMode`: `"normal" | "additive" | "subtractive" | "multiply" |
+"none"`.
+  - `polygonOffset`: `{ enabled, factor, units }`.
+- `shadowMode`: `"off" | "cast" | "receive" | "castReceive"`.
+
+Current GLTF support is intentionally first-pass: the renderer clones the loaded
+scene, preserves authored GLB material colors, and applies opacity, wireframe,
+render-state fields, and shadow flags to cloned mesh materials. `assetAnimation`
+plays named clips or all clips while preserving playback when material settings
+change. Do not rely on it yet for advanced material graph preservation or
+production asset lifecycle guarantees.
+
+Render-state defaults preserve current behavior: depth test/write on,
+`lessEqual` depth function, color write on, back-face culling, normal blending,
+RGBA color mask fully enabled, and polygon offset disabled. Instance count is not
+part of `MeshRenderer.material.renderState`; it belongs to instanced mesh
+rendering rather than material shading state.
+
+`assetUrl` uses Drei `useGLTF`, so it suspends while loading. `MeshRenderer`
+wraps asset-backed rendering in `Suspense fallback={null}` so data-driven
+`SceneObjectRenderer` usage is safe by default. Add your own outer `Suspense`
+or call `useGLTF.preload(url)` only when you want a visible loading state or
+early fetch. Primitive meshes do not require Suspense.
+
+### Screen Transform data and resolver
+
+Import `ScreenTransform2DSettings`, `DEFAULT_SCREEN_TRANSFORM_2D`,
+`DEFAULT_SCREEN_TRANSFORM_ROOT`, `DEFAULT_REFERENCE_PIXELS_PER_UNIT`,
+`mergeScreenTransform2D`, and `resolveScreenTransform2D` from the core door.
+
+`ScreenTransform2DSettings` owns enabled/visible state, canvas-pixel position and
+size, normalized pivot, degree rotation, 2D scale, reference pixels per unit,
+render order, overlay mode, and guide visibility.
+
+```ts
+import {
+  DEFAULT_SCREEN_TRANSFORM_2D,
+  mergeScreenTransform2D,
+  resolveScreenTransform2D,
+  type ScreenTransform2DSettings,
+} from "@vincentt-xr/sdk";
+
+const transform: ScreenTransform2DSettings = mergeScreenTransform2D({
+  position: { x: 0, y: 240 },
+  size: { width: 420, height: 420 },
+  showTransformGuides: true,
+});
+
+const resolved = resolveScreenTransform2D({
+  transform,
+  parentSize: { width: 9, height: 16 },
+});
+```
+
+Use `mergeScreenTransform2D` to fill nested defaults. Use
+`resolveScreenTransform2D` whenever runtime or editor tooling must convert the
+authoring model into center, size, rotation, pivot offset, and aspect. Do not copy
+the default `720x1280` root or `32` reference-pixel constant into another renderer
+or guide.
+
+### Screen/world coordinate utilities
+
+Import the `*ScreenPixels` coordinate helpers, `screenPointToRay`, and
+`smoothNumber` / `smoothVector2` / `smoothVector3` from `@vincentt-xr/sdk`. Use
+these shared helpers instead of rewriting mapping or projection math or assuming
+design pixels are Three.js world units.
+SDK screen pixels use the Effect House-style `720x1280` design canvas, center
+origin, and +Y up.
+
+```ts
+const units = screenPixelsToUnits(120, { parentSize: screenDimensions });
+const pixels = screenUnitsToPixels(units, { parentSize: screenDimensions });
+
+const labelPosition = worldToScreenPixels({
+  point: trackedObject.getWorldPosition(new THREE.Vector3()),
+  camera,
+  viewportSize,
+});
+
+const placementRay = screenPointToRay({
+  point: { x: tapX, y: tapY },
+  camera,
+  viewportSize,
+});
+```
+
+- Use pixel/unit conversion for Screen Image, Screen Text, Screen Shape, editor
+  handles, and custom `ScreenSpaceUI` content.
+- Use `worldToScreenPixels` for labels, prompts, and indicators that follow a
+  face, hand, body joint, or 3D object. Its `depth` is projected NDC depth; hide
+  the result when `depth` is outside `[-1, 1]` because it is outside the camera
+  clip range.
+- Use `screenPointToRay` for tap selection, hit testing, and 3D placement. Pass
+  design-canvas coordinates, not DOM client pixels.
+- Use `clientToScreenPixels` / `screenPixelsToClient` for pointer events and DOM
+  overlays; pass the viewport element's `getBoundingClientRect()` result.
+- Use `normalizedToScreenPixels` / `screenPixelsToNormalized` for normalized
+  viewport coordinates with top-left origin. These values are not automatically
+  camera-crop adjusted.
+- Use `mediaToScreenPixels` / `screenPixelsToMedia` with the shared
+  `XRMediaLayout` for camera/image pixels. They apply cover/contain offsets,
+  scaling, and optional display mirroring; do not manually repeat that math.
+- Use `smoothNumber`, `smoothVector2`, or `smoothVector3` for tracked animation.
+  Pass the R3F frame `delta` in seconds and a smoothing rate (larger is faster).
+  Reuse the optional `out` vector in per-frame paths to avoid allocations.
+- Zero-size viewport/parent inputs return neutral zero coordinates or units so
+  first paint and collapsed layouts do not throw. Invalid custom root sizes and
+  `referencePixelsPerUnit` still throw because they are configuration errors.
+- Use Three.js `localToWorld`, `worldToLocal`, `Vector3.project/unproject`,
+  `set`, `toArray`, and `fromArray` directly; do not add SDK wrappers for them.
+
+### Scene-object store
+
+```ts
+import {
+  addComponentToObject,
+  createDefaultComponent,
+  createSceneObject,
+  deleteSceneObject,
+  getOrderedComponents,
+  moveComponent,
+  removeComponent,
+  type SceneObjectStore,
+} from "@vincentt-xr/sdk/scene-object";
+
+const cube = createSceneObject({ name: "Cube" });
+const transform = createDefaultComponent("Transform", cube.id);
+const mesh = createDefaultComponent("MeshRenderer", cube.id);
+cube.componentIds = [transform.id, mesh.id];
+
+const store: SceneObjectStore = {
+  objects: { [cube.id]: cube },
+  components: { [transform.id]: transform, [mesh.id]: mesh },
+};
+
+const ordered = getOrderedComponents(store, cube.id);
+```
+
+`SceneObject` owns identity, display name, enabled state, optional `renderGroupId`,
+optional hierarchy fields, and ordered `componentIds`. `SceneComponent` owns one
+typed settings payload and points back to its object. `ComponentRegistry` maps
+component types to those settings.
+
+Persisted scenes may still provide the deprecated `layerId`; migration treats it
+as a fallback when `renderGroupId` is absent. New code should only write
+`renderGroupId`.
+
+Nested scene-object fields:
+
+- `parentObjectId?: SceneObjectId | null` points to the parent object.
+- `childObjectIds?: SceneObjectId[]` stores ordered child IDs for hierarchy and
+  runtime recursion.
+
+Nested transforms are evaluated through the runtime object tree. Child objects
+render inside the parent object, so parent movement affects descendants while
+each child keeps its own local component settings.
+
+Store helpers are immutable and preserve extra fields on an app-extended store:
+
+- `addComponentToObject(store, component)` adds the component and its ID.
+- `moveComponent(store, objectId, componentId, nextIndex)` reorders one object.
+- `removeComponent(...)` removes the component and its ID.
+- `deleteSceneObject(store, objectId)` removes the object and all owned components.
+- `replaceSceneComponent(store, component)` replaces one component.
+- `replaceSceneObject(store, object)` replaces one object.
+- `setSceneObjectVisible(store, objectId, visible)` toggles object `enabled`.
+- `getSceneObjectChildren(store, objectId)` resolves explicit and implicit child
+  objects in hierarchy order.
+- `setSceneObjectParent(store, objectId, parentObjectId, nextIndex?)` updates both
+  sides of a parent/child relationship and rejects cycles or mixed transform
+  domains. Parent `Transform` under `Transform`, and `ScreenTransform` under
+  `ScreenTransform`. Existing child values become local-to-parent values.
+- `setSceneObjectParentPreserveWorldTransform(store, objectId, parentObjectId,
+nextIndex?)` is the editor seam for drag/drop and parent dropdowns. It updates
+  the hierarchy and recalculates the child's local `Transform` or
+  `ScreenTransform` so the object does not visually jump when nested or
+  un-nested. This is exact for representable transforms. Rotation combined with
+  non-uniform ancestor scale introduces shear, which neither component stores,
+  so preservation in that case is approximate.
+- `createOrderedComponentsSelector()` creates a memoized ordered selector.
+
+### `<SceneObjectRenderer>`
+
+`SceneObjectRenderer` reads an object plus its ordered components and renders the
+supported composition. Import the renderer from core and its store type from
+`/scene-object`.
+
+```tsx
+import { SceneObjectRenderer } from "@vincentt-xr/sdk";
+import type { SceneComponent, SceneObjectStore } from "@vincentt-xr/sdk/scene-object";
+
+<SceneObjectRenderer
+  objectId={cube.id}
+  store={store}
+  editorMode
+  onComponentChange={(component: SceneComponent) => replaceComponent(component)}
+/>;
+```
+
+Props are `objectId`, `store`, optional `editorMode`, optional
+`onComponentChange`, and optional `fallback`. Supported compositions are:
+
+- `Transform` + `MeshRenderer`
+- `Transform` + `Light`
+- `Transform` + `MeshRenderer` with optional `LookAt` and `PinToMesh`
+- `Transform` only as an invisible 3D null/container
+- `ScreenTransform` only as an invisible 2D null/container
+- `ScreenTransform` + `ScreenImage`
+- `ScreenTransform` + `ScreenText`
+
+For mesh objects, `SceneObjectRenderer` registers the object id at runtime so
+behavior components can resolve serialized target ids. Inspector/editor changes
+must route through `onComponentChange` and replace the selected object's
+component in the store; do not keep separate page-local copies of transform,
+material, light, LookAt, or PinToMesh state.
+
+In editor mode, transform changes return through `onComponentChange`.
+Unsupported compositions render nothing in production and use `fallback` in
+editor mode.
+
+---
+
 ## `<ScreenText>` — Standard screen-space text
 
 Import from `@vincentt-xr/sdk`. Use this when you want the standard
@@ -545,6 +1585,387 @@ Use `TextLabel` when:
 - you want to place text manually in world space or inside a custom transform
 - you are building a lower-level composite where another component owns layout
 
+`SceneObjectRenderer` owns the required `ScreenSpaceUI` container when it renders
+an object composed from `ScreenTransform` + `ScreenText` or `ScreenImage`. Do not
+wrap those renderer instances in an additional `ScreenSpaceUI`; direct uses of
+`ScreenText` and `ScreenImage` still require the container shown above.
+
+Debug panels are independent, selection-driven surfaces. Use `HierarchyPanel` for a
+render-group-aware scene-object list and render one
+`ObjectInspectorPanel` for the selected object. Both accept `initialPosition` so the
+hierarchy and Inspector can be presented side by side instead of overlapping.
+`ScreenTextSettingsPanel` and `ScreenImageSettingsPanel` already own their complete
+Inspector UI; pass their optional `inspector` binding when they edit an object from
+a shared scene store. Do not nest either one inside another `ObjectInspectorPanel`.
+`ObjectInspectorPanel` is uncontrolled by default, but multi-object editors can pass
+`position` and `onPositionChange` to preserve one Inspector location while swapping
+the selected object's panel. `SceneObjectRenderer` forwards screen transform-guide
+drags through `onComponentChange`; selection policies such as closing active transform
+controls belong to the parent editor, not to `HierarchyPanel` or the standalone panels.
+
+### Reusable XR scene editor debug UI
+
+For temporary client-app scene setup, prefer the reusable scene editor adapters
+from `@vincentt-xr/sdk/debug-ui` instead of rewriting viewport, hierarchy, and
+inspector wiring in each app. These are debug/authoring adapters over the
+scene-object runtime, not production runtime UI.
+
+```tsx
+import {
+  SceneHierarchyPanel,
+  SceneInspectorPanel,
+  ViewportToolbar,
+  XRSceneEditorProvider,
+  XRSceneViewport,
+} from "@vincentt-xr/sdk/debug-ui";
+import {
+  replaceSceneComponent,
+  replaceSceneObject,
+  type RenderGroupSceneObjectStore,
+} from "@vincentt-xr/sdk/scene-object";
+
+<XRSceneEditorProvider
+  store={store}
+  selectedObjectId={selectedObjectId}
+  onSelectObject={setSelectedObjectId}
+  onStoreChange={setStore}
+  onComponentChange={(component) =>
+    setStore((current) => replaceSceneComponent(current, component))
+  }
+  onObjectChange={(object) => setStore((current) => replaceSceneObject(current, object))}
+>
+  <XRSceneViewport />
+  <ViewportToolbar />
+  <SceneHierarchyPanel />
+  <SceneInspectorPanel />
+</XRSceneEditorProvider>;
+```
+
+All pieces are optional and composable:
+
+- `XRSceneViewport` renders `XRScene`, an editor-owned camera-texture plane,
+  editor grid, camera, orbit controls, and `SceneObjectRenderer` entries from
+  `createRenderPlan`. The editor video plane consumes the same camera texture as
+  `VideoBackground`, but it is a separate debug-ui plane with `depthTest` and
+  `depthWrite` enabled. Do not add depth props to core `VideoBackground`.
+- `SceneHierarchyPanel` adapts `HierarchyPanel` to a
+  `RenderGroupSceneObjectStore`.
+- `SceneInspectorPanel` renders component settings for the selected object and
+  routes edits through `onComponentChange` or `onObjectChange`.
+- `ViewportToolbar` owns transient viewport controls such as orbit on/off.
+
+Keep `SceneObjectStore`/`RenderGroupSceneObjectStore` as the only persistent
+scene data. Selection, orbit state, grid visibility, video-background visibility,
+and editor camera choices are transient editor session state. Do not keep
+page-local shadow copies of Transform, MeshRenderer, Light, LookAt, or PinToMesh
+settings.
+
+Use these adapters in development/debug surfaces such as `/viewport-editor`
+or a temporary client-app editor. Omit them for final preview/runtime and render
+the scene through core runtime components instead.
+
+For debug pages that need a camera/image/video picker, import
+`MediaSourceSwitcher` and `useFaceTrackingMediaSourceSession` from
+`@vincentt-xr/sdk/debug-ui`. `useFaceTrackingMediaSourceSession(activeMediaSource)`
+applies the selected debug media preset to the current XR session and starts
+the face-tracking media pipeline used by the debug face examples. The older
+`useMediaSourceSession(activeMediaSource, { pipeline })` name remains available
+for custom debug pipelines. Use these only in debug/example UI; production
+runtime should set the session media source directly.
+
+### Debug UI usage in Harness client apps
+
+#### AI-agent integration contract
+
+Choose the import door by responsibility. Do not search other doors for an
+equivalent symbol and do not import SDK source files directly.
+
+| Agent task                                | Import door                     | Symbols                                                                              |
+| ----------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------ |
+| Render managed objects and compose passes | `@vincentt-xr/sdk`              | `SceneObjectRenderer`, `SequentialRenderPasses`, `RenderGroupLayer`                  |
+| Guard internal render layers              | `@vincentt-xr/sdk`              | `MAX_RENDER_GROUP_PASSES`, `getRenderGroupLayer`, `EXTERNAL_BACKGROUND_RENDER_LAYER` |
+| Create and mutate scene-object state      | `@vincentt-xr/sdk/scene-object` | `createSceneObject`, `createDefaultComponent`, store helpers                         |
+| Materialize and order render groups       | `@vincentt-xr/sdk/scene-object` | `migrateToRenderGroups`, `createRenderPlan`, reorder/move helpers                    |
+| Render DOM authoring controls             | `@vincentt-xr/sdk/debug-ui`     | `HierarchyPanel`, `ObjectInspectorPanel`, `ComponentEditor`, settings panels         |
+| Type a bulk hierarchy export              | `@vincentt-xr/sdk/debug-ui`     | `HierarchyPanelCopyConfig`                                                           |
+
+The integrating client, not the SDK panels, must own all mutable editor state:
+
+- the complete scene store, including `objects`, `components`, `renderGroups`,
+  and `renderGroupOrder`;
+- `selectedObjectId` and which selected Inspector is rendered;
+- component replacement and object/group visibility updates;
+- reorder and compatibility-checked move operations;
+- the rule that changing selection closes transform controls and guides belonging
+  to the previously selected object; and
+- the `HierarchyPanelCopyConfig` value.
+
+Required invariants:
+
+- Mount DOM debug panels outside `XRScene`; mount R3F/Three.js renderers and
+  controls inside `XRScene`.
+- Keep both branches below the same parent state and inside `XRProvider`.
+- Derive group order from `scene.renderGroupOrder`; never hardcode a canonical
+  order such as background/general/tracking/foreground/post.
+- Use `SequentialRenderPasses` for guaranteed cross-group composition. Do not
+  replace it with a larger Three.js `renderOrder` value.
+- Treat camera layers as internal visibility masks, not user-facing layer order.
+- Keep each managed object in exactly one materialized group and exactly once in
+  that group's `objectIds`.
+- Do not show transform controls for an unselected object. Initial control state
+  must agree with the initial `selectedObjectId`.
+- Do not create more than `MAX_RENDER_GROUP_PASSES` managed groups.
+- Treat Copy Config as a versioned export/debug payload, not as an import or
+  persistence API.
+
+Use these state transitions:
+
+| Event             | Required parent-state update                                                     |
+| ----------------- | -------------------------------------------------------------------------------- |
+| Select object     | Set `selectedObjectId`; disable all existing 2D guides and 3D transform controls |
+| Edit component    | Replace that component immutably in `scene.components`                           |
+| Reorder group     | Call `reorderRenderGroup`; keep object lists unchanged                           |
+| Reorder object    | Call `reorderObjectWithinGroup`; change only the selected group's `objectIds`    |
+| Move object       | Validate compatibility, then call `moveObjectToGroup`                            |
+| Toggle visibility | Update the object or group; do not encode visibility in selection state          |
+| Render frame      | Derive `createRenderPlan(scene)` and active pass layers from current state       |
+
+Failure recovery for generated integrations:
+
+| Symptom                                                 | Likely cause                                                                                                           | Required fix                                                                                                           | Do not                                      |
+| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| “R3F hooks can only be used within Canvas”              | R3F renderer/control mounted in the DOM branch, or duplicate React/R3F packages                                        | Move the scene component inside `XRScene`; in link mode pin React, React DOM, Three.js, R3F, and Drei to client copies | Move DOM panels into `XRScene`              |
+| Hierarchy order changes but visual composition does not | Only `renderOrder` or array order changed                                                                              | Recompute the render plan and pass the ordered layers to `SequentialRenderPasses`                                      | Expose camera-layer numbers as visual order |
+| Wrong object's gizmo remains visible                    | Selection changed without clearing component control flags                                                             | Disable all stale transform controls/guides in the same selection transition                                           | Assume `HierarchyPanel` owns control state  |
+| Screen transform drag stops after one move              | An unstable callback caused active pointer listeners to be replaced                                                    | Use current SDK components and keep component replacement callbacks wired to parent state                              | Fork private drag logic into the DOM panel  |
+| Cross-group drop silently fails                         | Target policy rejects the object's component composition                                                               | Call `validateGroupCompatibility` and preserve the original store on `false`                                           | Force incompatible membership               |
+| Group is omitted from the render plan                   | Its zero-based index is `>= MAX_RENDER_GROUP_PASSES` (`30`), so the 31st group onward is beyond the managed-pass limit | Prevent creation using `MAX_RENDER_GROUP_PASSES`                                                                       | Reuse/clamp multiple groups onto one layer  |
+| Copied JSON cannot be restored                          | Copy Config has no public importer                                                                                     | Treat it as export/debug handoff only                                                                                  | Invent an undocumented restore API          |
+
+Harness clients must keep the DOM authoring UI and R3F scene integration in sibling
+branches under the same parent-owned state:
+
+```text
+XRProvider
+└─ AspectRatioContainer
+   ├─ XRScene (R3F Canvas)
+   │  ├─ camera, lights, and scene content
+   │  ├─ SequentialRenderPasses
+   │  ├─ SceneObjectRenderer instances
+   │  └─ transform guides and controls
+   ├─ HierarchyPanel
+   └─ selected-object Inspector or standalone settings panel
+```
+
+Mount `HierarchyPanel`, `ObjectInspectorPanel`, `ComponentEditor`,
+`ScreenTextSettingsPanel`, and `ScreenImageSettingsPanel` outside `XRScene`.
+They render DOM portals and communicate through props and callbacks. Mount
+`SceneObjectRenderer`, `SequentialRenderPasses`, `ScreenSpaceUI`, `Transform3D`,
+and all Three.js content inside `XRScene` because they use R3F Canvas context.
+Keep both branches inside `XRProvider`.
+
+The parent Harness component owns:
+
+- the complete scene-object store;
+- `selectedObjectId`;
+- component replacement;
+- group and object reorder callbacks;
+- visibility callbacks;
+- compatibility-checked moves; and
+- the bulk Copy Config value.
+
+The data loop is:
+
+```text
+Hierarchy / Inspector callback
+        ↓
+parent scene store
+        ↓
+selection + render plan + active pass layers
+        ↓
+SceneObjectRenderer inside XRScene
+        ↓
+transform-control change
+        └──────────────→ parent scene store
+```
+
+If React reports that R3F hooks can only be used within Canvas, a scene renderer,
+render-pass controller, transform guide, or Three.js control has crossed into the
+DOM panel branch. Do not solve this by moving the panels into `XRScene`; move the
+R3F-dependent scene component back inside `XRScene` and keep the shared state above
+both branches.
+
+The working `test001` Harness client is the canonical external integration. It runs
+a Cube, Screen Image, and Screen Text together with `HierarchyPanel`,
+selection-driven Inspectors, component editors, group/object ordering, visibility,
+transform controls, sequential render passes, and bulk Copy Config. The SDK
+`/layer-panel-test` page is the matching in-repo fixture.
+
+For SDK co-development, run `pnpm build:watch` in `vincentt-xr-sdk` and
+`SDK_LINK=1 pnpm dev` in the Harness client. Use a different `PORT` when the SDK
+example is already using 5173, for example
+`PORT=5174 SDK_LINK=1 pnpm dev`. Also validate the client typecheck and linked
+production build; the in-repo SDK example alone does not validate package exports
+or Canvas placement in a separate client.
+
+### Render groups and hierarchy ordering
+
+Import render-group types, policies, migration, compatibility, reorder helpers, and
+`createRenderPlan` from `@vincentt-xr/sdk/scene-object`. Import
+`SceneObjectRenderer`, `SequentialRenderPasses`, `RenderGroupLayer`,
+`getRenderGroupLayer`, and `EXTERNAL_BACKGROUND_RENDER_LAYER` from core.
+
+Use `migrateToRenderGroups(store, objectOrder)` to group a flat scene-object store.
+It preserves compatible `renderGroupId` assignments, infers missing or incompatible
+assignments from components, and creates only the groups required by actual scene
+objects. Their initial order follows the first occurrence in `objectOrder`; there is
+no fixed render-order list. New
+objects can call `getDefaultRenderGroupId(components)` after their components are
+assembled.
+
+The ownership boundary is:
+
+| Concern                                            | Owner                      |
+| -------------------------------------------------- | -------------------------- |
+| Object identity, display name, and component order | `SceneObject`              |
+| Object behavior and settings                       | `SceneComponent`           |
+| Cross-domain composition and group visibility      | `RenderGroup`              |
+| Order inside a group                               | `RenderGroup.objectIds`    |
+| Order between groups                               | `renderGroupOrder`         |
+| Structural commands                                | `HierarchyPanel` callbacks |
+| Property editing and selection policy              | Parent editor + Inspector  |
+| Object-to-pass mapping                             | `createRenderPlan()`       |
+| Final frame composition                            | `SequentialRenderPasses`   |
+
+The Hierarchy and Inspector emit commands but do not own scene state or rendering.
+Every managed object must belong to exactly one materialized group, appear exactly
+once across all group `objectIds` arrays, and have a matching `renderGroupId`.
+Selection is editor state and never changes render order.
+
+Use only the immutable helpers to change structure:
+
+- `reorderRenderGroup(store, groupId, nextIndex)` changes group composition order.
+- `reorderObjectWithinGroup(store, groupId, objectId, nextIndex)` sorts within a group.
+- `moveObjectToGroup(...)` moves only when `validateGroupCompatibility(...)` passes.
+- `createRenderPlan(store)` returns top-first entries and stable 1000-value sorting bands.
+
+Unknown group/object IDs, incompatible targets, and reorders to the current index
+are safe no-ops that return the original store. `validateGroupCompatibility` is
+read-only and returns `false` for missing objects, missing groups, or rejected
+component compositions.
+
+Pass each plan entry's `renderOrder` and `renderLayer` to `SceneObjectRenderer`.
+Mount one `SequentialRenderPasses` with the active plan layers in top-first order.
+It takes over the R3F loop, preserves color between groups, and clears depth before
+each later group. Bottom groups therefore composite in front even across Three.js's
+opaque and transparent queues. `captureFrame()` uses the same grouped renderer.
+
+These mechanisms are different:
+
+- `renderGroupOrder` controls cross-group sequential composition. The first group
+  renders first; the last group renders last and appears in front.
+- `RenderGroup.objectIds` controls order inside one group.
+- Three.js camera layers are internal visibility masks; their numeric values do not
+  define visual order.
+- `renderOrder` is a sorting value inside one render call. It cannot by itself
+  impose ordering across opaque and transparent queues.
+
+```tsx
+const plan = createRenderPlan(scene);
+const passLayers = scene.renderGroupOrder.flatMap((groupId, groupIndex) =>
+  scene.renderGroups[groupId]?.enabled && scene.renderGroups[groupId].objectIds.length
+    ? [getRenderGroupLayer(groupIndex)]
+    : [],
+);
+
+<SequentialRenderPasses layers={passLayers} />;
+{
+  plan.map((entry) => (
+    <SceneObjectRenderer
+      key={entry.objectId}
+      objectId={entry.objectId}
+      store={scene}
+      renderOrder={entry.renderOrder}
+      renderLayer={entry.renderLayer}
+    />
+  ));
+}
+```
+
+Layer 0 is shared across passes for lights and non-renderable scene infrastructure.
+All visible managed project content in a grouped scene must be assigned to a group
+layer. `SequentialRenderPasses` also enables its layers on the R3F interaction
+raycaster. `RenderGroupLayer` leaves Drei `TransformControls` on shared layer 0,
+so 2D guides and 3D move/rotate/scale gizmos remain draggable after render-group
+isolation.
+
+For legacy flat camera backgrounds, render `VideoBackground` outside managed
+scene-object content. For the reusable scene editor, use `XRSceneViewport`; it
+owns a separate depth-writing camera-texture plane for editor-only 3D placement.
+
+`HierarchyPanel` receives ordered `groups`, scene `objects`, selection callbacks,
+and separate callbacks for group reorder, within-group reorder, and explicit moves.
+It owns collapse UI and drop feedback, but the parent store owns selection, group
+visibility, compatibility validation, the Inspector, and rendering.
+Empty reserved groups are not materialized in the store or presented in the hierarchy.
+The panel is expanded by default and can fold to its title button without losing
+its position, current selection, or per-group collapse state. The normal hierarchy
+shows human-readable names only; internal domains, IDs, camera layers, and ordering
+values belong in deliberate debug tooling rather than the primary object list.
+Pass a `HierarchyPanelCopyConfig` value as `copyConfig` to show one bulk
+**Copy Config** action. The panel writes that value as formatted JSON and confirms
+with **Copied Config**. For a complete scene
+handoff, include `renderGroupOrder`, `renderGroups`, `objects`, and `components`;
+omit transient editor state such as current selection and panel position. The copied
+group order therefore contains only groups backed by current scene objects.
+
+Use this versioned shape for a complete handoff:
+
+```ts
+type SceneConfigV1 = {
+  kind: "scene";
+  version: 1;
+  renderGroupOrder: RenderGroupId[];
+  renderGroups: Record<RenderGroupId, RenderGroup>;
+  objects: Record<SceneObjectId, SceneObject>;
+  components: Record<SceneComponentId, SceneComponent>;
+};
+```
+
+This is currently an export/debugging contract, not a guaranteed round-trip
+format: there is no public scene-config importer. Exclude selection, panel
+position, fold/collapse state, active drag state, feedback messages, and any
+flat external `VideoBackground`.
+
+Current compatibility and limits:
+
+| Domain             | Required composition                               | Status    |
+| ------------------ | -------------------------------------------------- | --------- |
+| General / 3D Scene | `Transform` + `MeshRenderer`                       | supported |
+| 2D Foreground      | `ScreenTransform` + `ScreenText` or `ScreenImage`  | supported |
+| Background         | editor camera-texture plane or external background | partial   |
+| AR Tracking        | tracking scene-object components                   | reserved  |
+| Post Effects       | post-processing scene object                       | reserved  |
+
+Reserved groups are not materialized or displayed until compatible managed scene
+objects exist. Each active group adds one scene render, with a maximum of
+`MAX_RENDER_GROUP_PASSES` (currently 30) managed passes. Import that constant from
+`@vincentt-xr/sdk` when guarding group creation. `createRenderPlan` omits groups
+beyond the limit instead of throwing or assigning colliding camera layers.
+`EXTERNAL_BACKGROUND_RENDER_LAYER` remains temporary infrastructure for legacy
+external background composition. The reusable scene editor should prefer its
+own camera-texture plane instead of treating `VideoBackground` as a managed
+scene object.
+
+An explicit `renderGroupId` assignment is retained only when its policy accepts the
+object's components; otherwise grouping uses the inferred compatible domain. Object
+IDs, component IDs, and component settings remain unchanged.
+
+The render-group tests protect derived group order, compatible defaults, local
+object reorder, rejected move no-ops, stable render bands/layers, sequential depth
+clearing, grouped capture, and interaction across active camera layers. The
+compiling reference implementation is `/layer-panel-test` in the SDK example.
+
 ### Shared debug authoring surface for `ScreenText`
 
 The SDK also ships a dev-only inspector at `lib/debug-ui/screen-text-settings`
@@ -558,12 +1979,12 @@ including `name`, `kind: "screenText"`, `transform`, `content`, `style`,
 `canvasSize`. Use that payload as the handoff from human layout tuning back to
 code.
 
-### Shared debug layer panel
+### Legacy debug layer panel
 
 The SDK ships a reusable `LayerPanel` in `lib/debug-ui/layer-panel` for
-Photoshop-style stack management. It is intended for dev / creator tooling
-only and is currently used by the template preview to manage `ScreenImage` and
-`ScreenText` layers. Production shipping surfaces should not include the panel.
+flat-stack compatibility. New grouped editors should use `HierarchyPanel`.
+Both are intended for dev / creator tooling only. Production shipping surfaces
+should not include either panel.
 
 ---
 
@@ -663,21 +2084,28 @@ import { AspectRatioContainer } from "@vincentt-xr/sdk";
 
 Grab a photo of the live render or record the canvas, then save or share it.
 
-### `session.captureFrame()` + `dataURLtoFile()` — Single-shot photo
+### `useFrameCapture()` + `dataURLtoFile()` — Single-shot photo
 
-`captureFrame()` forces a fresh render and returns a `data:` URL of the current
-frame. `dataURLtoFile(dataUrl, filename)` turns it into a `File` for upload or the
-Web Share API.
+Use `useFrameCapture` for UI/effect logic. It exposes `status`, `capturePhoto`,
+`clear`, `dataUrl`, and `error`, plus `onCaptureStart`, `onCaptureComplete`, and
+`onError`. Status is `idle | capturing | completed | error`. The underlying
+capture forces a fresh render and returns a `data:` URL; `dataURLtoFile` turns
+it into a `File` for upload or the Web Share API. `capturePhoto()` resolves to
+the URL on success or `null` after setting `status: "error"` and `error` on
+failure; callers do not need a rejection handler.
 
 ```tsx
-import { dataURLtoFile } from "@vincentt-xr/sdk";
-import { useXRContext } from "@vincentt-xr/sdk/low-level";
+import { dataURLtoFile, useFrameCapture } from "@vincentt-xr/sdk";
 
-const { session } = useXRContext();
-const dataUrl = session.captureFrame();
-const file = dataURLtoFile(dataUrl, "photo.png");
+const photo = useFrameCapture({
+  onCaptureComplete: (dataUrl) => share(dataURLtoFile(dataUrl, "photo.png")),
+});
+await photo.capturePhoto();
 ```
 
+For synchronous low-level code, `session.captureFrame()` remains available via
+`useXRContext` from `@vincentt-xr/sdk/low-level`.
+
 ### `useMediaRecorder()` — Record the canvas to a video Blob
 
 Records a `MediaStream` (from the canvas's `captureStream()`) to a `Blob`. Picks
@@ -694,6 +2122,20 @@ await rec.start(canvas.captureStream(30));
 rec.stop(); // -> rec.recordedBlob is the video Blob
 ```
 
+Use `rec.status` as the source of truth:
+`idle | starting | recording | paused | stopping | completed | error`.
+Controls are `start`, `pause`, `resume`, `stop`, and `clear`. Events are
+`onRecordingStart`, `onRecordingPause`, `onRecordingResume`,
+`onRecordingStop`, `onRecordingComplete`, and `onError`. Keep `isRecording`
+and `isPaused` only as convenience booleans; do not invent parallel state.
+When `passThroughStream` is configured, call `start()` without an argument;
+otherwise call `start(stream)` with the canvas capture stream.
+The verified `/capture-recording` example exercises the complete photo and video
+lifecycle against the live XR canvas. It displays a recording HUD and elapsed
+time for `starting`, `recording`, `paused`, `stopping`, and `completed`, then
+previews the resulting `recordedBlob` in a video player. Photo and recording
+flows were verified with a real webcam on 26 July 2026.
+
 ---
 
 ## Audio
@@ -753,3 +2195,154 @@ function SoundToggle() {
 Audio assets: m4a (AAC). A rare app needing a second, independent mixer can
 `new AudioEngine()` and drive it directly; the free functions always target the
 one default engine.
+
+## 3D behavior components: LookAt and PinToMesh
+
+`LookAt` and `PinToMesh` are partial-stage XRScene behavior components. They are
+exported for editor/API prototyping, but they are not yet a fully verified
+Effect House parity surface.
+
+`LookAt` rotates its child toward a target object resolved either from a direct
+`Object3D` prop or from serialized scene-object target ids. Treat it as suitable
+for current editor experiments, not final production behavior, until point vs
+direction mode, axis conventions, offset ordering, and missing-target behavior
+are covered by tests.
+
+When `SceneObjectRenderer` renders nested objects, child scene objects do not
+inherit the parent's LookAt reorientation by default. `LookAtSettings` includes
+`inheritChildren: boolean` for the special case where children should rigidly
+follow the parent's look-at facing. Defaults from
+`createDefaultComponent("LookAt", objectId)` set `inheritChildren: false`.
+
+`PinToMesh` wraps a source object and pins that source wrapper to a target mesh
+surface. Pass `PinToMeshSettings` with
+`enabled: true` and a non-null `targetObjectId`; default settings are disabled
+with no target. The component supports static mesh surface lookup, UV input,
+orientation, vertex-normal option, offset space, offset position, and offset
+rotation. Offset position and offset rotation default to `{ x: 0, y: 0, z: 0 }`.
+When PinToMesh is disabled or the target becomes unavailable, the runtime pin
+wrapper resets to local position `0,0,0` and identity rotation so the child
+`Transform3D` remains the authored source of truth.
+
+Pin wrapper rotation is identity-based for `orientation: "none"` and
+`orientation: "position"`. `orientation: "positionAndDirection"` aligns the
+wrapper to the target surface normal before offset rotation is applied. Offset
+rotation is reapplied from a clean base each frame and must not compound over
+time.
+
+Use `PinToMeshSettingsPanel` from `@vincentt-xr/sdk/debug-ui` for editor
+controls. The panel uses Transform-style text number inputs for UV and offsets:
+visible zero defaults, decimal validation, 0.1 arrow-step increments, Shift for
+larger steps, and Alt for finer steps. Serialized scenes should store stable
+scene-object ids for targets; runtime renderers resolve those ids to registered
+`Object3D` instances.
+
+Direct runtime usage:
+
+```tsx
+import { LookAt, PinToMesh, Transform3D, MeshRenderer } from "@vincentt-xr/sdk";
+
+<PinToMesh
+  target={targetObject}
+  settings={{
+    enabled: true,
+    targetObjectId: "base-plane",
+    orientation: "positionAndDirection",
+    uv: { x: 0.5, y: 0.5 },
+    vertexNormal: true,
+    offsetSpace: "local",
+    offsetPosition: { x: 0, y: 0.25, z: 0 },
+    offsetRotation: { x: 0, y: 0, z: 0 },
+  }}
+>
+  <Transform3D value={transformSettings}>
+    <LookAt
+      target={lookTargetObject}
+      settings={{
+        enabled: true,
+        targetObjectId: "target-object",
+        mode: "point",
+        offsetRotation: { x: 0, y: 0, z: 0 },
+      }}
+    >
+      <MeshRenderer value={meshSettings} />
+    </LookAt>
+  </Transform3D>
+</PinToMesh>;
+```
+
+Serialized component defaults:
+
+- `createDefaultComponent("LookAt", objectId)` returns disabled LookAt settings
+  with `targetObjectId: null`, `mode: "point"`, and zero offset rotation.
+- `createDefaultComponent("PinToMesh", objectId)` returns disabled PinToMesh
+  settings with `targetObjectId: null`, UV `{ x: 0.5, y: 0.5 }`,
+  `orientation: "none"`, `vertexNormal: false`, `offsetSpace: "local"`, and
+  zero position/rotation offsets.
+
+Current limitations:
+
+- UV behavior is not final. Missing UVs currently fall back to target bounds
+  center behavior instead of a visible invalid-target state.
+- LookAt has a minimal API: `enabled`, `targetObjectId`, `mode`, and
+  `offsetRotation`. Axis remapping and world-up controls are still planned.
+- Runtime target resolution is scoped by `XRProvider` through an internal
+  runtime-object registry. Direct calls to `registerRuntimeObject` and
+  `resolveRuntimeObject` outside an `XRProvider` use a legacy fallback registry
+  and should be avoided for multi-scene pages.
+
+## 3D light scene objects
+
+`LightObject` renders a serialized light component through `Transform3D`.
+Import from `@vincentt-xr/sdk`.
+
+```tsx
+import { LightObject } from "@vincentt-xr/sdk";
+
+<LightObject
+  transform={transformSettings}
+  settings={{
+    enabled: true,
+    type: "directional",
+    color: "#ffffff",
+    intensity: 2.2,
+    castShadow: true,
+    distance: 10,
+    angle: Math.PI / 6,
+    penumbra: 0.2,
+    decay: 2,
+    showHelper: false,
+  }}
+/>;
+```
+
+`LightSettings.type` is `"ambient" | "directional" | "point" | "spot"`.
+Directional, point, and spot lights support `castShadow`; ambient lights only
+contribute global light. `showHelper` draws a small non-physical editor marker
+for the light object and defaults to `false`; enable it only in editor/debug
+surfaces.
+
+For an Effect House-style declarative player, use `<AudioPlayer>`. It supports
+`once`, a finite `loop` count, and `infinite` playback, plus autoplay intent,
+per-player mute, and a clamped 0–100 volume. Browser autoplay policy still
+applies: audible autoplay may reject until a user gesture, surfaced through
+`onError`. The component is headless (it renders a hidden `<audio>`); attach a
+ref for custom controls.
+
+```tsx
+import { AudioPlayer, type AudioPlayerHandle } from "@vincentt-xr/sdk";
+
+const player = useRef<AudioPlayerHandle>(null);
+
+<AudioPlayer
+  ref={player}
+  src={musicUrl}
+  playMode="loop"
+  loopCount={3}
+  autoplay
+  volume={80}
+  onError={(error) => console.warn(error)}
+/>;
+
+// From a user gesture: player.current?.play(), .pause(), or .stop().
+```