@nebula-spatial/viewer 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @nebula-spatial/viewer
+
+只读的 Three.js Viewer Facade。它接收已经由 Loader 构建好的
+`THREE.Object3D`，负责场景挂载、相机视图、拾取和渲染生命周期，不解析文件，
+也不包含编辑命令、历史或工具系统。
+
+```ts
+import { createViewer } from '@nebula-spatial/viewer';
+
+const viewer = createViewer({
+  viewport: document.querySelector<HTMLElement>('#viewport')!,
+  canvas: document.querySelector<HTMLCanvasElement>('#viewport canvas')!,
+  // Set false when a format-specific selection store owns selection state.
+  autoSelectOnPick: false,
+  // Skip generic raycasting when the consumer resolves semantic picks itself.
+  pointerPick: false,
+});
+
+viewer.addObject(geoNode);
+viewer.fitView(geoNode);
+viewer.setSelection(geoNode);
+viewer.setHighlight(geoNode);
+
+const stopPicking = viewer.on('pick', ({ result }) => {
+  console.log(result?.object ?? null);
+});
+
+const point = viewer.screenToWorldOnPlane(clientX, clientY, 0);
+```
+
+`selectedObject` 和 `highlightedObject` 是 Viewer 会话维护的只读状态。Viewer
+会把画布上的短距离主键点击转换为 `pick` 事件和 selection 更新，也允许调用方
+通过 `pick()` 完成自定义交互编排。`on()` 返回的函数用于注销监听。
+`screenToWorldOnPlane()` 只负责通用的屏幕坐标到世界平面转换；CAD Block 等
+格式语义仍由对应 Loader 或 Product App 解析。
+自定义语义选择可以监听 `pointer-click`，并通过 `pointerPick: false` 跳过默认
+Raycaster；默认配置保持自动 `pick` 和单对象 selection 行为。
+
+Viewer 借用传入的 `Object3D`。`removeObject()` 和 `dispose()` 只解除场景挂载，
+不会释放 Geometry、Material、Texture，也不会调用 Loader 对象的 `dispose()`。
+调用方仍然负责 `GeoNode` 或其他 Loader 资源的生命周期。Viewer 自己创建的
+`SceneRuntime`、Renderer、Camera、Controls 和事件监听由 `dispose()` 统一释放。
+
+`three` 是唯一的运行时 peer dependency。私有的
+`@nebula-spatial/scene-runtime` 只在构建时使用并内联到 Viewer bundle，不是
+消费者需要安装的公共依赖。

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createViewer } from './viewer';
+export type { Viewer, ViewerEventMap, ViewerFitViewOptions, ViewerHighlightOptions, ViewerOptions, ViewerPickOptions, ViewerPickResult, ViewerViewMode, } from './types';

package/dist/index.js

@@ -0,0 +1,487 @@
+var P = Object.defineProperty;
+var C = (c, e, t) => e in c ? P(c, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : c[e] = t;
+var a = (c, e, t) => C(c, typeof e != "symbol" ? e + "" : e, t);
+import { Texture as x, Scene as j, Group as E, Raycaster as V, Vector2 as O, WebGLRenderer as F, Color as I, OrthographicCamera as T, PerspectiveCamera as L, MOUSE as M, TOUCH as R, Vector3 as v, Plane as S, Box3 as w, Object3D as z, BoxHelper as N } from "three";
+import { MapControls as q } from "three/addons/controls/MapControls.js";
+import { OrbitControls as D } from "three/addons/controls/OrbitControls.js";
+const H = [
+  "alphaMap",
+  "aoMap",
+  "bumpMap",
+  "clearcoatMap",
+  "clearcoatNormalMap",
+  "clearcoatRoughnessMap",
+  "displacementMap",
+  "emissiveMap",
+  "envMap",
+  "gradientMap",
+  "iridescenceMap",
+  "iridescenceThicknessMap",
+  "lightMap",
+  "map",
+  "metalnessMap",
+  "normalMap",
+  "roughnessMap",
+  "sheenColorMap",
+  "sheenRoughnessMap",
+  "specularColorMap",
+  "specularIntensityMap",
+  "specularMap",
+  "thicknessMap",
+  "transmissionMap"
+];
+function g(c, e) {
+  e.has(c) || (e.add(c), c.dispose());
+}
+function _(c, e, t) {
+  if (e) {
+    const i = c;
+    for (const s of H) {
+      const r = i[s];
+      r instanceof x && g(r, t);
+    }
+  }
+  g(c, t);
+}
+function A(c, e = {}) {
+  const t = e.disposedResources ?? /* @__PURE__ */ new WeakSet(), i = e.disposeTextures !== !1;
+  c.traverse((s) => {
+    const r = s;
+    r.geometry && g(r.geometry, t);
+    const n = Array.isArray(r.material) ? r.material : [r.material];
+    for (const o of n)
+      o && _(o, i, t);
+    r.renderTarget && g(r.renderTarget, t);
+  });
+}
+const Y = 1e3, W = -1e4, X = 1e4, y = 10, U = 2e6;
+class B {
+  constructor(e) {
+    a(this, "canvasArea");
+    a(this, "canvas");
+    a(this, "scene", new j());
+    a(this, "overlayRoot", new E());
+    a(this, "renderer");
+    a(this, "camera2d");
+    a(this, "camera3d");
+    a(this, "activeCamera");
+    a(this, "controls2d");
+    a(this, "controls3d");
+    a(this, "options");
+    a(this, "mountedObjects", /* @__PURE__ */ new Set());
+    a(this, "ownedObjects", /* @__PURE__ */ new Set());
+    a(this, "overlays", /* @__PURE__ */ new Map());
+    a(this, "eventCleanups", []);
+    a(this, "raycaster", new V());
+    a(this, "pointerNdc", new O());
+    a(this, "viewModeValue");
+    a(this, "initialized", !1);
+    a(this, "disposed", !1);
+    a(this, "renderRequested", !0);
+    a(this, "animationFrameId", null);
+    a(this, "animationLoopActive", !1);
+    a(this, "lastFrameTime", null);
+    a(this, "infoFrames", 0);
+    a(this, "infoLastTime", 0);
+    this.options = e, this.canvasArea = e.canvasArea, this.canvas = e.canvas, this.viewModeValue = e.initialViewMode ?? "2d", this.overlayRoot.name = "scene-runtime:overlays", this.scene.add(this.overlayRoot);
+  }
+  initialize() {
+    if (this.disposed) throw new Error("SceneRuntime has been disposed.");
+    if (this.initialized) return;
+    const e = this.options.factories, t = (e == null ? void 0 : e.createRenderer) ?? ((h) => new F(h)), i = (e == null ? void 0 : e.createMapControls) ?? ((h, d) => new q(h, d)), s = (e == null ? void 0 : e.createOrbitControls) ?? ((h, d) => new D(h, d));
+    this.renderer = t({
+      canvas: this.canvas,
+      antialias: this.options.antialias ?? !0,
+      alpha: this.options.alpha ?? !1,
+      powerPreference: this.options.powerPreference ?? "high-performance"
+    }), this.options.clearColor !== void 0 && this.renderer.setClearColor(new I(this.options.clearColor));
+    const r = Math.max(1, this.canvasArea.clientWidth || 1), n = Math.max(1, this.canvasArea.clientHeight || 1), o = r / n;
+    this.renderer.setPixelRatio(this.readDevicePixelRatio()), this.renderer.setSize(r, n, !1), this.camera2d = new T(-o, o, 1, -1, W, X), this.camera2d.position.set(0, 0, 1), this.camera2d.lookAt(0, 0, 0), this.camera3d = new L(40, o, y, U), this.camera3d.up.set(0, 0, 1), this.camera3d.position.set(1e4, 0, 1e4), this.camera3d.lookAt(0, 0, 0), this.controls2d = i(this.camera2d, this.renderer.domElement), this.controls2d.enableRotate = !1, this.controls2d.screenSpacePanning = !0, this.controls2d.zoomToCursor = !0, this.controls2d.minZoom = 2e-3, this.controls2d.maxZoom = 5e4, this.controls2d.mouseButtons = {
+      LEFT: M.PAN,
+      MIDDLE: M.DOLLY,
+      RIGHT: M.PAN
+    }, this.controls2d.touches = {
+      ONE: R.PAN,
+      TWO: R.DOLLY_PAN
+    }, this.controls3d = s(this.camera3d, this.renderer.domElement), this.controls3d.enablePan = !1, this.listen(this.controls2d, "change", () => this.requestRender()), this.listen(this.controls3d, "change", () => this.requestRender()), this.initialized = !0, this.setViewMode(this.viewModeValue);
+  }
+  get isInitialized() {
+    return this.initialized;
+  }
+  get isDisposed() {
+    return this.disposed;
+  }
+  get viewMode() {
+    return this.viewModeValue;
+  }
+  get needsRender() {
+    return this.renderRequested;
+  }
+  set needsRender(e) {
+    this.renderRequested = e;
+  }
+  requestRender() {
+    this.disposed || (this.renderRequested = !0);
+  }
+  setClearColor(e) {
+    var t;
+    (t = this.renderer) == null || t.setClearColor(e), this.requestRender();
+  }
+  setViewMode(e) {
+    this.viewModeValue = e, !(!this.camera2d || !this.camera3d) && (this.activeCamera = e === "3d" ? this.camera3d : this.camera2d, this.controls2d && (this.controls2d.enabled = e === "2d"), this.controls3d && (this.controls3d.enabled = e === "3d"), this.requestRender());
+  }
+  setPerspectivePose(e, t) {
+    var i;
+    return !this.camera3d || ![e.x, e.y, e.z, t.x, t.y, t.z].every(Number.isFinite) ? !1 : (this.camera3d.position.copy(e), this.camera3d.lookAt(t), this.camera3d.updateProjectionMatrix(), (i = this.controls3d) == null || i.target.copy(t), this.requestRender(), !0);
+  }
+  setPerspectiveAspect(e) {
+    return !this.camera3d || !Number.isFinite(e) || e <= 0 ? !1 : (this.camera3d.aspect = e, this.camera3d.updateProjectionMatrix(), this.requestRender(), !0);
+  }
+  setOrthographicViewport(e) {
+    var t;
+    return !this.camera2d || ![
+      e.left,
+      e.right,
+      e.top,
+      e.bottom,
+      e.zoom,
+      e.positionX,
+      e.positionY,
+      e.targetX,
+      e.targetY
+    ].every(Number.isFinite) || e.left >= e.right || e.bottom >= e.top || e.zoom <= 0 ? !1 : (this.camera2d.left = e.left, this.camera2d.right = e.right, this.camera2d.top = e.top, this.camera2d.bottom = e.bottom, this.camera2d.zoom = e.zoom, this.camera2d.position.set(e.positionX, e.positionY, 1), this.camera2d.updateProjectionMatrix(), (t = this.controls2d) != null && t.target && (this.controls2d.target.set(e.targetX, e.targetY, 0), this.controls2d.update()), this.requestRender(), !0);
+  }
+  addObject(e, t = {}) {
+    if (this.disposed) throw new Error("SceneRuntime has been disposed.");
+    this.mountedObjects.has(e) && e.parent === this.scene || (this.scene.add(e), this.mountedObjects.add(e), t.owned && this.ownedObjects.add(e), this.requestRender());
+  }
+  removeObject(e, t = {}) {
+    if (!this.mountedObjects.has(e) && e.parent !== this.scene) return !1;
+    e.removeFromParent(), this.mountedObjects.delete(e);
+    const i = this.ownedObjects.delete(e);
+    return (t.dispose === !0 || t.dispose === void 0 && i) && A(e), this.requestRender(), !0;
+  }
+  setObjectVisible(e, t) {
+    e.visible !== t && (e.visible = t, this.requestRender());
+  }
+  mountOverlay(e, t, i = {}) {
+    this.removeOverlay(e), this.overlayRoot.parent !== this.scene && this.scene.add(this.overlayRoot), this.overlayRoot.add(t), this.overlays.set(e, { object: t, owned: i.owned === !0 }), this.requestRender();
+  }
+  removeOverlay(e, t = {}) {
+    const i = this.overlays.get(e);
+    return i ? (this.overlays.delete(e), i.object.removeFromParent(), (t.dispose === !0 || t.dispose === void 0 && i.owned) && A(i.object), this.requestRender(), i.object) : null;
+  }
+  setHighlight(e, t = {}) {
+    if (!e) {
+      this.removeOverlay("highlight");
+      return;
+    }
+    this.mountOverlay("highlight", e, t);
+  }
+  resize() {
+    if (!this.renderer) return !1;
+    const e = this.canvasArea.clientWidth, t = this.canvasArea.clientHeight;
+    if (!Number.isFinite(e) || !Number.isFinite(t) || e <= 0 || t <= 0) return !1;
+    if (this.renderer.setPixelRatio(this.readDevicePixelRatio()), this.renderer.setSize(e, t, !1), this.camera2d) {
+      const i = (this.camera2d.top - this.camera2d.bottom) / 2, s = i * (e / t), r = (this.camera2d.left + this.camera2d.right) / 2, n = (this.camera2d.top + this.camera2d.bottom) / 2;
+      this.camera2d.left = r - s, this.camera2d.right = r + s, this.camera2d.top = n + i, this.camera2d.bottom = n - i, this.camera2d.updateProjectionMatrix();
+    }
+    return this.camera3d && (this.camera3d.aspect = e / t, this.camera3d.updateProjectionMatrix()), this.requestRender(), !0;
+  }
+  fitView(e, t = {}) {
+    if (!this.camera2d || !this.camera3d) return !1;
+    const i = this.resolveBox3(e);
+    if (!i || i.isEmpty()) return !1;
+    const s = i.getSize(new v()), r = i.getCenter(new v());
+    if (![s.x, s.y, s.z, r.x, r.y, r.z].every(Number.isFinite)) return !1;
+    const n = Math.max(1, t.padding ?? 1.05);
+    if ((t.viewMode ?? this.viewModeValue) === "2d") {
+      const h = Math.max(s.x, 1e-6) * n, d = Math.max(s.y, 1e-6) * n, l = Math.max(1, this.canvasArea.clientWidth), f = Math.max(1, this.canvasArea.clientHeight), p = l / f;
+      let u = h / 2, m = d / 2;
+      u / m < p ? u = m * p : m = u / p, this.camera2d.left = -u, this.camera2d.right = u, this.camera2d.top = m, this.camera2d.bottom = -m, this.camera2d.zoom = 1, this.camera2d.position.set(r.x, r.y, Math.max(r.z + 1, 1)), this.camera2d.updateProjectionMatrix(), this.controls2d.target.copy(r), this.controls2d.update();
+    } else {
+      const h = r.clone(), d = this.camera3d.fov * Math.PI / 180, l = 2 * Math.atan(Math.tan(d / 2) * Math.max(this.camera3d.aspect, 1e-6)), f = Math.max(s.length() / 2, 1e-6), p = Math.max(Math.min(d, l) / 2, 1e-6), u = f / Math.sin(p) * n, m = this.camera3d.position.clone().sub(this.controls3d.target);
+      m.lengthSq() <= 1e-12 && m.set(1, -1, 1), m.normalize(), this.controls3d.target.copy(h), this.camera3d.position.copy(h).addScaledVector(m, u), this.camera3d.lookAt(h), this.camera3d.near = Math.min(
+        y,
+        Math.max(u * 0.01, 1e-6)
+      ), this.camera3d.updateProjectionMatrix(), this.controls3d.update();
+    }
+    return this.requestRender(), !0;
+  }
+  clientToNdc(e, t, i = new O()) {
+    var n;
+    const s = (n = this.renderer) == null ? void 0 : n.domElement;
+    if (!s) return null;
+    const r = s.getBoundingClientRect();
+    return !Number.isFinite(r.width) || !Number.isFinite(r.height) || r.width <= 0 || r.height <= 0 ? null : (i.set(
+      (e - r.left) / r.width * 2 - 1,
+      -((t - r.top) / r.height) * 2 + 1
+    ), i);
+  }
+  screenToWorldOnPlane(e, t, i = 0) {
+    const s = this.clientToNdc(e, t, this.pointerNdc);
+    return !s || !this.activeCamera ? null : (this.raycaster.setFromCamera(s, this.activeCamera), this.raycaster.ray.intersectPlane(new S(new v(0, 0, 1), -i), new v()));
+  }
+  worldToClient(e, t = new O()) {
+    var n;
+    const i = (n = this.renderer) == null ? void 0 : n.domElement;
+    if (!i || !this.activeCamera) return null;
+    const s = i.getBoundingClientRect();
+    if (!Number.isFinite(s.width) || !Number.isFinite(s.height) || s.width <= 0 || s.height <= 0) return null;
+    const r = e.clone().project(this.activeCamera);
+    return t.set(
+      s.left + (r.x + 1) / 2 * s.width,
+      s.top + (1 - r.y) / 2 * s.height
+    ), t;
+  }
+  pick(e, t, i = {}) {
+    const s = this.clientToNdc(e, t, this.pointerNdc);
+    if (!s || !this.activeCamera) return null;
+    const r = i.roots ?? [...this.mountedObjects], n = i.includeInvisible ? r : r.filter((l) => l.visible);
+    this.raycaster.setFromCamera(s, this.activeCamera);
+    const [o] = this.raycaster.intersectObjects([...n], i.recursive !== !1);
+    if (!o) return null;
+    const d = n.find((l) => l === o.object || this.isDescendantOf(o.object, l)) ?? o.object;
+    return {
+      object: o.object,
+      root: d,
+      point: o.point.clone(),
+      distance: o.distance,
+      faceIndex: o.faceIndex ?? null,
+      instanceId: o.instanceId,
+      intersection: o
+    };
+  }
+  startAnimation(e = {}) {
+    if (this.disposed || this.animationLoopActive) return;
+    this.animationLoopActive = !0, this.infoFrames = 0, this.infoLastTime = performance.now();
+    const t = e.infoUpdateIntervalMs ?? Y, i = (s = performance.now()) => {
+      var o, h, d, l, f, p, u;
+      if (!this.animationLoopActive || this.disposed) {
+        this.animationFrameId = null;
+        return;
+      }
+      this.animationFrameId = requestAnimationFrame(i);
+      const r = this.lastFrameTime === null ? 0 : Math.max(0, (s - this.lastFrameTime) / 1e3);
+      this.lastFrameTime = s, this.viewModeValue === "2d" && ((o = this.controls2d) == null || o.update()), (h = e.onFrame) == null || h.call(e, s, r);
+      let n = !1;
+      this.renderRequested && (((d = e.shouldRender) == null ? void 0 : d.call(e, s)) ?? !0) && ((l = e.beforeRender) == null || l.call(e, s), this.renderer.render(this.scene, this.activeCamera), this.renderRequested = !1, n = !0, (f = e.afterRender) == null || f.call(e, s)), this.infoFrames += 1, s - this.infoLastTime >= t ? (this.infoFrames = 0, this.infoLastTime = s, (p = e.onInfoUpdate) == null || p.call(e)) : n && ((u = e.onInfoUpdate) == null || u.call(e));
+    };
+    i();
+  }
+  stopAnimation() {
+    this.animationLoopActive = !1, this.animationFrameId !== null && typeof cancelAnimationFrame == "function" && cancelAnimationFrame(this.animationFrameId), this.animationFrameId = null, this.lastFrameTime = null;
+  }
+  dispose() {
+    var e, t, i, s, r, n, o;
+    if (!this.disposed) {
+      for (this.disposed = !0, this.stopAnimation(); this.eventCleanups.length > 0; ) (e = this.eventCleanups.pop()) == null || e();
+      for (const h of [...this.overlays.keys()]) this.removeOverlay(h);
+      for (const h of [...this.mountedObjects]) this.removeObject(h);
+      (i = (t = this.controls2d) == null ? void 0 : t.dispose) == null || i.call(t), (r = (s = this.controls3d) == null ? void 0 : s.dispose) == null || r.call(s), (o = (n = this.renderer) == null ? void 0 : n.dispose) == null || o.call(n);
+    }
+  }
+  readDevicePixelRatio() {
+    const e = globalThis.devicePixelRatio;
+    return typeof e == "number" && Number.isFinite(e) && e > 0 ? e : 1;
+  }
+  resolveBox3(e) {
+    if (e instanceof w) return e.clone();
+    if (e instanceof z) return new w().setFromObject(e);
+    const { minX: t, minY: i, maxX: s, maxY: r } = e;
+    return ![t, i, s, r].every(Number.isFinite) || s < t || r < i ? null : new w(new v(t, i, 0), new v(s, r, 0));
+  }
+  isDescendantOf(e, t) {
+    let i = e.parent;
+    for (; i; ) {
+      if (i === t) return !0;
+      i = i.parent;
+    }
+    return !1;
+  }
+  listen(e, t, i) {
+    e.addEventListener(t, i), this.eventCleanups.push(() => {
+      var s;
+      return (s = e.removeEventListener) == null ? void 0 : s.call(e, t, i);
+    });
+  }
+}
+const b = "viewer:highlight", K = 6;
+class G {
+  constructor(e, t) {
+    a(this, "mountedObjects", /* @__PURE__ */ new Set());
+    a(this, "listeners", /* @__PURE__ */ new Map());
+    a(this, "selectedObjectValue", null);
+    a(this, "highlightedObjectValue", null);
+    a(this, "pointerStart", null);
+    a(this, "disposed", !1);
+    a(this, "handlePointerDown", (e) => {
+      this.disposed || (this.pointerStart = {
+        pointerId: e.pointerId,
+        clientX: e.clientX,
+        clientY: e.clientY,
+        button: e.button
+      });
+    });
+    a(this, "handlePointerUp", (e) => {
+      const t = this.pointerStart;
+      if (this.pointerStart = null, this.disposed || !t || t.pointerId !== e.pointerId || t.button !== 0 || e.button !== 0 || Math.hypot(e.clientX - t.clientX, e.clientY - t.clientY) > K)
+        return;
+      const i = {
+        clientX: e.clientX,
+        clientY: e.clientY,
+        shiftKey: e.shiftKey,
+        ctrlKey: e.ctrlKey,
+        metaKey: e.metaKey
+      };
+      if (this.emit("pointer-click", i), this.options.pointerPick === !1) return;
+      const s = this.pick(e.clientX, e.clientY);
+      this.emit("pick", {
+        ...i,
+        result: s
+      }), this.options.autoSelectOnPick !== !1 && this.setSelection((s == null ? void 0 : s.object) ?? null);
+    });
+    a(this, "handlePointerCancel", () => {
+      this.pointerStart = null;
+    });
+    var i, s, r, n, o, h;
+    this.options = e, this.runtime = t, (s = (i = this.options.canvas).addEventListener) == null || s.call(i, "pointerdown", this.handlePointerDown), (n = (r = this.options.canvas).addEventListener) == null || n.call(r, "pointerup", this.handlePointerUp), (h = (o = this.options.canvas).addEventListener) == null || h.call(o, "pointercancel", this.handlePointerCancel);
+  }
+  get viewport() {
+    return this.options.viewport;
+  }
+  get canvas() {
+    return this.options.canvas;
+  }
+  get viewMode() {
+    return this.runtime.viewMode;
+  }
+  get selectedObject() {
+    return this.selectedObjectValue;
+  }
+  get highlightedObject() {
+    return this.highlightedObjectValue;
+  }
+  get isDisposed() {
+    return this.disposed;
+  }
+  addObject(e) {
+    this.assertActive(), !this.mountedObjects.has(e) && (this.runtime.addObject(e), this.mountedObjects.add(e));
+  }
+  removeObject(e) {
+    if (this.assertActive(), !this.mountedObjects.has(e)) return !1;
+    this.selectedObjectValue && this.isObjectWithinRoot(this.selectedObjectValue, e) && this.setSelection(null), this.highlightedObjectValue && this.isObjectWithinRoot(this.highlightedObjectValue, e) && this.setHighlight(null);
+    const t = this.runtime.removeObject(e, { dispose: !1 });
+    return t && this.mountedObjects.delete(e), t;
+  }
+  setVisible(e, t) {
+    this.assertActive(), this.assertMounted(e), this.runtime.setObjectVisible(e, t);
+  }
+  setViewMode(e) {
+    this.assertActive(), e !== this.runtime.viewMode && (this.runtime.setViewMode(e), this.emit("view-mode-change", { viewMode: e }));
+  }
+  fitView(e, t) {
+    this.assertActive(), e && !(e instanceof w) && this.assertMounted(e);
+    const i = e ?? this.resolveMountedBounds();
+    return i ? this.runtime.fitView(i, t) : !1;
+  }
+  screenToWorldOnPlane(e, t, i = 0) {
+    var s;
+    return this.assertActive(), ((s = this.runtime.screenToWorldOnPlane(e, t, i)) == null ? void 0 : s.clone()) ?? null;
+  }
+  pick(e, t, i) {
+    var r;
+    this.assertActive(), (r = i == null ? void 0 : i.roots) == null || r.forEach((n) => this.assertMounted(n));
+    const s = this.runtime.pick(e, t, i);
+    return s ? {
+      object: s.object,
+      root: s.root,
+      point: s.point.clone(),
+      distance: s.distance,
+      faceIndex: s.faceIndex,
+      ...s.instanceId === void 0 ? {} : { instanceId: s.instanceId }
+    } : null;
+  }
+  setSelection(e) {
+    this.assertActive(), e && this.assertMounted(e), e !== this.selectedObjectValue && (this.selectedObjectValue = e, this.runtime.requestRender(), this.emit("selection-change", { object: e }));
+  }
+  setHighlight(e, t = {}) {
+    if (this.assertActive(), e && this.assertMounted(e), !(this.highlightedObjectValue === null && e === null)) {
+      if (this.runtime.removeOverlay(b), this.highlightedObjectValue = e, e) {
+        const i = new N(e, t.color ?? 6000111);
+        i.name = b, this.runtime.mountOverlay(b, i, { owned: !0 });
+      }
+      this.emit("highlight-change", { object: e });
+    }
+  }
+  on(e, t) {
+    this.assertActive();
+    const i = t, s = this.listeners.get(e) ?? /* @__PURE__ */ new Set();
+    s.add(i), this.listeners.set(e, s);
+    let r = !0;
+    return () => {
+      r && (r = !1, s.delete(i), s.size === 0 && this.listeners.delete(e));
+    };
+  }
+  resize() {
+    this.assertActive();
+    const e = this.runtime.resize();
+    return this.emit("resize", { resized: e }), e;
+  }
+  requestRender() {
+    this.assertActive(), this.runtime.requestRender();
+  }
+  dispose() {
+    var e, t, i, s, r, n;
+    if (!this.disposed) {
+      this.disposed = !0, (t = (e = this.options.canvas).removeEventListener) == null || t.call(e, "pointerdown", this.handlePointerDown), (s = (i = this.options.canvas).removeEventListener) == null || s.call(i, "pointerup", this.handlePointerUp), (n = (r = this.options.canvas).removeEventListener) == null || n.call(r, "pointercancel", this.handlePointerCancel), this.pointerStart = null, this.highlightedObjectValue && this.runtime.removeOverlay(b), this.highlightedObjectValue = null, this.selectedObjectValue = null;
+      for (const o of this.mountedObjects)
+        this.runtime.removeObject(o, { dispose: !1 });
+      this.mountedObjects.clear(), this.listeners.clear(), this.runtime.dispose();
+    }
+  }
+  resolveMountedBounds() {
+    const e = new w();
+    let t = !1;
+    for (const i of this.mountedObjects)
+      i.visible && (e.expandByObject(i), t = !0);
+    return t && !e.isEmpty() ? e : null;
+  }
+  assertActive() {
+    if (this.disposed) throw new Error("Viewer has been disposed.");
+  }
+  assertMounted(e) {
+    for (const t of this.mountedObjects)
+      if (this.isObjectWithinRoot(e, t)) return;
+    throw new Error("Viewer can only modify mounted objects.");
+  }
+  isObjectWithinRoot(e, t) {
+    let i = e;
+    for (; i; ) {
+      if (i === t) return !0;
+      i = i.parent;
+    }
+    return !1;
+  }
+  emit(e, t) {
+    for (const i of this.listeners.get(e) ?? []) i(t);
+  }
+}
+function ee(c) {
+  const e = new B({
+    canvasArea: c.viewport,
+    canvas: c.canvas,
+    clearColor: c.clearColor,
+    antialias: c.antialias,
+    alpha: c.alpha,
+    powerPreference: c.powerPreference,
+    initialViewMode: c.initialViewMode
+  });
+  return Z(c, e);
+}
+function Z(c, e) {
+  return e.initialize(), e.startAnimation(), new G(c, e);
+}
+export {
+  ee as createViewer
+};

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+import type { Box3, ColorRepresentation, Object3D, Vector3 } from 'three';
+export type ViewerViewMode = '2d' | '3d';
+export interface ViewerOptions {
+    viewport: HTMLElement;
+    canvas: HTMLCanvasElement;
+    clearColor?: ColorRepresentation;
+    antialias?: boolean;
+    alpha?: boolean;
+    powerPreference?: WebGLPowerPreference;
+    initialViewMode?: ViewerViewMode;
+    autoSelectOnPick?: boolean;
+    pointerPick?: boolean;
+}
+export interface ViewerFitViewOptions {
+    padding?: number;
+    viewMode?: ViewerViewMode;
+}
+export interface ViewerPickOptions {
+    roots?: readonly Object3D[];
+    recursive?: boolean;
+    includeInvisible?: boolean;
+}
+export interface ViewerPickResult {
+    object: Object3D;
+    root: Object3D;
+    point: Vector3;
+    distance: number;
+    faceIndex: number | null;
+    instanceId?: number;
+}
+export interface ViewerHighlightOptions {
+    color?: ColorRepresentation;
+}
+export interface ViewerEventMap {
+    'pointer-click': {
+        clientX: number;
+        clientY: number;
+        shiftKey: boolean;
+        ctrlKey: boolean;
+        metaKey: boolean;
+    };
+    pick: {
+        clientX: number;
+        clientY: number;
+        shiftKey: boolean;
+        ctrlKey: boolean;
+        metaKey: boolean;
+        result: ViewerPickResult | null;
+    };
+    'selection-change': {
+        object: Object3D | null;
+    };
+    'highlight-change': {
+        object: Object3D | null;
+    };
+    'view-mode-change': {
+        viewMode: ViewerViewMode;
+    };
+    resize: {
+        resized: boolean;
+    };
+}
+export interface Viewer {
+    readonly viewport: HTMLElement;
+    readonly canvas: HTMLCanvasElement;
+    readonly viewMode: ViewerViewMode;
+    readonly selectedObject: Object3D | null;
+    readonly highlightedObject: Object3D | null;
+    readonly isDisposed: boolean;
+    addObject(object: Object3D): void;
+    removeObject(object: Object3D): boolean;
+    setVisible(object: Object3D, visible: boolean): void;
+    setViewMode(mode: ViewerViewMode): void;
+    fitView(target?: Object3D | Box3, options?: ViewerFitViewOptions): boolean;
+    screenToWorldOnPlane(clientX: number, clientY: number, planeZ?: number): Vector3 | null;
+    pick(clientX: number, clientY: number, options?: ViewerPickOptions): ViewerPickResult | null;
+    setSelection(object: Object3D | null): void;
+    setHighlight(object: Object3D | null, options?: ViewerHighlightOptions): void;
+    on<K extends keyof ViewerEventMap>(type: K, listener: (event: ViewerEventMap[K]) => void): () => void;
+    resize(): boolean;
+    requestRender(): void;
+    dispose(): void;
+}

package/dist/viewer.d.ts

@@ -0,0 +1,2 @@
+import type { Viewer, ViewerOptions } from './types';
+export declare function createViewer(options: ViewerOptions): Viewer;

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@nebula-spatial/viewer",
+  "version": "0.1.0",
+  "description": "Read-only Three.js viewer facade",
+  "license": "ISC",
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "package.json"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "npm run check:boundary && npm run typecheck && npm run build:bundle && npm run build:types && npm run check:dist",
+    "build:bundle": "vite build --config vite.config.ts",
+    "build:types": "tsc --project tsconfig.build.json",
+    "check:boundary": "node scripts/check-boundary.mjs",
+    "check:dist": "node scripts/check-dist.mjs",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "pack:dry": "npm pack --dry-run",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "three": "0.182.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@types/three": "0.182.0",
+    "three": "0.182.0",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.10",
+    "vitest": "^2.1.8"
+  }
+}