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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (352) hide show
  1. package/GROUNDING.md +1588 -20
  2. package/dist/{DebuggerUI-CatYc-RG.cjs → DebuggerUI-B45_Gb9d.cjs} +1 -1
  3. package/dist/{DebuggerUI-gLMKiVwJ.js → DebuggerUI-Cq28c18s.js} +1 -1
  4. package/dist/FaceMeshRenderer-6t8OsQhK.js +1195 -0
  5. package/dist/FaceMeshRenderer-lQLhYIW-.cjs +155 -0
  6. package/dist/FaceRetouch-CDrL0pXg.js +551 -0
  7. package/dist/FaceRetouch-DtNl8-4e.cjs +134 -0
  8. package/dist/audio/AudioEngine.d.ts +3 -1
  9. package/dist/audio/AudioPlayer.d.ts +29 -0
  10. package/dist/audio/AudioPlayerLogic.d.ts +4 -0
  11. package/dist/audio/index.d.ts +2 -0
  12. package/dist/components/Axes/index.d.ts +6 -0
  13. package/dist/components/FaceMesh/FaceMeshRenderer.d.ts +17 -0
  14. package/dist/components/FaceMesh/canonical/CanonicalFaceMeshRenderer.d.ts +17 -1
  15. package/dist/components/FaceMesh/canonical/FaceMeshMaterial.d.ts +25 -0
  16. package/dist/components/FaceMesh/canonical/assets.d.ts +3 -0
  17. package/dist/components/FaceMesh/canonical/geometryGroups.d.ts +9 -0
  18. package/dist/components/FaceMesh/canonical/parseCanonicalFaceModel.d.ts +2 -0
  19. package/dist/components/FaceMesh/canonical/shaders.d.ts +2 -0
  20. package/dist/components/FaceMesh/deform.d.ts +3 -0
  21. package/dist/components/FaceMesh/index.d.ts +5 -0
  22. package/dist/components/FaceMesh/material/defaults.d.ts +70 -0
  23. package/dist/components/FaceMesh/material/index.d.ts +1 -0
  24. package/dist/components/FaceMesh/material/options.d.ts +5 -1
  25. package/dist/components/FaceMesh/material/support.d.ts +7 -2
  26. package/dist/components/FaceMesh/material/textures.d.ts +4 -0
  27. package/dist/components/FaceMesh/material/types.d.ts +2 -2
  28. package/dist/components/FaceRetouch/Background.d.ts +5 -6
  29. package/dist/components/FaceRetouch/FaceRetouch.d.ts +47 -0
  30. package/dist/components/FaceRetouch/index.d.ts +2 -8
  31. package/dist/components/FaceRetouch/landmarkMask.d.ts +0 -5
  32. package/dist/components/FaceRetouch/useFaceRetouchMask.d.ts +3 -7
  33. package/dist/components/FaceTracker/index.d.ts +5 -3
  34. package/dist/components/FaceWarp3D/FaceWarp3DHead.d.ts +1 -1
  35. package/dist/components/HandJoints2D/index.d.ts +1 -1
  36. package/dist/components/HandTracking2D/HandVisual.d.ts +1 -1
  37. package/dist/components/HandTracking2D/index.d.ts +1 -1
  38. package/dist/components/HandTracking2DController/index.d.ts +1 -1
  39. package/dist/components/HandTracking3D/index.d.ts +1 -1
  40. package/dist/components/LightObject/index.d.ts +20 -0
  41. package/dist/components/LookAt/index.d.ts +23 -0
  42. package/dist/components/MeshRenderer/index.d.ts +58 -0
  43. package/dist/components/PerspectiveCamera/index.d.ts +2 -8
  44. package/dist/components/PinToMesh/index.d.ts +47 -0
  45. package/dist/components/RenderGroupLayer/index.d.ts +6 -0
  46. package/dist/components/SceneObjectRenderer/index.d.ts +16 -0
  47. package/dist/components/Screen2D/ScreenTransformFrame.d.ts +11 -0
  48. package/dist/components/Screen2D/ScreenTransformHelpers.d.ts +19 -0
  49. package/dist/components/Screen2D/ScreenTransformInteraction.d.ts +18 -0
  50. package/dist/components/Screen2D/index.d.ts +5 -0
  51. package/dist/components/ScreenGlass/defaults.d.ts +3 -0
  52. package/dist/components/ScreenGlass/index.d.ts +5 -0
  53. package/dist/components/ScreenGlass/shaders.d.ts +2 -0
  54. package/dist/components/ScreenGlass/types.d.ts +10 -0
  55. package/dist/components/ScreenGradient/defaults.d.ts +5 -0
  56. package/dist/components/ScreenGradient/index.d.ts +5 -0
  57. package/dist/components/ScreenGradient/shaders.d.ts +2 -0
  58. package/dist/components/ScreenGradient/types.d.ts +19 -0
  59. package/dist/components/ScreenImage/ScreenImage.d.ts +4 -0
  60. package/dist/components/ScreenImage/components/DynamicTextureSync.d.ts +9 -0
  61. package/dist/components/ScreenImage/components/ScreenImageBody.d.ts +9 -0
  62. package/dist/components/ScreenImage/components/ScreenImageFrame.d.ts +9 -0
  63. package/dist/components/ScreenImage/components/ScreenImageTransformFrame.d.ts +9 -0
  64. package/dist/components/ScreenImage/fit.d.ts +52 -0
  65. package/dist/components/ScreenImage/index.d.ts +8 -87
  66. package/dist/components/ScreenImage/materials/ScreenImageBlendMaterial.d.ts +9 -0
  67. package/dist/components/ScreenImage/materials/ScreenImageMatcap.d.ts +3 -0
  68. package/dist/components/ScreenImage/source.d.ts +16 -0
  69. package/dist/components/ScreenImage/types.d.ts +37 -0
  70. package/dist/components/ScreenImage/utils/ScreenImageConstants.d.ts +9 -0
  71. package/dist/components/ScreenImage/utils/ScreenImageHelpers.d.ts +4 -0
  72. package/dist/components/ScreenShape/geometry.d.ts +5 -0
  73. package/dist/components/ScreenShape/index.d.ts +5 -0
  74. package/dist/components/ScreenShape/types.d.ts +41 -0
  75. package/dist/components/ScreenSpaceUI/ScreenTransformGuide.d.ts +15 -0
  76. package/dist/components/ScreenSpaceUI/ScreenTransformOverlayGuide.d.ts +9 -0
  77. package/dist/components/ScreenSpaceUI/index.d.ts +2 -0
  78. package/dist/components/ScreenText/components/ScreenTextBody.d.ts +2 -0
  79. package/dist/components/ScreenText/components/ScreenTextTransformFrame.d.ts +9 -0
  80. package/dist/components/ScreenText/constants.d.ts +5 -0
  81. package/dist/components/ScreenText/index.d.ts +6 -20
  82. package/dist/components/ScreenText/types.d.ts +31 -0
  83. package/dist/components/ScreenText/utils/ScreenTextHelpers.d.ts +14 -0
  84. package/dist/components/ScreenText/utils/ScreenTextMappings.d.ts +17 -0
  85. package/dist/components/SequentialRenderPasses/index.d.ts +6 -0
  86. package/dist/components/TextLabel/TextLabel.d.ts +5 -0
  87. package/dist/components/TextLabel/alignment.d.ts +4 -0
  88. package/dist/components/TextLabel/bend.d.ts +9 -0
  89. package/dist/components/TextLabel/canvas/buildTextLabelTexture.d.ts +4 -0
  90. package/dist/components/TextLabel/canvas/canvasTypography.d.ts +13 -0
  91. package/dist/components/TextLabel/canvas/drawBackground.d.ts +21 -0
  92. package/dist/components/TextLabel/canvas/drawEffects.d.ts +34 -0
  93. package/dist/components/TextLabel/canvas/drawText.d.ts +19 -0
  94. package/dist/components/TextLabel/components/TextLabelMesh.d.ts +13 -0
  95. package/dist/components/TextLabel/constants.d.ts +2 -0
  96. package/dist/components/TextLabel/hooks/useTextLabelTexture.d.ts +7 -0
  97. package/dist/components/TextLabel/index.d.ts +2 -161
  98. package/dist/components/TextLabel/layout/measurement.d.ts +8 -0
  99. package/dist/components/TextLabel/layout/resolveTextLayout.d.ts +25 -0
  100. package/dist/components/TextLabel/layout/wrapText.d.ts +6 -0
  101. package/dist/components/TextLabel/types.d.ts +227 -0
  102. package/dist/components/TrackingAnchor/index.d.ts +18 -2
  103. package/dist/components/Transform3D/index.d.ts +30 -0
  104. package/dist/components/XRMediaSurface/index.d.ts +6 -6
  105. package/dist/components/XRViewport/XRViewport.d.ts +11 -0
  106. package/dist/components/XRViewport/components/HiddenMedia.d.ts +7 -0
  107. package/dist/components/XRViewport/components/MediaAssetPicker.d.ts +8 -0
  108. package/dist/components/XRViewport/components/MediaControlStack.d.ts +13 -0
  109. package/dist/components/XRViewport/components/XRViewportLayers.d.ts +30 -0
  110. package/dist/components/XRViewport/constants.d.ts +24 -0
  111. package/dist/components/XRViewport/contexts.d.ts +6 -0
  112. package/dist/components/XRViewport/hooks/useViewportExternalFaces.d.ts +13 -0
  113. package/dist/components/XRViewport/hooks/useViewportMediaSource.d.ts +16 -0
  114. package/dist/components/XRViewport/hooks/useViewportMediaTexture.d.ts +10 -0
  115. package/dist/components/XRViewport/hooks/useViewportPipeline.d.ts +41 -0
  116. package/dist/components/XRViewport/hooks/useViewportRenderState.d.ts +47 -0
  117. package/dist/components/XRViewport/index.d.ts +3 -118
  118. package/dist/components/XRViewport/layout.d.ts +16 -0
  119. package/dist/components/XRViewport/slots.d.ts +16 -0
  120. package/dist/components/XRViewport/types.d.ts +89 -0
  121. package/dist/components/XRViewport/useViewportSize.d.ts +3 -0
  122. package/dist/components/index.d.ts +12 -0
  123. package/dist/contexts-BKvTIayr.cjs +1 -0
  124. package/dist/contexts-Bk5zz_VR.js +214 -0
  125. package/dist/debug-ui/component-editor/index.d.ts +19 -0
  126. package/dist/debug-ui/face-mesh-renderer-settings/index.d.ts +8 -0
  127. package/dist/debug-ui/face-retouch/index.d.ts +11 -0
  128. package/dist/debug-ui/hand-joints-2d/index.d.ts +1 -1
  129. package/dist/debug-ui/hand-tracking-2d/index.d.ts +1 -1
  130. package/dist/debug-ui/hand-tracking-2d-controller/index.d.ts +1 -1
  131. package/dist/debug-ui/hand-tracking-3d/index.d.ts +1 -1
  132. package/dist/debug-ui/hierarchy-panel/index.d.ts +29 -0
  133. package/dist/debug-ui/index.d.ts +25 -2
  134. package/dist/debug-ui/layer-panel/index.d.ts +3 -2
  135. package/dist/debug-ui/media-source/index.d.ts +2 -0
  136. package/dist/debug-ui/media-source/session.d.ts +12 -0
  137. package/dist/debug-ui/media-source.cjs +1 -1
  138. package/dist/debug-ui/media-source.js +6 -4
  139. package/dist/debug-ui/mesh-renderer-settings/index.d.ts +6 -0
  140. package/dist/debug-ui/object-inspector-panel/index.d.ts +25 -0
  141. package/dist/debug-ui/pin-to-mesh-settings/index.d.ts +10 -0
  142. package/dist/debug-ui/scene-editor/context.d.ts +38 -0
  143. package/dist/debug-ui/scene-editor/hierarchy-panel.d.ts +9 -0
  144. package/dist/debug-ui/scene-editor/index.d.ts +11 -0
  145. package/dist/debug-ui/scene-editor/inspector-panel.d.ts +7 -0
  146. package/dist/debug-ui/scene-editor/store-utils.d.ts +2 -0
  147. package/dist/debug-ui/scene-editor/viewport-toolbar.d.ts +4 -0
  148. package/dist/debug-ui/scene-editor/viewport.d.ts +21 -0
  149. package/dist/debug-ui/screen-glass-settings/index.d.ts +6 -0
  150. package/dist/debug-ui/screen-gradient-settings/GradientStopsEditor.d.ts +5 -0
  151. package/dist/debug-ui/screen-gradient-settings/index.d.ts +6 -0
  152. package/dist/debug-ui/screen-gradient-settings/styles.d.ts +3 -0
  153. package/dist/debug-ui/screen-image-settings/index.d.ts +4 -2
  154. package/dist/debug-ui/screen-shape-settings/index.d.ts +6 -0
  155. package/dist/debug-ui/screen-text-settings/NumberField.d.ts +9 -0
  156. package/dist/debug-ui/screen-text-settings/ScreenTextSettingsPanel.d.ts +3 -0
  157. package/dist/debug-ui/screen-text-settings/controls/NestedSection.d.ts +7 -0
  158. package/dist/debug-ui/screen-text-settings/controls/Section.d.ts +8 -0
  159. package/dist/debug-ui/screen-text-settings/controls/icons.d.ts +4 -0
  160. package/dist/debug-ui/screen-text-settings/index.d.ts +2 -122
  161. package/dist/debug-ui/screen-text-settings/sections/BackgroundSection.d.ts +8 -0
  162. package/dist/debug-ui/screen-text-settings/sections/ContentSection.d.ts +5 -0
  163. package/dist/debug-ui/screen-text-settings/sections/EffectsSection.d.ts +25 -0
  164. package/dist/debug-ui/screen-text-settings/sections/StyleSection.d.ts +5 -0
  165. package/dist/debug-ui/screen-text-settings/sections/TransformSection.d.ts +5 -0
  166. package/dist/debug-ui/screen-text-settings/sections/background/BackgroundFillControls.d.ts +2 -0
  167. package/dist/debug-ui/screen-text-settings/sections/background/BackgroundSizeControls.d.ts +2 -0
  168. package/dist/debug-ui/screen-text-settings/sections/background/BackgroundStrokeControls.d.ts +2 -0
  169. package/dist/debug-ui/screen-text-settings/sections/background/types.d.ts +7 -0
  170. package/dist/debug-ui/screen-text-settings/sections/effects/BendEffectSection.d.ts +4 -0
  171. package/dist/debug-ui/screen-text-settings/sections/effects/EffectChrome.d.ts +21 -0
  172. package/dist/debug-ui/screen-text-settings/sections/effects/GlowEffectSection.d.ts +4 -0
  173. package/dist/debug-ui/screen-text-settings/sections/effects/InnerShadowEffectSection.d.ts +4 -0
  174. package/dist/debug-ui/screen-text-settings/sections/effects/OutlineEffectSection.d.ts +4 -0
  175. package/dist/debug-ui/screen-text-settings/sections/effects/ShadowEffectSection.d.ts +4 -0
  176. package/dist/debug-ui/screen-text-settings/sections/effects/types.d.ts +14 -0
  177. package/dist/debug-ui/screen-text-settings/settings.d.ts +90 -0
  178. package/dist/debug-ui/screen-text-settings/styles.d.ts +26 -0
  179. package/dist/debug-ui/screen-text-settings/transform.d.ts +6 -0
  180. package/dist/debug-ui/screen-text-settings/types.d.ts +9 -0
  181. package/dist/debug-ui/shared/ScreenTransformSection.d.ts +6 -3
  182. package/dist/debug-ui/transform-3d-settings/index.d.ts +11 -0
  183. package/dist/debug-ui.cjs +3 -13
  184. package/dist/debug-ui.js +7896 -5098
  185. package/dist/drawNormalizedCrop-B-7zU-Xw.cjs +1 -0
  186. package/dist/drawNormalizedCrop-CRdIDyl1.js +44 -0
  187. package/dist/entries/all.d.ts +1 -0
  188. package/dist/entries/core.d.ts +53 -6
  189. package/dist/entries/face-effects.d.ts +10 -8
  190. package/dist/entries/internal.d.ts +1 -1
  191. package/dist/entries/low-level.d.ts +18 -4
  192. package/dist/entries/scene-object.d.ts +10 -0
  193. package/dist/entries/tracking.d.ts +25 -2
  194. package/dist/face-action/index.d.ts +34 -0
  195. package/dist/face-attribute-expression/index.d.ts +10 -0
  196. package/dist/face-effects.cjs +1 -342
  197. package/dist/face-effects.js +1391 -2767
  198. package/dist/face-info/blendshapes.d.ts +3 -0
  199. package/dist/face-info/derive.d.ts +8 -0
  200. package/dist/face-info/drawFaceCrop.d.ts +10 -0
  201. package/dist/face-info/getFaceInfo.d.ts +8 -0
  202. package/dist/face-info/index.d.ts +8 -0
  203. package/dist/face-info/landmarks.d.ts +21 -0
  204. package/dist/face-info/types.d.ts +52 -0
  205. package/dist/getFaceInfo-CyPAKh3h.cjs +1 -0
  206. package/dist/getFaceInfo-hUKMLFcr.js +118 -0
  207. package/dist/{handJoints2d.d.ts → hand/handJoints2d.d.ts} +1 -1
  208. package/dist/{handTracking2d.d.ts → hand/handTracking2d.d.ts} +1 -1
  209. package/dist/{handTracking2dController.d.ts → hand/handTracking2dController.d.ts} +1 -1
  210. package/dist/{handTracking3d.d.ts → hand/handTracking3d.d.ts} +1 -1
  211. package/dist/hooks/faceResults.d.ts +1 -1
  212. package/dist/hooks/useCalibrationFaceTracker.d.ts +1 -1
  213. package/dist/hooks/useFaceAction.d.ts +3 -0
  214. package/dist/hooks/useFaceAttributeExpression.d.ts +16 -0
  215. package/dist/hooks/useFaceDetection.d.ts +18 -0
  216. package/dist/hooks/useFaceInfo.d.ts +7 -0
  217. package/dist/hooks/useFaceInfos.d.ts +15 -0
  218. package/dist/hooks/useFaceResultReader.d.ts +10 -0
  219. package/dist/hooks/useFrameCapture.d.ts +18 -0
  220. package/dist/hooks/useMediaRecorder.d.ts +14 -2
  221. package/dist/hooks/useOwnedTexture.d.ts +6 -0
  222. package/dist/hooks/useTrackerContext.d.ts +2 -2
  223. package/dist/hooks/useXRSession/facade.d.ts +3 -0
  224. package/dist/hooks/useXRSession/registry.d.ts +9 -0
  225. package/dist/index-82aENaRq.cjs +1 -0
  226. package/dist/{index-BGNbrc4C.js → index-BgQAX8rs.js} +213 -125
  227. package/dist/index-CEc1CAmB.cjs +1 -0
  228. package/dist/index-CTHeBQOs.js +178 -0
  229. package/dist/index-D4bLzBr6.cjs +1 -0
  230. package/dist/index-DSpzjuqd.cjs +1 -0
  231. package/dist/index-Di70KWuY.js +2049 -0
  232. package/dist/index-DzEzkBIH.cjs +17 -0
  233. package/dist/{index-safCs_af.js → index-JygePOwo.js} +565 -508
  234. package/dist/index-UC0Ux38E.js +111 -0
  235. package/dist/{internal-Cae1ps15.js → internal-DuMPpcbp.js} +86 -80
  236. package/dist/internal-i2JkM85N.cjs +1 -0
  237. package/dist/internal.cjs +1 -1
  238. package/dist/internal.js +2 -2
  239. package/dist/low-level.cjs +1 -1
  240. package/dist/low-level.js +1229 -86
  241. package/dist/main.cjs +1 -73
  242. package/dist/main.js +545 -1693
  243. package/dist/material/MaterialFill.d.ts +20 -0
  244. package/dist/material/MeshMaterial.d.ts +14 -0
  245. package/dist/material/index.d.ts +2 -0
  246. package/dist/models/Body/index.d.ts +1 -1
  247. package/dist/models/Face/index.d.ts +1 -0
  248. package/dist/models/Face/rotation.d.ts +3 -0
  249. package/dist/render/renderGroups.d.ts +47 -0
  250. package/dist/render/renderPasses.d.ts +18 -0
  251. package/dist/renderGroups-C9QJrAXu.js +152 -0
  252. package/dist/renderGroups-Dvm1J4lW.cjs +1 -0
  253. package/dist/renderLayers-lDtL0_43.cjs +1 -0
  254. package/dist/renderLayers-zrK2pv5O.js +13 -0
  255. package/dist/renderPasses-CT5iBwtg.cjs +21 -0
  256. package/dist/renderPasses-CjgG_6kQ.js +1500 -0
  257. package/dist/scene-object/index.d.ts +146 -0
  258. package/dist/scene-object/runtimeRegistry.d.ts +14 -0
  259. package/dist/scene-object.cjs +1 -0
  260. package/dist/scene-object.js +40 -0
  261. package/dist/{screenImageSettings.d.ts → screen-image/screenImageSettings.d.ts} +9 -2
  262. package/dist/{screenTextSettings.d.ts → screen-text/screenTextSettings.d.ts} +18 -2
  263. package/dist/screen2d/coordinates.d.ts +87 -0
  264. package/dist/screen2d/index.d.ts +3 -0
  265. package/dist/screen2d/screenTransform.d.ts +47 -0
  266. package/dist/screen2d/smoothing.d.ts +5 -0
  267. package/dist/{selectors-BLl2JUWW.cjs → selectors-2QvO5RYY.cjs} +1 -1
  268. package/dist/{selectors-CXd_x-6t.js → selectors-Dw3C-gSk.js} +3 -3
  269. package/dist/services/MetricsCollector/index.d.ts +7 -1
  270. package/dist/services/MetricsCollector/utils.d.ts +1 -1
  271. package/dist/session-BChR4TgK.cjs +31 -0
  272. package/dist/session-C1StwN0f.js +363 -0
  273. package/dist/texture/animatedTexture.d.ts +61 -0
  274. package/dist/texture/animationMath.d.ts +8 -0
  275. package/dist/texture/sourceResolver.d.ts +30 -0
  276. package/dist/tracking.cjs +1 -1
  277. package/dist/tracking.js +580 -321
  278. package/dist/types/face.d.ts +1 -13
  279. package/dist/types/index.d.ts +0 -1
  280. package/dist/types/nodes.d.ts +2 -1
  281. package/dist/types/session.d.ts +2 -0
  282. package/dist/types/tracking.d.ts +8 -2
  283. package/dist/types/util-types.d.ts +1 -1
  284. package/dist/useFaceInfo-C-WfMlYp.cjs +1 -0
  285. package/dist/useFaceInfo-CwsHZedC.js +62 -0
  286. package/dist/useFaceResults-CkFc1egZ.js +19 -0
  287. package/dist/useFaceResults-VcFdOUFV.cjs +1 -0
  288. package/dist/utils/drawNormalizedCrop.d.ts +22 -0
  289. package/dist/utils/integrity.d.ts +4 -25
  290. package/dist/utils/landmarkBounds.d.ts +1 -1
  291. package/dist/utils/logger.d.ts +2 -2
  292. package/docs/MIGRATION_GUIDE.md +589 -0
  293. package/docs/SDK_DOCUMENTATION.md +1155 -0
  294. package/docs/api/audio.mdx +36 -0
  295. package/docs/api/behavior-components.mdx +164 -0
  296. package/docs/api/capture-recording.mdx +103 -0
  297. package/docs/api/debug-ui-scene-editor.mdx +249 -0
  298. package/docs/api/face-actions.mdx +104 -0
  299. package/docs/api/face-attribute-expression.mdx +87 -0
  300. package/docs/api/face-binding-anchors.mdx +53 -0
  301. package/docs/api/face-effects.mdx +19 -0
  302. package/docs/api/face-info.mdx +112 -0
  303. package/docs/api/face-mesh.mdx +98 -0
  304. package/docs/api/face-painting.mdx +33 -0
  305. package/docs/api/face-retouching.mdx +73 -0
  306. package/docs/api/material-render-state.mdx +132 -0
  307. package/docs/api/runtime-3d.mdx +311 -0
  308. package/docs/api/scene-object-store.mdx +213 -0
  309. package/docs/api/screen-image.mdx +41 -0
  310. package/docs/api/screen-shape.mdx +64 -0
  311. package/docs/api/screen-space-coordinates.mdx +41 -0
  312. package/docs/api/screen-text.mdx +39 -0
  313. package/docs/api/texture-sources.mdx +55 -0
  314. package/docs/api/trackers.mdx +46 -0
  315. package/docs/docs.json +70 -0
  316. package/docs/examples/scene-object-recipes.mdx +194 -0
  317. package/docs/guides/harness-debug-ui.mdx +139 -0
  318. package/docs/inspector/hierarchy-panel.mdx +51 -0
  319. package/docs/inspector/object-inspector-panel.mdx +51 -0
  320. package/docs/introduction.mdx +121 -0
  321. package/docs/scene-objects/overview.mdx +127 -0
  322. package/docs/scene-objects/render-groups.mdx +77 -0
  323. package/docs/scene-objects/runtime-rendering.mdx +75 -0
  324. package/docs/texture-api-consumer.md +58 -0
  325. package/package.json +37 -7
  326. package/dist/MediaSourceSwitcher-C-xYg0nQ.js +0 -317
  327. package/dist/MediaSourceSwitcher-Cq3g4IKw.cjs +0 -31
  328. package/dist/components/FaceRetouch/defaults.d.ts +0 -13
  329. package/dist/components/FaceRetouch/retouchRegions.d.ts +0 -23
  330. package/dist/components/FaceRetouch/useFaceRetouchRegions.d.ts +0 -12
  331. package/dist/defaults-BLpcN3pG.cjs +0 -1
  332. package/dist/defaults-LtY4M7dg.js +0 -55
  333. package/dist/index-BXyObVHF.cjs +0 -1
  334. package/dist/index-CY3bUAcW.js +0 -12
  335. package/dist/index-C_Duh13c.cjs +0 -1
  336. package/dist/index-D8fpPQkC.cjs +0 -1
  337. package/dist/index-DxshgBu0.cjs +0 -1
  338. package/dist/index-O-2crZ3M.js +0 -1102
  339. package/dist/internal-BjyhBP8i.cjs +0 -1
  340. package/dist/modules/XRClient/index.d.ts +0 -9
  341. package/dist/modules/index.d.ts +0 -1
  342. package/dist/screenImageSettings-6NRg4cx9.js +0 -39
  343. package/dist/screenImageSettings-y_B4_767.cjs +0 -1
  344. package/dist/services/ApiService.d.ts +0 -12
  345. package/dist/types/client.d.ts +0 -3
  346. package/dist/useFaceResults-cpsSmKKc.js +0 -81
  347. package/dist/useFaceResults-hVUJYSEY.cjs +0 -1
  348. package/dist/useXRModel-3DcUa28n.cjs +0 -1
  349. package/dist/useXRModel-BMJE1hrk.js +0 -28
  350. /package/dist/{layerStack.d.ts → render/layerStack.d.ts} +0 -0
  351. /package/dist/{screenImagePresets.d.ts → screen-image/screenImagePresets.d.ts} +0 -0
  352. /package/dist/{screenTextPresets.d.ts → screen-text/screenTextPresets.d.ts} +0 -0
@@ -0,0 +1,39 @@
1
+ ---
2
+ title: "Screen Text"
3
+ description: "Standard screen-space text with design-pixel transforms, layout, styles, and editor controls."
4
+ sidebarTitle: "Screen Text"
5
+ icon: "type"
6
+ ---
7
+
8
+ Use `ScreenText` for prompts, captions, banners, badges, and titles. Prefer it
9
+ over manually pairing `ScreenTransform` and `TextLabel` for ordinary screen UI.
10
+
11
+ ```tsx
12
+ import { ScreenSpaceUI, ScreenText } from "@vincentt-xr/sdk";
13
+
14
+ <ScreenSpaceUI>
15
+ <ScreenText
16
+ name="headline"
17
+ text="Head-Tilt Trivia"
18
+ coordinateSpace="canvas"
19
+ canvasSize={{ width: 720, height: 1280 }}
20
+ position={[0, 500]}
21
+ size={[620, 140]}
22
+ textAlign="center"
23
+ fontSize={270}
24
+ bgFit="text"
25
+ bgColor="transparent"
26
+ />
27
+ </ScreenSpaceUI>;
28
+ ```
29
+
30
+ `coordinateSpace="normalized"` uses normalized screen units. `"canvas"` uses
31
+ design pixels with center origin and positive Y upward. `size` is the text
32
+ bounding rectangle; alignment, overflow, background, stroke, and shadow are
33
+ resolved inside it.
34
+
35
+ Use `TextLabel` only for world-space text or lower-level composites whose
36
+ parent owns layout. For serialized scenes, combine `ScreenTransform` +
37
+ `ScreenText` and use `mapScreenTextSettingsToProps`. Use
38
+ `ScreenTextSettingsPanel` from `@vincentt-xr/sdk/debug-ui` for creator tooling,
39
+ not production UI.
@@ -0,0 +1,55 @@
1
+ ---
2
+ title: "Texture Sources and Animation"
3
+ description: "Static images, runtime textures, animated providers, playback capabilities, and lifecycle."
4
+ sidebarTitle: "Texture Sources"
5
+ icon: "film"
6
+ ---
7
+
8
+ `ScreenImage` is the standard render target. Pass a URL image or an existing
9
+ Three.js texture through the core API.
10
+
11
+ ```tsx
12
+ import { ScreenImage, ScreenSpaceUI } from "@vincentt-xr/sdk";
13
+
14
+ <ScreenSpaceUI>
15
+ <ScreenImage source={{ kind: "texture", texture }} stretchMode="fit" />
16
+ </ScreenSpaceUI>;
17
+ ```
18
+
19
+ Managed video, GIF, and image-sequence providers should resolve to a live
20
+ `THREE.Texture`. Animated sources can expose forward, reverse, ping-pong,
21
+ random, looping, finite loop counts, pause/resume, restart, frame status, and
22
+ ended state. Gate controls using provider capabilities; static images must not
23
+ show playback controls.
24
+
25
+ ## Example asset layout
26
+
27
+ Example-app media assets live under `example/src/assets/media`:
28
+
29
+ - `images/` for static textures and sample stills
30
+ - `images/people/` for face/body tracking sample stills
31
+ - `images/screenshots/` for screenshot references
32
+ - `videos/` for sample MP4/WebM sources
33
+ - `gifs/` for animated GIF inputs
34
+ - `sequences/<demo-name>/` for ordered image-sequence frames
35
+
36
+ GLB assets live under `example/src/assets/models`. Domain-specific effect
37
+ assets, such as face paint textures, stay under their owning domain folder
38
+ instead of being flattened into `media`.
39
+
40
+ Low-level integration lives at `@vincentt-xr/sdk/low-level`:
41
+
42
+ ```ts
43
+ import {
44
+ BasicAnimatedTextureController,
45
+ createTextureSourceResolver,
46
+ getPlaybackFrame,
47
+ getSequenceFrame,
48
+ } from "@vincentt-xr/sdk/low-level";
49
+ ```
50
+
51
+ The controller lifecycle is `play`, `pause`, `restart`, optional `seek`, play
52
+ mode and loop configuration, subscription, then `dispose`. Read `getSnapshot()`
53
+ for current state and errors. Dispose replaced owned sources and keep dynamic
54
+ canvas/video textures marked for GPU upload; source replacement should preserve
55
+ the scene object's transform and material settings.
@@ -0,0 +1,46 @@
1
+ ---
2
+ title: "Trackers"
3
+ description: "Face, hand, gesture, body, and segmentation trackers with shared lifecycle and performance controls."
4
+ sidebarTitle: "Trackers"
5
+ icon: "scan"
6
+ ---
7
+
8
+ Import trackers from `@vincentt-xr/sdk/tracking`. They acquire and share their
9
+ MediaPipe model automatically.
10
+
11
+ ```tsx
12
+ import {
13
+ BodyTracker,
14
+ FaceTracker,
15
+ GestureTracker,
16
+ HandTracker,
17
+ Segmentation,
18
+ } from "@vincentt-xr/sdk/tracking";
19
+
20
+ <FaceTracker />;
21
+ <HandTracker hand="right" />;
22
+ <GestureTracker />;
23
+ <BodyTracker />;
24
+ <Segmentation type="portrait" />;
25
+ ```
26
+
27
+ - `FaceTracker`: 468 landmarks and face transform; supports `faceIndex`,
28
+ `scaleWithFace`, and `followFaceRoll`
29
+ - `HandTracker`: 21-joint skeleton; use `hand` or `handIndex` for selection
30
+ - `GestureTracker`: named gesture recognition
31
+ - `BodyTracker`: 33 pose landmarks
32
+ - `Segmentation`: portrait mask for background replacement
33
+
34
+ The example app route `/body` shows the recommended body-tracking pattern:
35
+ mount `BodyTracker` once, then attach visible content with `TrackingAnchor`
36
+ targets such as `body.head`, `body.leftShoulder`, and `body.rightWrist`.
37
+
38
+ Gesture names are exactly `closed_fist`, `open_palm`, `pointing_up`,
39
+ `thumb_down`, `thumb_up`, `victory`, `i_love_you`, and `none`. Use
40
+ `GestureTrigger` for one-shot callbacks and `useXRModelNode` from
41
+ `@vincentt-xr/sdk/low-level` only for fine-grained frame reads.
42
+
43
+ Mount a tracker once above scene/phase switches when multiple scenes use it.
44
+ Use `active={false}` to pause without disposal. Control inference with
45
+ `targetFps` or the provider/session `perf` configuration; do not build a second
46
+ polling or throttling loop.
package/docs/docs.json ADDED
@@ -0,0 +1,70 @@
1
+ {
2
+ "$schema": "https://mintlify.com/docs.json",
3
+ "theme": "mint",
4
+ "name": "Vincentt XR SDK",
5
+ "colors": {
6
+ "primary": "#2563eb",
7
+ "light": "#2563eb",
8
+ "dark": "#60a5fa"
9
+ },
10
+ "navigation": {
11
+ "groups": [
12
+ {
13
+ "group": "Start Here",
14
+ "icon": "book-open",
15
+ "pages": ["introduction"]
16
+ },
17
+ {
18
+ "group": "Scene Objects",
19
+ "icon": "layers",
20
+ "pages": [
21
+ "scene-objects/overview",
22
+ "scene-objects/render-groups",
23
+ "scene-objects/runtime-rendering"
24
+ ]
25
+ },
26
+ {
27
+ "group": "API Reference",
28
+ "icon": "code",
29
+ "pages": [
30
+ "api/runtime-3d",
31
+ "api/screen-space-coordinates",
32
+ "api/screen-image",
33
+ "api/screen-text",
34
+ "api/screen-shape",
35
+ "api/trackers",
36
+ "api/face-info",
37
+ "api/face-actions",
38
+ "api/face-attribute-expression",
39
+ "api/face-binding-anchors",
40
+ "api/face-effects",
41
+ "api/face-mesh",
42
+ "api/face-painting",
43
+ "api/face-retouching",
44
+ "api/capture-recording",
45
+ "api/audio",
46
+ "api/texture-sources",
47
+ "api/material-render-state",
48
+ "api/behavior-components",
49
+ "api/scene-object-store",
50
+ "api/debug-ui-scene-editor"
51
+ ]
52
+ },
53
+ {
54
+ "group": "Inspector",
55
+ "icon": "panel-right",
56
+ "pages": ["inspector/hierarchy-panel", "inspector/object-inspector-panel"]
57
+ },
58
+ {
59
+ "group": "Client Integration",
60
+ "icon": "plug",
61
+ "pages": ["guides/harness-debug-ui"]
62
+ },
63
+ {
64
+ "group": "Examples",
65
+ "icon": "code",
66
+ "pages": ["examples/scene-object-recipes"]
67
+ }
68
+ ]
69
+ }
70
+ }
@@ -0,0 +1,194 @@
1
+ ---
2
+ title: "Scene Object Recipes"
3
+ description: "Create Screen Image, Screen Text, and 3D Object scene objects."
4
+ sidebarTitle: "Recipes"
5
+ icon: "code"
6
+ ---
7
+
8
+ These recipes show the current serialized authoring pattern.
9
+
10
+ ```ts
11
+ import { createDefaultComponent, createSceneObject } from "@vincentt-xr/sdk/scene-object";
12
+ ```
13
+
14
+ ## Screen Image object
15
+
16
+ ```ts
17
+ const object = createSceneObject({
18
+ name: "Screen Image",
19
+ renderGroupId: "2d-foreground",
20
+ });
21
+ const screenTransform = createDefaultComponent("ScreenTransform", object.id);
22
+ const screenImage = createDefaultComponent("ScreenImage", object.id);
23
+ const material = createDefaultComponent("Material", object.id);
24
+ const texture = createDefaultComponent("Texture", object.id);
25
+
26
+ object.componentIds = [screenTransform.id, screenImage.id, material.id, texture.id];
27
+ ```
28
+
29
+ ## Screen Text object
30
+
31
+ ```ts
32
+ const object = createSceneObject({
33
+ name: "Screen Text",
34
+ renderGroupId: "2d-foreground",
35
+ });
36
+ const screenTransform = createDefaultComponent("ScreenTransform", object.id);
37
+ const screenText = createDefaultComponent("ScreenText", object.id);
38
+ const material = createDefaultComponent("Material", object.id);
39
+ const texture = createDefaultComponent("Texture", object.id);
40
+
41
+ object.componentIds = [screenTransform.id, screenText.id, material.id, texture.id];
42
+ ```
43
+
44
+ ## 3D Object
45
+
46
+ ```ts
47
+ const object = createSceneObject({ name: "Cube", renderGroupId: "general" });
48
+ const transform = createDefaultComponent("Transform", object.id);
49
+ const meshRenderer = createDefaultComponent("MeshRenderer", object.id);
50
+
51
+ object.componentIds = [transform.id, meshRenderer.id];
52
+ ```
53
+
54
+ ## FaceMeshRenderer object
55
+
56
+ ```ts
57
+ import { DEFAULT_FACE_MESH_TRANSFORM } from "@vincentt-xr/sdk/face-effects";
58
+
59
+ const object = createSceneObject({ name: "Face Mesh", renderGroupId: "scene3d" });
60
+ const transform = createDefaultComponent("Transform", object.id);
61
+ const faceMesh = createDefaultComponent("FaceMeshRenderer", object.id);
62
+
63
+ transform.settings.position.y = DEFAULT_FACE_MESH_TRANSFORM.position.y;
64
+
65
+ object.componentIds = [transform.id, faceMesh.id];
66
+ ```
67
+
68
+ FaceMesh consumes `Transform` in landmark space before projection, not as a
69
+ normal world-space parent group. Position and uniform scale are supported;
70
+ rotation and non-uniform scale are ignored until object-space face solving lands.
71
+
72
+ ## 3D object with render state
73
+
74
+ ```ts
75
+ const object = createSceneObject({ name: "Base Plane", renderGroupId: "scene3d" });
76
+ const transform = createDefaultComponent("Transform", object.id);
77
+ const meshRenderer = createDefaultComponent("MeshRenderer", object.id);
78
+
79
+ transform.settings.position = { x: 0, y: -2.5, z: 0 };
80
+ transform.settings.rotation = { x: -90, y: 0, z: 0 };
81
+ transform.settings.scale = { x: 7.5, y: 7.5, z: 7.5 };
82
+
83
+ meshRenderer.settings.mesh = "plane";
84
+ meshRenderer.settings.material.color = "#1b2733";
85
+ meshRenderer.settings.material.renderState = {
86
+ depthTest: true,
87
+ depthWrite: true,
88
+ cullMode: "off",
89
+ colorMask: { r: true, g: true, b: true, a: true },
90
+ };
91
+ meshRenderer.settings.shadowMode = "receive";
92
+
93
+ object.componentIds = [transform.id, meshRenderer.id];
94
+ ```
95
+
96
+ ## Asset-backed GLTF object
97
+
98
+ ```ts
99
+ const micGlbUrl = new URL("../../assets/models/mic.glb", import.meta.url).href;
100
+
101
+ const object = createSceneObject({ name: "Mic", renderGroupId: "scene3d" });
102
+ const transform = createDefaultComponent("Transform", object.id);
103
+ const meshRenderer = createDefaultComponent("MeshRenderer", object.id);
104
+
105
+ transform.settings.position = { x: -1.1, y: -0.6, z: 0 };
106
+ transform.settings.scale = { x: 0.1, y: 0.1, z: 0.1 };
107
+
108
+ meshRenderer.settings.assetUrl = micGlbUrl;
109
+ meshRenderer.settings.shadowMode = "castReceive";
110
+
111
+ object.componentIds = [transform.id, meshRenderer.id];
112
+ ```
113
+
114
+ Keep example GLB files in `example/src/assets/models`. Put sample image, video,
115
+ GIF, and sequence inputs under `example/src/assets/media` by media type.
116
+
117
+ ## Light object
118
+
119
+ ```ts
120
+ const object = createSceneObject({ name: "Key Light", renderGroupId: "scene3d" });
121
+ const transform = createDefaultComponent("Transform", object.id);
122
+ const light = createDefaultComponent("Light", object.id);
123
+
124
+ transform.settings.position = { x: 3, y: 5, z: 4 };
125
+ light.settings.type = "directional";
126
+ light.settings.intensity = 2.2;
127
+ light.settings.castShadow = true;
128
+ light.settings.showHelper = true; // editor/debug only
129
+
130
+ object.componentIds = [transform.id, light.id];
131
+ ```
132
+
133
+ ## LookAt behavior
134
+
135
+ ```ts
136
+ const lookAt = createDefaultComponent("LookAt", object.id);
137
+
138
+ lookAt.settings.enabled = true;
139
+ lookAt.settings.targetObjectId = "target-object-id";
140
+ lookAt.settings.mode = "point";
141
+ lookAt.settings.offsetRotation = { x: 0, y: 0, z: 0 };
142
+
143
+ object.componentIds = [transform.id, meshRenderer.id, lookAt.id];
144
+ ```
145
+
146
+ ## PinToMesh behavior
147
+
148
+ ```ts
149
+ const pinToMesh = createDefaultComponent("PinToMesh", object.id);
150
+
151
+ pinToMesh.settings.enabled = true;
152
+ pinToMesh.settings.targetObjectId = "base-plane";
153
+ pinToMesh.settings.orientation = "positionAndDirection";
154
+ pinToMesh.settings.uv = { x: 0.5, y: 0.5 };
155
+ pinToMesh.settings.vertexNormal = true;
156
+ pinToMesh.settings.offsetSpace = "local";
157
+ pinToMesh.settings.offsetPosition = { x: 0, y: 0, z: 0 };
158
+ pinToMesh.settings.offsetRotation = { x: 0, y: 0, z: 0 };
159
+
160
+ object.componentIds = [transform.id, meshRenderer.id, pinToMesh.id];
161
+ ```
162
+
163
+ ## Reusable editor store shape
164
+
165
+ ```ts
166
+ const store = {
167
+ objects: {
168
+ [mic.id]: mic,
169
+ [emoji.id]: emoji,
170
+ [basePlane.id]: basePlane,
171
+ [keyLight.id]: keyLight,
172
+ },
173
+ components: {
174
+ [micTransform.id]: micTransform,
175
+ [micMesh.id]: micMesh,
176
+ [emojiTransform.id]: emojiTransform,
177
+ [emojiMesh.id]: emojiMesh,
178
+ [baseTransform.id]: baseTransform,
179
+ [baseMesh.id]: baseMesh,
180
+ [lightTransform.id]: lightTransform,
181
+ [light.id]: light,
182
+ },
183
+ renderGroups: {
184
+ scene3d: {
185
+ id: "scene3d",
186
+ name: "3D Scene",
187
+ domain: "general",
188
+ enabled: true,
189
+ objectIds: [mic.id, emoji.id, basePlane.id, keyLight.id],
190
+ },
191
+ },
192
+ renderGroupOrder: ["scene3d"],
193
+ };
194
+ ```
@@ -0,0 +1,139 @@
1
+ ---
2
+ title: "Debug UI in Harness Clients"
3
+ description: "Integrate Hierarchy, Inspectors, transform controls, and grouped rendering without crossing the R3F Canvas boundary."
4
+ sidebarTitle: "Harness Debug UI"
5
+ icon: "plug"
6
+ ---
7
+
8
+ `test001` is the canonical external Harness-client integration. For new 3D scene
9
+ setup work, prefer the reusable scene editor primitives from
10
+ `@vincentt-xr/sdk/debug-ui` instead of rewriting viewport, hierarchy, inspector,
11
+ and toolbar wiring in the client app.
12
+
13
+ ## Agent routing contract
14
+
15
+ Use the API door that owns the responsibility:
16
+
17
+ | Task | Import door |
18
+ | --------------------------------------------------------------------- | ------------------------------- |
19
+ | Runtime renderers, pass composition, and layer limits | `@vincentt-xr/sdk` |
20
+ | Scene-object state and pure render-group operations | `@vincentt-xr/sdk/scene-object` |
21
+ | Reusable viewport, hierarchy, inspector, toolbar, and settings panels | `@vincentt-xr/sdk/debug-ui` |
22
+
23
+ The client owns the scene store, `selectedObjectId`, component replacement,
24
+ visibility, reorder/move operations, selected Inspector, and preview/debug
25
+ mounting policy. Panels emit commands; they do not own persistent scene state.
26
+
27
+ ## Required invariants
28
+
29
+ - Derive ordering from `scene.renderGroupOrder`; do not hardcode group IDs or a
30
+ default group sequence.
31
+ - Use `createRenderPlan` plus `SequentialRenderPasses` for cross-group visual
32
+ composition. Three.js `renderOrder` is not a substitute.
33
+ - Treat camera layers as internal visibility masks.
34
+ - Keep every managed object in exactly one materialized compatible group.
35
+ - When selection changes, close 2D guides and 3D transform controls belonging to
36
+ the previous selection. Initial controls must match the initial selection.
37
+ - Guard group creation with `MAX_RENDER_GROUP_PASSES`.
38
+ - Treat Copy Config as an export/debug payload; no public importer exists.
39
+
40
+ ## Preferred reusable editor tree
41
+
42
+ ```text
43
+ XRProvider
44
+ └─ AspectRatioContainer
45
+ └─ XRSceneEditorProvider
46
+ ├─ XRSceneViewport
47
+ │ ├─ XRScene
48
+ │ ├─ editor-owned camera-texture plane
49
+ │ ├─ SequentialRenderPasses
50
+ │ └─ SceneObjectRenderer instances
51
+ ├─ ViewportToolbar
52
+ ├─ SceneHierarchyPanel
53
+ └─ SceneInspectorPanel
54
+ ```
55
+
56
+ The parent above both branches owns the scene store and selection.
57
+
58
+ ```tsx
59
+ <XRSceneEditorProvider
60
+ store={store}
61
+ selectedObjectId={selectedObjectId}
62
+ onSelectObject={setSelectedObjectId}
63
+ onStoreChange={setStore}
64
+ onComponentChange={(component) =>
65
+ setStore((current) => replaceSceneComponent(current, component))
66
+ }
67
+ onObjectChange={(object) => setStore((current) => replaceSceneObject(current, object))}
68
+ >
69
+ <XRSceneViewport />
70
+ <ViewportToolbar />
71
+ <SceneHierarchyPanel />
72
+ <SceneInspectorPanel />
73
+ </XRSceneEditorProvider>
74
+ ```
75
+
76
+ `XRSceneViewport` owns the editor camera-texture plane. Do not add
77
+ `depthTest/depthWrite` props to core `VideoBackground`; keep `VideoBackground`
78
+ for flat runtime camera backgrounds.
79
+
80
+ ## Placement rule
81
+
82
+ | Component | Placement |
83
+ | ----------------------------------------------- | ------------------------------ |
84
+ | `SceneObjectRenderer` | Inside `XRScene` |
85
+ | `SequentialRenderPasses` | Inside `XRScene` |
86
+ | `XRSceneViewport` | Outside panels; owns `XRScene` |
87
+ | `ScreenSpaceUI` and `Transform3D` | Inside `XRScene` |
88
+ | Three.js controls and scene content | Inside `XRScene` |
89
+ | `HierarchyPanel` | Outside `XRScene` |
90
+ | `ObjectInspectorPanel` and `ComponentEditor` | Outside `XRScene` |
91
+ | `SceneHierarchyPanel` and `SceneInspectorPanel` | Outside `XRScene` |
92
+ | Screen Text/Image settings panels | Outside `XRScene` |
93
+
94
+ Panels update the parent store through callbacks. `XRSceneEditorProvider` shares
95
+ that state with the reusable viewport, hierarchy, inspector, and toolbar.
96
+ Transform changes from inside the scene return to the same store through
97
+ `onComponentChange`.
98
+
99
+ ## R3F error
100
+
101
+ If React reports “R3F hooks can only be used within Canvas,” an R3F-dependent
102
+ renderer, render-pass controller, guide, or Three.js control was mounted in the
103
+ DOM panel branch. Move that scene component inside `XRScene`. Do not move the DOM
104
+ panels into Canvas.
105
+
106
+ ## Agent failure recovery
107
+
108
+ | Symptom | Check | Fix |
109
+ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
110
+ | R3F Canvas-context error | Component placement and duplicate React/R3F instances | Keep DOM panels outside `XRScene`, scene components inside, and pin peer packages in link mode |
111
+ | Reorder has no visible effect | Pass layers were not recomputed | Rebuild the plan and feed ordered active layers to `SequentialRenderPasses` |
112
+ | Wrong gizmo remains active | Selection changed without clearing control flags | Clear stale guides/controls during the selection state transition |
113
+ | Transform drag stops immediately | Integration replaced or remounted the active renderer | Keep one renderer per plan entry and route `onComponentChange` to immutable parent state |
114
+ | Cross-group move fails | Component composition is incompatible | Check `validateGroupCompatibility`; preserve state when it returns `false` |
115
+ | 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` |
116
+ | Copy Config cannot be restored | No importer is provided | Use the payload only for export, inspection, or handoff |
117
+
118
+ ## Linked SDK workflow
119
+
120
+ ```sh
121
+ # terminal 1 — rebuild the linked SDK
122
+ cd vincentt-xr-sdk
123
+ pnpm build:watch
124
+
125
+ # terminal 2 — run the Harness client
126
+ cd test001
127
+ PORT=5174 SDK_LINK=1 pnpm dev
128
+ ```
129
+
130
+ `SDK_LINK=1` resolves the sibling SDK checkout while the Harness config pins
131
+ React, React DOM, Three.js, R3F, and Drei to the client copies. This prevents
132
+ duplicate React/R3F instances—the other common cause of Canvas-context errors.
133
+
134
+ Validate with the client typecheck, linked production build, and local runtime.
135
+ The SDK `/viewport-editor` route is the matching in-repo reusable 3D editor
136
+ fixture. `/unified-architecture`, `/testing-hook`, and `/debugger` are current
137
+ example-app routes that exercise the same debug-ui style for legacy compatibility
138
+ surfaces. `/layer-panel-test` remains useful for older grouped 2D/3D panel
139
+ integration checks.
@@ -0,0 +1,51 @@
1
+ ---
2
+ title: "Hierarchy Panel"
3
+ description: "Select scene objects and edit materialized render-group structure."
4
+ sidebarTitle: "Hierarchy"
5
+ icon: "list-tree"
6
+ ---
7
+
8
+ Import `HierarchyPanel` and the `HierarchyPanelCopyConfig` type from
9
+ `@vincentt-xr/sdk/debug-ui`. It is a DOM authoring panel and must be mounted
10
+ outside `XRScene`.
11
+
12
+ ## Responsibilities
13
+
14
+ The panel displays materialized groups, selects objects, emits reorder/move
15
+ commands, controls visibility through callbacks, and copies a parent-provided
16
+ scene configuration. It does not own the scene store, selection, Inspector,
17
+ compatibility policy, or renderer.
18
+
19
+ Internal source layout: hierarchy UI consumes public render-group data from
20
+ `@vincentt-xr/sdk/debug-ui`; low-level layer-stack helpers live in
21
+ `lib/render/layerStack.ts`.
22
+
23
+ ```tsx
24
+ <HierarchyPanel
25
+ groups={scene.renderGroupOrder.map((id) => scene.renderGroups[id])}
26
+ objects={scene.objects}
27
+ selectedObjectId={scene.selectedObjectId}
28
+ copyConfig={{
29
+ kind: "scene",
30
+ version: 1,
31
+ renderGroupOrder: scene.renderGroupOrder,
32
+ renderGroups: scene.renderGroups,
33
+ objects: scene.objects,
34
+ components: scene.components,
35
+ }}
36
+ onSelectObject={selectObject}
37
+ onReorderGroup={reorderGroup}
38
+ onReorderObject={reorderObject}
39
+ onMoveObject={moveObject}
40
+ onToggleGroupEnabled={toggleGroup}
41
+ onToggleObjectVisible={toggleObject}
42
+ />
43
+ ```
44
+
45
+ The panel is expanded by default and can fold. Individual groups can collapse.
46
+ Fold, collapse, drag, position, and feedback messages are transient UI state and
47
+ are excluded from Copy Config.
48
+
49
+ Cross-group drops must return `false` when
50
+ `validateGroupCompatibility` rejects the target. The panel then displays
51
+ feedback without mutating scene state.
@@ -0,0 +1,51 @@
1
+ ---
2
+ title: "Object Inspector Panel"
3
+ description: "Build shared settings panels with ObjectInspectorPanel and ComponentEditor."
4
+ sidebarTitle: "Object Inspector"
5
+ icon: "panel-right"
6
+ ---
7
+
8
+ `ObjectInspectorPanel` is the shared shell for editor settings. It should be
9
+ used for Screen Image, Screen Text, 3D Object, and future scene objects.
10
+
11
+ ## Props
12
+
13
+ ```ts
14
+ type ObjectInspectorPanelProps = {
15
+ children: ReactNode;
16
+ copyConfig: unknown;
17
+ layer?: string;
18
+ objectId?: string;
19
+ objectName?: string;
20
+ onObjectNameChange?: (name: string) => void;
21
+ title?: string;
22
+ visible: boolean;
23
+ onVisibleChange: (visible: boolean) => void;
24
+ position?: { x: number; y: number };
25
+ onPositionChange?: (position: { x: number; y: number }) => void;
26
+ };
27
+ ```
28
+
29
+ ## Dynamic component editors
30
+
31
+ ```tsx
32
+ {
33
+ object.componentIds.map((componentId) => (
34
+ <ComponentEditor
35
+ key={componentId}
36
+ component={store.components[componentId]}
37
+ editors={componentEditors}
38
+ onChange={replaceComponent}
39
+ />
40
+ ));
41
+ }
42
+ ```
43
+
44
+ If an editor is not registered, the fallback panel shows the component type,
45
+ component ID, and raw component JSON instead of crashing.
46
+
47
+ The parent editor owns selection. Render one Inspector for `selectedObjectId`
48
+ and preserve its position while selection changes. `ScreenTextSettingsPanel`
49
+ and `ScreenImageSettingsPanel` already contain their Inspector shell when an
50
+ `inspector` binding is supplied; do not nest them in another
51
+ `ObjectInspectorPanel`.