@spatial-elements/core 1.0.0-beta.6 → 1.0.0-beta.8

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 (244) hide show
  1. package/dist/catalog/CarouselDeviceCamera.d.ts +20 -0
  2. package/dist/catalog/CarouselDeviceCamera.d.ts.map +1 -0
  3. package/dist/catalog/CarouselDeviceCamera.js +58 -0
  4. package/dist/catalog/CarouselDeviceCamera.js.map +1 -0
  5. package/dist/catalog/CarouselGlassCompositor.d.ts +8 -2
  6. package/dist/catalog/CarouselGlassCompositor.d.ts.map +1 -1
  7. package/dist/catalog/CarouselGlassCompositor.js +69 -12
  8. package/dist/catalog/CarouselGlassCompositor.js.map +1 -1
  9. package/dist/catalog/CarouselGround.d.ts +22 -1
  10. package/dist/catalog/CarouselGround.d.ts.map +1 -1
  11. package/dist/catalog/CarouselGround.js +185 -24
  12. package/dist/catalog/CarouselGround.js.map +1 -1
  13. package/dist/catalog/CatalogDepthBlur.d.ts +20 -1
  14. package/dist/catalog/CatalogDepthBlur.d.ts.map +1 -1
  15. package/dist/catalog/CatalogDepthBlur.js +126 -23
  16. package/dist/catalog/CatalogDepthBlur.js.map +1 -1
  17. package/dist/catalog/CatalogGeometryFade.d.ts +5 -1
  18. package/dist/catalog/CatalogGeometryFade.d.ts.map +1 -1
  19. package/dist/catalog/CatalogGeometryFade.js +39 -7
  20. package/dist/catalog/CatalogGeometryFade.js.map +1 -1
  21. package/dist/catalog/CatalogModelOutline.d.ts +3 -1
  22. package/dist/catalog/CatalogModelOutline.d.ts.map +1 -1
  23. package/dist/catalog/CatalogModelOutline.js +11 -2
  24. package/dist/catalog/CatalogModelOutline.js.map +1 -1
  25. package/dist/catalog/CatalogPreparation.d.ts.map +1 -1
  26. package/dist/catalog/CatalogPreparation.js +8 -6
  27. package/dist/catalog/CatalogPreparation.js.map +1 -1
  28. package/dist/catalog/CatalogSpatialElementLayer.d.ts +144 -3
  29. package/dist/catalog/CatalogSpatialElementLayer.d.ts.map +1 -1
  30. package/dist/catalog/CatalogSpatialElementLayer.js +554 -103
  31. package/dist/catalog/CatalogSpatialElementLayer.js.map +1 -1
  32. package/dist/catalog/CatalogTransition.d.ts +4 -0
  33. package/dist/catalog/CatalogTransition.d.ts.map +1 -1
  34. package/dist/catalog/CatalogTransition.js +109 -27
  35. package/dist/catalog/CatalogTransition.js.map +1 -1
  36. package/dist/catalog/CatalogWarmOutputContext.d.ts +39 -0
  37. package/dist/catalog/CatalogWarmOutputContext.d.ts.map +1 -0
  38. package/dist/catalog/CatalogWarmOutputContext.js +159 -0
  39. package/dist/catalog/CatalogWarmOutputContext.js.map +1 -0
  40. package/dist/catalog/EarlyNavigationCoordinator.d.ts +35 -0
  41. package/dist/catalog/EarlyNavigationCoordinator.d.ts.map +1 -0
  42. package/dist/catalog/EarlyNavigationCoordinator.js +103 -0
  43. package/dist/catalog/EarlyNavigationCoordinator.js.map +1 -0
  44. package/dist/catalog/NavigationFeedback.d.ts +12 -0
  45. package/dist/catalog/NavigationFeedback.d.ts.map +1 -0
  46. package/dist/catalog/NavigationFeedback.js +40 -0
  47. package/dist/catalog/NavigationFeedback.js.map +1 -0
  48. package/dist/catalog/PreparationGate.d.ts +4 -0
  49. package/dist/catalog/PreparationGate.d.ts.map +1 -1
  50. package/dist/catalog/PreparationGate.js +1 -0
  51. package/dist/catalog/PreparationGate.js.map +1 -1
  52. package/dist/catalog/SourceDomClipping.d.ts +8 -0
  53. package/dist/catalog/SourceDomClipping.d.ts.map +1 -0
  54. package/dist/catalog/SourceDomClipping.js +74 -0
  55. package/dist/catalog/SourceDomClipping.js.map +1 -0
  56. package/dist/catalog/SourceDomMotion.d.ts +28 -0
  57. package/dist/catalog/SourceDomMotion.d.ts.map +1 -0
  58. package/dist/catalog/SourceDomMotion.js +111 -0
  59. package/dist/catalog/SourceDomMotion.js.map +1 -0
  60. package/dist/catalog/SpatialPageRegistry.d.ts +1 -0
  61. package/dist/catalog/SpatialPageRegistry.d.ts.map +1 -1
  62. package/dist/catalog/SpatialPageRegistry.js.map +1 -1
  63. package/dist/catalog/StagedCatalogTransition.d.ts +74 -0
  64. package/dist/catalog/StagedCatalogTransition.d.ts.map +1 -0
  65. package/dist/catalog/StagedCatalogTransition.js +270 -0
  66. package/dist/catalog/StagedCatalogTransition.js.map +1 -0
  67. package/dist/catalog/cardProjection.d.ts +31 -0
  68. package/dist/catalog/cardProjection.d.ts.map +1 -1
  69. package/dist/catalog/cardProjection.js +63 -4
  70. package/dist/catalog/cardProjection.js.map +1 -1
  71. package/dist/catalog/carouselPanelProjection.d.ts.map +1 -1
  72. package/dist/catalog/carouselPanelProjection.js +48 -11
  73. package/dist/catalog/carouselPanelProjection.js.map +1 -1
  74. package/dist/catalog/catalogActivationFocus.d.ts +5 -0
  75. package/dist/catalog/catalogActivationFocus.d.ts.map +1 -0
  76. package/dist/catalog/catalogActivationFocus.js +39 -0
  77. package/dist/catalog/catalogActivationFocus.js.map +1 -0
  78. package/dist/catalog/catalogJourney.d.ts +2 -0
  79. package/dist/catalog/catalogJourney.d.ts.map +1 -1
  80. package/dist/catalog/catalogJourney.js.map +1 -1
  81. package/dist/catalog/catalogPose.d.ts +18 -0
  82. package/dist/catalog/catalogPose.d.ts.map +1 -1
  83. package/dist/catalog/catalogPose.js +26 -5
  84. package/dist/catalog/catalogPose.js.map +1 -1
  85. package/dist/catalog/catalogTransitionViewport.d.ts +9 -0
  86. package/dist/catalog/catalogTransitionViewport.d.ts.map +1 -0
  87. package/dist/catalog/catalogTransitionViewport.js +13 -0
  88. package/dist/catalog/catalogTransitionViewport.js.map +1 -0
  89. package/dist/catalog/catalogViewLink.d.ts +2 -0
  90. package/dist/catalog/catalogViewLink.d.ts.map +1 -1
  91. package/dist/catalog/catalogViewLink.js +10 -2
  92. package/dist/catalog/catalogViewLink.js.map +1 -1
  93. package/dist/catalog/deviceYaw.d.ts +21 -0
  94. package/dist/catalog/deviceYaw.d.ts.map +1 -0
  95. package/dist/catalog/deviceYaw.js +87 -0
  96. package/dist/catalog/deviceYaw.js.map +1 -0
  97. package/dist/catalog/listDeviceOrientation.d.ts +17 -0
  98. package/dist/catalog/listDeviceOrientation.d.ts.map +1 -0
  99. package/dist/catalog/listDeviceOrientation.js +262 -0
  100. package/dist/catalog/listDeviceOrientation.js.map +1 -0
  101. package/dist/catalog/stagedDetailGeometry.d.ts +37 -0
  102. package/dist/catalog/stagedDetailGeometry.d.ts.map +1 -0
  103. package/dist/catalog/stagedDetailGeometry.js +55 -0
  104. package/dist/catalog/stagedDetailGeometry.js.map +1 -0
  105. package/dist/catalog/stagedDockGeometry.d.ts +66 -0
  106. package/dist/catalog/stagedDockGeometry.d.ts.map +1 -0
  107. package/dist/catalog/stagedDockGeometry.js +66 -0
  108. package/dist/catalog/stagedDockGeometry.js.map +1 -0
  109. package/dist/index.d.ts +2 -1
  110. package/dist/index.d.ts.map +1 -1
  111. package/dist/index.js +2 -1
  112. package/dist/index.js.map +1 -1
  113. package/dist/spatial-element/ResponsiveViewportMetrics.d.ts +18 -0
  114. package/dist/spatial-element/ResponsiveViewportMetrics.d.ts.map +1 -0
  115. package/dist/spatial-element/ResponsiveViewportMetrics.js +68 -0
  116. package/dist/spatial-element/ResponsiveViewportMetrics.js.map +1 -0
  117. package/dist/spatial-element/SectionSurfaceRegistry.d.ts +24 -0
  118. package/dist/spatial-element/SectionSurfaceRegistry.d.ts.map +1 -0
  119. package/dist/spatial-element/SectionSurfaceRegistry.js +48 -0
  120. package/dist/spatial-element/SectionSurfaceRegistry.js.map +1 -0
  121. package/dist/spatial-element/SpatialElementDockController.d.ts +19 -9
  122. package/dist/spatial-element/SpatialElementDockController.d.ts.map +1 -1
  123. package/dist/spatial-element/SpatialElementDockController.js +189 -93
  124. package/dist/spatial-element/SpatialElementDockController.js.map +1 -1
  125. package/dist/spatial-element/SpatialElementPaneController.d.ts +67 -0
  126. package/dist/spatial-element/SpatialElementPaneController.d.ts.map +1 -0
  127. package/dist/spatial-element/SpatialElementPaneController.js +245 -0
  128. package/dist/spatial-element/SpatialElementPaneController.js.map +1 -0
  129. package/dist/spatial-element/activeDetailSection.d.ts +8 -0
  130. package/dist/spatial-element/activeDetailSection.d.ts.map +1 -0
  131. package/dist/spatial-element/activeDetailSection.js +19 -0
  132. package/dist/spatial-element/activeDetailSection.js.map +1 -0
  133. package/dist/spatial-element/layoutTokens.json +53 -0
  134. package/dist/spatial-element/responsiveLayout.d.ts +1389 -0
  135. package/dist/spatial-element/responsiveLayout.d.ts.map +1 -0
  136. package/dist/spatial-element/responsiveLayout.js +265 -0
  137. package/dist/spatial-element/responsiveLayout.js.map +1 -0
  138. package/dist/spatial-element/sectionBackground.d.ts +29 -0
  139. package/dist/spatial-element/sectionBackground.d.ts.map +1 -0
  140. package/dist/spatial-element/sectionBackground.js +66 -0
  141. package/dist/spatial-element/sectionBackground.js.map +1 -0
  142. package/dist/spatial-element/spatialElement.d.ts +1 -0
  143. package/dist/spatial-element/spatialElement.d.ts.map +1 -1
  144. package/dist/spatial-element/spatialElement.js +1 -0
  145. package/dist/spatial-element/spatialElement.js.map +1 -1
  146. package/dist/spatial-element/spatialElementDock.d.ts +15 -0
  147. package/dist/spatial-element/spatialElementDock.d.ts.map +1 -1
  148. package/dist/spatial-element/spatialElementDock.js +22 -0
  149. package/dist/spatial-element/spatialElementDock.js.map +1 -1
  150. package/dist/spatial-element/spatialElementMedia.d.ts +16 -0
  151. package/dist/spatial-element/spatialElementMedia.d.ts.map +1 -0
  152. package/dist/spatial-element/spatialElementMedia.js +29 -0
  153. package/dist/spatial-element/spatialElementMedia.js.map +1 -0
  154. package/dist/spatial-element/spatialTheme.d.ts +12 -1
  155. package/dist/spatial-element/spatialTheme.d.ts.map +1 -1
  156. package/dist/spatial-element/spatialTheme.js +30 -1
  157. package/dist/spatial-element/spatialTheme.js.map +1 -1
  158. package/dist/spatial-element/types.d.ts +50 -2
  159. package/dist/spatial-element/types.d.ts.map +1 -1
  160. package/dist/spatial-element/types.js.map +1 -1
  161. package/dist/stage/BackgroundLayerOutput.d.ts +76 -0
  162. package/dist/stage/BackgroundLayerOutput.d.ts.map +1 -0
  163. package/dist/stage/BackgroundLayerOutput.js +333 -0
  164. package/dist/stage/BackgroundLayerOutput.js.map +1 -0
  165. package/dist/stage/DeviceGeometryMotion.d.ts +13 -0
  166. package/dist/stage/DeviceGeometryMotion.d.ts.map +1 -0
  167. package/dist/stage/DeviceGeometryMotion.js +37 -0
  168. package/dist/stage/DeviceGeometryMotion.js.map +1 -0
  169. package/dist/stage/LiquidGlassPanel.d.ts +3 -0
  170. package/dist/stage/LiquidGlassPanel.d.ts.map +1 -1
  171. package/dist/stage/LiquidGlassPanel.js +27 -2
  172. package/dist/stage/LiquidGlassPanel.js.map +1 -1
  173. package/dist/stage/MinimapController.d.ts +1 -0
  174. package/dist/stage/MinimapController.d.ts.map +1 -1
  175. package/dist/stage/MinimapController.js +35 -47
  176. package/dist/stage/MinimapController.js.map +1 -1
  177. package/dist/stage/PageBindingController.d.ts +4 -0
  178. package/dist/stage/PageBindingController.d.ts.map +1 -1
  179. package/dist/stage/PageBindingController.js +12 -4
  180. package/dist/stage/PageBindingController.js.map +1 -1
  181. package/dist/stage/PanelPresentationController.d.ts +17 -0
  182. package/dist/stage/PanelPresentationController.d.ts.map +1 -1
  183. package/dist/stage/PanelPresentationController.js +83 -22
  184. package/dist/stage/PanelPresentationController.js.map +1 -1
  185. package/dist/stage/SpatialElementInteractionController.d.ts +7 -0
  186. package/dist/stage/SpatialElementInteractionController.d.ts.map +1 -1
  187. package/dist/stage/SpatialElementInteractionController.js +9 -0
  188. package/dist/stage/SpatialElementInteractionController.js.map +1 -1
  189. package/dist/stage/SpatialElementPresentationController.d.ts +14 -2
  190. package/dist/stage/SpatialElementPresentationController.d.ts.map +1 -1
  191. package/dist/stage/SpatialElementPresentationController.js +47 -2
  192. package/dist/stage/SpatialElementPresentationController.js.map +1 -1
  193. package/dist/stage/SpatialElementRefinement.d.ts +34 -1
  194. package/dist/stage/SpatialElementRefinement.d.ts.map +1 -1
  195. package/dist/stage/SpatialElementRefinement.js +175 -37
  196. package/dist/stage/SpatialElementRefinement.js.map +1 -1
  197. package/dist/stage/StageExperience.d.ts +183 -5
  198. package/dist/stage/StageExperience.d.ts.map +1 -1
  199. package/dist/stage/StageExperience.js +421 -57
  200. package/dist/stage/StageExperience.js.map +1 -1
  201. package/dist/stage/StageRenderPipeline.d.ts +76 -1
  202. package/dist/stage/StageRenderPipeline.d.ts.map +1 -1
  203. package/dist/stage/StageRenderPipeline.js +424 -47
  204. package/dist/stage/StageRenderPipeline.js.map +1 -1
  205. package/dist/stage/VirtualScrollController.d.ts +7 -0
  206. package/dist/stage/VirtualScrollController.d.ts.map +1 -1
  207. package/dist/stage/VirtualScrollController.js +57 -4
  208. package/dist/stage/VirtualScrollController.js.map +1 -1
  209. package/dist/stage/minimap/MinimapModel.d.ts +2 -1
  210. package/dist/stage/minimap/MinimapModel.d.ts.map +1 -1
  211. package/dist/stage/minimap/MinimapModel.js +34 -4
  212. package/dist/stage/minimap/MinimapModel.js.map +1 -1
  213. package/dist/stage/minimap/MinimapModelGeometry.d.ts +21 -0
  214. package/dist/stage/minimap/MinimapModelGeometry.d.ts.map +1 -0
  215. package/dist/stage/minimap/MinimapModelGeometry.js +68 -0
  216. package/dist/stage/minimap/MinimapModelGeometry.js.map +1 -0
  217. package/dist/stage/minimap/MinimapState.d.ts +3 -8
  218. package/dist/stage/minimap/MinimapState.d.ts.map +1 -1
  219. package/dist/stage/minimap/MinimapState.js.map +1 -1
  220. package/dist/stage/panelContext.d.ts +7 -0
  221. package/dist/stage/panelContext.d.ts.map +1 -1
  222. package/dist/stage/panelContext.js.map +1 -1
  223. package/dist/stage/rendererState.d.ts +2 -0
  224. package/dist/stage/rendererState.d.ts.map +1 -1
  225. package/dist/stage/rendererState.js +13 -0
  226. package/dist/stage/rendererState.js.map +1 -1
  227. package/dist/stage/sceneEndpointEligibility.d.ts +20 -0
  228. package/dist/stage/sceneEndpointEligibility.d.ts.map +1 -0
  229. package/dist/stage/sceneEndpointEligibility.js +363 -0
  230. package/dist/stage/sceneEndpointEligibility.js.map +1 -0
  231. package/dist/stage/stageDom.d.ts.map +1 -1
  232. package/dist/stage/stageDom.js +6 -1
  233. package/dist/stage/stageDom.js.map +1 -1
  234. package/dist/stage/stageMath.d.ts +3 -3
  235. package/dist/stage/stageMath.d.ts.map +1 -1
  236. package/dist/stage/stageMath.js +11 -10
  237. package/dist/stage/stageMath.js.map +1 -1
  238. package/dist/stage/stageTypes.d.ts +8 -1
  239. package/dist/stage/stageTypes.d.ts.map +1 -1
  240. package/dist/stage/stageTypes.js.map +1 -1
  241. package/dist/stage/stageVisualTest.d.ts +19 -0
  242. package/dist/stage/stageVisualTest.d.ts.map +1 -1
  243. package/dist/stage/stageVisualTest.js.map +1 -1
  244. package/package.json +1 -1
@@ -1,4 +1,6 @@
1
1
  import { describeRenderTargets } from './renderTargetInventory.js';
2
+ import { DeviceGeometryMotion } from './DeviceGeometryMotion.js';
3
+ import { isDeviceOrientationPaused, getListDeviceYaw, getListDevicePitch, getListDeviceRoll, retainListDeviceOrientation, subscribeListDeviceYaw, pauseDeviceOrientationForScroll, holdDeviceOrientationForTransition } from '../catalog/listDeviceOrientation.js';
2
4
  import { StageRenderPipeline } from './StageRenderPipeline.js';
3
5
  import { PanelPresentationController } from './PanelPresentationController.js';
4
6
  import { MinimapController } from './MinimapController.js';
@@ -21,15 +23,17 @@ import { CSS3DRenderer } from 'three/addons/renderers/CSS3DRenderer.js';
21
23
  import { uniform } from 'three/tsl';
22
24
  import { LiquidGlassPanel, resolveLiquidGlassPanelOptions } from './LiquidGlassPanel.js';
23
25
  import { STAGE_PANEL_LAYOUT_EVENT, STAGE_PANEL_VISUAL_EVENT } from './panelContext.js';
24
- import { DEFAULT_BACKGROUND, DEFAULT_INTERACTION_THEME, DEFAULT_PANELS, PANEL_CAMERA_FOV, PANEL_CONTENT_Z, SPATIAL_ELEMENT_CAMERA_FIT_MARGIN, ZOOM_FOCUS_NOTIFY_EPSILON } from './stageConstants.js';
26
+ import { DEFAULT_BACKGROUND, DEFAULT_INTERACTION_THEME, DEFAULT_PANELS, PANEL_CAMERA_FOV, PANEL_CONTENT_Z, ZOOM_FOCUS_NOTIFY_EPSILON } from './stageConstants.js';
25
27
  import { getStagePositionFromRect, isViewportRectVisible } from './stageDom.js';
26
28
  import { STAGE_SCROLL_PRIORITY, getStageVisualScrollPosition, hasPendingStageScrollFrame, subscribeStageScrollFrame } from './scrollFrame.js';
27
- import { getCameraFitDistance, getCameraOrbitDirection, getBoxCorners, getPanelFocusOpacity, getPerspectiveDistance, getSequencedMinimapFocus, getStageUiFocus, getZoomFocusDistanceRange, hasPanelGeometryChanged } from './stageMath.js';
29
+ import { getCameraOrbitDirection, getBoxCorners, getPanelFocusOpacity, getPerspectiveDistance, getSequencedMinimapFocus, getStageUiFocus, getZoomFocusDistanceRange, hasPanelGeometryChanged } from './stageMath.js';
28
30
  import {} from './SpaceMouseAdapter.js';
29
31
  import { disposeMinimapModelMaterials } from './minimap/MinimapModel.js';
30
32
  import {} from './minimap/MinimapProjection.js';
31
33
  import { disposeMaterialOnly, getMeshBounds, getMeshMaterials, isMesh } from './stageSceneUtils.js';
32
34
  import { isOutlineMesh } from './interactionOutline.js';
35
+ import { resolveDetailLayout, resolveZoomLayout } from '../spatial-element/responsiveLayout.js';
36
+ import { detailCameraFit, detailCameraFitDistance } from '../catalog/stagedDetailGeometry.js';
33
37
  const SCROLL_SETTLE_DELAY = 120;
34
38
  const VIEWPORT_CULL_MARGIN = 96;
35
39
  /** Shared spatial state for both WebGPU glass and DOM-backed panel surfaces. */
@@ -105,7 +109,64 @@ export class StageExperience {
105
109
  catalogLayer;
106
110
  catalogHandoff = false;
107
111
  catalogMotionComplete = false;
112
+ stagedDetailTarget;
113
+ stagedAwaitingFirstFrame = false;
114
+ stagedSceneCacheOwner;
115
+ stagedRevealPreparing;
116
+ releaseStagedSensorHold;
117
+ /** Use only already submitted source resources during the pre-route movement. */
118
+ beginStagedDetailMotion(source, fit, targetOptions) {
119
+ if (!this.catalogLayer || this.spatialCapture || this.catalogHandoff)
120
+ return false;
121
+ if (this.pipeline.backgroundOutputHeld || !this.catalogLayer.isStagedDetailReady(source.spatialElementId, source.occurrence, this.renderer, this.pipeline.ensureCatalogWarmOutputContext()))
122
+ return false;
123
+ const target = this.catalogLayer.getStagedDetailTarget(source.spatialElementId, source.occurrence, fit, { width: window.innerWidth, height: window.innerHeight }, targetOptions, this.renderer.coordinateSystem);
124
+ if (!target || !this.catalogLayer.capture(source.spatialElementId, source.occurrence))
125
+ return false;
126
+ this.stagedDetailTarget = target;
127
+ // Progress zero preserves the currently displayed source. The transition's
128
+ // clock submits the first changed pose; an intervening Stage RAF would draw
129
+ // that same source again and delay the first visible acknowledgement.
130
+ this.stagedAwaitingFirstFrame = true;
131
+ cancelAnimationFrame(this.renderRequestId);
132
+ this.renderRequestId = 0;
133
+ this.catalogLayer.freezeStagedSource();
134
+ this.releaseStagedSensorHold = holdDeviceOrientationForTransition();
135
+ this.deviceMotion.update(0, 0, 0, 1);
136
+ this.catalogHandoff = true;
137
+ this.catalogMotionComplete = false;
138
+ this.preparationGate.setPaused(true);
139
+ this.detailPreparationGate.setPaused(true);
140
+ this.setStagedDetailProgress(0);
141
+ return true;
142
+ }
143
+ setStagedDetailProgress(progress) {
144
+ if (!this.stagedDetailTarget)
145
+ return;
146
+ this.catalogLayer?.setHandoffTarget({ ...this.stagedDetailTarget, progress, environmentIntensity: 0.5 });
147
+ this.requestRender();
148
+ }
149
+ setStagedDetailPanel(card, corners, width, height) {
150
+ return this.catalogLayer?.setStagedPanel(card, corners, width, height) ?? false;
151
+ }
152
+ setStagedPanelOpacity(opacity) { this.catalogLayer?.setStagedPanelOpacity(opacity); }
153
+ /** Called only after the final moving frame: route teardown may now replace its source. */
154
+ holdStagedDetail(spatialElementId, kind = 'hero') {
155
+ if (!this.stagedDetailTarget)
156
+ return false;
157
+ this.setStagedDetailProgress(1);
158
+ this.flushCatalogFrame();
159
+ const held = this.adoptCatalogPresentation({ spatialElementId, kind }, true);
160
+ this.stagedDetailTarget = undefined;
161
+ return held;
162
+ }
163
+ deferredZoomPreparation = false;
164
+ deferredScrollWarmup;
165
+ zoomPreparationFrame = 0;
108
166
  catalogLayerAnimating = false;
167
+ stagedPreparationIdle = 0;
168
+ stagedPreparationFallback = false;
169
+ stagedPreparationAbort = new AbortController();
109
170
  catalogPresentation = { ...RESTING_CATALOG_PRESENTATION };
110
171
  pageModelReady = false;
111
172
  preparationGate = new PreparationGate();
@@ -179,7 +240,12 @@ export class StageExperience {
179
240
  get minimaps() {
180
241
  return this.minimapController.views;
181
242
  }
182
- resize = () => this.resizeRenderer();
243
+ resize = () => this.requestRender();
244
+ rendererSize = new THREE.Vector2();
245
+ deviceMotion = new DeviceGeometryMotion();
246
+ deviceOrientationEnabled;
247
+ releaseDeviceOrientation;
248
+ unsubscribeDeviceOrientation;
183
249
  render = () => {
184
250
  this.renderRequestId = 0;
185
251
  // The shared callback will draw after updating DOM/dock positions. Avoid
@@ -263,6 +329,31 @@ export class StageExperience {
263
329
  panelMeasurementsDirty = true;
264
330
  viewportMeasurementDirty = true;
265
331
  stageViewportVisible = true;
332
+ readLayoutMetrics;
333
+ detailMedia = 'minimap';
334
+ get detailMediaActive() { return this.detailMedia === 'minimap'; }
335
+ /** Changing media keeps the model/cache/camera but stops its interaction and sensor clock. */
336
+ setDetailMedia(media) {
337
+ if (this.detailMedia === media)
338
+ return;
339
+ this.detailMedia = media;
340
+ this.interaction.releasePage();
341
+ if (!this.detailMediaActive) {
342
+ this.releaseDeviceOrientation?.();
343
+ this.releaseDeviceOrientation = undefined;
344
+ }
345
+ this.requestRender();
346
+ }
347
+ readDetailInteractionLayout() {
348
+ const input = this.catalog ? this.readLayoutMetrics?.('stable') : undefined;
349
+ if (!input)
350
+ return;
351
+ const layout = resolveDetailLayout(input);
352
+ const split = layout.composition === 'split';
353
+ return { media: this.detailMedia, split,
354
+ paneHidden: split && (this.fullscreen || this.panelUiFocus >= 0.99),
355
+ paneLeft: layout.base.pane.x };
356
+ }
266
357
  fullscreen = false;
267
358
  setFullscreen(fullscreen) {
268
359
  if (this.fullscreen === fullscreen)
@@ -324,8 +415,16 @@ export class StageExperience {
324
415
  */
325
416
  constructor(container, options = {}) {
326
417
  this.container = container;
418
+ this.readLayoutMetrics = options.readLayoutMetrics;
419
+ this.detailMedia = options.detailMedia ?? 'minimap';
327
420
  if (options.dracoDecoderPath)
328
421
  this.assets.setDracoDecoderPath(options.dracoDecoderPath);
422
+ this.deviceOrientationEnabled = options.deviceOrientation ?? false;
423
+ if (this.deviceOrientationEnabled)
424
+ this.unsubscribeDeviceOrientation = subscribeListDeviceYaw(() => {
425
+ if (this.releaseDeviceOrientation && !this.scrollActive)
426
+ this.requestRender();
427
+ });
329
428
  this.interaction = new SpatialElementInteractionController({
330
429
  camera: this.camera,
331
430
  canvas: this.backgroundCanvas,
@@ -336,15 +435,17 @@ export class StageExperience {
336
435
  readGeometry: () => ({
337
436
  poseOwner: this.catalogHandoff || this.spatialCapture
338
437
  ? 'transition'
339
- : this.catalog && !this.viewportTarget
438
+ : !this.detailMediaActive || (this.catalog && !this.viewportTarget)
340
439
  ? 'none'
341
440
  : 'page',
342
- visible: this.stageViewportVisible,
441
+ visible: this.stageViewportVisible && this.detailMediaActive,
442
+ detail: this.readDetailInteractionLayout(),
343
443
  viewport: this.viewportFrame,
344
444
  bounds: this.modelBounds
345
445
  })
346
446
  });
347
447
  this.minimapController = new MinimapController({
448
+ sensorRotation: () => this.deviceMotion.rotation,
348
449
  renderer: this.renderer,
349
450
  camera: this.camera,
350
451
  panelCamera: this.panelCamera,
@@ -374,6 +475,10 @@ export class StageExperience {
374
475
  includeMesh: (mesh) => this.isSpatialElementMesh(mesh)
375
476
  });
376
477
  this.panels = new PanelPresentationController({
478
+ zoomLayout: () => {
479
+ const input = this.catalog ? this.readLayoutMetrics?.('visible') : undefined;
480
+ return input ? resolveZoomLayout(input) : undefined;
481
+ },
377
482
  camera: this.panelCamera,
378
483
  contentScene: this.panelContentScene,
379
484
  flatLayer: this.flatPanelLayer,
@@ -449,6 +554,7 @@ export class StageExperience {
449
554
  catalogHandoff: this.catalogHandoff,
450
555
  catalogMotionComplete: this.catalogMotionComplete,
451
556
  stageViewportVisible: this.stageViewportVisible,
557
+ detailMediaActive: this.detailMediaActive,
452
558
  modelHover: this.modelHover,
453
559
  modelInteractionActive: this.modelInteractionActive,
454
560
  catalog: this.catalog,
@@ -489,6 +595,7 @@ export class StageExperience {
489
595
  this.renderer.dispose();
490
596
  return;
491
597
  }
598
+ this.pipeline.initializeBackgroundOutput();
492
599
  this.backgroundCanvas.className = 'stage-webgpu-background';
493
600
  this.container.appendChild(this.backgroundCanvas);
494
601
  this.configureCssRenderer();
@@ -526,6 +633,7 @@ export class StageExperience {
526
633
  this.currentScrollY = scrollPosition.scrollY;
527
634
  this.lastScrollY = this.currentScrollY;
528
635
  window.addEventListener('resize', this.resize);
636
+ window.visualViewport?.addEventListener('resize', this.resize);
529
637
  this.stopScrollFrames = subscribeStageScrollFrame(this.scroll, STAGE_SCROLL_PRIORITY.stage);
530
638
  window.addEventListener(STAGE_PANEL_LAYOUT_EVENT, this.requestPanelSync);
531
639
  window.addEventListener(STAGE_PANEL_VISUAL_EVENT, this.requestPanelVisualSync);
@@ -551,9 +659,21 @@ export class StageExperience {
551
659
  if (this.disposed)
552
660
  return;
553
661
  this.disposed = true;
662
+ this.stagedPreparationAbort.abort();
663
+ if (this.stagedPreparationIdle) {
664
+ if (this.stagedPreparationFallback)
665
+ clearTimeout(this.stagedPreparationIdle);
666
+ else
667
+ window.cancelIdleCallback(this.stagedPreparationIdle);
668
+ }
669
+ this.releaseDeviceOrientation?.();
670
+ this.unsubscribeDeviceOrientation?.();
671
+ this.releaseStagedSensorHold?.();
672
+ this.releaseStagedSensorHold = undefined;
554
673
  this.releaseSpatialCapture();
555
674
  this.container.removeAttribute('data-stage-scroll-rendering');
556
675
  window.removeEventListener('resize', this.resize);
676
+ window.visualViewport?.removeEventListener('resize', this.resize);
557
677
  this.stopScrollFrames?.();
558
678
  this.stopScrollFrames = undefined;
559
679
  window.removeEventListener(STAGE_PANEL_LAYOUT_EVENT, this.requestPanelSync);
@@ -601,6 +721,10 @@ export class StageExperience {
601
721
  }
602
722
  /** Page DOM is a replaceable binding, not the owner of the device or element cache. */
603
723
  releasePage() {
724
+ cancelAnimationFrame(this.zoomPreparationFrame);
725
+ this.zoomPreparationFrame = 0;
726
+ this.deferredZoomPreparation = false;
727
+ this.deferredScrollWarmup = undefined;
604
728
  this.pageBinding.invalidate();
605
729
  this.pageModelReady = false;
606
730
  this.presentation.cancelRequests();
@@ -630,8 +754,12 @@ export class StageExperience {
630
754
  element);
631
755
  }
632
756
  capturePanelSurface(element) {
633
- if (element.closest('[data-carousel-spatial-element]'))
634
- return captureCssSurface(element, element, '::before');
757
+ if (element.closest('[data-carousel-spatial-element]')) {
758
+ const bounds = element.matches('.summary') ? element :
759
+ (element.closest('[data-spatial-presentation-root]') ?? element);
760
+ const surface = bounds.querySelector('.spatial-summary-surface');
761
+ return captureCssSurface(bounds, surface ?? bounds, surface ? undefined : '::before');
762
+ }
635
763
  if (element.hasAttribute('data-catalog-dock-surface')) {
636
764
  const header = element.closest('[data-spatial-element-sticky-header]');
637
765
  if (header)
@@ -744,11 +872,11 @@ export class StageExperience {
744
872
  if (!target)
745
873
  continue; // Navigation owns newly registered panels.
746
874
  const appearance = (panel) => JSON.stringify([
747
- panel.options, panel.minimap, panel.surface, panel.contentInset
875
+ panel.options, panel.minimap, panel.surface, panel.contentInset, panel.nativeContent
748
876
  ]);
749
877
  if (appearance(target) === appearance(next))
750
878
  continue;
751
- surfaceChanged ||= target.surface !== next.surface;
879
+ surfaceChanged ||= target.surface !== next.surface || target.nativeContent !== next.nativeContent;
752
880
  Object.assign(target, next);
753
881
  changed.push(index);
754
882
  }
@@ -757,7 +885,7 @@ export class StageExperience {
757
885
  .filter((target) => target.surface === 'glass' || target.minimap).map((target) => target.options);
758
886
  this.pipeline.syncPanelBlurCaptures();
759
887
  if (surfaceChanged) {
760
- // A backend change only replaces panel presentation, never the element scene.
888
+ // Surface/DOM ownership changes move the entire live root, never its children or scene.
761
889
  this.minimapController.dispose();
762
890
  this.panels.release();
763
891
  this.createPanels();
@@ -837,11 +965,14 @@ export class StageExperience {
837
965
  this.createPanels();
838
966
  this.observePanelTargets();
839
967
  this.resizeRenderer();
840
- // New page targets must be GPU-ready before navigation or the first zoom.
841
- // Resting frosted panels do not otherwise submit their hidden backdrop blur.
842
- this.pipeline.warmRenderTargetSets();
968
+ // Navigation needs the visible full-quality frame, not future scroll/zoom variants.
969
+ // Direct/zoomed entries keep eager warming; ordinary handoffs warm after their final paint.
970
+ this.deferredZoomPreparation = this.catalogPresentation.active && this.panelUiFocus === 0;
971
+ if (!this.deferredZoomPreparation)
972
+ this.pipeline.warmRenderTargetSets();
843
973
  this.renderFrame(true);
844
- await this.pipeline.prepareZoomEffects();
974
+ if (!this.deferredZoomPreparation)
975
+ await this.pipeline.prepareZoomEffects();
845
976
  if (this.disposed || !this.pageBinding.isCurrent(generation))
846
977
  return;
847
978
  // A submitted Low/panel frame is not yet GPU-ready. Drain the required binding work
@@ -861,7 +992,111 @@ export class StageExperience {
861
992
  : this.catalogPresentation.exitOpacity, this.catalogPresentation.active);
862
993
  return this.catalogLayer.setSpatialElements(brandId, items);
863
994
  }
995
+ /** Finish required DETAIL GPU preparation before its first visible reveal frame.
996
+ * Binding happens with enterOpacity=0, which intentionally skips minimaps and
997
+ * panel blur passes. Borrow fractional/end-point alpha to prepare both real
998
+ * material owners, restore all presentation state synchronously, then fence.
999
+ */
1000
+ async prepareStagedReveal(signal) {
1001
+ if (this.disposed || signal?.aborted || !this.catalogPresentation.active)
1002
+ return false;
1003
+ const generation = this.pageBinding.token;
1004
+ const owner = {};
1005
+ const pageBackground = this.pageBackground;
1006
+ this.presentation.invalidateSceneEndpoints();
1007
+ this.stagedSceneCacheOwner = this.stagedRevealPreparing = owner;
1008
+ const presentation = this.catalogPresentation;
1009
+ const backgroundReveal = this.catalogBackgroundReveal.value;
1010
+ let prepared = true;
1011
+ let succeeded = false;
1012
+ let ticket;
1013
+ let scrollWarmup;
1014
+ this.deferredScrollWarmup = undefined;
1015
+ try {
1016
+ try {
1017
+ // List/Card does not necessarily flush after binding. Adopt only already-ready
1018
+ // asynchronous High; this starts no loading and advances neither p nor q.
1019
+ if (this.pageModelReady && this.catalogHandoff && this.catalogMotionComplete && !this.catalogDockTarget &&
1020
+ this.catalogMode !== 'synchronous' && this.pagePreparation?.highState === 'ready')
1021
+ this.adoptPreparedHigh();
1022
+ // Programmatic dock restoration may still own the temporary scroll targets.
1023
+ // The reveal uses full quality; do not let its settle timer select cold targets.
1024
+ this.pipeline.setScrollRenderQuality(false);
1025
+ this.syncPanelLayouts();
1026
+ for (const opacity of [0.5, 1]) {
1027
+ this.catalogPresentation = {
1028
+ ...presentation, enterOpacity: opacity, sharedOpacity: opacity
1029
+ };
1030
+ this.catalogBackgroundReveal.value = opacity;
1031
+ this.updatePanelPointerInteraction(0);
1032
+ if (!this.pipeline.warmRevealFrame()) {
1033
+ prepared = false;
1034
+ break;
1035
+ }
1036
+ }
1037
+ if (prepared && this.deferredZoomPreparation && !this.catalogDockTarget && !this.refinement) {
1038
+ const model = this.model, low = this.presentation.assetInstance, high = this.highInstance, environment = this.scene.environment, background = this.backgroundScene.background;
1039
+ scrollWarmup = this.pipeline.captureDeferredScrollWarmup(() => !this.disposed && !signal?.aborted && this.pageBinding.isCurrent(generation) && this.pageModelReady && this.detailMediaActive &&
1040
+ this.model === model && this.presentation.assetInstance === low && this.highInstance === high && !this.refinement &&
1041
+ this.scene.environment === environment && this.backgroundScene.background === background && this.pageBackground === pageBackground);
1042
+ }
1043
+ // Shader/target warm-up is finished. Only now capture final endpoint pixels.
1044
+ if (prepared && this.catalogHandoff && this.catalogMotionComplete && !this.catalogDockTarget &&
1045
+ this.renderer.backend.isWebGPUBackend) {
1046
+ try {
1047
+ ticket = this.pipeline.withSceneCapture(() => {
1048
+ const target = this.renderer.getRenderTarget();
1049
+ const width = target.width, height = target.height;
1050
+ return this.presentation.prepareSceneEndpoints(this.renderer, this.scene, this.camera, this.pagePreparation?.environment.value?.target.texture, (p) => {
1051
+ const previous = this.catalogBackgroundReveal.value;
1052
+ this.catalogBackgroundReveal.value = p;
1053
+ try {
1054
+ this.pipeline.renderStageContents();
1055
+ }
1056
+ finally {
1057
+ this.catalogBackgroundReveal.value = previous;
1058
+ }
1059
+ }, () => !this.disposed && !signal?.aborted && this.stagedSceneCacheOwner === owner && this.pageBinding.isCurrent(generation) &&
1060
+ this.catalogPresentation.active && !this.catalogDockTarget && this.detailMediaActive &&
1061
+ this.pageBackground === pageBackground && this.pipeline.isSceneCaptureCurrent(target, width, height), [this.backgroundScene, this.tintScene], [this.tintCamera]);
1062
+ });
1063
+ }
1064
+ catch (error) {
1065
+ console.warn('Optional staged scene endpoint preparation failed; retaining live rendering', error);
1066
+ }
1067
+ }
1068
+ }
1069
+ finally {
1070
+ this.catalogPresentation = presentation;
1071
+ this.catalogBackgroundReveal.value = backgroundReveal;
1072
+ this.updatePanelPointerInteraction(0);
1073
+ }
1074
+ if (!prepared)
1075
+ return false;
1076
+ const device = this.renderer.backend.device;
1077
+ await device?.queue.onSubmittedWorkDone();
1078
+ if (this.disposed || signal?.aborted || !this.pageBinding.isCurrent(generation) || this.stagedSceneCacheOwner !== owner)
1079
+ return false;
1080
+ // A live Low/High write during the fence invalidates its ticket even with the same page generation.
1081
+ ticket?.commit();
1082
+ this.deferredScrollWarmup = scrollWarmup;
1083
+ succeeded = true;
1084
+ return true;
1085
+ }
1086
+ finally {
1087
+ if (this.stagedRevealPreparing === owner)
1088
+ this.stagedRevealPreparing = undefined;
1089
+ if (!succeeded)
1090
+ ticket?.cancel();
1091
+ }
1092
+ }
864
1093
  setCatalogTransitionPresentation(state) {
1094
+ if (!state.active) {
1095
+ this.stagedSceneCacheOwner = undefined;
1096
+ this.presentation.invalidateSceneEndpoints();
1097
+ }
1098
+ if (!state.active)
1099
+ this.scheduleZoomPreparation();
865
1100
  this.catalogPresentation = normalizeCatalogPresentation(state);
866
1101
  for (const entry of this.exitingMinimaps) {
867
1102
  this.setMinimapDisplayModelOpacity(entry.minimap, entry.opacity * state.exitOpacity);
@@ -886,6 +1121,58 @@ export class StageExperience {
886
1121
  this.backgroundCanvas.style.opacity = String(state.active ? state.exitOpacity : 0);
887
1122
  this.requestRender();
888
1123
  }
1124
+ scheduleZoomPreparation() {
1125
+ if (!this.deferredZoomPreparation || this.zoomPreparationFrame || this.disposed)
1126
+ return;
1127
+ const generation = this.pageBinding.token;
1128
+ // A nested RAF lets the final transition frame paint before optional work starts.
1129
+ this.zoomPreparationFrame = requestAnimationFrame(() => {
1130
+ this.zoomPreparationFrame = requestAnimationFrame(() => {
1131
+ this.zoomPreparationFrame = 0;
1132
+ if (this.disposed || !this.pageBinding.isCurrent(generation) || this.catalogPresentation.active)
1133
+ return;
1134
+ this.deferredZoomPreparation = false;
1135
+ const scrollWarmup = this.deferredScrollWarmup;
1136
+ this.deferredScrollWarmup = undefined;
1137
+ void (async () => {
1138
+ if (!scrollWarmup || !this.pipeline.warmInactiveScrollTargetSet(scrollWarmup))
1139
+ this.pipeline.warmRenderTargetSets();
1140
+ await this.pipeline.prepareZoomEffects();
1141
+ if (!this.disposed && this.pageBinding.isCurrent(generation))
1142
+ this.requestRender();
1143
+ })().catch(error => {
1144
+ // Rendering still prepares effects on demand if optional warming fails.
1145
+ if (!this.disposed && this.pageBinding.isCurrent(generation))
1146
+ console.warn('Optional zoom preparation failed', error);
1147
+ });
1148
+ });
1149
+ });
1150
+ }
1151
+ scheduleStagedPreparation() {
1152
+ if (this.disposed || this.stagedPreparationIdle || this.catalogHandoff || this.scrollActive ||
1153
+ this.catalogPresentation.active || this.pipeline.backgroundOutputHeld ||
1154
+ !this.catalogLayer?.needsStagedPreparation(this.renderer, this.pipeline.ensureCatalogWarmOutputContext()))
1155
+ return;
1156
+ const prepare = () => {
1157
+ this.stagedPreparationIdle = 0;
1158
+ if (this.disposed || this.catalogHandoff || this.scrollActive || this.catalogPresentation.active || this.pipeline.backgroundOutputHeld)
1159
+ return;
1160
+ void this.preparationGate.run(() => {
1161
+ if (this.disposed || this.catalogHandoff || this.scrollActive || this.catalogPresentation.active || this.pipeline.backgroundOutputHeld)
1162
+ return;
1163
+ return this.catalogLayer?.prepareStagedNavigation(this.renderer, this.pipeline.ensureCatalogWarmOutputContext());
1164
+ }, this.stagedPreparationAbort.signal).catch(() => {
1165
+ // Early navigation remains unavailable; ordinary routing still works.
1166
+ }).finally(() => {
1167
+ // Models can finish their first render while another actor's GPU work
1168
+ // is pending. Recheck once idle instead of waiting for a new input frame.
1169
+ this.scheduleStagedPreparation();
1170
+ });
1171
+ };
1172
+ this.stagedPreparationFallback = !window.requestIdleCallback;
1173
+ this.stagedPreparationIdle = window.requestIdleCallback
1174
+ ? window.requestIdleCallback(prepare, { timeout: 1000 }) : window.setTimeout(prepare, 50);
1175
+ }
889
1176
  /** Reports actual applied GPU alpha for browser verification without layout or style reads. */
890
1177
  getCatalogPresentation() {
891
1178
  const triangles = (root) => {
@@ -917,6 +1204,7 @@ export class StageExperience {
917
1204
  backgroundPrepared: this.catalogBackgroundPrepared,
918
1205
  handoffPoint: this.getCatalogGeometryPoint(),
919
1206
  representations: {
1207
+ sceneEndpointCache: this.presentation.getSceneEndpointStats(),
920
1208
  retainedBlendTargets: this.returnBlend?.targetCount ?? 0,
921
1209
  state: this.refinementState,
922
1210
  hero: this.model ? (this.refinementState === 'high' ? 'high' : 'low') : null,
@@ -1057,7 +1345,7 @@ export class StageExperience {
1057
1345
  return this.spatialCapture?.getPoint() ?? this.catalogLayer?.getHandoffPoint() ?? null;
1058
1346
  }
1059
1347
  /** Lease the last submitted element frame before another page binding can release it. */
1060
- adoptCatalogPresentation(destination) {
1348
+ adoptCatalogPresentation(destination, restoreSourceOnCancel = false) {
1061
1349
  const { spatialElementId } = destination;
1062
1350
  const reverse = destination.kind === 'content';
1063
1351
  if (!this.spatialCapture) {
@@ -1097,7 +1385,10 @@ export class StageExperience {
1097
1385
  highPose?.removeFromParent();
1098
1386
  transferredHigh?.overrides.forEach(disposeMaterialOnly);
1099
1387
  high?.dispose();
1100
- moving.release();
1388
+ if (restoreSourceOnCancel && !this.disposed && this.pageBinding.token === generation)
1389
+ moving.restore();
1390
+ else
1391
+ moving.release();
1101
1392
  }
1102
1393
  });
1103
1394
  }
@@ -1190,17 +1481,21 @@ export class StageExperience {
1190
1481
  this.outgoingBackground = true;
1191
1482
  return true;
1192
1483
  }
1193
- getDockProjection() {
1484
+ getDockProjection(allowViewportClipping = false) {
1194
1485
  const candidates = [...this.minimaps.values()].filter((minimap) => minimap.viewportVisible);
1195
1486
  if (candidates.length !== 1)
1196
1487
  return;
1197
1488
  const minimap = candidates[0];
1198
1489
  const rect = this.getProjectedMinimapModelRect(minimap);
1199
- if (!rect ||
1200
- rect.x < 0 ||
1201
- rect.y < 0 ||
1202
- rect.x + rect.width > innerWidth ||
1203
- rect.y + rect.height > innerHeight)
1490
+ if (!rect)
1491
+ return;
1492
+ // Canonical dock fits can extend above the viewport (XS/S centers an 80px
1493
+ // fit in a 76px header). A known destination may be partially clipped;
1494
+ // reverse capture retains its stricter, wholly visible source requirement.
1495
+ if (allowViewportClipping
1496
+ ? rect.width <= 0 || rect.height <= 0 || rect.x >= innerWidth || rect.y >= innerHeight ||
1497
+ rect.x + rect.width <= 0 || rect.y + rect.height <= 0
1498
+ : rect.x < 0 || rect.y < 0 || rect.x + rect.width > innerWidth || rect.y + rect.height > innerHeight)
1204
1499
  return;
1205
1500
  return {
1206
1501
  ...captureSpatialElementProjection(minimap.spatialElementRoot, minimap.screenCamera),
@@ -1249,9 +1544,18 @@ export class StageExperience {
1249
1544
  }
1250
1545
  prepareCatalogDestination(dock) {
1251
1546
  this.catalogDockTarget = dock;
1547
+ if (dock) {
1548
+ // Scroll restoration can dock the DOM after updatePage's submitted frame.
1549
+ // Its layout event invalidates the cache, but the next Stage RAF need not
1550
+ // have run before this binding handshake. Resolve the live destination
1551
+ // and its visibility/projection together, without drawing a GPU frame or
1552
+ // advancing hover animation while the retained source is held onscreen.
1553
+ this.syncPanelLayouts(true);
1554
+ this.updatePanelPointerInteraction(0);
1555
+ }
1252
1556
  if (this.adoptedForward) {
1253
1557
  this.returnProjection = dock
1254
- ? this.getDockProjection()
1558
+ ? this.getDockProjection(true)
1255
1559
  : this.model
1256
1560
  ? {
1257
1561
  ...captureSpatialElementProjection(this.model, this.camera),
@@ -1260,7 +1564,7 @@ export class StageExperience {
1260
1564
  : undefined;
1261
1565
  return Boolean(this.returnProjection);
1262
1566
  }
1263
- return !dock || Boolean(this.getDockProjection());
1567
+ return !dock || Boolean(this.getDockProjection(true));
1264
1568
  }
1265
1569
  prepareReturnDestination() {
1266
1570
  if (!this.returnSpatialElement || !this.spatialCapture)
@@ -1394,14 +1698,31 @@ export class StageExperience {
1394
1698
  }
1395
1699
  /** Commit GPU and DOM motion in the same browser frame, not on consecutive RAFs. */
1396
1700
  flushCatalogFrame() {
1701
+ this.stagedAwaitingFirstFrame = false;
1397
1702
  cancelAnimationFrame(this.renderRequestId);
1398
1703
  this.renderRequestId = 0;
1399
1704
  this.renderFrame(true);
1705
+ // A synchronous render callback (for example adopting newly prepared High)
1706
+ // can invalidate while this forced frame is running. Its own RAF would run
1707
+ // before the next external-clock pose and draw this pose again. Keep the
1708
+ // dirty flag, but let that next external flush consume it. Invalidations
1709
+ // outside this flush remain schedulable, including during held page binding.
1710
+ if (this.catalogPresentation.active) {
1711
+ cancelAnimationFrame(this.renderRequestId);
1712
+ this.renderRequestId = 0;
1713
+ }
1400
1714
  // After the transition's external clock stops, optional refinement resumes its own RAF.
1401
- if (!this.catalogPresentation.active && (this.animationActive || this.renderInvalidated))
1715
+ else if (this.animationActive || this.renderInvalidated)
1402
1716
  this.scheduleRender();
1403
1717
  }
1404
1718
  finishCatalogGeometry() {
1719
+ this.stagedSceneCacheOwner = undefined;
1720
+ this.presentation.invalidateSceneEndpoints();
1721
+ this.stagedAwaitingFirstFrame = false;
1722
+ this.stagedDetailTarget = undefined;
1723
+ this.releaseStagedSensorHold?.();
1724
+ this.releaseStagedSensorHold = undefined;
1725
+ this.catalogLayer?.finishStagedPanel();
1405
1726
  this.releaseSpatialCapture();
1406
1727
  this.adoptedForward = false;
1407
1728
  this.returnSpatialElement = undefined;
@@ -1564,6 +1885,14 @@ export class StageExperience {
1564
1885
  height: Math.max(...yCoordinates) - top
1565
1886
  };
1566
1887
  }
1888
+ /** Returns the bound renderer's projection for query-gated handoff regressions. */
1889
+ getVisualTestDetailProjection(kind) {
1890
+ // Forward ownership releases SpatialGeometryCapture at progress one. Read
1891
+ // its actual successor instead of expecting a final retained-capture frame.
1892
+ if (kind === 'dock')
1893
+ return this.getDockProjection(true)?.clip.toArray() ?? null;
1894
+ return this.model ? captureSpatialElementProjection(this.model, this.camera).clip.toArray() : null;
1895
+ }
1567
1896
  /** Returns the main element's projected bounds for query-gated layout regressions. */
1568
1897
  getVisualTestModelRect() {
1569
1898
  if (!this.model || this.modelBounds.isEmpty())
@@ -1629,7 +1958,25 @@ export class StageExperience {
1629
1958
  }
1630
1959
  /** Returns Low-band and glass-compositor counters without scheduling rendering. */
1631
1960
  getCarouselStats() {
1632
- return this.catalogLayer?.getStats() ?? null;
1961
+ return this.catalogLayer?.getStats(this.renderer, this.pipeline.peekCatalogWarmOutputContext()) ?? null;
1962
+ }
1963
+ /** Query-gated snapshot: no new frame state, DOM measurements, scheduling or settling. */
1964
+ getVisualTestRenderActivity() {
1965
+ const preparation = this.preparation?.current;
1966
+ const assets = this.assets.getStats();
1967
+ return { at: performance.now(), lastFrameAt: this.lastFrameTime,
1968
+ animationActive: this.animationActive, catalogAnimating: this.catalogLayerAnimating,
1969
+ renderInvalidated: this.renderInvalidated, pendingRenderFrame: this.renderRequestId !== 0,
1970
+ pendingScrollFrame: hasPendingStageScrollFrame(), scrollActive: this.scrollActive,
1971
+ stagedAwaitingFirstFrame: this.stagedAwaitingFirstFrame,
1972
+ transitionActive: this.catalogPresentation.active,
1973
+ preparation: { stagedIdlePending: this.stagedPreparationIdle !== 0,
1974
+ zoomFramePending: this.zoomPreparationFrame !== 0, zoomDeferred: this.deferredZoomPreparation,
1975
+ gate: this.preparationGate.getActivity(), detailGate: this.detailPreparationGate.getActivity(),
1976
+ background: preparation?.backgroundState ?? null, high: preparation?.highState ?? null,
1977
+ assetLoads: assets.pendingLoads, activeInstances: assets.activeInstances },
1978
+ catalog: this.catalogLayer?.getRenderActivity() ?? null,
1979
+ panels: this.panels.getRenderActivity() };
1633
1980
  }
1634
1981
  /** Returns render-target lifecycle counters for query-gated performance tests. */
1635
1982
  getVisualTestRenderTargetStats() {
@@ -1661,6 +2008,8 @@ export class StageExperience {
1661
2008
  creations: this.pipeline.renderTargetSetCreations,
1662
2009
  resizes: this.pipeline.renderTargetSetResizes,
1663
2010
  warmups: this.pipeline.renderTargetSetWarmups,
2011
+ inactiveScrollWarmups: this.pipeline.deferredScrollWarmups,
2012
+ backgroundOutput: this.pipeline.getBackgroundOutputStats(),
1664
2013
  activeScale: this.pipeline.activeRenderTargets?.scale ?? 0
1665
2014
  };
1666
2015
  }
@@ -1723,7 +2072,7 @@ export class StageExperience {
1723
2072
  this.scheduleRender();
1724
2073
  }
1725
2074
  scheduleRender() {
1726
- if (this.disposed || document.hidden || this.renderRequestId)
2075
+ if (this.disposed || document.hidden || this.renderRequestId || this.stagedAwaitingFirstFrame)
1727
2076
  return;
1728
2077
  this.renderRequestId = requestAnimationFrame(this.render);
1729
2078
  }
@@ -1951,23 +2300,20 @@ export class StageExperience {
1951
2300
  if (this.referenceBounds)
1952
2301
  bounds.copy(this.referenceBounds);
1953
2302
  this.modelBounds.copy(bounds);
1954
- const sphere = bounds.getBoundingSphere(new THREE.Sphere());
1955
- const radius = Math.max(sphere.radius, 1);
1956
- this.modelRadius = radius;
1957
- const orbitDirection = getCameraOrbitDirection(this.cameraSettings.azimuth, this.cameraSettings.elevation);
1958
2303
  this.updateViewportFrame();
1959
2304
  this.camera.aspect = window.innerWidth / window.innerHeight;
1960
2305
  this.camera.updateProjectionMatrix();
1961
- const fitDistance = this.getSpatialElementCameraFitDistance(bounds, orbitDirection);
1962
- const maxDistance = Math.max(fitDistance, radius * 0.6);
2306
+ const fit = detailCameraFit(bounds, this.camera, this.cameraSettings, { width: window.innerWidth, height: window.innerHeight }, { width: this.viewportLayoutSize.x, height: this.viewportLayoutSize.y });
2307
+ const { radius, center, distance: maxDistance } = fit;
2308
+ this.modelRadius = radius;
1963
2309
  this.rememberFittedViewportMetrics();
1964
- this.camera.position.copy(sphere.center).addScaledVector(orbitDirection, maxDistance);
1965
- this.camera.near = Math.max(maxDistance / 100, 0.01);
1966
- this.camera.far = Math.max(maxDistance * 100, radius * 20);
2310
+ this.camera.position.copy(center).addScaledVector(fit.direction, maxDistance);
2311
+ this.camera.near = fit.near;
2312
+ this.camera.far = fit.far;
1967
2313
  this.camera.updateProjectionMatrix();
1968
2314
  const focusRange = getZoomFocusDistanceRange(maxDistance, radius);
1969
2315
  this.interaction.setFocusRange(focusRange.restDistance, focusRange.closeDistance);
1970
- this.controls?.target.copy(sphere.center);
2316
+ this.controls?.target.copy(center);
1971
2317
  if (this.controls) {
1972
2318
  this.controls.minDistance = this.focusCloseDistance * 0.64;
1973
2319
  this.controls.maxDistance = maxDistance;
@@ -2175,7 +2521,9 @@ export class StageExperience {
2175
2521
  if (!target.nativeContent || target.getVisible?.() === false)
2176
2522
  return;
2177
2523
  target.updateNativeLayout?.();
2178
- this.syncPanelLayout(target, index, true);
2524
+ // Only an actively positioned native popover needs a fresh DOM measurement.
2525
+ // Pane summaries use the same resize/scroll-invalidated cache as other panels.
2526
+ this.syncPanelLayout(target, index, Boolean(target.updateNativeLayout));
2179
2527
  const runtime = this.panelRuntimes[index];
2180
2528
  if (runtime)
2181
2529
  runtime.group.visible = this.isPanelTargetVisible(index);
@@ -2230,6 +2578,8 @@ export class StageExperience {
2230
2578
  const target = this.panelTargets[index];
2231
2579
  if (!target)
2232
2580
  return true;
2581
+ if (!this.detailMediaActive && target.frame.closest('[data-spatial-model-controls]'))
2582
+ return false;
2233
2583
  if (target.getVisible?.() === false)
2234
2584
  return false;
2235
2585
  if (this.fullscreen)
@@ -2240,9 +2590,10 @@ export class StageExperience {
2240
2590
  return true;
2241
2591
  return isViewportRectVisible(this.resolveStageRect(cachedRect), window.innerWidth, window.innerHeight, VIEWPORT_CULL_MARGIN);
2242
2592
  }
2243
- resizeRenderer() {
2593
+ resizeRenderer(invalidate = true) {
2244
2594
  const width = window.innerWidth;
2245
2595
  const height = window.innerHeight;
2596
+ this.rendererSize.set(width, height);
2246
2597
  this.panelMeasurementsDirty = true;
2247
2598
  this.viewportMeasurementDirty = true;
2248
2599
  this.pipeline.resizeRenderTargets();
@@ -2263,7 +2614,8 @@ export class StageExperience {
2263
2614
  this.nativePanelLayer.style.height = `${height}px`;
2264
2615
  this.layoutDirty = true;
2265
2616
  this.syncPanelLayouts(true);
2266
- this.requestRender();
2617
+ if (invalidate)
2618
+ this.requestRender();
2267
2619
  }
2268
2620
  /**
2269
2621
  * Forces WebGPU to allocate and bind both quality levels before input starts.
@@ -2302,19 +2654,8 @@ export class StageExperience {
2302
2654
  const frameHeight = Math.max(bottom - top, 1);
2303
2655
  this.viewportFrame.set(left, top, frameWidth, frameHeight);
2304
2656
  }
2305
- getViewportScale() {
2306
- const width = Math.max(window.innerWidth, 1);
2307
- const height = Math.max(window.innerHeight, 1);
2308
- const maximumPadding = Math.max(Math.min(this.viewportLayoutSize.x, this.viewportLayoutSize.y) * 0.5 - 1, 0);
2309
- const padding = THREE.MathUtils.clamp(this.cameraSettings.fitPadding ?? 0, 0, maximumPadding);
2310
- return {
2311
- x: THREE.MathUtils.clamp((this.viewportLayoutSize.x - padding * 2) / width, 0.08, 1),
2312
- y: THREE.MathUtils.clamp((this.viewportLayoutSize.y - padding * 2) / height, 0.08, 1)
2313
- };
2314
- }
2315
2657
  getSpatialElementCameraFitDistance(bounds, viewDirection) {
2316
- const fitScale = THREE.MathUtils.clamp(this.cameraSettings.fitScale ?? 1, 0.2, 4);
2317
- return (getCameraFitDistance(bounds, viewDirection, this.camera, SPATIAL_ELEMENT_CAMERA_FIT_MARGIN, this.getViewportScale()) / fitScale);
2658
+ return detailCameraFitDistance(bounds, viewDirection, this.camera, this.cameraSettings, { width: window.innerWidth, height: window.innerHeight }, { width: this.viewportLayoutSize.x, height: this.viewportLayoutSize.y });
2318
2659
  }
2319
2660
  rememberFittedViewportMetrics() {
2320
2661
  this.fittedViewportMetrics.set(window.innerWidth, window.innerHeight, this.viewportLayoutSize.x, this.viewportLayoutSize.y);
@@ -2395,6 +2736,7 @@ export class StageExperience {
2395
2736
  handleScrollFrame(frame) {
2396
2737
  if (this.disposed)
2397
2738
  return;
2739
+ pauseDeviceOrientationForScroll();
2398
2740
  this.currentScrollX = frame.scrollX;
2399
2741
  this.currentScrollY = frame.scrollY;
2400
2742
  if (this.renderRequestId)
@@ -2477,8 +2819,20 @@ export class StageExperience {
2477
2819
  return this.panels.renderFlatPanelSurfaces();
2478
2820
  }
2479
2821
  renderFrame(force = false) {
2822
+ if (this.disposed)
2823
+ return;
2824
+ if (!force && this.stagedAwaitingFirstFrame)
2825
+ return;
2826
+ if (!this.disposed && (this.rendererSize.x !== window.innerWidth || this.rendererSize.y !== window.innerHeight))
2827
+ this.resizeRenderer(false);
2480
2828
  const renderTargets = this.pipeline.activeRenderTargets;
2481
2829
  const listOnly = this.catalog && !this.viewportTarget;
2830
+ if (this.deviceOrientationEnabled && this.detailMediaActive && !listOnly && this.model && !this.releaseDeviceOrientation)
2831
+ this.releaseDeviceOrientation = retainListDeviceOrientation(this.container, () => { });
2832
+ else if ((listOnly || !this.detailMediaActive) && this.releaseDeviceOrientation) {
2833
+ this.releaseDeviceOrientation();
2834
+ this.releaseDeviceOrientation = undefined;
2835
+ }
2482
2836
  if (this.disposed || (!listOnly && (!renderTargets || !this.pipeline.stageDisplayQuad)))
2483
2837
  return;
2484
2838
  if (!force && document.hidden)
@@ -2507,6 +2861,7 @@ export class StageExperience {
2507
2861
  const domAnimating = this.updatePanelDomRenderModes();
2508
2862
  this.renderPanelContents();
2509
2863
  this.pipeline.renderFrame(true, false);
2864
+ this.scheduleStagedPreparation();
2510
2865
  this.animationActive = this.catalogLayerAnimating || panelsAnimating || domAnimating;
2511
2866
  if (!force && (this.animationActive || this.renderInvalidated))
2512
2867
  this.scheduleRender();
@@ -2515,9 +2870,15 @@ export class StageExperience {
2515
2870
  if (!renderTargets)
2516
2871
  return;
2517
2872
  const { controls: controlsAnimating, wheel: wheelZoomAnimating } = this.interaction.advance(now, delta);
2873
+ let deviceAnimating = false;
2874
+ if (this.deviceOrientationEnabled && this.detailMediaActive && this.model?.parent === this.scene && !this.catalogHandoff && !this.spatialCapture) {
2875
+ if (!isDeviceOrientationPaused())
2876
+ deviceAnimating = this.deviceMotion.update(getListDeviceYaw(), getListDevicePitch(), getListDeviceRoll(), delta);
2877
+ this.deviceMotion.apply(this.model, this.camera, this.initialControlsTarget);
2878
+ }
2518
2879
  // The damped camera distance is the single animation clock for geometry and
2519
2880
  // every close-up UI phase. Phase remapping remains, temporal lag does not.
2520
- this.panelFocus = this.getZoomFocusFactor();
2881
+ this.panelFocus = this.detailMediaActive ? this.getZoomFocusFactor() : 0;
2521
2882
  this.panelUiFocus = this.fullscreen ? 1 : getStageUiFocus(this.panelFocus);
2522
2883
  this.minimapFocus = this.fullscreen ? 1 : getSequencedMinimapFocus(this.panelFocus, this.panelUiFocus);
2523
2884
  this.updateStageCameraProjection();
@@ -2532,10 +2893,12 @@ export class StageExperience {
2532
2893
  const panelDomModeAnimating = this.updatePanelDomRenderModes();
2533
2894
  this.renderPanelContents();
2534
2895
  this.pipeline.renderFrame(false, !this.scrollActive && !this.catalogHandoff);
2896
+ this.scheduleStagedPreparation();
2535
2897
  this.animationActive =
2536
- this.presentation.readiness.animating ||
2898
+ deviceAnimating ||
2899
+ (this.detailMediaActive && this.presentation.readiness.animating) ||
2537
2900
  this.catalogLayerAnimating ||
2538
- (this.stageViewportVisible &&
2901
+ (this.detailMediaActive && this.stageViewportVisible &&
2539
2902
  (!this.catalogHandoff || this.catalogMotionComplete) &&
2540
2903
  Boolean(this.refinement)) ||
2541
2904
  this.spaceMouseMoving ||
@@ -2552,13 +2915,14 @@ export class StageExperience {
2552
2915
  /** Draws only spatial UI into the transparent canvas above the page DOM. */
2553
2916
  /** Renders every glass surface below the DOM while preserving minimap screen projection. */
2554
2917
  renderStage() {
2555
- if (this.stageViewportVisible &&
2918
+ if (this.detailMediaActive && this.stageViewportVisible &&
2556
2919
  (!this.catalogHandoff || this.catalogMotionComplete) &&
2557
2920
  this.pageModelReady &&
2558
2921
  this.presentation.renderRefinement(this.renderer, this.scene, this.pagePreparation?.environment.value?.target.texture, () => this.pipeline.renderStageContents(), (model, outline) => {
2559
2922
  this.collectModelPickTargets(model);
2560
2923
  this.pipeline.createModelOutline(outline);
2561
- }, window.matchMedia('(prefers-reduced-motion: reduce)').matches))
2924
+ }, window.matchMedia('(prefers-reduced-motion: reduce)').matches, { backgroundReveal: this.catalogBackgroundReveal.value,
2925
+ advanceClock: !(this.stagedRevealPreparing && this.stagedRevealPreparing === this.stagedSceneCacheOwner) }))
2562
2926
  return;
2563
2927
  this.pipeline.renderStageContents();
2564
2928
  }