@spatial-elements/core 1.0.0-beta.12 → 1.0.0-beta.14

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 (74) hide show
  1. package/dist/catalog/CarouselSectionSurfaces.d.ts.map +1 -1
  2. package/dist/catalog/CarouselSectionSurfaces.js +8 -2
  3. package/dist/catalog/CarouselSectionSurfaces.js.map +1 -1
  4. package/dist/catalog/CatalogSpatialElementLayer.d.ts.map +1 -1
  5. package/dist/catalog/CatalogSpatialElementLayer.js +12 -4
  6. package/dist/catalog/CatalogSpatialElementLayer.js.map +1 -1
  7. package/dist/catalog/SourceDomMotion.d.ts.map +1 -1
  8. package/dist/catalog/SourceDomMotion.js +2 -3
  9. package/dist/catalog/SourceDomMotion.js.map +1 -1
  10. package/dist/catalog/carouselRenderClip.d.ts +4 -0
  11. package/dist/catalog/carouselRenderClip.d.ts.map +1 -0
  12. package/dist/catalog/carouselRenderClip.js +15 -0
  13. package/dist/catalog/carouselRenderClip.js.map +1 -0
  14. package/dist/spatial-element/SpatialElementPaneController.d.ts +4 -4
  15. package/dist/spatial-element/SpatialElementPaneController.d.ts.map +1 -1
  16. package/dist/spatial-element/SpatialElementPaneController.js +49 -23
  17. package/dist/spatial-element/SpatialElementPaneController.js.map +1 -1
  18. package/dist/spatial-element/responsiveLayout.d.ts.map +1 -1
  19. package/dist/spatial-element/responsiveLayout.js +4 -2
  20. package/dist/spatial-element/responsiveLayout.js.map +1 -1
  21. package/dist/stage/DetailWheelGesture.d.ts +11 -0
  22. package/dist/stage/DetailWheelGesture.d.ts.map +1 -0
  23. package/dist/stage/DetailWheelGesture.js +19 -0
  24. package/dist/stage/DetailWheelGesture.js.map +1 -0
  25. package/dist/stage/HeldSceneCapture.d.ts +15 -0
  26. package/dist/stage/HeldSceneCapture.d.ts.map +1 -0
  27. package/dist/stage/HeldSceneCapture.js +48 -0
  28. package/dist/stage/HeldSceneCapture.js.map +1 -0
  29. package/dist/stage/LiquidGlassPanel.d.ts +2 -0
  30. package/dist/stage/LiquidGlassPanel.d.ts.map +1 -1
  31. package/dist/stage/LiquidGlassPanel.js +24 -17
  32. package/dist/stage/LiquidGlassPanel.js.map +1 -1
  33. package/dist/stage/PanelPresentationController.d.ts +5 -0
  34. package/dist/stage/PanelPresentationController.d.ts.map +1 -1
  35. package/dist/stage/PanelPresentationController.js +76 -30
  36. package/dist/stage/PanelPresentationController.js.map +1 -1
  37. package/dist/stage/SpaceMouseAdapter.js +8 -6
  38. package/dist/stage/SpaceMouseAdapter.js.map +1 -1
  39. package/dist/stage/SpatialElementInteractionController.d.ts +44 -1
  40. package/dist/stage/SpatialElementInteractionController.d.ts.map +1 -1
  41. package/dist/stage/SpatialElementInteractionController.js +378 -39
  42. package/dist/stage/SpatialElementInteractionController.js.map +1 -1
  43. package/dist/stage/SpatialElementPresentationController.js +4 -4
  44. package/dist/stage/SpatialElementPresentationController.js.map +1 -1
  45. package/dist/stage/StageExperience.d.ts +8 -0
  46. package/dist/stage/StageExperience.d.ts.map +1 -1
  47. package/dist/stage/StageExperience.js +39 -21
  48. package/dist/stage/StageExperience.js.map +1 -1
  49. package/dist/stage/StageRenderPipeline.d.ts +4 -0
  50. package/dist/stage/StageRenderPipeline.d.ts.map +1 -1
  51. package/dist/stage/StageRenderPipeline.js +30 -8
  52. package/dist/stage/StageRenderPipeline.js.map +1 -1
  53. package/dist/stage/browserPinch.d.ts +5 -0
  54. package/dist/stage/browserPinch.d.ts.map +1 -0
  55. package/dist/stage/browserPinch.js +29 -0
  56. package/dist/stage/browserPinch.js.map +1 -0
  57. package/dist/stage/cssProjection.d.ts +3 -1
  58. package/dist/stage/cssProjection.d.ts.map +1 -1
  59. package/dist/stage/cssProjection.js +8 -3
  60. package/dist/stage/cssProjection.js.map +1 -1
  61. package/dist/stage/panelContext.d.ts +2 -1
  62. package/dist/stage/panelContext.d.ts.map +1 -1
  63. package/dist/stage/panelContext.js.map +1 -1
  64. package/dist/stage/panelFocusMath.d.ts +2 -0
  65. package/dist/stage/panelFocusMath.d.ts.map +1 -1
  66. package/dist/stage/panelFocusMath.js +8 -0
  67. package/dist/stage/panelFocusMath.js.map +1 -1
  68. package/dist/stage/rendererState.d.ts.map +1 -1
  69. package/dist/stage/rendererState.js +24 -9
  70. package/dist/stage/rendererState.js.map +1 -1
  71. package/dist/stage/stageVisualTest.d.ts +1 -0
  72. package/dist/stage/stageVisualTest.d.ts.map +1 -1
  73. package/dist/stage/stageVisualTest.js.map +1 -1
  74. package/package.json +1 -1
@@ -3,18 +3,37 @@ import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
3
3
  import { recreateOrbitControlsForExternalNavigation } from './OrbitControlsInterop.js';
4
4
  import { WHEEL_ZOOM_DAMPING, ZOOM_RESET_DAMPING } from './stageConstants.js';
5
5
  import { isStageUiTarget } from './stageDom.js';
6
- import { getCameraZoomFocus, getCameraZoomReferenceDistance, getEffectiveCameraDistance, getWheelZoomTargetDistance, normalizeWheelZoomDelta, getViewResetDuration, getViewResetInterpolation } from './stageMath.js';
6
+ import { getCameraZoomFocus, getCameraZoomReferenceDistance, getEffectiveCameraDistance, getWheelZoomTargetDistance, normalizeWheelZoomDelta, getViewResetDuration, getViewResetInterpolation, getStageUiFocus } from './stageMath.js';
7
+ import { markStageScrollInput } from './scrollFrame.js';
7
8
  import { dampAndSnap } from './damping.js';
8
9
  import { getInteractionGuidance, MODEL_INPUT_EVENT } from './interactionGuidance.js';
9
10
  import { ModelPointerPreview } from './ModelPointerPreview.js';
10
11
  import { resolveDetailGestureOwner } from '../spatial-element/spatialElementMedia.js';
12
+ import { DetailWheelGesture, DETAIL_WHEEL_IDLE_MS } from './DetailWheelGesture.js';
13
+ import { getPanelFocusOpacity, getPanelFocusProgress, getPanelFocusFromProgress } from './panelFocusMath.js';
11
14
  /** Owns user navigation state; consumes the facade clock and never creates a RAF loop. */
12
15
  export class SpatialElementInteractionController {
13
16
  ports;
14
17
  disposed = false;
18
+ wheelGesture = new DetailWheelGesture();
19
+ lastWheelTime = -Infinity;
20
+ lastWheelCtrlKey = false;
21
+ cancelledWheelUntil = -Infinity;
22
+ cancelledWheelCtrlKey = false;
23
+ pinch;
24
+ zoomAnchor;
25
+ tap;
26
+ zoomScroll;
27
+ previousZoomFocus = 0;
15
28
  fullscreen = false;
29
+ _viewportCentering = 0;
30
+ _viewStartCentering = 0;
31
+ _viewEndCentering = 0;
32
+ get viewportCentering() { return this._viewportCentering; }
16
33
  setFullscreen(fullscreen) {
17
34
  this.fullscreen = fullscreen;
35
+ this.cancelledWheelUntil = -Infinity;
36
+ this.wheelGesture.reset();
18
37
  this.clearWheelZoom();
19
38
  this._viewResetActive = false;
20
39
  this.preview.clear();
@@ -65,6 +84,13 @@ export class SpatialElementInteractionController {
65
84
  });
66
85
  }
67
86
  releasePage() {
87
+ this.lastWheelTime = this.cancelledWheelUntil = -Infinity;
88
+ this._viewportCentering = 0;
89
+ this.tap = undefined;
90
+ this.wheelGesture.reset();
91
+ this.endPinch();
92
+ this.zoomScroll = undefined;
93
+ this.previousZoomFocus = 0;
68
94
  this.preview.forget();
69
95
  this._interactionPointers.clear();
70
96
  this._pointer.active = false;
@@ -112,6 +138,10 @@ export class SpatialElementInteractionController {
112
138
  _pointerNdc = new THREE.Vector2();
113
139
  _wheelZoomDirection = new THREE.Vector3();
114
140
  _wheelZoomForward = new THREE.Vector3();
141
+ zoomAnchorPlane = new THREE.Plane();
142
+ zoomAnchorNormal = new THREE.Vector3();
143
+ zoomAnchorIntersection = new THREE.Vector3();
144
+ zoomAnchorShift = new THREE.Vector3();
115
145
  _controlsChange = () => this.requestRender();
116
146
  _pointer = { x: 0, y: 0, active: false };
117
147
  _modelPickTargets = [];
@@ -127,6 +157,7 @@ export class SpatialElementInteractionController {
127
157
  spaceMouseGeneration = 0;
128
158
  spaceMouseAbort;
129
159
  _spaceMouseMoving = false;
160
+ spaceMouseRevealPending = false;
130
161
  _modelHover = false;
131
162
  _modelInteractionActive = false;
132
163
  _interactionPointers = new Map();
@@ -144,6 +175,7 @@ export class SpatialElementInteractionController {
144
175
  _zoomResetStartDistance;
145
176
  _zoomResetScrollDistance = 0;
146
177
  _wheelZoomTargetDistance;
178
+ _wheelZoomOut = false;
147
179
  _initialCameraPosition = new THREE.Vector3();
148
180
  _initialControlsTarget = new THREE.Vector3();
149
181
  _initialCameraFov = 45;
@@ -154,20 +186,70 @@ export class SpatialElementInteractionController {
154
186
  _viewResetStartFov = 45;
155
187
  _viewResetElapsed = 0;
156
188
  _viewResetDuration = 0;
189
+ _viewEndPosition = new THREE.Vector3();
190
+ _viewEndTarget = new THREE.Vector3();
191
+ _viewEndFov = 45;
157
192
  resetView() {
158
193
  if (!this._controls || !this._initialViewCaptured)
159
194
  return;
195
+ this._viewEndCentering = 0;
196
+ this._viewEndPosition.copy(this._initialCameraPosition);
197
+ this._viewEndTarget.copy(this._initialControlsTarget);
198
+ this._viewEndFov = this._initialCameraFov;
199
+ this.startViewAnimation();
200
+ }
201
+ startViewAnimation() {
202
+ if (!this._controls)
203
+ return;
160
204
  this.guidance.interact();
205
+ // A click supersedes the previous wheel burst, including hardware/trackpad
206
+ // inertia delivered after pointerup. A fresh burst still interrupts normally.
207
+ if (performance.now() - this.lastWheelTime < DETAIL_WHEEL_IDLE_MS) {
208
+ this.cancelledWheelUntil = this.lastWheelTime + DETAIL_WHEEL_IDLE_MS;
209
+ this.cancelledWheelCtrlKey = this.lastWheelCtrlKey;
210
+ }
211
+ this.wheelGesture.reset();
161
212
  this.clearWheelZoom();
162
213
  this.clearZoomReset();
163
214
  this._viewResetStartCameraPosition.copy(this.camera.position);
164
215
  this._viewResetStartControlsTarget.copy(this._controls.target);
165
216
  this._viewResetStartFov = this.camera.fov;
217
+ this._viewStartCentering = this._viewportCentering;
166
218
  this._viewResetElapsed = 0;
167
219
  this._viewResetDuration = getViewResetDuration(this.getZoomFocusFactor());
168
220
  this._viewResetActive = true;
169
221
  this.requestRender();
170
222
  }
223
+ /** A tap reaches the shared UI/minimap endpoint; another tap restores the fitted view. */
224
+ toggleEnlargedView() {
225
+ if (!this._controls || !this._initialViewCaptured)
226
+ return;
227
+ if (this.getEffectiveCameraDistance() < this._controls.maxDistance - 0.001) {
228
+ this.resetView();
229
+ return;
230
+ }
231
+ this.normalizeCameraFovForOrbitControls();
232
+ // The camera focus is eased; solve its clearance endpoint rather than
233
+ // zooming all the way to the minimum distance or starting a second UI clock.
234
+ if (!this.ports.readGeometry().detail?.split && window.scrollY > 0 && !this.zoomScroll) {
235
+ this.zoomScroll = { focus: this.getRevealFocus(), scrollY: window.scrollY,
236
+ uiProgress: getPanelFocusProgress(this.getUiFocus(this.getZoomFocusFactor())) };
237
+ }
238
+ let near = this._controls.minDistance, far = this._controls.maxDistance;
239
+ for (let i = 0; i < 32; i++) {
240
+ const distance = (near + far) / 2;
241
+ const focus = getCameraZoomFocus(distance, this._initialCameraFov, this._initialCameraFov, this._focusCloseDistance, this._focusRestDistance);
242
+ if (this.getUiFocus(focus, distance) >= 0.96)
243
+ near = distance;
244
+ else
245
+ far = distance;
246
+ }
247
+ this._viewEndTarget.copy(this._initialControlsTarget);
248
+ this._viewEndPosition.copy(this.camera.position).sub(this._controls.target).setLength(near).add(this._viewEndTarget);
249
+ this._viewEndFov = this._initialCameraFov;
250
+ this._viewEndCentering = 1;
251
+ this.startViewAnimation();
252
+ }
171
253
  createControls() {
172
254
  const controls = new OrbitControls(this.camera, this.backgroundCanvas);
173
255
  controls.enableDamping = true;
@@ -175,8 +257,8 @@ export class SpatialElementInteractionController {
175
257
  controls.zoomToCursor = true;
176
258
  controls.enabled = false;
177
259
  controls.addEventListener('change', this._controlsChange);
178
- // Gesture policy is stable before contact. Touch Events claim only gestures
179
- // that start on the model; empty canvas keeps native pan/pinch behavior.
260
+ // Single-finger background gestures retain native page scrolling. The shell
261
+ // blocks browser magnification; detail pinch gestures are routed below.
180
262
  this.backgroundCanvas.style.touchAction = 'manipulation';
181
263
  return controls;
182
264
  }
@@ -260,6 +342,7 @@ export class SpatialElementInteractionController {
260
342
  applySpaceMouseNavigationUpdate(update) {
261
343
  if (!this._controls || this.disposed || !this.canInteract)
262
344
  return;
345
+ const previousFocus = this.getZoomFocusFactor();
263
346
  if (update.viewMatrix || update.target || update.fov !== undefined)
264
347
  this.guidance.interact();
265
348
  this.clearWheelZoom();
@@ -291,6 +374,14 @@ export class SpatialElementInteractionController {
291
374
  this.constrainEffectiveZoom();
292
375
  this.camera.lookAt(this._controls.target);
293
376
  this.camera.updateMatrixWorld(true);
377
+ if (this.spaceMouseRevealPending && (update.viewMatrix || update.target || update.fov !== undefined)) {
378
+ this.spaceMouseRevealPending = false;
379
+ // Zoom reveals the document progressively. Rotation/pan still reveals an
380
+ // offscreen viewer immediately, as it does not change the zoom clock.
381
+ if (this.getZoomFocusFactor() <= previousFocus && !this.ports.readGeometry().detail?.split && window.scrollY > 0) {
382
+ window.scrollTo({ top: 0, behavior: window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ? 'instant' : 'smooth' });
383
+ }
384
+ }
294
385
  this.requestRender();
295
386
  }
296
387
  setSpaceMouseMoving(moving) {
@@ -303,12 +394,8 @@ export class SpatialElementInteractionController {
303
394
  if (moving)
304
395
  this.recreateOrbitControls();
305
396
  this._spaceMouseMoving = moving;
397
+ this.spaceMouseRevealPending = moving;
306
398
  if (moving) {
307
- // In the split (3XL) layout the geometry remains visible beside the text.
308
- // Otherwise reveal it without moving keyboard focus or resetting its pose.
309
- if (!this.ports.readGeometry().detail?.split && window.scrollY > 0) {
310
- window.scrollTo({ top: 0, behavior: window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ? 'instant' : 'smooth' });
311
- }
312
399
  this.clearWheelZoom();
313
400
  this.clearZoomReset();
314
401
  this._viewResetActive = false;
@@ -323,8 +410,15 @@ export class SpatialElementInteractionController {
323
410
  this._controls = recreateOrbitControlsForExternalNavigation(this._controls, () => this.createControls());
324
411
  }
325
412
  handlePointerMove(event) {
413
+ // A remaining finger resumes Orbit rotation. Do not keep pulling its old
414
+ // two-finger anchor back into place while that rotation is being applied.
415
+ if (event.pointerType === 'touch' && !this.pinch && this._interactionPointers.size === 1)
416
+ this.clearWheelZoom();
417
+ if (this.tap?.id === event.pointerId && Math.hypot(event.clientX - this.tap.x, event.clientY - this.tap.y) >= 6)
418
+ this.tap = undefined;
326
419
  const start = this._interactionPointers.get(event.pointerId);
327
420
  if (start && Math.hypot(event.clientX - start.x, event.clientY - start.y) >= 6) {
421
+ this.cancelledWheelUntil = -Infinity;
328
422
  this.guidance.interact();
329
423
  }
330
424
  if (event.pointerType !== 'mouse') {
@@ -350,6 +444,12 @@ export class SpatialElementInteractionController {
350
444
  }
351
445
  }
352
446
  handlePointerDown(event) {
447
+ this.tap = undefined;
448
+ if (!this.fullscreen && this.ports.readGeometry().detail?.media === 'minimap' &&
449
+ this._interactionPointers.size === 0 && (event.button === 0 || event.pointerType === 'touch') &&
450
+ this.hitTestModel(event.clientX, event.clientY, event.target, true)) {
451
+ this.tap = { id: event.pointerId, x: event.clientX, y: event.clientY, time: performance.now() };
452
+ }
353
453
  if (event.pointerType !== 'mouse')
354
454
  this.clearPointerHover();
355
455
  // Once a model gesture owns contact, a second finger may land outside its
@@ -371,6 +471,8 @@ export class SpatialElementInteractionController {
371
471
  this.requestRender();
372
472
  }
373
473
  handlePointerUp(event) {
474
+ const tap = this.tap;
475
+ this.tap = undefined;
374
476
  this._interactionPointers.delete(event.pointerId);
375
477
  this._modelInteractionActive = this._interactionPointers.size > 0;
376
478
  if (event.pointerType !== 'mouse')
@@ -380,16 +482,87 @@ export class SpatialElementInteractionController {
380
482
  this.hitTestModel(event.clientX, event.clientY, event.target));
381
483
  this.notifyModelInput();
382
484
  this.updateControlsAvailability();
485
+ // The down event already picked the geometry. A moving/damped camera can
486
+ // move that surface away before release; that does not cancel a stationary tap.
487
+ if (tap?.id === event.pointerId && event.type === 'pointerup' && performance.now() - tap.time < 500 &&
488
+ Math.hypot(event.clientX - tap.x, event.clientY - tap.y) < 6)
489
+ this.toggleEnlargedView();
383
490
  this.requestRender();
384
491
  }
385
492
  handleTouchStart(event) {
493
+ if (event.touches?.length >= 2 && !this.pinch) {
494
+ this.cancelledWheelUntil = -Infinity;
495
+ this.tap = undefined;
496
+ const a = event.touches[0], b = event.touches[1];
497
+ const x = (a.clientX + b.clientX) / 2, y = (a.clientY + b.clientY) / 2;
498
+ if (this.isPinchArea(x, y)) {
499
+ // Orbit keeps pointer bookkeeping for seamless one-finger rotation,
500
+ // but must not also dolly/pan using page coordinates that move on scroll.
501
+ this.pinch = { distance: Math.hypot(a.clientX - b.clientX, a.clientY - b.clientY),
502
+ zoom: this._controls.enableZoom, pan: this._controls.enablePan };
503
+ this._controls.enableZoom = this._controls.enablePan = false;
504
+ this.wheelGesture.reset();
505
+ this.clearWheelZoom();
506
+ // Match Orbit's screen-space pan plane through its target. Surface
507
+ // picking is reserved for mouse zoom, which has no moving touch anchor.
508
+ this.captureZoomAnchor(x, y, false);
509
+ event.preventDefault();
510
+ event.stopImmediatePropagation();
511
+ return;
512
+ }
513
+ }
386
514
  // touch-action cannot be changed after pointerdown to claim the current
387
- // gesture. Cancel this one start only when the exact geometry was hit.
388
- // No blocking touchmove handler is needed while native scrolling proceeds.
515
+ // gesture. Cancel this start when model navigation owns the contacts.
389
516
  if (this._modelInteractionActive && this._controls?.enabled && event.cancelable) {
390
517
  event.preventDefault();
391
518
  }
392
519
  }
520
+ handleTouchMove(event) {
521
+ if (!this.pinch || event.touches.length < 2 || !this.canInteract)
522
+ return;
523
+ const a = event.touches[0], b = event.touches[1];
524
+ const x = (a.clientX + b.clientX) / 2, y = (a.clientY + b.clientY) / 2;
525
+ const distance = Math.hypot(a.clientX - b.clientX, a.clientY - b.clientY);
526
+ event.preventDefault();
527
+ event.stopImmediatePropagation();
528
+ this.guidance.interact();
529
+ this.clearZoomReset();
530
+ this._viewResetActive = false;
531
+ if (!this.zoomAnchor)
532
+ this.captureZoomAnchor(x, y, false);
533
+ // Keep the same world point under the moving midpoint. Compensation runs
534
+ // after scroll/projection updates, so even pan without dolly stays stable.
535
+ if (this.pinch.pan)
536
+ this.zoomAnchor.client.set(x, y);
537
+ this.zoomAnchor.until = performance.now() + DETAIL_WHEEL_IDLE_MS;
538
+ if (this.pinch.zoom && distance !== this.pinch.distance) {
539
+ // Normalized wheel curve: doubling finger distance halves camera distance.
540
+ const delta = Math.log(Math.max(distance, 1) / Math.max(this.pinch.distance, 1)) * 100 / Math.log(0.95);
541
+ this.queueDolly(delta, x, y, true);
542
+ }
543
+ this.pinch.distance = distance;
544
+ this.requestRender();
545
+ }
546
+ handleTouchEnd(event) {
547
+ if (event.touches.length < 2)
548
+ this.endPinch();
549
+ }
550
+ endPinch() {
551
+ if (this.pinch && this._controls) {
552
+ this._controls.enableZoom = this.pinch.zoom;
553
+ this._controls.enablePan = this.pinch.pan;
554
+ }
555
+ this.pinch = undefined;
556
+ }
557
+ isPinchArea(x, y) {
558
+ if (!this.canInteract || !this._controls)
559
+ return false;
560
+ if (this.fullscreen)
561
+ return true;
562
+ const detail = this.ports.readGeometry().detail;
563
+ return Boolean(detail && detail.media === 'minimap' && (detail.paneHidden ||
564
+ (detail.split ? x < detail.paneLeft : y < (detail.contentTop ?? this.viewportFrame.y + this.viewportFrame.w))));
565
+ }
393
566
  handlePointerContact(event) {
394
567
  if (event.pointerType !== 'mouse')
395
568
  this.clearPointerHover();
@@ -403,10 +576,46 @@ export class SpatialElementInteractionController {
403
576
  this.requestRender();
404
577
  }
405
578
  handleWheel(event) {
406
- const hit = this.hitTestModel(event.clientX, event.clientY, event.target);
407
- this.setModelHover(hit);
579
+ if (!this._controls || !this.canInteract || event.deltaY === 0)
580
+ return;
581
+ const now = performance.now();
582
+ const detail = this.ports.readGeometry().detail;
583
+ let modelHit;
584
+ // Only swallow the cancelled spatial gesture. The separate 3XL content
585
+ // region and a changed pinch modifier represent independent new input.
586
+ if (now < this.cancelledWheelUntil && Boolean(event.ctrlKey) === this.cancelledWheelCtrlKey &&
587
+ (!detail?.split || (modelHit = this.hitTestModel(event.clientX, event.clientY, event.target)))) {
588
+ this.cancelledWheelUntil = now + DETAIL_WHEEL_IDLE_MS;
589
+ event.preventDefault();
590
+ event.stopImmediatePropagation();
591
+ return;
592
+ }
593
+ this.cancelledWheelUntil = -Infinity;
594
+ this.lastWheelTime = now;
595
+ this.lastWheelCtrlKey = Boolean(event.ctrlKey);
596
+ const pinch = event.ctrlKey && this.isPinchArea(event.clientX, event.clientY);
597
+ const model = pinch || (modelHit ?? this.hitTestModel(event.clientX, event.clientY, event.target));
598
+ this.setModelHover(model);
408
599
  this.updateControlsAvailability();
409
- if (!hit || !this._controls) {
600
+ const clearingUi = detail?.media === 'minimap' &&
601
+ getPanelFocusProgress(detail.uiFocus ?? this.getUiFocus(this.getZoomFocusFactor())) > 0;
602
+ // Once panels start clearing, wheel navigation also owns the empty stage.
603
+ // Keep visible HTML and the separate 3XL content region independently usable.
604
+ const hit = model || (clearingUi && !detail?.split && this.stageViewportVisible &&
605
+ event.target === this.backgroundCanvas && this.isPinchArea(event.clientX, event.clientY) &&
606
+ !this.isPointerOccludedByHtml(event.clientX, event.clientY));
607
+ const atOverview = !this.fullscreen && this.getEffectiveCameraDistance() >= this._controls.maxDistance - 0.001;
608
+ const separateArea = this.fullscreen || detail?.split;
609
+ if (separateArea)
610
+ this.wheelGesture.reset();
611
+ const owner = separateArea ? (hit ? 'zoom' : 'scroll') :
612
+ this.wheelGesture.resolve(performance.now(), hit, event.deltaY > 0, atOverview, pinch, clearingUi);
613
+ if (owner === 'scroll') {
614
+ if (!separateArea)
615
+ this._viewResetActive = false;
616
+ this.clearWheelZoom();
617
+ // Let the browser scroll, but never let OrbitControls consume this burst.
618
+ this._controls.enabled = false;
410
619
  this.requestRender();
411
620
  return;
412
621
  }
@@ -417,17 +626,36 @@ export class SpatialElementInteractionController {
417
626
  // advance from one shared damped camera distance instead.
418
627
  event.preventDefault();
419
628
  event.stopImmediatePropagation();
629
+ this.queueDolly(normalizeWheelZoomDelta(event.deltaY, event.deltaMode, event.ctrlKey), event.clientX, event.clientY);
630
+ }
631
+ queueDolly(deltaY, x, y, touch = false) {
632
+ if (!this._controls)
633
+ return;
420
634
  this.normalizeCameraFovForOrbitControls();
421
635
  this.clearZoomReset();
422
636
  this._viewResetActive = false;
423
- const deltaY = normalizeWheelZoomDelta(event.deltaY, event.deltaMode, event.ctrlKey);
424
637
  const currentDistance = this.camera.position.distanceTo(this._controls.target);
425
638
  const previousTargetDistance = this._wheelZoomTargetDistance ?? currentDistance;
426
639
  const targetDistance = getWheelZoomTargetDistance(previousTargetDistance, deltaY, this._controls.zoomSpeed, this._controls.minDistance, this._controls.maxDistance);
427
640
  this._wheelZoomTargetDistance =
428
641
  Math.abs(targetDistance - currentDistance) > 0.0001 ? targetDistance : undefined;
429
- const rect = this.backgroundCanvas.getBoundingClientRect();
430
- this._pointerNdc.set(((event.clientX - rect.left) / Math.max(rect.width, 1)) * 2 - 1, -((event.clientY - rect.top) / Math.max(rect.height, 1)) * 2 + 1);
642
+ // Mouse zoom-out returns to the fitted centre; a touch gesture keeps its
643
+ // freely movable anchor in either direction, including the damped tail.
644
+ this._wheelZoomOut = deltaY > 0 && !touch;
645
+ if (this._wheelZoomOut) {
646
+ // Outward dolly converges on the authored centre, regardless of cursor
647
+ // movement since zoom-in. Do not anchor it to another off-centre point.
648
+ this.zoomAnchor = undefined;
649
+ this.requestRender();
650
+ return;
651
+ }
652
+ // A different pointer position chooses a new world point. Moving the old
653
+ // point to a new screen position would pan the model along with the mouse.
654
+ if (!this.zoomAnchor || (!touch && (performance.now() >= this.zoomAnchor.until ||
655
+ Math.hypot(this.zoomAnchor.client.x - x, this.zoomAnchor.client.y - y) > 0.5)))
656
+ this.captureZoomAnchor(x, y, !touch);
657
+ this.zoomAnchor.until = performance.now() + DETAIL_WHEEL_IDLE_MS;
658
+ this.setPointerNdc(x, y);
431
659
  this._wheelZoomDirection
432
660
  .set(this._pointerNdc.x, this._pointerNdc.y, 1)
433
661
  .unproject(this.camera)
@@ -435,8 +663,51 @@ export class SpatialElementInteractionController {
435
663
  .normalize();
436
664
  this.requestRender();
437
665
  }
666
+ setPointerNdc(x, y) {
667
+ this._pointerNdc.set(x / Math.max(window.innerWidth, 1) * 2 - 1, 1 - y / Math.max(window.innerHeight, 1) * 2);
668
+ }
669
+ captureZoomAnchor(x, y, pickSurface = true) {
670
+ this.updateStageCameraProjection();
671
+ this.camera.updateMatrixWorld(true);
672
+ this.setPointerNdc(x, y);
673
+ this._raycaster.setFromCamera(this._pointerNdc, this.camera);
674
+ const point = new THREE.Vector3();
675
+ const hits = pickSurface ? this._raycaster.intersectObjects(this._modelPickTargets, false) : undefined;
676
+ const plane = this.zoomAnchorPlane.setFromNormalAndCoplanarPoint(this.camera.getWorldDirection(this.zoomAnchorNormal), this._controls.target);
677
+ if (hits?.length)
678
+ point.copy(hits[0].point);
679
+ else if (!this._raycaster.ray.intersectPlane(plane, point))
680
+ point.copy(this._controls.target);
681
+ this.zoomAnchor = { point, client: new THREE.Vector2(x, y), until: performance.now() + DETAIL_WHEEL_IDLE_MS };
682
+ }
683
+ /** Run after the scroll-dependent projection has changed, before rendering. */
684
+ compensateZoomAnchor() {
685
+ const anchor = this.zoomAnchor;
686
+ if (!anchor || !this._controls || !this.canInteract)
687
+ return;
688
+ if (!this.pinch && this._wheelZoomTargetDistance === undefined && performance.now() >= anchor.until) {
689
+ this.zoomAnchor = undefined;
690
+ return;
691
+ }
692
+ this.camera.updateMatrixWorld(true);
693
+ this.setPointerNdc(anchor.client.x, anchor.client.y);
694
+ this._raycaster.setFromCamera(this._pointerNdc, this.camera);
695
+ const plane = this.zoomAnchorPlane.setFromNormalAndCoplanarPoint(this.camera.getWorldDirection(this.zoomAnchorNormal), anchor.point);
696
+ const intersection = this._raycaster.ray.intersectPlane(plane, this.zoomAnchorIntersection);
697
+ if (!intersection)
698
+ return;
699
+ const shift = this.zoomAnchorShift.copy(anchor.point).sub(intersection);
700
+ this.camera.position.add(shift);
701
+ this._controls.target.add(shift);
702
+ this.camera.updateMatrixWorld(true);
703
+ if (!this.pinch && this._wheelZoomTargetDistance === undefined)
704
+ this.zoomAnchor = undefined;
705
+ }
438
706
  requestScrollZoomReset(scrollDelta) {
439
- if (!this._controls || this.fullscreen)
707
+ if (!this._controls || this.fullscreen || this._viewResetActive || this.ports.readGeometry().detail?.split)
708
+ return;
709
+ if (this.pinch || this._interactionPointers.size > 1 ||
710
+ (this._wheelZoomTargetDistance !== undefined && this.wheelGesture.zooming(performance.now())))
440
711
  return;
441
712
  this.clearWheelZoom();
442
713
  this._viewResetActive = false;
@@ -461,6 +732,7 @@ export class SpatialElementInteractionController {
461
732
  const currentDistance = this.camera.position.distanceTo(this._controls.target);
462
733
  const targetDistance = THREE.MathUtils.clamp(this._zoomResetTargetDistance, this._controls.minDistance, this._controls.maxDistance);
463
734
  const nextDistance = THREE.MathUtils.damp(currentDistance, targetDistance, ZOOM_RESET_DAMPING, delta);
735
+ this.restoreStageAlignment(currentDistance, nextDistance);
464
736
  this.setCameraDistance(nextDistance);
465
737
  this.camera.fov = THREE.MathUtils.damp(this.camera.fov, this._initialCameraFov, ZOOM_RESET_DAMPING, delta);
466
738
  this.camera.updateProjectionMatrix();
@@ -470,6 +742,7 @@ export class SpatialElementInteractionController {
470
742
  this.camera.fov = this._initialCameraFov;
471
743
  this.camera.updateProjectionMatrix();
472
744
  if (targetDistance >= this._controls.maxDistance - 0.001) {
745
+ this._viewportCentering = 0;
473
746
  this.clearZoomReset();
474
747
  }
475
748
  else {
@@ -481,20 +754,21 @@ export class SpatialElementInteractionController {
481
754
  applyViewReset(delta) {
482
755
  if (!this._controls || !this._viewResetActive || !this._initialViewCaptured)
483
756
  return;
484
- this._viewResetElapsed += Math.max(delta, 0);
757
+ this._viewResetElapsed += this.reducedMotion?.matches ? this._viewResetDuration : Math.max(delta, 0);
485
758
  const interpolation = getViewResetInterpolation(this._viewResetElapsed, this._viewResetDuration);
759
+ this._viewportCentering = THREE.MathUtils.lerp(this._viewStartCentering, this._viewEndCentering, interpolation);
486
760
  this.camera.position
487
761
  .copy(this._viewResetStartCameraPosition)
488
- .lerp(this._initialCameraPosition, interpolation);
762
+ .lerp(this._viewEndPosition, interpolation);
489
763
  this._controls.target
490
764
  .copy(this._viewResetStartControlsTarget)
491
- .lerp(this._initialControlsTarget, interpolation);
492
- this.camera.fov = THREE.MathUtils.lerp(this._viewResetStartFov, this._initialCameraFov, interpolation);
765
+ .lerp(this._viewEndTarget, interpolation);
766
+ this.camera.fov = THREE.MathUtils.lerp(this._viewResetStartFov, this._viewEndFov, interpolation);
493
767
  this.camera.updateProjectionMatrix();
494
768
  if (interpolation >= 1) {
495
- this.camera.position.copy(this._initialCameraPosition);
496
- this._controls.target.copy(this._initialControlsTarget);
497
- this.camera.fov = this._initialCameraFov;
769
+ this.camera.position.copy(this._viewEndPosition);
770
+ this._controls.target.copy(this._viewEndTarget);
771
+ this.camera.fov = this._viewEndFov;
498
772
  this.camera.updateProjectionMatrix();
499
773
  this._viewResetActive = false;
500
774
  }
@@ -508,6 +782,7 @@ export class SpatialElementInteractionController {
508
782
  }
509
783
  clearWheelZoom() {
510
784
  this._wheelZoomTargetDistance = undefined;
785
+ this.zoomAnchor = undefined;
511
786
  }
512
787
  applyWheelZoom(delta) {
513
788
  if (!this._controls || this._wheelZoomTargetDistance === undefined)
@@ -516,17 +791,32 @@ export class SpatialElementInteractionController {
516
791
  const targetDistance = THREE.MathUtils.clamp(this._wheelZoomTargetDistance, this._controls.minDistance, this._controls.maxDistance);
517
792
  const nextDistance = dampAndSnap(currentDistance, targetDistance, WHEEL_ZOOM_DAMPING, delta, 0.001);
518
793
  const radiusDelta = currentDistance - nextDistance;
519
- this.camera.position.addScaledVector(this._wheelZoomDirection, radiusDelta);
520
- this.camera.updateMatrixWorld(true);
521
- this.camera.getWorldDirection(this._wheelZoomForward);
522
- this._controls.target
523
- .copy(this.camera.position)
524
- .addScaledVector(this._wheelZoomForward, nextDistance);
794
+ if (this._wheelZoomOut) {
795
+ this.restoreStageAlignment(currentDistance, nextDistance);
796
+ const direction = this._wheelZoomForward.copy(this.camera.position).sub(this._controls.target).normalize();
797
+ const remaining = this._controls.maxDistance - currentDistance;
798
+ const progress = remaining > 0.0001 ? THREE.MathUtils.clamp((nextDistance - currentDistance) / remaining, 0, 1) : 1;
799
+ this._controls.target.lerp(this._initialControlsTarget, progress);
800
+ this.camera.position.copy(this._controls.target).addScaledVector(direction, nextDistance);
801
+ }
802
+ else {
803
+ this.camera.position.addScaledVector(this._wheelZoomDirection, radiusDelta);
804
+ this.camera.updateMatrixWorld(true);
805
+ this.camera.getWorldDirection(this._wheelZoomForward);
806
+ this._controls.target.copy(this.camera.position).addScaledVector(this._wheelZoomForward, nextDistance);
807
+ }
525
808
  this._controls.update();
526
809
  if (nextDistance === targetDistance)
527
810
  this._wheelZoomTargetDistance = undefined;
528
811
  return this._wheelZoomTargetDistance !== undefined;
529
812
  }
813
+ restoreStageAlignment(current, next) {
814
+ if (!this._controls || next < current)
815
+ return;
816
+ const remaining = this._controls.maxDistance - current;
817
+ this._viewportCentering *= remaining > 0.0001
818
+ ? THREE.MathUtils.clamp((this._controls.maxDistance - next) / remaining, 0, 1) : 0;
819
+ }
530
820
  setCameraDistance(distance) {
531
821
  if (!this._controls)
532
822
  return;
@@ -564,6 +854,9 @@ export class SpatialElementInteractionController {
564
854
  this.camera.updateProjectionMatrix();
565
855
  }
566
856
  handlePointerLeave() {
857
+ this.tap = undefined;
858
+ this.endPinch();
859
+ this.zoomAnchor = undefined;
567
860
  this.preview.clear();
568
861
  const wasInteracting = this._modelInteractionActive;
569
862
  this._interactionPointers.clear();
@@ -578,13 +871,13 @@ export class SpatialElementInteractionController {
578
871
  this.updateControlsAvailability();
579
872
  this.requestRender();
580
873
  }
581
- hitTestModel(clientX, clientY, target) {
874
+ hitTestModel(clientX, clientY, target, exact = false) {
582
875
  // Fullscreen owns the canvas, including its empty background. UI events
583
876
  // never reach this gate as canvas input; no geometry or DOM picking is needed.
584
- if (this.fullscreen)
877
+ if (this.fullscreen && !exact)
585
878
  return this.canInteract && this.stageViewportVisible && target === this.backgroundCanvas;
586
879
  const detail = this.ports.readGeometry().detail;
587
- if (detail && (detail.split || detail.paneHidden)) {
880
+ if (!exact && detail && (detail.split || detail.paneHidden)) {
588
881
  if (!this.canInteract || !this.stageViewportVisible)
589
882
  return false;
590
883
  return resolveDetailGestureOwner({ ...detail, clientX, modelHit: false,
@@ -593,16 +886,17 @@ export class SpatialElementInteractionController {
593
886
  }
594
887
  if (!this.canInteract ||
595
888
  !this.stageViewportVisible ||
596
- clientX < this.viewportFrame.x ||
597
- clientX > this.viewportFrame.x + this.viewportFrame.z ||
598
- clientY < this.viewportFrame.y ||
599
- clientY > this.viewportFrame.y + this.viewportFrame.w ||
889
+ (!exact && (clientX < this.viewportFrame.x ||
890
+ clientX > this.viewportFrame.x + this.viewportFrame.z ||
891
+ clientY < this.viewportFrame.y ||
892
+ clientY > this.viewportFrame.y + this.viewportFrame.w)) ||
600
893
  !this._modelPickTargets.length ||
601
894
  isStageUiTarget(target) ||
602
895
  this.isPointerOccludedByHtml(clientX, clientY)) {
603
896
  return false;
604
897
  }
605
898
  this.updateStageCameraProjection();
899
+ this.camera.updateMatrixWorld();
606
900
  this._pointerNdc.set((clientX / window.innerWidth) * 2 - 1, -(clientY / window.innerHeight) * 2 + 1);
607
901
  this._raycaster.setFromCamera(this._pointerNdc, this.camera);
608
902
  // This is a boolean interaction gate, not a nearest-surface query. Do not
@@ -652,7 +946,7 @@ export class SpatialElementInteractionController {
652
946
  updateControlsAvailability() {
653
947
  const enabled = this.canInteract &&
654
948
  !this._spaceMouseMoving &&
655
- (this.fullscreen || this._modelHover || this._modelInteractionActive);
949
+ (this.fullscreen || this.ports.readGeometry().detail?.paneHidden || this._modelHover || this._modelInteractionActive);
656
950
  if (this._controls) {
657
951
  this._controls.enabled = enabled;
658
952
  }
@@ -661,7 +955,7 @@ export class SpatialElementInteractionController {
661
955
  : enabled
662
956
  ? 'grab'
663
957
  : 'auto';
664
- this.backgroundCanvas.style.touchAction = this.fullscreen ? 'none' : 'manipulation';
958
+ this.backgroundCanvas.style.touchAction = this.fullscreen || this.ports.readGeometry().detail?.paneHidden ? 'none' : 'manipulation';
665
959
  }
666
960
  getZoomFocusFactor() {
667
961
  if (!this._controls)
@@ -687,10 +981,55 @@ export class SpatialElementInteractionController {
687
981
  const wheel = this.applyWheelZoom(delta);
688
982
  this.applyZoomReset(delta);
689
983
  this.applyViewReset(delta);
984
+ this.revealStageOnZoom();
985
+ this.updateControlsAvailability();
690
986
  const preview = !this.fullscreen && !this._modelInteractionActive && !this._spaceMouseMoving &&
691
987
  this.preview.advance(this.camera, delta, this.reducedMotion?.matches);
692
988
  return { controls: controls || preview, wheel };
693
989
  }
990
+ getRevealFocus(distance = this.getEffectiveCameraDistance()) {
991
+ // Start at the fitted distance, before the later UI-clearance phase. The
992
+ // first 35% of inward dolly reveals the whole stage without a second clock.
993
+ const maxDistance = this._controls.maxDistance;
994
+ return THREE.MathUtils.clamp((maxDistance - distance) /
995
+ Math.max(maxDistance * 0.35, 0.001), 0, 1);
996
+ }
997
+ /** Couple document reveal and UI clearance to one camera-driven timeline. */
998
+ revealStageOnZoom() {
999
+ const focus = this.getRevealFocus();
1000
+ if (focus > this.previousZoomFocus + 0.00001 && !this.ports.readGeometry().detail?.split) {
1001
+ if (!this.zoomScroll && window.scrollY > 0)
1002
+ this.zoomScroll = {
1003
+ focus: this.previousZoomFocus, scrollY: window.scrollY,
1004
+ uiProgress: getPanelFocusProgress(this.ports.readGeometry().detail?.uiFocus ?? getStageUiFocus(this.getZoomFocusFactor()))
1005
+ };
1006
+ if (this.zoomScroll) {
1007
+ const progress = Math.min(1, (focus - this.zoomScroll.focus) / Math.max(1 - this.zoomScroll.focus, 0.001));
1008
+ const y = Math.max(0, this.zoomScroll.scrollY * (1 - progress));
1009
+ if (window.scrollY > y) {
1010
+ markStageScrollInput('direct');
1011
+ window.scrollTo({ top: y < 1 ? 0 : y, behavior: 'instant' });
1012
+ }
1013
+ }
1014
+ }
1015
+ // Keep the same curve when zooming back out; dropping it at the first
1016
+ // outward sample would abruptly show the interface again.
1017
+ if (this.zoomScroll && focus <= this.zoomScroll.focus)
1018
+ this.zoomScroll = undefined;
1019
+ this.previousZoomFocus = focus;
1020
+ }
1021
+ getUiFocus(cameraFocus, distance = this.getEffectiveCameraDistance()) {
1022
+ const normal = getStageUiFocus(cameraFocus);
1023
+ if (!this.zoomScroll || this.ports.readGeometry().detail?.split)
1024
+ return normal;
1025
+ const progress = THREE.MathUtils.clamp((this.getRevealFocus(distance) - this.zoomScroll.focus) /
1026
+ Math.max(1 - this.zoomScroll.focus, 0.001), 0, 1);
1027
+ return Math.max(normal, getPanelFocusFromProgress(THREE.MathUtils.lerp(this.zoomScroll.uiProgress, 1, progress)));
1028
+ }
1029
+ get outlineOpacity() {
1030
+ const detail = this.ports.readGeometry().detail;
1031
+ return this.fullscreen || detail?.split ? 0 : getPanelFocusOpacity(detail?.uiFocus ?? 0);
1032
+ }
694
1033
  get controls() {
695
1034
  return this._controls;
696
1035
  }