@expofp/renderer 1.5.0 → 2.0.0

package/dist/index.js

@@ -2,7 +2,7 @@ var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 var _a;
-import { Color, Matrix4, Vector3, DataTexture, RGBAFormat, FloatType, RedFormat, UnsignedIntType, IntType, RGBAIntegerFormat, RGFormat, RGIntegerFormat, RedIntegerFormat, BatchedMesh as BatchedMesh$1, BufferAttribute, StreamDrawUsage, Vector4, AlwaysDepth, DoubleSide, MeshBasicMaterial, Texture, Group, PlaneGeometry, SRGBColorSpace, Vector2, Mesh, LessEqualDepth, Quaternion, BufferGeometry, LinearSRGBColorSpace, Plane, Raycaster, Sphere, Box3, Spherical, PerspectiveCamera, Scene, Camera, MathUtils, Clock, WebGLRenderer } from "three";
+import { Color, Matrix4, Vector3, DataTexture, RGBAFormat, FloatType, RedFormat, UnsignedIntType, IntType, RGBAIntegerFormat, RGFormat, RGIntegerFormat, RedIntegerFormat, BatchedMesh as BatchedMesh$1, BufferAttribute, StreamDrawUsage, Vector4, AlwaysDepth, DoubleSide, MeshBasicMaterial, Texture, Group, PlaneGeometry, SRGBColorSpace, Vector2, Mesh, LessEqualDepth, Quaternion, BufferGeometry, LinearSRGBColorSpace, Plane, Raycaster, Sphere, Box3, Spherical, PerspectiveCamera, Camera, Scene, MathUtils, Clock, WebGLRenderer } from "three";
 import { traverseAncestorsGenerator } from "three/examples/jsm/utils/SceneUtils.js";
 import { BatchedText as BatchedText$1, Text as Text$1 } from "troika-three-text";
 import { LineMaterial, LineSegmentsGeometry } from "three/examples/jsm/Addons.js";
@@ -336,7 +336,7 @@ const dimColorVertexImpl = (
   `
   void setDimAmount() {
     float instanceDim = 0.;
-#ifdef USE_BATCH_UNIFORMS    
+#ifdef USE_BATCH_UNIFORMS
     instanceDim = batch_skipDimInstance;
 #endif
 #ifdef TROIKA_DERIVED_MATERIAL_1
@@ -747,7 +747,7 @@ const _BatchedMesh = class _BatchedMesh extends BatchedMesh$1 {
   }
   dispose() {
     var _a2;
-    this.geometry.setIndex(this.indexBuffer ?? null);
+    if (this.indexBuffer) this.geometry.setIndex(this.indexBuffer);
     super.dispose();
     this.uniformSchema = {};
     (_a2 = this.uniformsTexture) == null ? void 0 : _a2.dispose();
@@ -1082,19 +1082,6 @@ function isVisible(object) {
   if (!object.visible) return false;
   return [...traverseAncestorsGenerator(object)].every((obj) => obj.visible);
 }
-function printTree(object, fullName = false) {
-  object.traverse((obj) => {
-    let s = "";
-    let obj2 = obj;
-    while (obj2 !== object) {
-      s = "|___ " + s;
-      obj2 = (obj2 == null ? void 0 : obj2.parent) ?? null;
-    }
-    const renderOrder = obj.isGroup ? "" : `, RO: ${obj.renderOrder}`;
-    const name = fullName ? obj.name : obj.name.split(":").at(-1);
-    console.log(`${s}${name}<${obj.type}>${renderOrder}`);
-  });
-}
 class RenderableSystem {
   /**
    * @param type readable name of the system's type for debugging
@@ -1825,6 +1812,7 @@ class TextSystem extends RenderableSystem {
     __publicField(this, "initialTextScale", new Vector2(1, -1));
     __publicField(this, "textColor", new Color());
     __publicField(this, "pendingUpdates", /* @__PURE__ */ new Map());
+    __publicField(this, "sdfAtlases", /* @__PURE__ */ new Set());
     __publicField(this, "alignmentOffset", new Vector2());
     __publicField(this, "alignmentDirection", new Vector2());
     __publicField(this, "localPosition", new Vector2());
@@ -1834,6 +1822,10 @@ class TextSystem extends RenderableSystem {
     __publicField(this, "localToMax", new Vector2());
     this.materialSystem = materialSystem;
   }
+  dispose() {
+    super.dispose();
+    this.sdfAtlases.forEach((texture) => texture.dispose());
+  }
   buildLayer(layer) {
     const group = new Group();
     const batchedText = this.buildBatchedText(layer);
@@ -1911,7 +1903,12 @@ class TextSystem extends RenderableSystem {
     for (const { textDef, instanceIds } of mappingData) {
       this.registerDefObject(textDef, batchedText, instanceIds);
     }
-    batchedText.addEventListener("synccomplete", () => this.renderer.update());
+    batchedText.addEventListener("synccomplete", () => {
+      var _a2;
+      const sdfTexture = (_a2 = batchedText.textRenderInfo) == null ? void 0 : _a2.sdfTexture;
+      if (sdfTexture) this.sdfAtlases.add(sdfTexture);
+      this.renderer.update();
+    });
     return batchedText;
   }
   // TODO: Simplify
@@ -2044,6 +2041,7 @@ class LayerSystem {
   }
   /**
    * Update the given defs immediately, or queue them for update if update buffering is enabled.
+   * NOTE: Currently update buffering is disabled, as observed performance gains are negligible. Need to revisit this.
    * @param defs {@link RenderableDef} array
    */
   updateDefs(defs) {
@@ -2211,6 +2209,19 @@ class LayerSystem {
     return fullName;
   }
 }
+function printTree(object, fullName = false) {
+  object.traverse((obj) => {
+    let s = "";
+    let obj2 = obj;
+    while (obj2 !== object) {
+      s = "|___ " + s;
+      obj2 = (obj2 == null ? void 0 : obj2.parent) ?? null;
+    }
+    const renderOrder = obj.isGroup ? "" : `, RO: ${obj.renderOrder}`;
+    const name = fullName ? obj.name : obj.name.split(":").at(-1);
+    console.log(`${s}${name}<${obj.type}>${renderOrder}`);
+  });
+}
 /*!
  * camera-controls
  * https://github.com/yomotsu/camera-controls
@@ -4747,6 +4758,20 @@ class CameraController extends CameraControls {
   constructor(camera, renderer) {
     super(camera);
     this.renderer = renderer;
+    this.dollyToCursor = true;
+    this.draggingSmoothTime = 0;
+    void this.rotatePolarTo(0, false);
+    this.mouseButtons = {
+      left: CameraController.ACTION.NONE,
+      middle: CameraController.ACTION.NONE,
+      right: CameraController.ACTION.NONE,
+      wheel: CameraController.ACTION.NONE
+    };
+    this.touches = {
+      one: CameraController.ACTION.NONE,
+      two: CameraController.ACTION.NONE,
+      three: CameraController.ACTION.NONE
+    };
   }
   update(delta) {
     var _a2;
@@ -4767,31 +4792,30 @@ class CameraSystem {
    * @param renderer {@link Renderer} instance
    */
   constructor(renderer) {
-    /** External camera instance. Used to render the scene in external mode (e.g. Mapbox GL JS). */
-    __publicField(this, "externalCamera");
+    /** {@link PerspectiveCamera} instance. Used to render the scene in internal mode. */
+    __publicField(this, "camera");
     /** {@link CameraController} instance. Used to smoothly animate the camera. */
     __publicField(this, "controller");
-    __publicField(this, "camera");
-    __publicField(this, "zoomIdentityDistance");
+    /**
+     * Cached previous viewport height used to preserve zoom across resizes.
+     * Note: we intentionally keep this separate from the derived identity distance.
+     */
+    __publicField(this, "prevViewportHeightPx");
+    /** [min, max] zoom factors */
     __publicField(this, "zoomBounds");
+    /** Default FOV for the camera. Taken from Mapbox GL JS. */
+    __publicField(this, "defaultFov", 36.87);
     this.renderer = renderer;
-    const [w, h] = renderer.size;
-    this.camera = new PerspectiveCamera(90, w / (h || 1));
+    const h = renderer.size[1];
+    this.prevViewportHeightPx = h;
+    this.camera = new PerspectiveCamera(this.defaultFov);
     this.camera.up.set(0, 0, -1);
-    this.zoomIdentityDistance = h / 2;
-    this.camera.position.z = this.zoomIdentityDistance;
-    this.controller = new CameraController(this.camera, renderer);
-    this.controller.polarAngle = 0;
+    this.controller = new CameraController(this.camera, this.renderer);
     this.controller.distance = this.zoomIdentityDistance;
   }
-  /** Current camera instance. */
-  get currentCamera() {
-    return this.externalCamera ?? this.camera;
-  }
   /** Current camera zoom factor. */
   get zoomFactor() {
-    const distance = this.controller.distance;
-    return distance ? this.zoomIdentityDistance / distance : 1;
+    return this.zoomFactorForHeight(this.renderer.size[1]);
   }
   /**
    * Calculates the camera distance from the scene's plane for a given zoom factor.
@@ -4799,7 +4823,7 @@ class CameraSystem {
    * @returns Corresponding camera distance on the Z axis
    */
   zoomFactorToDistance(zoomFactor) {
-    return zoomFactor > 0 ? this.zoomIdentityDistance / zoomFactor : this.zoomIdentityDistance;
+    return this.zoomIdentityDistance / zoomFactor;
   }
   /**
    * Initializes the camera with the given zoom bounds.
@@ -4813,41 +4837,188 @@ class CameraSystem {
   updateCamera() {
     if (!this.zoomBounds) return;
     const [w, h] = this.renderer.size;
-    const zoomFactor = this.zoomFactor;
-    this.zoomIdentityDistance = h / 2;
-    const maxDistance = Math.abs(this.zoomIdentityDistance / this.zoomBounds[0]);
-    const minDistance = Math.abs(this.zoomIdentityDistance / this.zoomBounds[1]);
+    if (w <= 0 || h <= 0) return;
+    const zoomFactor = this.zoomFactorForHeight(this.prevViewportHeightPx);
+    const newZoomIdentity = this.zoomIdentityDistanceForHeight(h);
+    const maxDistance = Math.abs(newZoomIdentity / this.zoomBounds[0]);
+    const minDistance = Math.abs(newZoomIdentity / this.zoomBounds[1]);
     this.camera.aspect = w / (h || 1);
-    this.computeCameraClipPlanes(minDistance, maxDistance);
+    this.camera.near = 0.01;
+    this.camera.far = Math.max(maxDistance, this.camera.near) * 2;
     this.camera.updateProjectionMatrix();
-    this.syncController(minDistance, maxDistance, zoomFactor);
-  }
-  computeCameraClipPlanes(minDistance, maxDistance, nearSafetyFactor = 0.5, farSafetyFactor = 1.5) {
-    const fov = this.camera.fov * DEG2RAD$1;
-    const aspect = this.camera.aspect;
-    const maxPolarAngle = 85 * DEG2RAD$1;
-    const halfFovY = fov / 2;
-    const halfFovX = Math.atan(Math.tan(halfFovY) * aspect);
-    const diagonalFov = 2 * Math.atan(Math.sqrt(Math.tan(halfFovX) ** 2 + Math.tan(halfFovY) ** 2));
-    const minHeight = minDistance * Math.cos(maxPolarAngle);
-    const near = Math.max(0.1, minHeight * nearSafetyFactor);
-    const criticalHeight = minHeight;
-    const horizontalDistToOrbit = minDistance * Math.sin(maxPolarAngle);
-    const distToOrbit = minDistance;
-    const visibleRadiusAtOrbit = distToOrbit * Math.tan(diagonalFov / 2);
-    const planeExtent = Math.max(maxDistance, visibleRadiusAtOrbit);
-    const horizontalDistToFarEdge = horizontalDistToOrbit + planeExtent;
-    const maxViewDistance = Math.sqrt(criticalHeight ** 2 + horizontalDistToFarEdge ** 2);
-    const far = maxViewDistance * farSafetyFactor;
-    this.camera.near = near;
-    this.camera.far = far;
-    if (this.renderer.debugLog) console.log("camera clip planes", near, far);
-  }
-  syncController(minDistance, maxDistance, zoomFactor) {
-    if (this.renderer.debugLog) console.log("syncController", minDistance, maxDistance, zoomFactor);
     this.controller.minDistance = minDistance;
     this.controller.maxDistance = maxDistance;
     void this.controller.dollyTo(this.zoomFactorToDistance(zoomFactor), false);
+    this.prevViewportHeightPx = h;
+  }
+  /**
+   * Distance from the scene plane corresponding to zoomFactor = 1 for the current viewport height.
+   * Derived from camera FOV and renderer height (in pixels).
+   */
+  get zoomIdentityDistance() {
+    return this.zoomIdentityDistanceForHeight(this.renderer.size[1]);
+  }
+  /**
+   * Calculates the zoom identity distance for a given viewport height.
+   * @param viewportHeightPx Renderer height in pixels
+   * @returns Zoom identity distance
+   */
+  zoomIdentityDistanceForHeight(viewportHeightPx) {
+    if (viewportHeightPx <= 0) return 0;
+    return viewportHeightPx * 0.5 / Math.tan(this.camera.fov * DEG2RAD$1 / 2);
+  }
+  /**
+   * Calculates the zoom factor for a given viewport height.
+   * @param viewportHeightPx Renderer height in pixels
+   * @returns Zoom factor
+   */
+  zoomFactorForHeight(viewportHeightPx) {
+    const zid = this.zoomIdentityDistanceForHeight(viewportHeightPx);
+    if (zid === 0) return 1;
+    return zid / (this.controller.distance || zid);
+  }
+}
+class ExternalSystem {
+  /**
+   * @param pickingSystem {@link PickingSystem} instance
+   */
+  constructor(pickingSystem) {
+    /** External camera instance */
+    __publicField(this, "camera", new Camera());
+    __publicField(this, "staticTransformMatrix", new Matrix4());
+    __publicField(this, "intersectionPoint", new Vector3());
+    /**
+     * Scratch NDC coordinate used by external ptScale. Kept as a field to avoid allocating a Vector2 each frame.
+     * (This is always screen center: NDC (0,0))
+     */
+    __publicField(this, "ndcCenter", new Vector2(0, 0));
+    /**
+     * Scratch clip-space vector used when projecting SVG points through the external camera matrix.
+     * Kept as a field to avoid allocating a Vector4 each frame.
+     */
+    __publicField(this, "clipPoint", new Vector4());
+    /**
+     * Scratch pixel points used by external ptScale estimation.
+     * p0 is the screen center in drawing-buffer pixels; p1/p2 are projected offsets from the anchor point.
+     */
+    __publicField(this, "px0", new Vector2());
+    __publicField(this, "px1", new Vector2());
+    __publicField(this, "px2", new Vector2());
+    this.pickingSystem = pickingSystem;
+  }
+  /**
+   * Set static part of an svg -> px transform matrix
+   * @param staticTransformMatrix static transform matrix to apply to the scene
+   */
+  setStaticTransform(staticTransformMatrix) {
+    if (!this.validateMatrix(staticTransformMatrix, "setStaticTransform")) return;
+    this.staticTransformMatrix.fromArray(staticTransformMatrix);
+  }
+  /**
+   * Set dynamic part of an svg -> px transform matrix. Should be called every frame.
+   * @param dynamicTransformMatrix dynamic transform matrix (changes every frame)
+   */
+  setDynamicTransform(dynamicTransformMatrix) {
+    if (!this.validateMatrix(dynamicTransformMatrix, "setDynamicTransform")) return;
+    this.camera.projectionMatrix.fromArray(dynamicTransformMatrix).multiply(this.staticTransformMatrix);
+    this.camera.projectionMatrixInverse.copy(this.camera.projectionMatrix).invert();
+  }
+  /**
+   * Estimates pixel→SVG scale for external context rendering (e.g. Mapbox).
+   *
+   * In external mode we don't own a camera rig/controller, so we can't derive scale from "camera distance".
+   * Instead, we:
+   * 1) Find the point on the SVG plane that is currently under the screen center.
+   * 2) Measure how much the screen position changes when moving 1 SVG unit in X/Y around that point.
+   * 3) Convert that local plane→screen mapping into a single "zoom-like" scalar that is stable under tilt+rotate.
+   *
+   * This matches internal mode semantics better because the internal orbit target is also kept under screen center.
+   * @param viewportSize Size of the viewport in drawing-buffer pixels
+   * @returns Pixel-to-SVG scale factor (px → svg units)
+   */
+  pxToSvgScale(viewportSize) {
+    const M = this.camera.projectionMatrix;
+    const [viewportW, viewportH] = viewportSize;
+    if (viewportW <= 0 || viewportH <= 0) return;
+    const intersectionPoint = this.pickingSystem.intersectPlane(this.ndcCenter, this.camera, this.intersectionPoint);
+    if (!intersectionPoint) return;
+    const anchorX = intersectionPoint.x;
+    const anchorY = intersectionPoint.y;
+    const clip = this.clipPoint;
+    const p0 = this.px0.set(viewportW * 0.5, viewportH * 0.5);
+    const p1 = this.px1;
+    const p2 = this.px2;
+    const svgToPixels = (x, y, out) => {
+      clip.set(x, y, 0, 1).applyMatrix4(M);
+      if (clip.w === 0) return false;
+      const ndcX = clip.x / clip.w;
+      const ndcY = clip.y / clip.w;
+      out.set((ndcX + 1) * 0.5 * viewportW, (1 - ndcY) * 0.5 * viewportH);
+      return true;
+    };
+    const svgStep = 1;
+    if (!svgToPixels(anchorX + svgStep, anchorY, p1)) return;
+    if (!svgToPixels(anchorX, anchorY + svgStep, p2)) return;
+    const pxDeltaPerSvgX = p1.sub(p0).divideScalar(svgStep);
+    const pxDeltaPerSvgY = p2.sub(p0).divideScalar(svgStep);
+    const pixelsSqPerSvgX = pxDeltaPerSvgX.dot(pxDeltaPerSvgX);
+    const pixelsSqPerSvgY = pxDeltaPerSvgY.dot(pxDeltaPerSvgY);
+    const pixelsSqCross = pxDeltaPerSvgX.dot(pxDeltaPerSvgY);
+    const sumPixelsSq = pixelsSqPerSvgX + pixelsSqPerSvgY;
+    const areaPixelsSq = pixelsSqPerSvgX * pixelsSqPerSvgY - pixelsSqCross * pixelsSqCross;
+    const maxStretchDiscriminant = Math.max(0, sumPixelsSq * sumPixelsSq - 4 * areaPixelsSq);
+    const maxPixelsSqPerSvg = 0.5 * (sumPixelsSq + Math.sqrt(maxStretchDiscriminant));
+    const pxPerSvg = Math.sqrt(maxPixelsSqPerSvg);
+    if (!Number.isFinite(pxPerSvg) || pxPerSvg <= 0) return;
+    return 1 / pxPerSvg;
+  }
+  validateMatrix(matrix, name) {
+    if (matrix.length !== 16) {
+      console.warn(`[ViewportSystem.${name}]: Matrix must be 16 elements long`);
+      return false;
+    }
+    return true;
+  }
+}
+class PickingSystem {
+  /** */
+  constructor() {
+    __publicField(this, "raycaster", new Raycaster());
+    __publicField(this, "ndcPoint", new Vector2());
+    __publicField(this, "viewboxPlane", new Plane(new Vector3(0, 0, 1), 0));
+    this.raycaster.layers.set(INTERACTIVE_LAYER);
+  }
+  /**
+   * Gets the objects intersected by the raycaster.
+   * @param ndcCoords raycast point in NDC (normalized device coordinates)
+   * @param scene {@link Scene} instance
+   * @param camera {@link Camera} instance
+   * @returns Array of {@link Intersection} instances
+   */
+  getIntersectedObjects(ndcCoords, scene, camera) {
+    this.setRaycasterFromCamera(ndcCoords, camera);
+    const intersections = this.raycaster.intersectObject(scene, true);
+    return intersections.filter((i) => isVisible(i.object));
+  }
+  /**
+   * Intersects the xy-plane with the raycaster.
+   * @param ndcCoords raycast point in NDC (normalized device coordinates
+   * @param camera {@link Camera} instance
+   * @param out Output vector
+   * @returns Intersection point in world space or null if no intersection.
+   */
+  intersectPlane(ndcCoords, camera, out) {
+    this.setRaycasterFromCamera(ndcCoords, camera);
+    return this.raycaster.ray.intersectPlane(this.viewboxPlane, out) ?? void 0;
+  }
+  setRaycasterFromCamera(ndcCoords, camera) {
+    if (camera.isPerspectiveCamera || camera.isOrthographicCamera) {
+      this.ndcPoint.set(ndcCoords.x, ndcCoords.y);
+      this.raycaster.setFromCamera(this.ndcPoint, camera);
+    } else {
+      this.raycaster.ray.origin.set(0, 0, 0).unproject(camera);
+      this.raycaster.ray.direction.set(ndcCoords.x, ndcCoords.y, 1).unproject(camera).sub(this.raycaster.ray.origin).normalize();
+    }
   }
 }
 class SceneSystem {
@@ -4857,29 +5028,22 @@ class SceneSystem {
   constructor(renderer) {
     /** {@link Scene} instance */
     __publicField(this, "scene");
-    /** World matrix - SVG → World transform */
+    /** World matrix - model → world transform */
     __publicField(this, "worldMatrix", new Matrix4());
-    /** Inverse world matrix - World → SVG transform */
+    /** Inverse world matrix - world → model transform */
     __publicField(this, "inverseWorldMatrix", new Matrix4());
+    __publicField(this, "tempVector3", new Vector3());
     __publicField(this, "translationMatrix", new Matrix4());
     __publicField(this, "scaleMatrix", new Matrix4());
-    __publicField(this, "scaleVector", new Vector3());
     __publicField(this, "visibleRectOffsetMatrix", new Matrix4());
     __publicField(this, "viewbox");
     this.renderer = renderer;
     this.scene = new Scene();
     this.scene.matrixAutoUpdate = false;
   }
-  /** Scene scale factor (SVG to pixel) */
+  /** Scene scale factor (model space to world space) */
   get scaleFactor() {
-    this.scaleVector.setFromMatrixScale(this.scene.matrix);
-    if (this.scaleVector.z === 1) {
-      return this.scaleVector.x;
-    } else {
-      const perspectiveW = this.scene.matrix.elements[15];
-      const halfViewportWidth = this.renderer.size[0] / 2;
-      return halfViewportWidth * this.scaleVector.x / perspectiveW;
-    }
+    return this.scene.matrix.elements[0];
   }
   /**
    * Initializes the scene with the given SVG viewbox.
@@ -4889,28 +5053,48 @@ class SceneSystem {
     this.viewbox = viewbox;
     this.updateScene();
   }
-  /**
-   * Updates the scene transform when the renderer size changes.
-   */
+  /** Updates the scene transform from the current viewbox and renderer size. */
   updateScene() {
     if (!this.viewbox) return;
+    this.composeMatrices(this.viewbox);
+  }
+  /**
+   * Converts a point from model coordinates to world coordinates.
+   * @param modelCoords Point in model coordinates
+   * @param out Output vector
+   * @returns Point in world coordinates
+   */
+  modelToWorld(modelCoords, out) {
+    const worldPoint = this.tempVector3.set(modelCoords.x, modelCoords.y, 0).applyMatrix4(this.worldMatrix);
+    out.set(worldPoint.x, worldPoint.y, 0);
+    return out;
+  }
+  /**
+   * Converts a point from world coordinates to model coordinates. Z axis is ignored.
+   * @param worldCoords Point in world coordinates
+   * @param out Output vector
+   * @returns Point in SVG coordinates
+   */
+  worldToModel(worldCoords, out) {
+    const modelPoint = this.tempVector3.copy(worldCoords).applyMatrix4(this.inverseWorldMatrix);
+    out.set(modelPoint.x, modelPoint.y);
+    return out;
+  }
+  composeMatrices(viewbox) {
     const dpr = this.renderer.context.getPixelRatio();
     const visibleRect = this.renderer.visibleRect;
-    const [viewBoxWidth, viewBoxHeight] = this.viewbox.size;
+    const [viewBoxWidth, viewBoxHeight] = viewbox.size;
     const [visibleRectWidth, visibleRectHeight] = (visibleRect == null ? void 0 : visibleRect.size.clone().multiplyScalar(dpr)) ?? this.renderer.size;
     const scaleFactor = Math.min(visibleRectWidth / viewBoxWidth, visibleRectHeight / viewBoxHeight);
-    const [centerX, centerY] = this.viewbox.center;
+    const [centerX, centerY] = viewbox.center;
     this.translationMatrix.makeTranslation(-centerX, -centerY, 0);
     this.scaleMatrix.makeScale(scaleFactor, scaleFactor, 1);
     if (visibleRect) {
       const visibleRectCenter = visibleRect.center.clone().multiplyScalar(dpr);
-      const canvasCenter = new Vector2(...this.renderer.size).multiplyScalar(0.5);
+      const canvasCenter = { x: this.renderer.size[0] / 2, y: this.renderer.size[1] / 2 };
       const offset = visibleRectCenter.sub(canvasCenter);
       this.visibleRectOffsetMatrix.makeTranslation(offset.x, offset.y, 0);
     }
-    this.composeMatrices();
-  }
-  composeMatrices() {
     this.worldMatrix.copy(this.translationMatrix).premultiply(this.scaleMatrix);
     if (this.renderer.visibleRect) this.worldMatrix.premultiply(this.visibleRectOffsetMatrix);
     this.scene.matrix.copy(this.worldMatrix);
@@ -4924,19 +5108,18 @@ class ViewportSystem {
    * @param eventSystem {@link EventSystem} instance
    */
   constructor(renderer, eventSystem) {
+    __publicField(this, "pickingSystem");
+    __publicField(this, "externalSystem");
     __publicField(this, "sceneSystem");
     __publicField(this, "cameraSystem");
-    __publicField(this, "raycaster", new Raycaster());
-    __publicField(this, "intersectionPoint", new Vector3());
-    __publicField(this, "viewboxPlane", new Plane(new Vector3(0, 0, 1), 0));
     __publicField(this, "pxToSvgScaleThreshold", 1e-4);
     __publicField(this, "prevPxToSvgScale");
-    __publicField(this, "externalStaticTransformMatrix", new Matrix4());
     this.renderer = renderer;
     this.eventSystem = eventSystem;
+    this.pickingSystem = new PickingSystem();
     this.sceneSystem = new SceneSystem(renderer);
     this.cameraSystem = new CameraSystem(renderer);
-    this.raycaster.layers.set(INTERACTIVE_LAYER);
+    this.externalSystem = new ExternalSystem(this.pickingSystem);
   }
   /** {@link Scene} instance */
   get scene() {
@@ -4944,10 +5127,10 @@ class ViewportSystem {
   }
   /** Current {@link Camera} instance */
   get camera() {
-    return this.cameraSystem.currentCamera;
+    return this.renderer.isExternalMode ? this.externalSystem.camera : this.cameraSystem.camera;
   }
   /** {@link CameraController} instance */
-  get cameraController() {
+  get controller() {
     return this.cameraSystem.controller;
   }
   /** Current camera zoom factor. */
@@ -4960,14 +5143,22 @@ class ViewportSystem {
   }
   /** Pixel to SVG scale factor */
   get pxToSvgScale() {
-    return 1 / (this.scaleFactor * this.zoomFactor);
+    return this.renderer.isExternalMode ? this.externalSystem.pxToSvgScale(this.renderer.size) ?? this.prevPxToSvgScale ?? 1 : 1 / (this.scaleFactor * this.zoomFactor);
+  }
+  /**
+   * Get bearing angle between current camera orientation and true north (in radians).
+   * Angle is in range [0, 2π), going clockwise from north.
+   */
+  get bearing() {
+    const tau = Math.PI * 2;
+    return MathUtils.euclideanModulo(-this.controller.azimuthAngle, tau);
   }
   /**
    * Initializes the viewport and zoom bounds with the given scene definition.
    * @param sceneDef {@link SceneDef} scene definition
    */
   initViewport(sceneDef) {
-    this.sceneSystem.initScene(sceneDef.viewbox);
+    if (!this.renderer.isExternalMode) this.sceneSystem.initScene(sceneDef.viewbox);
     this.cameraSystem.initCamera([0.1, sceneDef.viewbox.size.width > 1e5 ? 100 : 35]);
   }
   /** Updates the viewport when the renderer size changes. */
@@ -4987,71 +5178,99 @@ class ViewportSystem {
   }
   /**
    * Gets the objects intersected by the raycaster.
-   * @param normalizedCoords raycast point in NDC (normalized device coordinates
+   * @param ndcCoords raycast point in NDC (normalized device coordinates)
    * @returns Array of {@link Intersection} instances
    */
-  getIntersectedObjects(normalizedCoords) {
-    const { scene, camera } = this;
-    this.raycaster.setFromCamera(normalizedCoords, camera);
-    const intersections = this.raycaster.intersectObject(scene, true).filter((i) => isVisible(i.object));
-    return intersections;
+  getIntersectedObjects(ndcCoords) {
+    return this.pickingSystem.getIntersectedObjects(ndcCoords, this.scene, this.camera);
   }
   /**
-   * Converts a point from SVG coordinates to world coordinates.
-   * @param svgCoords Point in SVG coordinates
+   * Converts a point from model coordinates to world coordinates.
+   * @param modelCoords Point in model coordinates
+   * @param out Optional output vector
    * @returns Point in world coordinates
    */
-  svgToWorld(svgCoords) {
-    const svg3D = new Vector3(...svgCoords, 0);
-    svg3D.applyMatrix4(this.sceneSystem.worldMatrix);
-    return new Vector2(svg3D.x, svg3D.y);
+  modelToWorld(modelCoords, out = new Vector3()) {
+    return this.sceneSystem.modelToWorld(modelCoords, out);
   }
   /**
-   * Converts a point from world coordinates to SVG coordinates. Z axis is ignored.
+   * Converts a point from world coordinates to model coordinates. Z axis is ignored.
    * @param worldCoords Point in world coordinates
-   * @returns Point in SVG coordinates
+   * @param out Optional output vector
+   * @returns Point in model coordinates
    */
-  worldToSvg(worldCoords) {
-    const svgCoords = worldCoords.clone().applyMatrix4(this.sceneSystem.inverseWorldMatrix);
-    return new Vector2(svgCoords.x, svgCoords.y);
+  worldToModel(worldCoords, out = new Vector2()) {
+    return this.sceneSystem.worldToModel(worldCoords, out);
   }
   /**
-   * Converts a point from screen coordinates to the given coordinate space.
-   * @param space Space to convert to (either "svg" or "world")
-   * @param normalizedCoords Point in NDC (normalized device coordinates)
-   * @returns Point in the given space
+   * Converts a point from screen coordinates to world space.
+   * @param ndcCoords Point in NDC (normalized device coordinates)
+   * @param out Optional output vector
+   * @returns Point in world space
    */
-  screenTo(space, normalizedCoords) {
-    this.raycaster.setFromCamera(normalizedCoords, this.camera);
-    this.raycaster.ray.intersectPlane(this.viewboxPlane, this.intersectionPoint);
-    if (space === "svg") this.intersectionPoint.applyMatrix4(this.sceneSystem.inverseWorldMatrix);
-    return { x: this.intersectionPoint.x, y: this.intersectionPoint.y };
+  ndcToWorld(ndcCoords, out = new Vector3()) {
+    return this.pickingSystem.intersectPlane(ndcCoords, this.camera, out);
   }
   /**
-   * Calculates the camera distance from the scene's plane for a given zoom factor.
-   * @param zoomFactor Zoom factor
-   * @returns Corresponding camera distance on the Z axis
+   * Convert canvas coordinates (relative to the canvas's top left corner)
+   * to NDC (normalized device coordinates).
+   * @param point object defining the coordinates relative to the canvas's top left corner
+   * @param out Optional output vector
+   * @returns Point in NDC space
    */
-  zoomFactorToDistance(zoomFactor) {
-    return this.cameraSystem.zoomFactorToDistance(zoomFactor);
+  canvasToNDC(point, out = new Vector2()) {
+    const dpr = this.renderer.context.getPixelRatio();
+    const [width, height] = [this.renderer.size[0] / dpr, this.renderer.size[1] / dpr];
+    const uv = [point.x / width, point.y / height];
+    const ndc = [uv[0] * 2 - 1, -uv[1] * 2 + 1];
+    return out.set(MathUtils.clamp(ndc[0], -1, 1), MathUtils.clamp(ndc[1], -1, 1));
+  }
+  /**
+   * Convert canvas coordinates (CSS pixels, relative to canvas top-left) to SVG coordinates.
+   * @param point point in canvas space (CSS pixels)
+   * @returns point in SVG coordinates or undefined if point is outside the SVG plane
+   */
+  canvasToSvg(point) {
+    const vec2 = new Vector2();
+    const vec3 = new Vector3();
+    const ndcPoint = this.canvasToNDC(point, vec2);
+    const worldPoint = this.ndcToWorld(ndcPoint, vec3);
+    if (!worldPoint) return;
+    return this.worldToModel(worldPoint, vec2);
   }
   /**
-   * Sets the external transform matrix.
+   * Set static part of an svg -> px transform matrix
    * @param staticTransformMatrix static transform matrix to apply to the scene
    */
-  setExternalTransform(staticTransformMatrix) {
-    this.cameraSystem.externalCamera = new Camera();
-    this.externalStaticTransformMatrix.fromArray(staticTransformMatrix);
+  setStaticTransform(staticTransformMatrix) {
+    this.externalSystem.setStaticTransform(staticTransformMatrix);
   }
   /**
-   * Updates the external camera.
-   * @param dynamicTransformMatrix dynamic transform matrix to apply to the scene
+   * Set dynamic part of an svg -> px transform matrix. Should be called every frame.
+   * @param dynamicTransformMatrix dynamic transform matrix (changes every frame)
    */
-  updateExternalCamera(dynamicTransformMatrix) {
-    this.scene.matrix.fromArray(dynamicTransformMatrix).multiply(this.externalStaticTransformMatrix);
-    this.scene.matrixWorldNeedsUpdate = true;
+  setDynamicTransform(dynamicTransformMatrix) {
+    this.externalSystem.setDynamicTransform(dynamicTransformMatrix);
+  }
+  /**
+   * Calculates the camera distance from the scene's plane for a given zoom factor.
+   * @param zoomFactor Zoom factor
+   * @returns Corresponding camera distance on the Z axis
+   */
+  zoomFactorToDistance(zoomFactor) {
+    return this.cameraSystem.zoomFactorToDistance(zoomFactor);
   }
 }
+function asViewportAPI(viewportSystem) {
+  return {
+    canvasToSvg: viewportSystem.canvasToSvg.bind(viewportSystem),
+    setStaticTransform: viewportSystem.setStaticTransform.bind(viewportSystem),
+    setDynamicTransform: viewportSystem.setDynamicTransform.bind(viewportSystem)
+  };
+}
+function eventToCanvas(event) {
+  return { x: event.offsetX, y: event.offsetY };
+}
 class ControlsSystem {
   /**
    * @param renderer {@link Renderer} instance
@@ -5063,7 +5282,7 @@ class ControlsSystem {
     this.renderer = renderer;
     this.viewportSystem = viewportSystem;
     this.interactionsSystem = interactionsSystem;
-    this.controller = viewportSystem.cameraController;
+    this.controller = viewportSystem.controller;
   }
   /** Gesture handlers for camera controls. */
   get handlers() {
@@ -5092,7 +5311,9 @@ class ControlsSystem {
     const dpr = this.renderer.context.getPixelRatio();
     const visibleRect = this.renderer.visibleRect;
     const bearingAngle = -this.controller.azimuthAngle;
-    const worldRect = new Rect(this.viewportSystem.svgToWorld(rect.min), this.viewportSystem.svgToWorld(rect.max));
+    const worldMin = this.viewportSystem.modelToWorld(rect.min);
+    const worldMax = this.viewportSystem.modelToWorld(rect.max);
+    const worldRect = new Rect(worldMin, worldMax);
     const worldPolygon = Polygon.fromRect(worldRect).rotate(bearingAngle, worldRect.center);
     const xValues = worldPolygon.vertices.map((p) => p.x);
     const yValues = worldPolygon.vertices.map((p) => p.y);
@@ -5100,7 +5321,7 @@ class ControlsSystem {
       [Math.min(...xValues), Math.min(...yValues)],
       [Math.max(...xValues), Math.max(...yValues)]
     );
-    const targetRect = visibleRect ? new Rect(visibleRect.min.clone().multiplyScalar(dpr), visibleRect.max.clone().multiplyScalar(dpr)) : new Rect([0, 0], this.renderer.size);
+    const targetRect = visibleRect ? new Rect(visibleRect.min.clone().multiplyScalar(dpr), visibleRect.max.clone().multiplyScalar(dpr)) : new Rect([0, 0], [...this.renderer.size]);
     if (paddingPercent) targetRect.addPadding(targetRect.size.x * paddingPercent, targetRect.size.y * paddingPercent);
     const zoomByWidth = targetRect.size.x / sourceRect.size.x;
     const zoomByHeight = targetRect.size.y / sourceRect.size.y;
@@ -5125,8 +5346,8 @@ class ControlsSystem {
    * @returns Promise that resolves when the pan animation completes
    */
   panBy(x, y, immediate) {
-    const svgOrigin = this.viewportSystem.svgToWorld(new Vector2(0, 0));
-    const svgOffset = this.viewportSystem.svgToWorld(new Vector2(x, y));
+    const svgOrigin = this.viewportSystem.modelToWorld({ x: 0, y: 0 });
+    const svgOffset = this.viewportSystem.modelToWorld({ x, y });
     const worldOffset = new Vector3(svgOffset.x - svgOrigin.x, svgOffset.y - svgOrigin.y, 0);
     const currentTarget = this.controller.getTarget(new Vector3());
     const newTarget = currentTarget.add(worldOffset);
@@ -5140,7 +5361,7 @@ class ControlsSystem {
    * @returns Promise that resolves when the pan animation completes
    */
   panTo(x, y, immediate) {
-    const worldCoords = this.viewportSystem.svgToWorld(new Vector2(x, y));
+    const worldCoords = this.viewportSystem.modelToWorld({ x, y });
     return this.controller.moveTo(worldCoords.x, worldCoords.y, 0, !immediate);
   }
   /**
@@ -5238,8 +5459,8 @@ class ControlsSystem {
       this.controller.setBoundary(void 0);
       return;
     }
-    const worldMin = this.viewportSystem.svgToWorld(rect.min);
-    const worldMax = this.viewportSystem.svgToWorld(rect.max);
+    const worldMin = this.viewportSystem.modelToWorld(rect.min);
+    const worldMax = this.viewportSystem.modelToWorld(rect.max);
     const boundary = new Box3(new Vector3(worldMin.x, worldMin.y, 0), new Vector3(worldMax.x, worldMax.y, 0));
     this.controller.setBoundary(boundary);
   }
@@ -5249,9 +5470,9 @@ class ControlsSystem {
    */
   getCameraState() {
     const target = this.controller.getTarget(new Vector3());
-    const center = this.viewportSystem.worldToSvg(target);
+    const center = this.viewportSystem.worldToModel(target);
     const zoom = this.viewportSystem.zoomFactor;
-    const roll = this.interactionsSystem.bearing * RAD2DEG;
+    const roll = this.viewportSystem.bearing * RAD2DEG;
     const pitch = this.controller.polarAngle * RAD2DEG;
     const ptScale = this.viewportSystem.pxToSvgScale;
     return { center, zoom, roll, pitch, ptScale };
@@ -5348,21 +5569,6 @@ function asEventAPI(system) {
     clear: system.clear.bind(system)
   };
 }
-function clientToCanvas(event, domElement, target) {
-  target = target ?? new Vector2();
-  const { left, top } = domElement.getBoundingClientRect();
-  const clientX = "clientX" in event ? event.clientX : event.x;
-  const clientY = "clientY" in event ? event.clientY : event.y;
-  target.set(clientX - left, clientY - top);
-  return target;
-}
-function canvasToNDC(coordinates, canvas, target) {
-  target = target ?? new Vector2();
-  const { width, height } = canvas.getBoundingClientRect();
-  const uv = [coordinates.x / width, coordinates.y / height];
-  target.set(uv[0] * 2 - 1, -uv[1] * 2 + 1);
-  return target;
-}
 class Handler {
   /**
    * @param viewportSystem The viewport system instance
@@ -5377,7 +5583,7 @@ class Handler {
     this.viewportSystem = viewportSystem;
     this.domElement = domElement;
     this.eventManager = eventManager;
-    this.controller = viewportSystem.cameraController;
+    this.controller = viewportSystem.controller;
   }
   /**
    * Per-frame update for this handler.
@@ -5588,13 +5794,15 @@ class PitchHandler extends Handler {
     __publicField(this, "isValid");
     __publicField(this, "firstMove");
     __publicField(this, "lastPoints");
+    __publicField(this, "p0", new Vector2());
+    __publicField(this, "p1", new Vector2());
     __publicField(this, "prevTwoFingerAction");
     __publicField(this, "onPitchStart", (e) => {
       const pointers = e.pointers.sort((a, b) => a.pointerId - b.pointerId);
-      const p0 = clientToCanvas(pointers[0], this.domElement);
-      const p1 = clientToCanvas(pointers[1], this.domElement);
-      this.lastPoints = [p0, p1];
-      if (this.isVertical(p0.clone().sub(p1))) {
+      this.p0.copy(eventToCanvas(pointers[0]));
+      this.p1.copy(eventToCanvas(pointers[1]));
+      this.lastPoints = [new Vector2().copy(this.p0), new Vector2().copy(this.p1)];
+      if (this.isVertical(this.p0.sub(this.p1))) {
         this.isValid = false;
       }
     });
@@ -5609,18 +5817,19 @@ class PitchHandler extends Handler {
       const lastPoints = this.lastPoints;
       if (!lastPoints) return;
       const pointers = e.pointers.sort((a, b) => a.pointerId - b.pointerId);
-      const p0 = clientToCanvas(pointers[0], this.domElement);
-      const p1 = clientToCanvas(pointers[1], this.domElement);
-      const vectorA = p0.clone().sub(lastPoints[0]);
-      const vectorB = p1.clone().sub(lastPoints[1]);
-      this.isValid = this.gestureBeginsVertically(vectorA, vectorB, e.timeStamp);
+      this.p0.copy(eventToCanvas(pointers[0]));
+      this.p1.copy(eventToCanvas(pointers[1]));
+      this.p0.sub(lastPoints[0]);
+      this.p1.sub(lastPoints[1]);
+      this.isValid = this.gestureBeginsVertically(this.p0, this.p1, e.timeStamp);
       if (!this.isValid) return;
       if (this.prevTwoFingerAction === void 0) {
         this.prevTwoFingerAction = this.controller.touches.two;
         this.controller.touches.two = CameraController.ACTION.NONE;
       }
-      this.lastPoints = [p0, p1];
-      const yDeltaAverage = (vectorA.y + vectorB.y) / 2;
+      lastPoints[0].add(this.p0);
+      lastPoints[1].add(this.p1);
+      const yDeltaAverage = (this.p0.y + this.p1.y) / 2;
       const degreesPerPixelMoved = -0.5;
       const deltaAngle = yDeltaAverage * degreesPerPixelMoved * DEG2RAD$1;
       void this.controller.rotatePolarTo(this.controller.polarAngle + deltaAngle, false);
@@ -5665,12 +5874,10 @@ class PitchHandler extends Handler {
   updatePolarAngles() {
     this.controller.minPolarAngle = this.minPitch * DEG2RAD$1;
     this.controller.maxPolarAngle = this.maxPitch * DEG2RAD$1;
-    if (this.controller.polarAngle < this.controller.minPolarAngle) {
+    if (this.controller.polarAngle < this.controller.minPolarAngle)
       void this.controller.rotatePolarTo(this.controller.minPolarAngle, false);
-    }
-    if (this.controller.polarAngle > this.controller.maxPolarAngle) {
+    if (this.controller.polarAngle > this.controller.maxPolarAngle)
       void this.controller.rotatePolarTo(this.controller.maxPolarAngle, false);
-    }
   }
   gestureBeginsVertically(vectorA, vectorB, timeStamp) {
     if (this.isValid !== void 0) return this.isValid;
@@ -5702,35 +5909,36 @@ class RollHandler extends Handler {
     __publicField(this, "rotationThreshold", 25);
     // Threshold tracking (Mapbox-style)
     __publicField(this, "startVector");
-    __publicField(this, "vector");
+    __publicField(this, "vector", new Vector2());
+    __publicField(this, "p0", new Vector2());
+    __publicField(this, "p1", new Vector2());
     __publicField(this, "minDiameter", 0);
     __publicField(this, "prevAngle", 0);
     // Camera and pivot vectors
+    __publicField(this, "pivotNDC", new Vector2());
     __publicField(this, "pivotWorld", new Vector3());
     __publicField(this, "targetWorld", new Vector3());
     __publicField(this, "cameraPosition", new Vector3());
     __publicField(this, "cameraForward", new Vector3());
     __publicField(this, "rotationMatrix", new Matrix4());
     __publicField(this, "onRotateStart", (e) => {
-      console.log("onRotateStart");
       const pointers = e.pointers;
-      const p0 = clientToCanvas(pointers[0], this.domElement);
-      const p1 = clientToCanvas(pointers[1], this.domElement);
-      this.startVector = p0.sub(p1);
+      this.p0.copy(eventToCanvas(pointers[0]));
+      this.p1.copy(eventToCanvas(pointers[1]));
+      this.startVector = new Vector2().copy(this.p0).sub(this.p1);
       this.minDiameter = this.startVector.length();
     });
     __publicField(this, "onRotateEnd", () => {
       this.isRolling = false;
       this.startVector = void 0;
-      this.vector = void 0;
       this.minDiameter = 0;
     });
     __publicField(this, "onRotate", (e) => {
       const pointers = e.pointers;
       if (!this.isRolling) {
-        const p0 = clientToCanvas(pointers[0], this.domElement);
-        const p1 = clientToCanvas(pointers[1], this.domElement);
-        this.vector = p0.sub(p1);
+        this.p0.copy(eventToCanvas(pointers[0]));
+        this.p1.copy(eventToCanvas(pointers[1]));
+        this.vector.copy(this.p0).sub(this.p1);
         if (this.isBelowThreshold(this.vector)) return;
         this.isRolling = true;
         this.prevAngle = e.rotation;
@@ -5738,7 +5946,7 @@ class RollHandler extends Handler {
       const deltaAngle = (e.rotation - this.prevAngle) * -DEG2RAD$1;
       this.prevAngle = e.rotation;
       if (Math.abs(deltaAngle) < 1e-3) return;
-      this.setPivot(e);
+      if (!this.setPivot(e)) return;
       this.rotationMatrix.makeRotationZ(deltaAngle);
       this.cameraPosition.sub(this.pivotWorld).applyMatrix4(this.rotationMatrix).add(this.pivotWorld);
       this.cameraForward.applyMatrix4(this.rotationMatrix);
@@ -5786,13 +5994,12 @@ class RollHandler extends Handler {
     this.eventManager.off("rotateend", this.onRotateEnd);
   }
   setPivot(e) {
-    const pivotScreen = e.center;
-    const pivotNDC = canvasToNDC(pivotScreen, this.domElement);
-    const pivotWorld2D = this.viewportSystem.screenTo("world", pivotNDC);
-    this.pivotWorld.set(pivotWorld2D.x, pivotWorld2D.y, 0);
+    this.viewportSystem.canvasToNDC(e.offsetCenter, this.pivotNDC);
+    if (!this.viewportSystem.ndcToWorld(this.pivotNDC, this.pivotWorld)) return false;
     this.controller.getPosition(this.cameraPosition);
     this.controller.getTarget(this.targetWorld);
     this.cameraForward.copy(this.targetWorld).sub(this.cameraPosition);
+    return true;
   }
   /**
    * Check if rotation is below threshold (Mapbox-style).
@@ -5812,7 +6019,6 @@ class RollHandler extends Handler {
     const startVector = this.startVector;
     if (!startVector) return false;
     const bearingDeltaSinceStart = this.getBearingDelta(vector, startVector);
-    console.log("bearingDeltaSinceStart", vector, startVector);
     return Math.abs(bearingDeltaSinceStart) < threshold;
   }
   /**
@@ -5824,16 +6030,6 @@ class RollHandler extends Handler {
   getBearingDelta(a, b) {
     return a.angleTo(b) * RAD2DEG;
   }
-  /**
-   * Normalize angle to be between -π and π
-   * @param angle Angle in radians
-   * @returns Normalized angle in radians
-   */
-  normalizeAngle(angle) {
-    while (angle > Math.PI) angle -= 2 * Math.PI;
-    while (angle < -Math.PI) angle += 2 * Math.PI;
-    return angle;
-  }
 }
 class ZoomHandler extends Handler {
   reset(enableTransition = true) {
@@ -5868,12 +6064,16 @@ class InteractionsSystem {
     __publicField(this, "handlers");
     __publicField(this, "handlerArray");
     __publicField(this, "canvas");
-    __publicField(this, "mousePointer", new Vector2());
     __publicField(this, "eventManager");
+    __publicField(this, "mousePointerNDC", new Vector2());
+    __publicField(this, "mousePointerWorld", new Vector3());
+    __publicField(this, "mousePointerModel", new Vector2());
+    __publicField(this, "canvasListeners");
     __publicField(this, "dragStart");
     __publicField(this, "dragThreshold", 15);
     __publicField(this, "isDragging", false);
     __publicField(this, "prevBearing", 0);
+    this.renderer = renderer;
     this.events = events;
     this.viewportSystem = viewportSystem;
     this.layerSystem = layerSystem;
@@ -5881,8 +6081,6 @@ class InteractionsSystem {
     this.eventManager = new EventManager(this.canvas, {
       recognizers: [Rotate, [Pan, { event: "pitch", pointers: 2 }, "rotate"]]
     });
-    this.configureCameraControls();
-    this.attachCanvasListeners();
     const handlers = {
       pan: new PanHandler(viewportSystem, this.canvas, this.eventManager),
       zoom: new ZoomHandler(viewportSystem, this.canvas, this.eventManager),
@@ -5891,17 +6089,32 @@ class InteractionsSystem {
     };
     this.handlers = handlers;
     this.handlerArray = Object.values(handlers);
-    this.handlers.pan.enable();
-    this.handlers.zoom.enable();
   }
   /**
-   * Get bearing angle between current camera orientation and true north (in radians).
-   * Angle is in range [0, 2π), going clockwise from north.
+   * Initializes the interactions system and attaches event listeners.
+   * Should be called once as part of renderer initialization.
    */
-  // TODO: Move somewhere else
-  get bearing() {
-    const tau = Math.PI * 2;
-    return MathUtils.euclideanModulo(-this.viewportSystem.cameraController.azimuthAngle, tau);
+  init() {
+    this.attachCanvasListeners();
+    if (!this.renderer.isExternalMode) {
+      const controller = this.viewportSystem.controller;
+      controller.connect(this.canvas);
+      controller.addEventListener("transitionstart", () => {
+        this.events.emit("navigation:change");
+      });
+      this.handlers.pan.enable();
+      this.handlers.zoom.enable();
+    }
+  }
+  /**
+   * Disposes the interactions system.
+   * WARNING: This method is final and cannot be undone. To re-enable interactions, create a new renderer instance.
+   */
+  dispose() {
+    for (const handler of this.handlerArray) handler.disable();
+    this.viewportSystem.controller.disconnect();
+    this.detachCanvasListeners();
+    this.eventManager.destroy();
   }
   /**
    * Update camera position and directions.
@@ -5910,77 +6123,67 @@ class InteractionsSystem {
    * @returns true if re-rendering is needed
    */
   updateControls(delta) {
-    let needsUpdate = this.viewportSystem.cameraController.update(delta);
+    let needsUpdate = this.viewportSystem.controller.update(delta);
     for (const handler of this.handlerArray) {
       if (handler.isEnabled()) {
         needsUpdate = handler.update(delta) || needsUpdate;
       }
     }
-    if (this.bearing !== this.prevBearing) {
-      this.prevBearing = this.bearing;
-      this.events.emit("navigation:roll", this.bearing);
+    if (this.viewportSystem.bearing !== this.prevBearing) {
+      this.prevBearing = this.viewportSystem.bearing;
+      this.events.emit("navigation:roll", this.viewportSystem.bearing);
     }
     return needsUpdate;
   }
-  /** Disconnect the interactions system. */
-  disconnect() {
-    this.viewportSystem.cameraController.disconnect();
-    for (const handler of this.handlerArray) {
-      handler.disable();
-    }
-  }
-  configureCameraControls() {
-    const controller = this.viewportSystem.cameraController;
-    controller.draggingSmoothTime = 0;
-    controller.dollyToCursor = true;
-    controller.mouseButtons = {
-      left: CameraController.ACTION.NONE,
-      middle: CameraController.ACTION.NONE,
-      right: CameraController.ACTION.NONE,
-      wheel: CameraController.ACTION.NONE
-    };
-    controller.touches = {
-      one: CameraController.ACTION.NONE,
-      two: CameraController.ACTION.NONE,
-      three: CameraController.ACTION.NONE
-    };
-    controller.connect(this.canvas);
-    controller.addEventListener("transitionstart", () => {
-      this.events.emit("navigation:change");
-    });
-  }
   attachCanvasListeners() {
-    this.canvas.addEventListener("pointerdown", (event) => {
+    if (this.canvasListeners) return;
+    const pointerdown = (event) => {
       this.isDragging = false;
       this.dragStart = { x: event.offsetX, y: event.offsetY };
-    });
-    this.canvas.addEventListener("pointerup", (event) => {
+    };
+    const pointerup = (event) => {
       if (!this.dragStart) return;
       const dX = event.offsetX - this.dragStart.x;
       const dY = event.offsetY - this.dragStart.y;
       this.dragStart = void 0;
       if (dX * dX + dY * dY > this.dragThreshold) this.isDragging = true;
-    });
+    };
     const mouseEventsMap = {
       mousemove: "pointer:move",
       mouseout: "pointer:out",
       click: "pointer:click"
     };
     const mouseEventKeys = Object.keys(mouseEventsMap);
-    mouseEventKeys.forEach((type) => {
-      this.canvas.addEventListener(type, (event) => {
-        const eventType = mouseEventsMap[type];
-        const isDragging = type === "click" && this.isDragging;
-        const hasListeners = this.events.hasListeners(eventType);
-        if (isDragging || !hasListeners) return;
-        clientToCanvas(event, this.canvas, this.mousePointer);
-        canvasToNDC(this.mousePointer, this.canvas, this.mousePointer);
-        const intersections = this.viewportSystem.getIntersectedObjects(this.mousePointer);
-        const point = this.viewportSystem.screenTo("svg", this.mousePointer);
-        const defs = this.layerSystem.getIntersectedDefs(intersections);
-        this.events.emit(eventType, { event, point, defs });
-      });
-    });
+    const sharedMouseHandler = (type, event) => {
+      const eventType = mouseEventsMap[type];
+      const isDragging = type === "click" && this.isDragging;
+      const hasListeners = this.events.hasListeners(eventType);
+      if (isDragging || !hasListeners) return;
+      const mousePointer = eventToCanvas(event);
+      this.viewportSystem.canvasToNDC(mousePointer, this.mousePointerNDC);
+      if (!this.viewportSystem.ndcToWorld(this.mousePointerNDC, this.mousePointerWorld)) return;
+      const intersections = this.viewportSystem.getIntersectedObjects(this.mousePointerNDC);
+      const point = this.viewportSystem.worldToModel(this.mousePointerWorld, this.mousePointerModel);
+      const defs = this.layerSystem.getIntersectedDefs(intersections);
+      this.events.emit(eventType, { event, point: { x: point.x, y: point.y }, defs });
+    };
+    const mousemove = (event) => sharedMouseHandler("mousemove", event);
+    const mouseout = (event) => sharedMouseHandler("mouseout", event);
+    const click = (event) => sharedMouseHandler("click", event);
+    const canvasListeners = { pointerdown, pointerup, mousemove, mouseout, click };
+    this.canvas.addEventListener("pointerdown", pointerdown);
+    this.canvas.addEventListener("pointerup", pointerup);
+    mouseEventKeys.forEach((type) => this.canvas.addEventListener(type, canvasListeners[type]));
+    this.canvasListeners = canvasListeners;
+  }
+  detachCanvasListeners() {
+    if (!this.canvasListeners) return;
+    this.canvas.removeEventListener("pointerdown", this.canvasListeners.pointerdown);
+    this.canvas.removeEventListener("pointerup", this.canvasListeners.pointerup);
+    this.canvas.removeEventListener("mousemove", this.canvasListeners.mousemove);
+    this.canvas.removeEventListener("mouseout", this.canvasListeners.mouseout);
+    this.canvas.removeEventListener("click", this.canvasListeners.click);
+    this.canvasListeners = void 0;
   }
 }
 class Renderer {
@@ -6000,13 +6203,17 @@ class Renderer {
     __publicField(this, "viewportSystem");
     __publicField(this, "interactionsSystem");
     __publicField(this, "controlsSystem");
+    __publicField(this, "controlsAPI");
+    __publicField(this, "eventsAPI");
+    __publicField(this, "viewportAPI");
     __publicField(this, "clock");
     __publicField(this, "renderer");
-    __publicField(this, "viewport");
+    __publicField(this, "visibleRectValue");
+    __publicField(this, "memoryInfoExtension", null);
+    __publicField(this, "memoryInfo");
+    __publicField(this, "initialized", false);
+    __publicField(this, "disposed", false);
     __publicField(this, "needsRedraw", true);
-    __publicField(this, "memoryInfoExtension");
-    __publicField(this, "memoryInfo", "");
-    var _a2, _b;
     const { canvas, gl, debugLog = false, ui } = opts;
     this.canvas = canvas;
     this.debugLog = debugLog;
@@ -6021,42 +6228,84 @@ class Renderer {
     this.renderer = new WebGLRenderer(rendererOptions);
     this.renderer.setSize(this.canvas.clientWidth, this.canvas.clientHeight, false);
     this.renderer.setPixelRatio(window.devicePixelRatio);
+    this.renderer.autoClear = !this.isExternalMode;
     this.eventSystem = new EventSystem();
     this.viewportSystem = new ViewportSystem(this, this.eventSystem);
     this.layerSystem = new LayerSystem(this);
     this.interactionsSystem = new InteractionsSystem(this, this.eventSystem, this.viewportSystem, this.layerSystem);
     this.controlsSystem = new ControlsSystem(this, this.viewportSystem, this.interactionsSystem);
-    this.memoryInfoExtension = this.renderer.getContext().getExtension("GMAN_webgl_memory");
-    this.canvas.addEventListener("webglcontextlost", (e) => this.onContextLost(e), false);
-    this.canvas.addEventListener("webglcontextrestored", (e) => this.onContextRestored(e), false);
-    void ((_b = (_a2 = this.ui) == null ? void 0 : _a2.stats) == null ? void 0 : _b.init(this.renderer.getContext()));
+    this.initContext(this.renderer.getContext());
     BatchedMesh.useMultiDraw = this.renderer.extensions.has("WEBGL_multi_draw");
   }
   /**
    * {@link ControlsAPI} instance for controlling the viewport
    */
   get controls() {
-    return asControlsAPI(this.controlsSystem);
+    if (this.controlsAPI) return this.controlsAPI;
+    const api = asControlsAPI(this.controlsSystem);
+    const guard = (name) => this.assertInitialized(`controls.${name}`) && this.assertNotDisposed(`controls.${name}`) && this.assertNotExternalMode(`controls.${name}`);
+    this.controlsAPI = {
+      handlers: api.handlers,
+      configure: api.configure,
+      zoomBy: guardFn(guard, api.zoomBy, Promise.resolve()),
+      zoomTo: guardFn(guard, api.zoomTo, Promise.resolve()),
+      panBy: guardFn(guard, api.panBy, Promise.resolve()),
+      panTo: guardFn(guard, api.panTo, Promise.resolve()),
+      rollBy: guardFn(guard, api.rollBy, Promise.resolve()),
+      rollTo: guardFn(guard, api.rollTo, Promise.resolve()),
+      pitchBy: guardFn(guard, api.pitchBy, Promise.resolve()),
+      pitchTo: guardFn(guard, api.pitchTo, Promise.resolve()),
+      resetCamera: guardFn(guard, api.resetCamera, Promise.resolve()),
+      setCameraBounds: guardFn(guard, api.setCameraBounds),
+      getCameraState: guardFn(guard, api.getCameraState, {
+        center: { x: 0, y: 0 },
+        roll: 0,
+        pitch: 0,
+        zoom: 1,
+        ptScale: 1
+      })
+    };
+    return this.controlsAPI;
   }
   /**
    * {@link EventsAPI} instance for subscribing to internal events
    */
   get events() {
-    return asEventAPI(this.eventSystem);
+    if (this.eventsAPI) return this.eventsAPI;
+    this.eventsAPI = asEventAPI(this.eventSystem);
+    return this.eventsAPI;
+  }
+  /**
+   * {@link ViewportAPI} instance for view transforms and external transforms.
+   */
+  get viewport() {
+    if (this.viewportAPI) return this.viewportAPI;
+    const api = asViewportAPI(this.viewportSystem);
+    const guard = (name) => this.assertInitialized(`viewport.${name}`) && this.assertNotDisposed(`viewport.${name}`);
+    const guardExternal = (name) => guard(name) && this.assertExternalMode(`viewport.${name}`);
+    this.viewportAPI = {
+      canvasToSvg: guardFn(guard, api.canvasToSvg, { x: 0, y: 0 }),
+      setStaticTransform: guardFn(guardExternal, api.setStaticTransform),
+      setDynamicTransform: guardFn(guardExternal, api.setDynamicTransform)
+    };
+    return this.viewportAPI;
   }
   /**
    * Optional sub-rectangle of the viewport that is used for positioning scene's viewbox
    */
   get visibleRect() {
-    return this.viewport;
+    return this.visibleRectValue;
   }
   /**
    * Optional sub-rectangle of the viewport that is used for positioning scene's viewbox
    */
   set visibleRect(rect) {
-    this.viewport = rect;
-    this.viewportSystem.updateViewport();
-    this.update();
+    if (!this.assertNotExternalMode("visibleRect")) return;
+    this.visibleRectValue = rect;
+    if (this.initialized && !this.disposed) {
+      this.viewportSystem.updateViewport();
+      this.update();
+    }
   }
   /**
    * Underlying {@link WebGLRenderer} instance
@@ -6072,64 +6321,73 @@ class Renderer {
     return [this.canvas.width, this.canvas.height];
   }
   /**
-   * Sets the renderer to external mode, where parts of rendering process are not managed by the renderer (e.g. Mapbox GL JS).
-   * @param staticTransformMatrix static transform matrix to apply to the scene
+   * Returns true if the renderer is in external mode, meaning that webgl context is managed outside of the renderer
+   * (for example, when using Mapbox GL JS as a host context). In this mode renderer will not clear the canvas before
+   * rendering, and will not automatically compute scene and camera transformations. Clients are responsible for setting
+   * the matrices manually by using {@link Renderer.viewport} methods.
    */
-  // TODO: Move somewhere
-  setExternalTransform(staticTransformMatrix) {
-    this.renderer.autoClear = false;
-    this.interactionsSystem.disconnect();
-    this.viewportSystem.setExternalTransform(staticTransformMatrix);
+  get isExternalMode() {
+    return this.gl !== void 0;
   }
   /**
-   * Update scene matrix from dynamic transform matrix.
-   * @param dynamicTransformMatrix dynamic transform matrix (changes every frame)
+   * Returns true if the renderer is initialized, meaning that the viewport and scene have been set up.
+   */
+  get isInitialized() {
+    return this.initialized;
+  }
+  /**
+   * Returns true if the renderer is disposed, meaning that all WebGL resources have been released.
    */
-  updateExternalCamera(dynamicTransformMatrix) {
-    this.viewportSystem.updateExternalCamera(dynamicTransformMatrix);
+  get isDisposed() {
+    return this.disposed;
   }
   /**
-   * Initialize the scene and start the rendering loop
+   * Initializes viewport and scene with the given scene definition.
+   * Should be called once on startup. Repeated calls will produce console warnings.
    * @param sceneDef {@link SceneDef} to render
-   * @param startLoop whether to start the rendering loop
    */
-  start(sceneDef, startLoop = true) {
-    this.clock.start();
+  init(sceneDef) {
+    if (!this.assertNotDisposed("init")) return;
+    if (!this.assertNotInitialized("init")) return;
     this.viewportSystem.initViewport(sceneDef);
+    this.interactionsSystem.init();
     this.viewportSystem.scene.add(this.layerSystem.buildScene(sceneDef));
-    if (startLoop) this.renderer.setAnimationLoop(() => this.render());
+    this.initialized = true;
+  }
+  /**
+   * Start the rendering loop
+   */
+  start() {
+    if (!this.assertNotDisposed("start")) return;
+    if (!this.assertInitialized("start")) return;
+    if (this.clock.running) return;
+    this.clock.start();
+    this.renderer.setAnimationLoop(() => this.render());
   }
   /**
    * Update the given defs to make them reflect the current state
    * @param defs {@link RenderableDef} array to update
    */
   update(...defs) {
+    if (!this.assertNotDisposed("update")) return;
+    if (!this.assertInitialized("update")) return;
     this.layerSystem.updateDefs(defs);
     this.needsRedraw = true;
   }
   /**
-   * Converts coordinates from canvas space to SVG space.
-   * @param point point in canvas space (relative to the canvas's top left corner), in css pixels
-   * @returns point in SVG space
-   */
-  screenToSvg(point) {
-    const vector2 = new Vector2(point.x, point.y);
-    canvasToNDC(vector2, this.canvas, vector2);
-    return this.viewportSystem.screenTo("svg", vector2);
-  }
-  /**
-   * Main rendering loop
+   * Render a single frame
    */
   render() {
     var _a2, _b, _c, _d, _e, _f;
+    if (!this.assertNotDisposed("render")) return;
+    if (!this.assertInitialized("render")) return;
     (_b = (_a2 = this.ui) == null ? void 0 : _a2.stats) == null ? void 0 : _b.begin();
-    if (this.gl !== void 0) this.renderer.resetState();
+    if (this.isExternalMode) this.renderer.resetState();
     else this.resizeCanvasToDisplaySize();
     this.viewportSystem.updatePtScale();
-    const delta = this.clock.getDelta();
     const hasDefsUpdated = this.layerSystem.processPendingUpdates();
-    const hasControlsUpdated = this.interactionsSystem.updateControls(delta);
-    const needsRedraw = this.needsRedraw || hasControlsUpdated || hasDefsUpdated || this.ui;
+    const hasControlsUpdated = this.interactionsSystem.updateControls(this.clock.getDelta());
+    const needsRedraw = this.needsRedraw || hasControlsUpdated || hasDefsUpdated || this.isExternalMode || this.ui;
     if (needsRedraw) {
       this.renderer.render(this.viewportSystem.scene, this.viewportSystem.camera);
       this.needsRedraw = false;
@@ -6146,11 +6404,21 @@ class Renderer {
     this.clock.stop();
   }
   /**
-   * Dispose all WebGL resources
+   * Dispose all WebGL resources. This calls {@link Renderer.stop} internally.
+   * WARNING: This method is final and cannot be undone. Attempting to use the renderer after calling this method
+   * will result in a console warning and no-op methods. If you need to re-initialize the renderer, create a new instance.
    */
   dispose() {
+    if (this.disposed) return;
+    this.stop();
+    this.interactionsSystem.dispose();
     this.layerSystem.disposeScene();
     this.viewportSystem.scene.clear();
+    this.renderer.clear();
+    this.renderer.info.reset();
+    this.renderer.dispose();
+    this.updateMemoryInfo();
+    this.disposed = true;
   }
   // https://webgl2fundamentals.org/webgl/lessons/webgl-resizing-the-canvas.html
   resizeCanvasToDisplaySize() {
@@ -6167,35 +6435,93 @@ class Renderer {
     }
   }
   updateMemoryInfo() {
-    var _a2;
+    var _a2, _b, _c, _d;
     if (this.memoryInfoExtension && ((_a2 = this.ui) == null ? void 0 : _a2.memoryInfoPanel)) {
       const memoryInfo = this.memoryInfoExtension.getMemoryInfo();
       memoryInfo.resources["drawCalls"] = this.renderer.info.render.calls;
-      const memoryInfoContent = JSON.stringify(memoryInfo.memory, null, 2);
-      const elapsedTime = this.clock.getElapsedTime() * 1e3;
-      if (memoryInfoContent !== this.memoryInfo) {
+      if (memoryInfo.memory["texture"] !== ((_b = this.memoryInfo) == null ? void 0 : _b.memory["texture"]) || memoryInfo.memory["buffer"] !== ((_c = this.memoryInfo) == null ? void 0 : _c.memory["buffer"]) || memoryInfo.memory["renderbuffer"] !== ((_d = this.memoryInfo) == null ? void 0 : _d.memory["renderbuffer"])) {
+        const elapsedTime = this.clock.getElapsedTime() * 1e3;
         const logMarker = `memoryInfo [${elapsedTime.toFixed(2)}ms since start]`;
         if (this.debugLog) console.log(logMarker, memoryInfo);
-        console.log("Buffers", this.memoryInfoExtension.getResourcesInfo(WebGLBuffer));
-        this.memoryInfo = memoryInfoContent;
+        this.memoryInfo = memoryInfo;
+        this.ui.memoryInfoPanel.textContent = JSON.stringify(memoryInfo, null, 2);
       }
-      this.ui.memoryInfoPanel.textContent = JSON.stringify(memoryInfo, null, 2);
     }
   }
-  // FIXME: Test with mapbox
   onContextLost(event) {
+    var _a2, _b;
     event.preventDefault();
     console.log("webglcontextlost event", event);
-    this.renderer.setAnimationLoop(null);
-    this.clock.stop();
-    if (this.ui) setTimeout(() => this.renderer.forceContextRestore(), 0);
+    const stats = (_a2 = this.ui) == null ? void 0 : _a2.stats;
+    const context = this.renderer.getContext();
+    if (stats && "deleteQuery" in context) {
+      const gpuQueries = stats.gpuQueries;
+      for (const queryInfo of gpuQueries) {
+        this.renderer.getContext().deleteQuery(queryInfo.query);
+      }
+      stats.gpuQueries = [];
+      if (stats.gpuPanel) {
+        stats.dom.removeChild((_b = stats.gpuPanel) == null ? void 0 : _b.canvas);
+        stats.gpuPanel = null;
+        stats._panelId--;
+      }
+    }
+    this.stop();
   }
   onContextRestored(event) {
     event.preventDefault();
     console.log("webglcontextrestored event", event);
-    this.renderer.setAnimationLoop(() => this.render());
-    this.clock.start();
+    this.initContext(this.renderer.getContext());
+    this.needsRedraw = true;
+    this.start();
+  }
+  initContext(context) {
+    var _a2, _b;
+    this.memoryInfoExtension = context.getExtension("GMAN_webgl_memory");
+    void ((_b = (_a2 = this.ui) == null ? void 0 : _a2.stats) == null ? void 0 : _b.init(context));
+  }
+  assertNotDisposed(funcName) {
+    if (this.disposed) {
+      console.warn(`[Renderer.${funcName}]: Renderer is used after being disposed. Please create a new instance.`);
+      return false;
+    }
+    return true;
+  }
+  assertInitialized(funcName) {
+    if (!this.initialized) {
+      console.warn(`[Renderer.${funcName}]: Renderer is not initialized. Please call init() before using it.`);
+      return false;
+    }
+    return true;
   }
+  assertNotInitialized(funcName) {
+    if (this.initialized) {
+      console.warn(`[Renderer.${funcName}]: Renderer is already initialized. Please call init() only once.`);
+      return false;
+    }
+    return true;
+  }
+  assertNotExternalMode(funcName) {
+    if (this.isExternalMode) {
+      console.warn(`[Renderer.${funcName}]: This operation is not supported in external mode.`);
+      return false;
+    }
+    return true;
+  }
+  assertExternalMode(funcName) {
+    if (!this.isExternalMode) {
+      console.warn(`[Renderer.${funcName}]: This operation is only supported in external mode.`);
+      return false;
+    }
+    return true;
+  }
+}
+function guardFn(guard, fn, ...fallback) {
+  return (...args) => {
+    const name = fn.name.split(" ").at(-1);
+    if (!guard(name)) return fallback[0];
+    return fn(...args);
+  };
 }
 export {
   Polygon,