@spatial-elements/core 1.0.0-beta.7 → 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 (235) hide show
  1. package/dist/catalog/CarouselDeviceCamera.d.ts +8 -0
  2. package/dist/catalog/CarouselDeviceCamera.d.ts.map +1 -1
  3. package/dist/catalog/CarouselDeviceCamera.js +15 -1
  4. package/dist/catalog/CarouselDeviceCamera.js.map +1 -1
  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 +129 -3
  29. package/dist/catalog/CatalogSpatialElementLayer.d.ts.map +1 -1
  30. package/dist/catalog/CatalogSpatialElementLayer.js +408 -33
  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 +91 -22
  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/listDeviceOrientation.d.ts +2 -0
  94. package/dist/catalog/listDeviceOrientation.d.ts.map +1 -1
  95. package/dist/catalog/listDeviceOrientation.js +18 -1
  96. package/dist/catalog/listDeviceOrientation.js.map +1 -1
  97. package/dist/catalog/stagedDetailGeometry.d.ts +37 -0
  98. package/dist/catalog/stagedDetailGeometry.d.ts.map +1 -0
  99. package/dist/catalog/stagedDetailGeometry.js +55 -0
  100. package/dist/catalog/stagedDetailGeometry.js.map +1 -0
  101. package/dist/catalog/stagedDockGeometry.d.ts +66 -0
  102. package/dist/catalog/stagedDockGeometry.d.ts.map +1 -0
  103. package/dist/catalog/stagedDockGeometry.js +66 -0
  104. package/dist/catalog/stagedDockGeometry.js.map +1 -0
  105. package/dist/index.d.ts +2 -1
  106. package/dist/index.d.ts.map +1 -1
  107. package/dist/index.js +2 -1
  108. package/dist/index.js.map +1 -1
  109. package/dist/spatial-element/ResponsiveViewportMetrics.d.ts +18 -0
  110. package/dist/spatial-element/ResponsiveViewportMetrics.d.ts.map +1 -0
  111. package/dist/spatial-element/ResponsiveViewportMetrics.js +68 -0
  112. package/dist/spatial-element/ResponsiveViewportMetrics.js.map +1 -0
  113. package/dist/spatial-element/SectionSurfaceRegistry.d.ts +24 -0
  114. package/dist/spatial-element/SectionSurfaceRegistry.d.ts.map +1 -0
  115. package/dist/spatial-element/SectionSurfaceRegistry.js +48 -0
  116. package/dist/spatial-element/SectionSurfaceRegistry.js.map +1 -0
  117. package/dist/spatial-element/SpatialElementDockController.d.ts +19 -9
  118. package/dist/spatial-element/SpatialElementDockController.d.ts.map +1 -1
  119. package/dist/spatial-element/SpatialElementDockController.js +189 -93
  120. package/dist/spatial-element/SpatialElementDockController.js.map +1 -1
  121. package/dist/spatial-element/SpatialElementPaneController.d.ts +67 -0
  122. package/dist/spatial-element/SpatialElementPaneController.d.ts.map +1 -0
  123. package/dist/spatial-element/SpatialElementPaneController.js +245 -0
  124. package/dist/spatial-element/SpatialElementPaneController.js.map +1 -0
  125. package/dist/spatial-element/activeDetailSection.d.ts +8 -0
  126. package/dist/spatial-element/activeDetailSection.d.ts.map +1 -0
  127. package/dist/spatial-element/activeDetailSection.js +19 -0
  128. package/dist/spatial-element/activeDetailSection.js.map +1 -0
  129. package/dist/spatial-element/layoutTokens.json +53 -0
  130. package/dist/spatial-element/responsiveLayout.d.ts +1389 -0
  131. package/dist/spatial-element/responsiveLayout.d.ts.map +1 -0
  132. package/dist/spatial-element/responsiveLayout.js +265 -0
  133. package/dist/spatial-element/responsiveLayout.js.map +1 -0
  134. package/dist/spatial-element/sectionBackground.d.ts +29 -0
  135. package/dist/spatial-element/sectionBackground.d.ts.map +1 -0
  136. package/dist/spatial-element/sectionBackground.js +66 -0
  137. package/dist/spatial-element/sectionBackground.js.map +1 -0
  138. package/dist/spatial-element/spatialElement.d.ts +1 -0
  139. package/dist/spatial-element/spatialElement.d.ts.map +1 -1
  140. package/dist/spatial-element/spatialElement.js +1 -0
  141. package/dist/spatial-element/spatialElement.js.map +1 -1
  142. package/dist/spatial-element/spatialElementDock.d.ts +15 -0
  143. package/dist/spatial-element/spatialElementDock.d.ts.map +1 -1
  144. package/dist/spatial-element/spatialElementDock.js +22 -0
  145. package/dist/spatial-element/spatialElementDock.js.map +1 -1
  146. package/dist/spatial-element/spatialElementMedia.d.ts +16 -0
  147. package/dist/spatial-element/spatialElementMedia.d.ts.map +1 -0
  148. package/dist/spatial-element/spatialElementMedia.js +29 -0
  149. package/dist/spatial-element/spatialElementMedia.js.map +1 -0
  150. package/dist/spatial-element/spatialTheme.d.ts +12 -1
  151. package/dist/spatial-element/spatialTheme.d.ts.map +1 -1
  152. package/dist/spatial-element/spatialTheme.js +30 -1
  153. package/dist/spatial-element/spatialTheme.js.map +1 -1
  154. package/dist/spatial-element/types.d.ts +50 -2
  155. package/dist/spatial-element/types.d.ts.map +1 -1
  156. package/dist/spatial-element/types.js.map +1 -1
  157. package/dist/stage/BackgroundLayerOutput.d.ts +76 -0
  158. package/dist/stage/BackgroundLayerOutput.d.ts.map +1 -0
  159. package/dist/stage/BackgroundLayerOutput.js +333 -0
  160. package/dist/stage/BackgroundLayerOutput.js.map +1 -0
  161. package/dist/stage/LiquidGlassPanel.d.ts +3 -0
  162. package/dist/stage/LiquidGlassPanel.d.ts.map +1 -1
  163. package/dist/stage/LiquidGlassPanel.js +27 -2
  164. package/dist/stage/LiquidGlassPanel.js.map +1 -1
  165. package/dist/stage/MinimapController.d.ts.map +1 -1
  166. package/dist/stage/MinimapController.js +28 -47
  167. package/dist/stage/MinimapController.js.map +1 -1
  168. package/dist/stage/PageBindingController.d.ts +4 -0
  169. package/dist/stage/PageBindingController.d.ts.map +1 -1
  170. package/dist/stage/PageBindingController.js +12 -4
  171. package/dist/stage/PageBindingController.js.map +1 -1
  172. package/dist/stage/PanelPresentationController.d.ts +17 -0
  173. package/dist/stage/PanelPresentationController.d.ts.map +1 -1
  174. package/dist/stage/PanelPresentationController.js +69 -13
  175. package/dist/stage/PanelPresentationController.js.map +1 -1
  176. package/dist/stage/SpatialElementInteractionController.d.ts +7 -0
  177. package/dist/stage/SpatialElementInteractionController.d.ts.map +1 -1
  178. package/dist/stage/SpatialElementInteractionController.js +9 -0
  179. package/dist/stage/SpatialElementInteractionController.js.map +1 -1
  180. package/dist/stage/SpatialElementPresentationController.d.ts +14 -2
  181. package/dist/stage/SpatialElementPresentationController.d.ts.map +1 -1
  182. package/dist/stage/SpatialElementPresentationController.js +47 -2
  183. package/dist/stage/SpatialElementPresentationController.js.map +1 -1
  184. package/dist/stage/SpatialElementRefinement.d.ts +34 -1
  185. package/dist/stage/SpatialElementRefinement.d.ts.map +1 -1
  186. package/dist/stage/SpatialElementRefinement.js +175 -37
  187. package/dist/stage/SpatialElementRefinement.js.map +1 -1
  188. package/dist/stage/StageExperience.d.ts +167 -5
  189. package/dist/stage/StageExperience.d.ts.map +1 -1
  190. package/dist/stage/StageExperience.js +384 -58
  191. package/dist/stage/StageExperience.js.map +1 -1
  192. package/dist/stage/StageRenderPipeline.d.ts +76 -1
  193. package/dist/stage/StageRenderPipeline.d.ts.map +1 -1
  194. package/dist/stage/StageRenderPipeline.js +421 -46
  195. package/dist/stage/StageRenderPipeline.js.map +1 -1
  196. package/dist/stage/VirtualScrollController.d.ts +7 -0
  197. package/dist/stage/VirtualScrollController.d.ts.map +1 -1
  198. package/dist/stage/VirtualScrollController.js +57 -4
  199. package/dist/stage/VirtualScrollController.js.map +1 -1
  200. package/dist/stage/minimap/MinimapModel.d.ts +2 -1
  201. package/dist/stage/minimap/MinimapModel.d.ts.map +1 -1
  202. package/dist/stage/minimap/MinimapModel.js +34 -4
  203. package/dist/stage/minimap/MinimapModel.js.map +1 -1
  204. package/dist/stage/minimap/MinimapModelGeometry.d.ts +21 -0
  205. package/dist/stage/minimap/MinimapModelGeometry.d.ts.map +1 -0
  206. package/dist/stage/minimap/MinimapModelGeometry.js +68 -0
  207. package/dist/stage/minimap/MinimapModelGeometry.js.map +1 -0
  208. package/dist/stage/minimap/MinimapState.d.ts +3 -8
  209. package/dist/stage/minimap/MinimapState.d.ts.map +1 -1
  210. package/dist/stage/minimap/MinimapState.js.map +1 -1
  211. package/dist/stage/panelContext.d.ts +7 -0
  212. package/dist/stage/panelContext.d.ts.map +1 -1
  213. package/dist/stage/panelContext.js.map +1 -1
  214. package/dist/stage/rendererState.d.ts +2 -0
  215. package/dist/stage/rendererState.d.ts.map +1 -1
  216. package/dist/stage/rendererState.js +13 -0
  217. package/dist/stage/rendererState.js.map +1 -1
  218. package/dist/stage/sceneEndpointEligibility.d.ts +20 -0
  219. package/dist/stage/sceneEndpointEligibility.d.ts.map +1 -0
  220. package/dist/stage/sceneEndpointEligibility.js +363 -0
  221. package/dist/stage/sceneEndpointEligibility.js.map +1 -0
  222. package/dist/stage/stageDom.d.ts.map +1 -1
  223. package/dist/stage/stageDom.js +6 -1
  224. package/dist/stage/stageDom.js.map +1 -1
  225. package/dist/stage/stageMath.d.ts +3 -3
  226. package/dist/stage/stageMath.d.ts.map +1 -1
  227. package/dist/stage/stageMath.js +11 -10
  228. package/dist/stage/stageMath.js.map +1 -1
  229. package/dist/stage/stageTypes.d.ts +7 -1
  230. package/dist/stage/stageTypes.d.ts.map +1 -1
  231. package/dist/stage/stageTypes.js.map +1 -1
  232. package/dist/stage/stageVisualTest.d.ts +19 -0
  233. package/dist/stage/stageVisualTest.d.ts.map +1 -1
  234. package/dist/stage/stageVisualTest.js.map +1 -1
  235. package/package.json +1 -1
@@ -1,6 +1,6 @@
1
1
  import { describeRenderTargets } from './renderTargetInventory.js';
2
2
  import { DeviceGeometryMotion } from './DeviceGeometryMotion.js';
3
- import { isDeviceOrientationPaused, getListDeviceYaw, getListDevicePitch, getListDeviceRoll, retainListDeviceOrientation, subscribeListDeviceYaw, pauseDeviceOrientationForScroll } from '../catalog/listDeviceOrientation.js';
3
+ import { isDeviceOrientationPaused, getListDeviceYaw, getListDevicePitch, getListDeviceRoll, retainListDeviceOrientation, subscribeListDeviceYaw, pauseDeviceOrientationForScroll, holdDeviceOrientationForTransition } from '../catalog/listDeviceOrientation.js';
4
4
  import { StageRenderPipeline } from './StageRenderPipeline.js';
5
5
  import { PanelPresentationController } from './PanelPresentationController.js';
6
6
  import { MinimapController } from './MinimapController.js';
@@ -23,15 +23,17 @@ import { CSS3DRenderer } from 'three/addons/renderers/CSS3DRenderer.js';
23
23
  import { uniform } from 'three/tsl';
24
24
  import { LiquidGlassPanel, resolveLiquidGlassPanelOptions } from './LiquidGlassPanel.js';
25
25
  import { STAGE_PANEL_LAYOUT_EVENT, STAGE_PANEL_VISUAL_EVENT } from './panelContext.js';
26
- 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';
27
27
  import { getStagePositionFromRect, isViewportRectVisible } from './stageDom.js';
28
28
  import { STAGE_SCROLL_PRIORITY, getStageVisualScrollPosition, hasPendingStageScrollFrame, subscribeStageScrollFrame } from './scrollFrame.js';
29
- 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';
30
30
  import {} from './SpaceMouseAdapter.js';
31
31
  import { disposeMinimapModelMaterials } from './minimap/MinimapModel.js';
32
32
  import {} from './minimap/MinimapProjection.js';
33
33
  import { disposeMaterialOnly, getMeshBounds, getMeshMaterials, isMesh } from './stageSceneUtils.js';
34
34
  import { isOutlineMesh } from './interactionOutline.js';
35
+ import { resolveDetailLayout, resolveZoomLayout } from '../spatial-element/responsiveLayout.js';
36
+ import { detailCameraFit, detailCameraFitDistance } from '../catalog/stagedDetailGeometry.js';
35
37
  const SCROLL_SETTLE_DELAY = 120;
36
38
  const VIEWPORT_CULL_MARGIN = 96;
37
39
  /** Shared spatial state for both WebGPU glass and DOM-backed panel surfaces. */
@@ -107,7 +109,64 @@ export class StageExperience {
107
109
  catalogLayer;
108
110
  catalogHandoff = false;
109
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;
110
166
  catalogLayerAnimating = false;
167
+ stagedPreparationIdle = 0;
168
+ stagedPreparationFallback = false;
169
+ stagedPreparationAbort = new AbortController();
111
170
  catalogPresentation = { ...RESTING_CATALOG_PRESENTATION };
112
171
  pageModelReady = false;
113
172
  preparationGate = new PreparationGate();
@@ -270,6 +329,31 @@ export class StageExperience {
270
329
  panelMeasurementsDirty = true;
271
330
  viewportMeasurementDirty = true;
272
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
+ }
273
357
  fullscreen = false;
274
358
  setFullscreen(fullscreen) {
275
359
  if (this.fullscreen === fullscreen)
@@ -331,6 +415,8 @@ export class StageExperience {
331
415
  */
332
416
  constructor(container, options = {}) {
333
417
  this.container = container;
418
+ this.readLayoutMetrics = options.readLayoutMetrics;
419
+ this.detailMedia = options.detailMedia ?? 'minimap';
334
420
  if (options.dracoDecoderPath)
335
421
  this.assets.setDracoDecoderPath(options.dracoDecoderPath);
336
422
  this.deviceOrientationEnabled = options.deviceOrientation ?? false;
@@ -349,10 +435,11 @@ export class StageExperience {
349
435
  readGeometry: () => ({
350
436
  poseOwner: this.catalogHandoff || this.spatialCapture
351
437
  ? 'transition'
352
- : this.catalog && !this.viewportTarget
438
+ : !this.detailMediaActive || (this.catalog && !this.viewportTarget)
353
439
  ? 'none'
354
440
  : 'page',
355
- visible: this.stageViewportVisible,
441
+ visible: this.stageViewportVisible && this.detailMediaActive,
442
+ detail: this.readDetailInteractionLayout(),
356
443
  viewport: this.viewportFrame,
357
444
  bounds: this.modelBounds
358
445
  })
@@ -388,6 +475,10 @@ export class StageExperience {
388
475
  includeMesh: (mesh) => this.isSpatialElementMesh(mesh)
389
476
  });
390
477
  this.panels = new PanelPresentationController({
478
+ zoomLayout: () => {
479
+ const input = this.catalog ? this.readLayoutMetrics?.('visible') : undefined;
480
+ return input ? resolveZoomLayout(input) : undefined;
481
+ },
391
482
  camera: this.panelCamera,
392
483
  contentScene: this.panelContentScene,
393
484
  flatLayer: this.flatPanelLayer,
@@ -463,6 +554,7 @@ export class StageExperience {
463
554
  catalogHandoff: this.catalogHandoff,
464
555
  catalogMotionComplete: this.catalogMotionComplete,
465
556
  stageViewportVisible: this.stageViewportVisible,
557
+ detailMediaActive: this.detailMediaActive,
466
558
  modelHover: this.modelHover,
467
559
  modelInteractionActive: this.modelInteractionActive,
468
560
  catalog: this.catalog,
@@ -503,6 +595,7 @@ export class StageExperience {
503
595
  this.renderer.dispose();
504
596
  return;
505
597
  }
598
+ this.pipeline.initializeBackgroundOutput();
506
599
  this.backgroundCanvas.className = 'stage-webgpu-background';
507
600
  this.container.appendChild(this.backgroundCanvas);
508
601
  this.configureCssRenderer();
@@ -566,8 +659,17 @@ export class StageExperience {
566
659
  if (this.disposed)
567
660
  return;
568
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
+ }
569
669
  this.releaseDeviceOrientation?.();
570
670
  this.unsubscribeDeviceOrientation?.();
671
+ this.releaseStagedSensorHold?.();
672
+ this.releaseStagedSensorHold = undefined;
571
673
  this.releaseSpatialCapture();
572
674
  this.container.removeAttribute('data-stage-scroll-rendering');
573
675
  window.removeEventListener('resize', this.resize);
@@ -619,6 +721,10 @@ export class StageExperience {
619
721
  }
620
722
  /** Page DOM is a replaceable binding, not the owner of the device or element cache. */
621
723
  releasePage() {
724
+ cancelAnimationFrame(this.zoomPreparationFrame);
725
+ this.zoomPreparationFrame = 0;
726
+ this.deferredZoomPreparation = false;
727
+ this.deferredScrollWarmup = undefined;
622
728
  this.pageBinding.invalidate();
623
729
  this.pageModelReady = false;
624
730
  this.presentation.cancelRequests();
@@ -648,8 +754,12 @@ export class StageExperience {
648
754
  element);
649
755
  }
650
756
  capturePanelSurface(element) {
651
- if (element.closest('[data-carousel-spatial-element]'))
652
- 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
+ }
653
763
  if (element.hasAttribute('data-catalog-dock-surface')) {
654
764
  const header = element.closest('[data-spatial-element-sticky-header]');
655
765
  if (header)
@@ -762,11 +872,11 @@ export class StageExperience {
762
872
  if (!target)
763
873
  continue; // Navigation owns newly registered panels.
764
874
  const appearance = (panel) => JSON.stringify([
765
- panel.options, panel.minimap, panel.surface, panel.contentInset
875
+ panel.options, panel.minimap, panel.surface, panel.contentInset, panel.nativeContent
766
876
  ]);
767
877
  if (appearance(target) === appearance(next))
768
878
  continue;
769
- surfaceChanged ||= target.surface !== next.surface;
879
+ surfaceChanged ||= target.surface !== next.surface || target.nativeContent !== next.nativeContent;
770
880
  Object.assign(target, next);
771
881
  changed.push(index);
772
882
  }
@@ -775,7 +885,7 @@ export class StageExperience {
775
885
  .filter((target) => target.surface === 'glass' || target.minimap).map((target) => target.options);
776
886
  this.pipeline.syncPanelBlurCaptures();
777
887
  if (surfaceChanged) {
778
- // 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.
779
889
  this.minimapController.dispose();
780
890
  this.panels.release();
781
891
  this.createPanels();
@@ -855,11 +965,14 @@ export class StageExperience {
855
965
  this.createPanels();
856
966
  this.observePanelTargets();
857
967
  this.resizeRenderer();
858
- // New page targets must be GPU-ready before navigation or the first zoom.
859
- // Resting frosted panels do not otherwise submit their hidden backdrop blur.
860
- 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();
861
973
  this.renderFrame(true);
862
- await this.pipeline.prepareZoomEffects();
974
+ if (!this.deferredZoomPreparation)
975
+ await this.pipeline.prepareZoomEffects();
863
976
  if (this.disposed || !this.pageBinding.isCurrent(generation))
864
977
  return;
865
978
  // A submitted Low/panel frame is not yet GPU-ready. Drain the required binding work
@@ -879,7 +992,111 @@ export class StageExperience {
879
992
  : this.catalogPresentation.exitOpacity, this.catalogPresentation.active);
880
993
  return this.catalogLayer.setSpatialElements(brandId, items);
881
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
+ }
882
1093
  setCatalogTransitionPresentation(state) {
1094
+ if (!state.active) {
1095
+ this.stagedSceneCacheOwner = undefined;
1096
+ this.presentation.invalidateSceneEndpoints();
1097
+ }
1098
+ if (!state.active)
1099
+ this.scheduleZoomPreparation();
883
1100
  this.catalogPresentation = normalizeCatalogPresentation(state);
884
1101
  for (const entry of this.exitingMinimaps) {
885
1102
  this.setMinimapDisplayModelOpacity(entry.minimap, entry.opacity * state.exitOpacity);
@@ -904,6 +1121,58 @@ export class StageExperience {
904
1121
  this.backgroundCanvas.style.opacity = String(state.active ? state.exitOpacity : 0);
905
1122
  this.requestRender();
906
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
+ }
907
1176
  /** Reports actual applied GPU alpha for browser verification without layout or style reads. */
908
1177
  getCatalogPresentation() {
909
1178
  const triangles = (root) => {
@@ -935,6 +1204,7 @@ export class StageExperience {
935
1204
  backgroundPrepared: this.catalogBackgroundPrepared,
936
1205
  handoffPoint: this.getCatalogGeometryPoint(),
937
1206
  representations: {
1207
+ sceneEndpointCache: this.presentation.getSceneEndpointStats(),
938
1208
  retainedBlendTargets: this.returnBlend?.targetCount ?? 0,
939
1209
  state: this.refinementState,
940
1210
  hero: this.model ? (this.refinementState === 'high' ? 'high' : 'low') : null,
@@ -1075,7 +1345,7 @@ export class StageExperience {
1075
1345
  return this.spatialCapture?.getPoint() ?? this.catalogLayer?.getHandoffPoint() ?? null;
1076
1346
  }
1077
1347
  /** Lease the last submitted element frame before another page binding can release it. */
1078
- adoptCatalogPresentation(destination) {
1348
+ adoptCatalogPresentation(destination, restoreSourceOnCancel = false) {
1079
1349
  const { spatialElementId } = destination;
1080
1350
  const reverse = destination.kind === 'content';
1081
1351
  if (!this.spatialCapture) {
@@ -1115,7 +1385,10 @@ export class StageExperience {
1115
1385
  highPose?.removeFromParent();
1116
1386
  transferredHigh?.overrides.forEach(disposeMaterialOnly);
1117
1387
  high?.dispose();
1118
- moving.release();
1388
+ if (restoreSourceOnCancel && !this.disposed && this.pageBinding.token === generation)
1389
+ moving.restore();
1390
+ else
1391
+ moving.release();
1119
1392
  }
1120
1393
  });
1121
1394
  }
@@ -1208,17 +1481,21 @@ export class StageExperience {
1208
1481
  this.outgoingBackground = true;
1209
1482
  return true;
1210
1483
  }
1211
- getDockProjection() {
1484
+ getDockProjection(allowViewportClipping = false) {
1212
1485
  const candidates = [...this.minimaps.values()].filter((minimap) => minimap.viewportVisible);
1213
1486
  if (candidates.length !== 1)
1214
1487
  return;
1215
1488
  const minimap = candidates[0];
1216
1489
  const rect = this.getProjectedMinimapModelRect(minimap);
1217
- if (!rect ||
1218
- rect.x < 0 ||
1219
- rect.y < 0 ||
1220
- rect.x + rect.width > innerWidth ||
1221
- 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)
1222
1499
  return;
1223
1500
  return {
1224
1501
  ...captureSpatialElementProjection(minimap.spatialElementRoot, minimap.screenCamera),
@@ -1267,9 +1544,18 @@ export class StageExperience {
1267
1544
  }
1268
1545
  prepareCatalogDestination(dock) {
1269
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
+ }
1270
1556
  if (this.adoptedForward) {
1271
1557
  this.returnProjection = dock
1272
- ? this.getDockProjection()
1558
+ ? this.getDockProjection(true)
1273
1559
  : this.model
1274
1560
  ? {
1275
1561
  ...captureSpatialElementProjection(this.model, this.camera),
@@ -1278,7 +1564,7 @@ export class StageExperience {
1278
1564
  : undefined;
1279
1565
  return Boolean(this.returnProjection);
1280
1566
  }
1281
- return !dock || Boolean(this.getDockProjection());
1567
+ return !dock || Boolean(this.getDockProjection(true));
1282
1568
  }
1283
1569
  prepareReturnDestination() {
1284
1570
  if (!this.returnSpatialElement || !this.spatialCapture)
@@ -1412,14 +1698,31 @@ export class StageExperience {
1412
1698
  }
1413
1699
  /** Commit GPU and DOM motion in the same browser frame, not on consecutive RAFs. */
1414
1700
  flushCatalogFrame() {
1701
+ this.stagedAwaitingFirstFrame = false;
1415
1702
  cancelAnimationFrame(this.renderRequestId);
1416
1703
  this.renderRequestId = 0;
1417
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
+ }
1418
1714
  // After the transition's external clock stops, optional refinement resumes its own RAF.
1419
- if (!this.catalogPresentation.active && (this.animationActive || this.renderInvalidated))
1715
+ else if (this.animationActive || this.renderInvalidated)
1420
1716
  this.scheduleRender();
1421
1717
  }
1422
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();
1423
1726
  this.releaseSpatialCapture();
1424
1727
  this.adoptedForward = false;
1425
1728
  this.returnSpatialElement = undefined;
@@ -1582,6 +1885,14 @@ export class StageExperience {
1582
1885
  height: Math.max(...yCoordinates) - top
1583
1886
  };
1584
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
+ }
1585
1896
  /** Returns the main element's projected bounds for query-gated layout regressions. */
1586
1897
  getVisualTestModelRect() {
1587
1898
  if (!this.model || this.modelBounds.isEmpty())
@@ -1647,7 +1958,25 @@ export class StageExperience {
1647
1958
  }
1648
1959
  /** Returns Low-band and glass-compositor counters without scheduling rendering. */
1649
1960
  getCarouselStats() {
1650
- 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() };
1651
1980
  }
1652
1981
  /** Returns render-target lifecycle counters for query-gated performance tests. */
1653
1982
  getVisualTestRenderTargetStats() {
@@ -1679,6 +2008,8 @@ export class StageExperience {
1679
2008
  creations: this.pipeline.renderTargetSetCreations,
1680
2009
  resizes: this.pipeline.renderTargetSetResizes,
1681
2010
  warmups: this.pipeline.renderTargetSetWarmups,
2011
+ inactiveScrollWarmups: this.pipeline.deferredScrollWarmups,
2012
+ backgroundOutput: this.pipeline.getBackgroundOutputStats(),
1682
2013
  activeScale: this.pipeline.activeRenderTargets?.scale ?? 0
1683
2014
  };
1684
2015
  }
@@ -1741,7 +2072,7 @@ export class StageExperience {
1741
2072
  this.scheduleRender();
1742
2073
  }
1743
2074
  scheduleRender() {
1744
- if (this.disposed || document.hidden || this.renderRequestId)
2075
+ if (this.disposed || document.hidden || this.renderRequestId || this.stagedAwaitingFirstFrame)
1745
2076
  return;
1746
2077
  this.renderRequestId = requestAnimationFrame(this.render);
1747
2078
  }
@@ -1969,23 +2300,20 @@ export class StageExperience {
1969
2300
  if (this.referenceBounds)
1970
2301
  bounds.copy(this.referenceBounds);
1971
2302
  this.modelBounds.copy(bounds);
1972
- const sphere = bounds.getBoundingSphere(new THREE.Sphere());
1973
- const radius = Math.max(sphere.radius, 1);
1974
- this.modelRadius = radius;
1975
- const orbitDirection = getCameraOrbitDirection(this.cameraSettings.azimuth, this.cameraSettings.elevation);
1976
2303
  this.updateViewportFrame();
1977
2304
  this.camera.aspect = window.innerWidth / window.innerHeight;
1978
2305
  this.camera.updateProjectionMatrix();
1979
- const fitDistance = this.getSpatialElementCameraFitDistance(bounds, orbitDirection);
1980
- 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;
1981
2309
  this.rememberFittedViewportMetrics();
1982
- this.camera.position.copy(sphere.center).addScaledVector(orbitDirection, maxDistance);
1983
- this.camera.near = Math.max(maxDistance / 100, 0.01);
1984
- 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;
1985
2313
  this.camera.updateProjectionMatrix();
1986
2314
  const focusRange = getZoomFocusDistanceRange(maxDistance, radius);
1987
2315
  this.interaction.setFocusRange(focusRange.restDistance, focusRange.closeDistance);
1988
- this.controls?.target.copy(sphere.center);
2316
+ this.controls?.target.copy(center);
1989
2317
  if (this.controls) {
1990
2318
  this.controls.minDistance = this.focusCloseDistance * 0.64;
1991
2319
  this.controls.maxDistance = maxDistance;
@@ -2193,7 +2521,9 @@ export class StageExperience {
2193
2521
  if (!target.nativeContent || target.getVisible?.() === false)
2194
2522
  return;
2195
2523
  target.updateNativeLayout?.();
2196
- 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));
2197
2527
  const runtime = this.panelRuntimes[index];
2198
2528
  if (runtime)
2199
2529
  runtime.group.visible = this.isPanelTargetVisible(index);
@@ -2248,6 +2578,8 @@ export class StageExperience {
2248
2578
  const target = this.panelTargets[index];
2249
2579
  if (!target)
2250
2580
  return true;
2581
+ if (!this.detailMediaActive && target.frame.closest('[data-spatial-model-controls]'))
2582
+ return false;
2251
2583
  if (target.getVisible?.() === false)
2252
2584
  return false;
2253
2585
  if (this.fullscreen)
@@ -2322,19 +2654,8 @@ export class StageExperience {
2322
2654
  const frameHeight = Math.max(bottom - top, 1);
2323
2655
  this.viewportFrame.set(left, top, frameWidth, frameHeight);
2324
2656
  }
2325
- getViewportScale() {
2326
- const width = Math.max(window.innerWidth, 1);
2327
- const height = Math.max(window.innerHeight, 1);
2328
- const maximumPadding = Math.max(Math.min(this.viewportLayoutSize.x, this.viewportLayoutSize.y) * 0.5 - 1, 0);
2329
- const padding = THREE.MathUtils.clamp(this.cameraSettings.fitPadding ?? 0, 0, maximumPadding);
2330
- return {
2331
- x: THREE.MathUtils.clamp((this.viewportLayoutSize.x - padding * 2) / width, 0.08, 1),
2332
- y: THREE.MathUtils.clamp((this.viewportLayoutSize.y - padding * 2) / height, 0.08, 1)
2333
- };
2334
- }
2335
2657
  getSpatialElementCameraFitDistance(bounds, viewDirection) {
2336
- const fitScale = THREE.MathUtils.clamp(this.cameraSettings.fitScale ?? 1, 0.2, 4);
2337
- 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 });
2338
2659
  }
2339
2660
  rememberFittedViewportMetrics() {
2340
2661
  this.fittedViewportMetrics.set(window.innerWidth, window.innerHeight, this.viewportLayoutSize.x, this.viewportLayoutSize.y);
@@ -2500,13 +2821,15 @@ export class StageExperience {
2500
2821
  renderFrame(force = false) {
2501
2822
  if (this.disposed)
2502
2823
  return;
2824
+ if (!force && this.stagedAwaitingFirstFrame)
2825
+ return;
2503
2826
  if (!this.disposed && (this.rendererSize.x !== window.innerWidth || this.rendererSize.y !== window.innerHeight))
2504
2827
  this.resizeRenderer(false);
2505
2828
  const renderTargets = this.pipeline.activeRenderTargets;
2506
2829
  const listOnly = this.catalog && !this.viewportTarget;
2507
- if (this.deviceOrientationEnabled && !listOnly && this.model && !this.releaseDeviceOrientation)
2830
+ if (this.deviceOrientationEnabled && this.detailMediaActive && !listOnly && this.model && !this.releaseDeviceOrientation)
2508
2831
  this.releaseDeviceOrientation = retainListDeviceOrientation(this.container, () => { });
2509
- else if (listOnly && this.releaseDeviceOrientation) {
2832
+ else if ((listOnly || !this.detailMediaActive) && this.releaseDeviceOrientation) {
2510
2833
  this.releaseDeviceOrientation();
2511
2834
  this.releaseDeviceOrientation = undefined;
2512
2835
  }
@@ -2538,6 +2861,7 @@ export class StageExperience {
2538
2861
  const domAnimating = this.updatePanelDomRenderModes();
2539
2862
  this.renderPanelContents();
2540
2863
  this.pipeline.renderFrame(true, false);
2864
+ this.scheduleStagedPreparation();
2541
2865
  this.animationActive = this.catalogLayerAnimating || panelsAnimating || domAnimating;
2542
2866
  if (!force && (this.animationActive || this.renderInvalidated))
2543
2867
  this.scheduleRender();
@@ -2547,14 +2871,14 @@ export class StageExperience {
2547
2871
  return;
2548
2872
  const { controls: controlsAnimating, wheel: wheelZoomAnimating } = this.interaction.advance(now, delta);
2549
2873
  let deviceAnimating = false;
2550
- if (this.deviceOrientationEnabled && this.model?.parent === this.scene && !this.catalogHandoff && !this.spatialCapture) {
2874
+ if (this.deviceOrientationEnabled && this.detailMediaActive && this.model?.parent === this.scene && !this.catalogHandoff && !this.spatialCapture) {
2551
2875
  if (!isDeviceOrientationPaused())
2552
2876
  deviceAnimating = this.deviceMotion.update(getListDeviceYaw(), getListDevicePitch(), getListDeviceRoll(), delta);
2553
2877
  this.deviceMotion.apply(this.model, this.camera, this.initialControlsTarget);
2554
2878
  }
2555
2879
  // The damped camera distance is the single animation clock for geometry and
2556
2880
  // every close-up UI phase. Phase remapping remains, temporal lag does not.
2557
- this.panelFocus = this.getZoomFocusFactor();
2881
+ this.panelFocus = this.detailMediaActive ? this.getZoomFocusFactor() : 0;
2558
2882
  this.panelUiFocus = this.fullscreen ? 1 : getStageUiFocus(this.panelFocus);
2559
2883
  this.minimapFocus = this.fullscreen ? 1 : getSequencedMinimapFocus(this.panelFocus, this.panelUiFocus);
2560
2884
  this.updateStageCameraProjection();
@@ -2569,11 +2893,12 @@ export class StageExperience {
2569
2893
  const panelDomModeAnimating = this.updatePanelDomRenderModes();
2570
2894
  this.renderPanelContents();
2571
2895
  this.pipeline.renderFrame(false, !this.scrollActive && !this.catalogHandoff);
2896
+ this.scheduleStagedPreparation();
2572
2897
  this.animationActive =
2573
2898
  deviceAnimating ||
2574
- this.presentation.readiness.animating ||
2899
+ (this.detailMediaActive && this.presentation.readiness.animating) ||
2575
2900
  this.catalogLayerAnimating ||
2576
- (this.stageViewportVisible &&
2901
+ (this.detailMediaActive && this.stageViewportVisible &&
2577
2902
  (!this.catalogHandoff || this.catalogMotionComplete) &&
2578
2903
  Boolean(this.refinement)) ||
2579
2904
  this.spaceMouseMoving ||
@@ -2590,13 +2915,14 @@ export class StageExperience {
2590
2915
  /** Draws only spatial UI into the transparent canvas above the page DOM. */
2591
2916
  /** Renders every glass surface below the DOM while preserving minimap screen projection. */
2592
2917
  renderStage() {
2593
- if (this.stageViewportVisible &&
2918
+ if (this.detailMediaActive && this.stageViewportVisible &&
2594
2919
  (!this.catalogHandoff || this.catalogMotionComplete) &&
2595
2920
  this.pageModelReady &&
2596
2921
  this.presentation.renderRefinement(this.renderer, this.scene, this.pagePreparation?.environment.value?.target.texture, () => this.pipeline.renderStageContents(), (model, outline) => {
2597
2922
  this.collectModelPickTargets(model);
2598
2923
  this.pipeline.createModelOutline(outline);
2599
- }, 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) }))
2600
2926
  return;
2601
2927
  this.pipeline.renderStageContents();
2602
2928
  }