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

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 (42) hide show
  1. package/dist/spatial-element/SpatialElementPaneController.js +3 -3
  2. package/dist/spatial-element/SpatialElementPaneController.js.map +1 -1
  3. package/dist/stage/DetailWheelGesture.d.ts +9 -0
  4. package/dist/stage/DetailWheelGesture.d.ts.map +1 -0
  5. package/dist/stage/DetailWheelGesture.js +16 -0
  6. package/dist/stage/DetailWheelGesture.js.map +1 -0
  7. package/dist/stage/LiquidGlassPanel.d.ts +2 -0
  8. package/dist/stage/LiquidGlassPanel.d.ts.map +1 -1
  9. package/dist/stage/LiquidGlassPanel.js +24 -17
  10. package/dist/stage/LiquidGlassPanel.js.map +1 -1
  11. package/dist/stage/PanelPresentationController.d.ts.map +1 -1
  12. package/dist/stage/PanelPresentationController.js +2 -0
  13. package/dist/stage/PanelPresentationController.js.map +1 -1
  14. package/dist/stage/SpatialElementInteractionController.d.ts +21 -0
  15. package/dist/stage/SpatialElementInteractionController.d.ts.map +1 -1
  16. package/dist/stage/SpatialElementInteractionController.js +185 -16
  17. package/dist/stage/SpatialElementInteractionController.js.map +1 -1
  18. package/dist/stage/SpatialElementPresentationController.js +4 -4
  19. package/dist/stage/SpatialElementPresentationController.js.map +1 -1
  20. package/dist/stage/StageExperience.d.ts +8 -0
  21. package/dist/stage/StageExperience.d.ts.map +1 -1
  22. package/dist/stage/StageExperience.js +34 -19
  23. package/dist/stage/StageExperience.js.map +1 -1
  24. package/dist/stage/StageRenderPipeline.d.ts +3 -0
  25. package/dist/stage/StageRenderPipeline.d.ts.map +1 -1
  26. package/dist/stage/StageRenderPipeline.js +15 -0
  27. package/dist/stage/StageRenderPipeline.js.map +1 -1
  28. package/dist/stage/browserPinch.d.ts +5 -0
  29. package/dist/stage/browserPinch.d.ts.map +1 -0
  30. package/dist/stage/browserPinch.js +29 -0
  31. package/dist/stage/browserPinch.js.map +1 -0
  32. package/dist/stage/panelContext.d.ts +2 -1
  33. package/dist/stage/panelContext.d.ts.map +1 -1
  34. package/dist/stage/panelContext.js.map +1 -1
  35. package/dist/stage/panelFocusMath.d.ts +2 -0
  36. package/dist/stage/panelFocusMath.d.ts.map +1 -1
  37. package/dist/stage/panelFocusMath.js +8 -0
  38. package/dist/stage/panelFocusMath.js.map +1 -1
  39. package/dist/stage/stageVisualTest.d.ts +1 -0
  40. package/dist/stage/stageVisualTest.d.ts.map +1 -1
  41. package/dist/stage/stageVisualTest.js.map +1 -1
  42. package/package.json +1 -1
@@ -3,18 +3,27 @@ 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 } 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
+ pinch;
20
+ zoomAnchor;
21
+ zoomScroll;
22
+ previousZoomFocus = 0;
15
23
  fullscreen = false;
16
24
  setFullscreen(fullscreen) {
17
25
  this.fullscreen = fullscreen;
26
+ this.wheelGesture.reset();
18
27
  this.clearWheelZoom();
19
28
  this._viewResetActive = false;
20
29
  this.preview.clear();
@@ -65,6 +74,10 @@ export class SpatialElementInteractionController {
65
74
  });
66
75
  }
67
76
  releasePage() {
77
+ this.wheelGesture.reset();
78
+ this.endPinch();
79
+ this.zoomScroll = undefined;
80
+ this.previousZoomFocus = 0;
68
81
  this.preview.forget();
69
82
  this._interactionPointers.clear();
70
83
  this._pointer.active = false;
@@ -127,6 +140,7 @@ export class SpatialElementInteractionController {
127
140
  spaceMouseGeneration = 0;
128
141
  spaceMouseAbort;
129
142
  _spaceMouseMoving = false;
143
+ spaceMouseRevealPending = false;
130
144
  _modelHover = false;
131
145
  _modelInteractionActive = false;
132
146
  _interactionPointers = new Map();
@@ -175,8 +189,8 @@ export class SpatialElementInteractionController {
175
189
  controls.zoomToCursor = true;
176
190
  controls.enabled = false;
177
191
  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.
192
+ // Single-finger background gestures retain native page scrolling. The shell
193
+ // blocks browser magnification; detail pinch gestures are routed below.
180
194
  this.backgroundCanvas.style.touchAction = 'manipulation';
181
195
  return controls;
182
196
  }
@@ -260,6 +274,7 @@ export class SpatialElementInteractionController {
260
274
  applySpaceMouseNavigationUpdate(update) {
261
275
  if (!this._controls || this.disposed || !this.canInteract)
262
276
  return;
277
+ const previousFocus = this.getZoomFocusFactor();
263
278
  if (update.viewMatrix || update.target || update.fov !== undefined)
264
279
  this.guidance.interact();
265
280
  this.clearWheelZoom();
@@ -291,6 +306,14 @@ export class SpatialElementInteractionController {
291
306
  this.constrainEffectiveZoom();
292
307
  this.camera.lookAt(this._controls.target);
293
308
  this.camera.updateMatrixWorld(true);
309
+ if (this.spaceMouseRevealPending && (update.viewMatrix || update.target || update.fov !== undefined)) {
310
+ this.spaceMouseRevealPending = false;
311
+ // Zoom reveals the document progressively. Rotation/pan still reveals an
312
+ // offscreen viewer immediately, as it does not change the zoom clock.
313
+ if (this.getZoomFocusFactor() <= previousFocus && !this.ports.readGeometry().detail?.split && window.scrollY > 0) {
314
+ window.scrollTo({ top: 0, behavior: window.matchMedia?.('(prefers-reduced-motion: reduce)').matches ? 'instant' : 'smooth' });
315
+ }
316
+ }
294
317
  this.requestRender();
295
318
  }
296
319
  setSpaceMouseMoving(moving) {
@@ -303,12 +326,8 @@ export class SpatialElementInteractionController {
303
326
  if (moving)
304
327
  this.recreateOrbitControls();
305
328
  this._spaceMouseMoving = moving;
329
+ this.spaceMouseRevealPending = moving;
306
330
  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
331
  this.clearWheelZoom();
313
332
  this.clearZoomReset();
314
333
  this._viewResetActive = false;
@@ -383,13 +402,63 @@ export class SpatialElementInteractionController {
383
402
  this.requestRender();
384
403
  }
385
404
  handleTouchStart(event) {
405
+ if (event.touches?.length >= 2 && !this.pinch) {
406
+ const [a, b] = Array.from(event.touches);
407
+ const x = (a.clientX + b.clientX) / 2, y = (a.clientY + b.clientY) / 2;
408
+ if (this.isPinchArea(x, y)) {
409
+ // Orbit keeps pointer bookkeeping for seamless one-finger rotation,
410
+ // but must not also dolly/pan using page coordinates that move on scroll.
411
+ this.pinch = { distance: Math.hypot(a.clientX - b.clientX, a.clientY - b.clientY),
412
+ zoom: this._controls.enableZoom, pan: this._controls.enablePan };
413
+ this._controls.enableZoom = this._controls.enablePan = false;
414
+ this.clearWheelZoom();
415
+ this.captureZoomAnchor(x, y);
416
+ event.preventDefault();
417
+ event.stopImmediatePropagation();
418
+ return;
419
+ }
420
+ }
386
421
  // 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.
422
+ // gesture. Cancel this start when model navigation owns the contacts.
389
423
  if (this._modelInteractionActive && this._controls?.enabled && event.cancelable) {
390
424
  event.preventDefault();
391
425
  }
392
426
  }
427
+ handleTouchMove(event) {
428
+ if (!this.pinch || event.touches.length < 2)
429
+ return;
430
+ const [a, b] = Array.from(event.touches);
431
+ const distance = Math.hypot(a.clientX - b.clientX, a.clientY - b.clientY);
432
+ event.preventDefault();
433
+ event.stopImmediatePropagation();
434
+ // Convert the distance ratio once into the wheel curve (including ctrl's
435
+ // factor ten): doubling finger distance halves camera distance.
436
+ const delta = Math.log(Math.max(distance, 1) / Math.max(this.pinch.distance, 1)) * 10 / Math.log(0.95);
437
+ this.handleWheel({ clientX: (a.clientX + b.clientX) / 2, clientY: (a.clientY + b.clientY) / 2, deltaY: delta,
438
+ deltaMode: 0, ctrlKey: true, target: this.backgroundCanvas,
439
+ preventDefault() { }, stopImmediatePropagation() { } });
440
+ this.pinch.distance = distance;
441
+ }
442
+ handleTouchEnd(event) {
443
+ if (event.touches.length < 2)
444
+ this.endPinch();
445
+ }
446
+ endPinch() {
447
+ if (this.pinch && this._controls) {
448
+ this._controls.enableZoom = this.pinch.zoom;
449
+ this._controls.enablePan = this.pinch.pan;
450
+ }
451
+ this.pinch = undefined;
452
+ }
453
+ isPinchArea(x, y) {
454
+ if (!this.canInteract || !this._controls)
455
+ return false;
456
+ if (this.fullscreen)
457
+ return true;
458
+ const detail = this.ports.readGeometry().detail;
459
+ return Boolean(detail && detail.media === 'minimap' && (detail.paneHidden ||
460
+ (detail.split ? x < detail.paneLeft : y < (detail.contentTop ?? this.viewportFrame.y + this.viewportFrame.w))));
461
+ }
393
462
  handlePointerContact(event) {
394
463
  if (event.pointerType !== 'mouse')
395
464
  this.clearPointerHover();
@@ -403,10 +472,18 @@ export class SpatialElementInteractionController {
403
472
  this.requestRender();
404
473
  }
405
474
  handleWheel(event) {
406
- const hit = this.hitTestModel(event.clientX, event.clientY, event.target);
475
+ const pinch = event.ctrlKey && this.isPinchArea(event.clientX, event.clientY);
476
+ const hit = pinch || this.hitTestModel(event.clientX, event.clientY, event.target);
407
477
  this.setModelHover(hit);
408
478
  this.updateControlsAvailability();
409
- if (!hit || !this._controls) {
479
+ if (!this._controls || !this.canInteract || event.deltaY === 0)
480
+ return;
481
+ const atOverview = !this.fullscreen && this.getEffectiveCameraDistance() >= this._controls.maxDistance - 0.001;
482
+ const owner = this.wheelGesture.resolve(performance.now(), hit, event.deltaY > 0, atOverview, pinch);
483
+ if (owner === 'scroll') {
484
+ this.zoomAnchor = undefined;
485
+ // Let the browser scroll, but never let OrbitControls consume this burst.
486
+ this._controls.enabled = false;
410
487
  this.requestRender();
411
488
  return;
412
489
  }
@@ -426,8 +503,11 @@ export class SpatialElementInteractionController {
426
503
  const targetDistance = getWheelZoomTargetDistance(previousTargetDistance, deltaY, this._controls.zoomSpeed, this._controls.minDistance, this._controls.maxDistance);
427
504
  this._wheelZoomTargetDistance =
428
505
  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);
506
+ if (!this.zoomAnchor || performance.now() >= this.zoomAnchor.until)
507
+ this.captureZoomAnchor(event.clientX, event.clientY);
508
+ this.zoomAnchor.client.set(event.clientX, event.clientY);
509
+ this.zoomAnchor.until = performance.now() + 800;
510
+ this.setPointerNdc(event.clientX, event.clientY);
431
511
  this._wheelZoomDirection
432
512
  .set(this._pointerNdc.x, this._pointerNdc.y, 1)
433
513
  .unproject(this.camera)
@@ -435,9 +515,50 @@ export class SpatialElementInteractionController {
435
515
  .normalize();
436
516
  this.requestRender();
437
517
  }
518
+ setPointerNdc(x, y) {
519
+ this._pointerNdc.set(x / Math.max(window.innerWidth, 1) * 2 - 1, 1 - y / Math.max(window.innerHeight, 1) * 2);
520
+ }
521
+ captureZoomAnchor(x, y) {
522
+ this.updateStageCameraProjection();
523
+ this.camera.updateMatrixWorld(true);
524
+ this.setPointerNdc(x, y);
525
+ this._raycaster.setFromCamera(this._pointerNdc, this.camera);
526
+ const point = new THREE.Vector3();
527
+ const hits = this._raycaster.intersectObjects(this._modelPickTargets, false);
528
+ const plane = new THREE.Plane().setFromNormalAndCoplanarPoint(this.camera.getWorldDirection(new THREE.Vector3()), this._controls.target);
529
+ if (hits.length)
530
+ point.copy(hits[0].point);
531
+ else if (!this._raycaster.ray.intersectPlane(plane, point))
532
+ point.copy(this._controls.target);
533
+ this.zoomAnchor = { point, client: new THREE.Vector2(x, y), until: performance.now() + 800 };
534
+ }
535
+ /** Run after the scroll-dependent projection has changed, before rendering. */
536
+ compensateZoomAnchor() {
537
+ const anchor = this.zoomAnchor;
538
+ if (!anchor || !this._controls || !this.canInteract)
539
+ return;
540
+ if (!this.pinch && this._wheelZoomTargetDistance === undefined && performance.now() >= anchor.until) {
541
+ this.zoomAnchor = undefined;
542
+ return;
543
+ }
544
+ this.camera.updateMatrixWorld(true);
545
+ this.setPointerNdc(anchor.client.x, anchor.client.y);
546
+ this._raycaster.setFromCamera(this._pointerNdc, this.camera);
547
+ const plane = new THREE.Plane().setFromNormalAndCoplanarPoint(this.camera.getWorldDirection(new THREE.Vector3()), anchor.point);
548
+ const intersection = this._raycaster.ray.intersectPlane(plane, new THREE.Vector3());
549
+ if (!intersection)
550
+ return;
551
+ const shift = anchor.point.clone().sub(intersection);
552
+ this.camera.position.add(shift);
553
+ this._controls.target.add(shift);
554
+ this.camera.updateMatrixWorld(true);
555
+ }
438
556
  requestScrollZoomReset(scrollDelta) {
439
557
  if (!this._controls || this.fullscreen)
440
558
  return;
559
+ if (this.pinch || this._interactionPointers.size > 1 ||
560
+ (this._wheelZoomTargetDistance !== undefined && this.wheelGesture.zooming(performance.now())))
561
+ return;
441
562
  this.clearWheelZoom();
442
563
  this._viewResetActive = false;
443
564
  const currentDistance = this.getEffectiveCameraDistance();
@@ -508,6 +629,7 @@ export class SpatialElementInteractionController {
508
629
  }
509
630
  clearWheelZoom() {
510
631
  this._wheelZoomTargetDistance = undefined;
632
+ this.zoomAnchor = undefined;
511
633
  }
512
634
  applyWheelZoom(delta) {
513
635
  if (!this._controls || this._wheelZoomTargetDistance === undefined)
@@ -564,6 +686,8 @@ export class SpatialElementInteractionController {
564
686
  this.camera.updateProjectionMatrix();
565
687
  }
566
688
  handlePointerLeave() {
689
+ this.endPinch();
690
+ this.zoomAnchor = undefined;
567
691
  this.preview.clear();
568
692
  const wasInteracting = this._modelInteractionActive;
569
693
  this._interactionPointers.clear();
@@ -652,7 +776,7 @@ export class SpatialElementInteractionController {
652
776
  updateControlsAvailability() {
653
777
  const enabled = this.canInteract &&
654
778
  !this._spaceMouseMoving &&
655
- (this.fullscreen || this._modelHover || this._modelInteractionActive);
779
+ (this.fullscreen || this.ports.readGeometry().detail?.paneHidden || this._modelHover || this._modelInteractionActive);
656
780
  if (this._controls) {
657
781
  this._controls.enabled = enabled;
658
782
  }
@@ -661,7 +785,7 @@ export class SpatialElementInteractionController {
661
785
  : enabled
662
786
  ? 'grab'
663
787
  : 'auto';
664
- this.backgroundCanvas.style.touchAction = this.fullscreen ? 'none' : 'manipulation';
788
+ this.backgroundCanvas.style.touchAction = this.fullscreen || this.ports.readGeometry().detail?.paneHidden ? 'none' : 'manipulation';
665
789
  }
666
790
  getZoomFocusFactor() {
667
791
  if (!this._controls)
@@ -687,10 +811,55 @@ export class SpatialElementInteractionController {
687
811
  const wheel = this.applyWheelZoom(delta);
688
812
  this.applyZoomReset(delta);
689
813
  this.applyViewReset(delta);
814
+ this.revealStageOnZoom();
815
+ this.updateControlsAvailability();
690
816
  const preview = !this.fullscreen && !this._modelInteractionActive && !this._spaceMouseMoving &&
691
817
  this.preview.advance(this.camera, delta, this.reducedMotion?.matches);
692
818
  return { controls: controls || preview, wheel };
693
819
  }
820
+ getRevealFocus() {
821
+ // Start at the fitted distance, before the later UI-clearance phase. The
822
+ // first 35% of inward dolly reveals the whole stage without a second clock.
823
+ const maxDistance = this._controls.maxDistance;
824
+ return THREE.MathUtils.clamp((maxDistance - this.getEffectiveCameraDistance()) /
825
+ Math.max(maxDistance * 0.35, 0.001), 0, 1);
826
+ }
827
+ /** Couple document reveal and UI clearance to one camera-driven timeline. */
828
+ revealStageOnZoom() {
829
+ const focus = this.getRevealFocus();
830
+ if (focus > this.previousZoomFocus + 0.00001 && !this.ports.readGeometry().detail?.split) {
831
+ if (!this.zoomScroll && window.scrollY > 0)
832
+ this.zoomScroll = {
833
+ focus: this.previousZoomFocus, scrollY: window.scrollY,
834
+ uiProgress: getPanelFocusProgress(this.ports.readGeometry().detail?.uiFocus ?? getStageUiFocus(this.getZoomFocusFactor()))
835
+ };
836
+ if (this.zoomScroll) {
837
+ const progress = Math.min(1, (focus - this.zoomScroll.focus) / Math.max(1 - this.zoomScroll.focus, 0.001));
838
+ const y = Math.max(0, this.zoomScroll.scrollY * (1 - progress));
839
+ if (window.scrollY > y) {
840
+ markStageScrollInput('direct');
841
+ window.scrollTo({ top: y < 1 ? 0 : y, behavior: 'instant' });
842
+ }
843
+ }
844
+ }
845
+ // Keep the same curve when zooming back out; dropping it at the first
846
+ // outward sample would abruptly show the interface again.
847
+ if (this.zoomScroll && focus <= this.zoomScroll.focus)
848
+ this.zoomScroll = undefined;
849
+ this.previousZoomFocus = focus;
850
+ }
851
+ getUiFocus(cameraFocus) {
852
+ const normal = getStageUiFocus(cameraFocus);
853
+ if (!this.zoomScroll || this.ports.readGeometry().detail?.split)
854
+ return normal;
855
+ const progress = THREE.MathUtils.clamp((this.getRevealFocus() - this.zoomScroll.focus) /
856
+ Math.max(1 - this.zoomScroll.focus, 0.001), 0, 1);
857
+ return Math.max(normal, getPanelFocusFromProgress(THREE.MathUtils.lerp(this.zoomScroll.uiProgress, 1, progress)));
858
+ }
859
+ get outlineOpacity() {
860
+ const detail = this.ports.readGeometry().detail;
861
+ return this.fullscreen || detail?.split ? 0 : getPanelFocusOpacity(detail?.uiFocus ?? 0);
862
+ }
694
863
  get controls() {
695
864
  return this._controls;
696
865
  }