@navaramap/three-plugins 0.0.4 → 0.0.5

package/dist/index.d.ts

@@ -388,8 +388,28 @@ export declare type TileJson = {
     maxzoom?: number;
     /** Tiling scheme. `"tms"` flips the Y axis (raster sources only). @defaultValue "xyz" */
     scheme?: "xyz" | "tms";
+    /**
+     * Tile size in pixels. Not part of the TileJSON spec, but emitted by
+     * MapLibre-oriented tile servers; applied to `raster-dem` sources only.
+     * @defaultValue 512
+     */
+    tileSize?: number;
+    /**
+     * Elevation encoding of DEM tiles. Not part of the TileJSON spec, but
+     * emitted by MapLibre-oriented tile servers; applied to `raster-dem` sources
+     * only.
+     * @defaultValue "mapbox"
+     */
+    encoding?: TileJsonDemEncoding;
 };
 
+/**
+ * How a `raster-dem` document's RGB tiles encode elevation, matching MapLibre's
+ * `encoding` values. MapLibre's `"custom"` (free-form decode factors) is not
+ * supported.
+ */
+export declare type TileJsonDemEncoding = "mapbox" | "terrarium";
+
 /** Detail passed to the {@link TileJsonPlugin} `loaded` event. */
 export declare type TileJsonLoadedEvent = {
     /** The Navara source created for the document. */
@@ -420,9 +440,13 @@ export declare class TileJsonPlugin extends Plugin_2<View_4, ViewContext> {
      *
      * `desc.url` is the TileJSON document URL; the plugin fetches it, then creates
      * one source of the requested `desc.type` using the document's first tile
-     * endpoint, `minzoom`/`maxzoom`, and `scheme`. The document's `attribution` is
-     * surfaced through the view's built-in attribution UI (`view.attribution`), and
-     * a `loaded` event is emitted carrying the source, document, and attribution.
+     * endpoint, `minzoom`/`maxzoom`, and `scheme` — plus, for `raster-dem`, the
+     * MapLibre-compatible `tileSize` and `encoding` fields (defaulting to
+     * MapLibre's 512 and `"mapbox"`). Each of those fields can also be set on
+     * `desc` itself, taking precedence over the document. The document's
+     * `attribution` is surfaced through the view's built-in attribution UI
+     * (`view.attribution`), and a `loaded` event is emitted carrying the source,
+     * document, and attribution.
      *
      * A TileJSON `tiles` array lists mirror endpoints for the same tileset (as in
      * MapLibre, which shards requests across them). Navara sources take a single
@@ -456,15 +480,36 @@ export declare type TileJsonPluginEventMap = {
     loaded: (event: TileJsonLoadedEvent) => void;
 };
 
+/** Registers a TileJSON document as a `raster-dem` (elevation) source. */
+export declare type TileJsonRasterDemSourceDescription = TileJsonSourceDescriptionBase & {
+    type: "raster-dem";
+    /** Overrides the document's `tileSize` when set. @defaultValue 512 */
+    tileSize?: number;
+    /** Overrides the document's `encoding` when set. @defaultValue "mapbox" */
+    encoding?: TileJsonDemEncoding;
+};
+
+/** Registers a TileJSON document as a `raster-tile` (imagery) source. */
+export declare type TileJsonRasterTileSourceDescription = TileJsonSourceDescriptionBase & {
+    type: "raster-tile";
+};
+
 /**
  * Describes a TileJSON tile source to register via {@link TileJsonPlugin.addSource}.
  * Mirrors the shape of {@link ThreeView.addSource}, except `url` is the TileJSON
  * document URL (not a tile template) — the plugin fetches it and derives the tile
- * URL, zoom range, and attribution from the document.
+ * URL, zoom range, and attribution from the document. Document-derived fields
+ * (`minzoom`, `maxzoom`, `scheme` — plus `tileSize` and `encoding` for
+ * `raster-dem`) can also be set here to take precedence over the document.
  */
-export declare type TileJsonSourceDescription = {
-    /** Navara source type to create, as in `addSource`. */
-    type: TileJsonSourceType;
+export declare type TileJsonSourceDescription = TileJsonRasterTileSourceDescription | TileJsonVectorTileSourceDescription | TileJsonRasterDemSourceDescription;
+
+/**
+ * Fields shared by every {@link TileJsonSourceDescription} variant. Alongside
+ * `url` and `id`, it accepts the same optional fields the TileJSON document
+ * carries; a field set here takes precedence over the fetched document's value.
+ */
+declare type TileJsonSourceDescriptionBase = {
     /** URL of the TileJSON 3.0.0 document to fetch and expand. */
     url: string;
     /**
@@ -473,14 +518,25 @@ export declare type TileJsonSourceDescription = {
      * handle. When omitted, the engine generates one.
      */
     id?: string;
+    /** Overrides the document's `minzoom` when set. */
+    minzoom?: number;
+    /** Overrides the document's `maxzoom` when set. */
+    maxzoom?: number;
+    /** Overrides the document's `scheme` when set. */
+    scheme?: "xyz" | "tms";
 };
 
 /**
  * Which Navara source type a TileJSON document is materialized into. Declared by
  * the caller because TileJSON has no field that reliably distinguishes raster
- * imagery from vector tiles.
+ * imagery from vector or elevation tiles.
  */
-export declare type TileJsonSourceType = "raster-tile" | "vector-tile";
+export declare type TileJsonSourceType = "raster-tile" | "vector-tile" | "raster-dem";
+
+/** Registers a TileJSON document as a `vector-tile` (MVT) source. */
+export declare type TileJsonVectorTileSourceDescription = TileJsonSourceDescriptionBase & {
+    type: "vector-tile";
+};
 
 declare type UpdateListener = (state: OverlayState) => void;
 

package/dist/index.js

@@ -1,11 +1,11 @@
-import { EventHandler as e, Plugin as t, convertWorldToScreen as n, degreeToRadian as r, eastNorthUpToFixedFrame as i, geodeticToVector3 as a, radianToDegree as o, vector3ToGeodetic as s } from "@navaramap/three";
-import { Matrix4 as c, Vector3 as l } from "three";
+import { EventHandler as e, MAPBOX_ELEVATION_DECODER as t, Plugin as n, TERRARIUM_ELEVATION_DECODER as r, convertWorldToScreen as i, degreeToRadian as a, eastNorthUpToFixedFrame as o, geodeticToVector3 as s, radianToDegree as c, vector3ToGeodetic as l } from "@navaramap/three";
+import { Matrix4 as u, Vector3 as d } from "three";
 //#region src/PersonViewPlugin.ts
-var u = {
+var f = {
 	x: 0,
 	y: 0,
 	z: 0
-}, d = {
+}, p = {
 	forward: ["KeyW"],
 	backward: ["KeyS"],
 	turnLeft: ["KeyA"],
@@ -19,7 +19,7 @@ var u = {
 	dash: ["ShiftLeft", "ShiftRight"],
 	orbitCamera: ["AltLeft", "AltRight"],
 	toggleView: ["KeyV"]
-}, f = {
+}, m = {
 	allowCameraControl: !1,
 	initialView: "tpv",
 	moveSpeed: 50,
@@ -37,7 +37,7 @@ var u = {
 	startLng: 139.7671,
 	startHeight: 500,
 	startHeading: Math.PI * 1.3
-}, p = 3, m = 1e3, h = class extends t {
+}, h = 3, g = 1e3, _ = class extends n {
 	view;
 	config;
 	character;
@@ -60,21 +60,21 @@ var u = {
 	movementSuppressed = !1;
 	boundKeyDown;
 	boundKeyUp;
-	_curPos = new l();
-	_east = new l();
-	_north = new l();
-	_worldForward = new l();
-	_offset = new l();
-	_headingMatrix = new c();
-	_characterFrame = new c();
+	_curPos = new d();
+	_east = new d();
+	_north = new d();
+	_worldForward = new d();
+	_offset = new d();
+	_headingMatrix = new u();
+	_characterFrame = new u();
 	constructor(e = {}) {
 		super();
 		let { character: t, keys: n, ...r } = e;
 		this.config = {
-			...f,
+			...m,
 			...r
 		}, this.character = t ? this.resolveCharacter(t) : null, this.keys = {
-			...d,
+			...p,
 			...n
 		}, this.keyToAction = this.buildKeyMap(this.keys), this.modelHeading = this.config.startHeading, this.cameraHeading = this.config.startHeading, this.viewMode = this.config.initialView, this.currentAnimState = this.character ? this.character.animation.idleClip : null, this.boundKeyDown = this.onKeyDown.bind(this), this.boundKeyUp = this.onKeyUp.bind(this);
 	}
@@ -92,18 +92,18 @@ var u = {
 	start() {
 		if (!this.view || this.animId != null) return;
 		this.animId = -1;
-		let { startLat: e, startLng: t, startHeight: n, startHeading: i } = this.config, o = a({
-			lat: r(e),
-			lng: r(t),
+		let { startLat: e, startLng: t, startHeight: n, startHeading: r } = this.config, i = s({
+			lat: a(e),
+			lng: a(t),
 			height: n
 		});
-		if (this.modelHeading = i, this.cameraHeading = i, this.character) {
-			let { animation: e, modelRotationOffset: t, modelScale: n, castShadow: r, receiveShadow: a } = this.character;
+		if (this.modelHeading = r, this.cameraHeading = r, this.character) {
+			let { animation: e, modelRotationOffset: t, modelScale: n, castShadow: a, receiveShadow: o } = this.character;
 			this.handle = this.view.addMesh({
 				gltfModel: {
 					url: this.character.modelUrl,
-					castShadow: r,
-					receiveShadow: a,
+					castShadow: a,
+					receiveShadow: o,
 					animationEnabled: !0,
 					animationAutoPlay: !0,
 					animationActiveClip: e.idleClip,
@@ -111,7 +111,7 @@ var u = {
 					animationLoop: !0,
 					animationCrossfadeDuration: e.crossfadeDuration
 				},
-				matrixWorld: this.composeCharacterFrame(o, i),
+				matrixWorld: this.composeCharacterFrame(i, r),
 				rotation: {
 					x: t.x,
 					y: t.y,
@@ -130,20 +130,20 @@ var u = {
 	}
 	teleport(e) {
 		if (!this.view) return;
-		let { lng: t, lat: n, alt: i } = e, o = e.heading == null ? this.cameraHeading : e.heading;
+		let { lng: t, lat: n, alt: r } = e, i = e.heading == null ? this.cameraHeading : e.heading;
 		if (this.handle && this.character) {
-			let e = a({
-				lat: r(n),
-				lng: r(t),
-				height: i
+			let e = s({
+				lat: a(n),
+				lng: a(t),
+				height: r
 			});
-			this.handle.update({ matrixWorld: this.composeCharacterFrame(e, o) });
+			this.handle.update({ matrixWorld: this.composeCharacterFrame(e, i) });
 		}
-		this.modelHeading = o, this.cameraHeading = o, this.placeChaseCamera(n, t, i, o), this.state = {
+		this.modelHeading = i, this.cameraHeading = i, this.placeChaseCamera(n, t, r, i), this.state = {
 			lng: t,
 			lat: n,
-			alt: i,
-			heading: o,
+			alt: r,
+			heading: i,
 			speed: 0,
 			animationState: this.currentAnimState,
 			mode: this.viewMode
@@ -169,16 +169,16 @@ var u = {
 	}
 	setHeading(e) {
 		if (!this.view) return;
-		let { lat: t, lng: n, alt: i } = this.state;
+		let { lat: t, lng: n, alt: r } = this.state;
 		if (this.modelHeading = e, this.cameraHeading = e, this.handle && this.character) {
-			let o = a({
-				lat: r(t),
-				lng: r(n),
-				height: i
+			let i = s({
+				lat: a(t),
+				lng: a(n),
+				height: r
 			});
-			this.handle.update({ matrixWorld: this.composeCharacterFrame(o, e) });
+			this.handle.update({ matrixWorld: this.composeCharacterFrame(i, e) });
 		}
-		this.isFreeCamera() || this.placeChaseCamera(t, n, i, e), this.state = {
+		this.isFreeCamera() || this.placeChaseCamera(t, n, r, e), this.state = {
 			...this.state,
 			heading: e
 		}, this.notify();
@@ -212,10 +212,10 @@ var u = {
 			modelUrl: e.modelUrl,
 			animation: e.animation,
 			modelRotationOffset: e.modelRotationOffset ? {
-				...u,
+				...f,
 				...e.modelRotationOffset
-			} : u,
-			modelScale: e.modelScale ?? p,
+			} : f,
+			modelScale: e.modelScale ?? h,
 			hideModelInFpv: e.hideModelInFpv ?? !0,
 			castShadow: e.castShadow ?? !1,
 			receiveShadow: e.receiveShadow ?? !1
@@ -246,7 +246,7 @@ var u = {
 		if (!this.view) return;
 		let { cameraDistance: i, cameraPitch: a, fpvPitch: o, fpvHeightOffset: s, fpvForwardOffset: c } = this.config, l = this.viewMode === "fpv", u = n + s;
 		if (l) {
-			let n = m, i = c + m, a = Math.tan(o) * n, s = this.advanceLatLng(e, t, r, i);
+			let n = g, i = c + g, a = Math.tan(o) * n, s = this.advanceLatLng(e, t, r, i);
 			this._offset.set(-Math.sin(r) * n, -Math.cos(r) * n, a), this.view.cameraFollow(!0, {
 				lat: s.lat,
 				lng: s.lng,
@@ -262,20 +262,20 @@ var u = {
 		}, this._offset);
 	}
 	composeCharacterFrame(e, t) {
-		let n = i(e);
+		let n = o(e);
 		return this._headingMatrix.makeRotationZ(-t), this._characterFrame.multiplyMatrices(n, this._headingMatrix);
 	}
-	advanceLatLng(e, t, n, c) {
-		let l = a({
-			lat: r(e),
-			lng: r(t),
+	advanceLatLng(e, t, n, r) {
+		let i = s({
+			lat: a(e),
+			lng: a(t),
 			height: 0
-		}), u = i(l);
-		this._east.setFromMatrixColumn(u, 0).normalize(), this._north.setFromMatrixColumn(u, 1).normalize(), this._worldForward.copy(this._east).multiplyScalar(Math.sin(n)).addScaledVector(this._north, Math.cos(n)), l.addScaledVector(this._worldForward, c);
-		let d = s(l);
+		}), u = o(i);
+		this._east.setFromMatrixColumn(u, 0).normalize(), this._north.setFromMatrixColumn(u, 1).normalize(), this._worldForward.copy(this._east).multiplyScalar(Math.sin(n)).addScaledVector(this._north, Math.cos(n)), i.addScaledVector(this._worldForward, r);
+		let d = l(i);
 		return {
-			lat: o(d.lat),
-			lng: o(d.lng)
+			lat: c(d.lat),
+			lng: c(d.lng)
 		};
 	}
 	notify() {
@@ -323,27 +323,27 @@ var u = {
 		this.animId = requestAnimationFrame(this.tick);
 		let t = Math.min((e - this.lastTime) / 1e3, .1);
 		this.lastTime = e;
-		let n = 0, c = 0, l = 0;
-		this.heldActions.has("forward") && (c += 1), this.heldActions.has("backward") && --c, this.heldActions.has("turnLeft") && --n, this.heldActions.has("turnRight") && (n += 1), this.heldActions.has("ascend") && (l += 1), this.heldActions.has("descend") && --l;
+		let n = 0, r = 0, i = 0;
+		this.heldActions.has("forward") && (r += 1), this.heldActions.has("backward") && --r, this.heldActions.has("turnLeft") && --n, this.heldActions.has("turnRight") && (n += 1), this.heldActions.has("ascend") && (i += 1), this.heldActions.has("descend") && --i;
 		let { moveSpeed: u, rotationSpeed: d, altSpeed: f, minAlt: p, maxAlt: m, cameraLerpSpeed: h } = this.config;
-		n !== 0 && (this.modelHeading += r(d * n));
+		n !== 0 && (this.modelHeading += a(d * n));
 		let g = this._curPos;
 		if (this.handle && this.modelRef) {
 			let e = this.modelRef.getWorldPosition();
 			if (!e) return;
 			g.copy(e);
-		} else g.copy(a({
-			lat: r(this.state.lat),
-			lng: r(this.state.lng),
+		} else g.copy(s({
+			lat: a(this.state.lat),
+			lng: a(this.state.lng),
 			height: this.state.alt
 		}));
-		let _ = i(g);
+		let _ = o(g);
 		this._east.setFromMatrixColumn(_, 0).normalize(), this._north.setFromMatrixColumn(_, 1).normalize();
-		let v = s(g);
-		this._worldForward.copy(this._east).multiplyScalar(Math.sin(this.modelHeading)).addScaledVector(this._north, Math.cos(this.modelHeading)), c !== 0 && g.addScaledVector(this._worldForward, u * this.dashMultiplier * t * c);
-		let y = s(g), b = v.height + l * f * t, x = Math.max(p, Math.min(m, b)), S = o(y.lat), C = o(y.lng), w = x;
+		let v = l(g);
+		this._worldForward.copy(this._east).multiplyScalar(Math.sin(this.modelHeading)).addScaledVector(this._north, Math.cos(this.modelHeading)), r !== 0 && g.addScaledVector(this._worldForward, u * this.dashMultiplier * t * r);
+		let y = l(g), b = v.height + i * f * t, x = Math.max(p, Math.min(m, b)), S = c(y.lat), C = c(y.lng), w = x;
 		if (this.handle && this.character) {
-			let e = a({
+			let e = s({
 				lat: y.lat,
 				lng: y.lng,
 				height: x
@@ -364,7 +364,7 @@ var u = {
 			height: w + this.config.fpvHeightOffset
 		});
 		else this.placeChaseCamera(S, C, w, this.cameraHeading);
-		let E = c !== 0 || n !== 0 || l !== 0, D = E && this.dashMultiplier > 1, O = this.currentAnimState;
+		let E = r !== 0 || n !== 0 || i !== 0, D = E && this.dashMultiplier > 1, O = this.currentAnimState;
 		if (this.character && this.modelRef) {
 			let { animation: e } = this.character, t = e.walkClip ?? e.idleClip, n;
 			n = D ? e.dashClip : E ? t : e.idleClip, n !== this.currentAnimState && (this.modelRef.crossFadeAnimation(this.currentAnimState ?? "", n, e.crossfadeDuration), this.currentAnimState = n), O = n;
@@ -386,10 +386,10 @@ var u = {
 };
 //#endregion
 //#region src/OverlayPlugin.ts
-function g(e, t, n) {
+function v(e, t, n) {
 	e.style.transform = `translate(${t}px, ${n}px)`, e.style.willChange = "transform";
 }
-var _ = 1e5, v = class extends t {
+var y = 1e5, b = class extends n {
 	view;
 	maxDistance;
 	positions = [];
@@ -397,7 +397,7 @@ var _ = 1e5, v = class extends t {
 	listeners = /* @__PURE__ */ new Set();
 	boundHandler;
 	constructor(e) {
-		super(), this.maxDistance = e?.maxDistance ?? _, this.boundHandler = this.handlePreRender.bind(this);
+		super(), this.maxDistance = e?.maxDistance ?? y, this.boundHandler = this.handlePreRender.bind(this);
 	}
 	async init(e, t) {
 		this.view = e, e.on("preRender", this.boundHandler);
@@ -411,47 +411,47 @@ var _ = 1e5, v = class extends t {
 	dispose() {
 		this.view && this.view.off("preRender", this.boundHandler), this.listeners.clear(), this.positions = [], this.projected.clear();
 	}
-	worldToScreen(e, t, i) {
+	worldToScreen(e, t, n) {
 		if (!this.view) return null;
-		let o = a({
-			lng: r(e),
-			lat: r(t),
-			height: i
-		}), s = n({
+		let r = s({
+			lng: a(e),
+			lat: a(t),
+			height: n
+		}), o = i({
 			width: this.view.screenSize.x,
 			height: this.view.screenSize.y,
 			pixelRatio: this.view.pixelRatio
-		}, this.view.camera.raw, o);
-		return s ? {
-			x: s.x,
-			y: s.y
+		}, this.view.camera.raw, r);
+		return o ? {
+			x: o.x,
+			y: o.y
 		} : null;
 	}
 	handlePreRender() {
 		if (!this.view) return;
-		let e = this.view.camera.positionGeographic, t = a({
-			lng: r(e.lng),
-			lat: r(e.lat),
+		let e = this.view.camera.positionGeographic, t = s({
+			lng: a(e.lng),
+			lat: a(e.lat),
 			height: e.height
 		}), n = /* @__PURE__ */ new Map();
 		for (let e of this.positions) {
-			let i = a({
-				lng: r(e.lng),
-				lat: r(e.lat),
+			let r = s({
+				lng: a(e.lng),
+				lat: a(e.lat),
 				height: e.alt
-			}), o = t.distanceTo(i);
-			if (o > this.maxDistance) continue;
-			let s = this.worldToScreen(e.lng, e.lat, e.alt);
-			s && n.set(e.id, {
-				...s,
-				distance: o
+			}), i = t.distanceTo(r);
+			if (i > this.maxDistance) continue;
+			let o = this.worldToScreen(e.lng, e.lat, e.alt);
+			o && n.set(e.id, {
+				...o,
+				distance: i
 			});
 		}
 		this.projected = n;
-		let i = { projected: this.projected };
-		for (let e of this.listeners) e(i);
+		let r = { projected: this.projected };
+		for (let e of this.listeners) e(r);
 	}
-}, y = "https://api.cesium.com/v1/assets", b = class extends t {
+}, x = "https://api.cesium.com/v1/assets", S = class extends n {
 	view;
 	config;
 	endpoint;
@@ -460,7 +460,7 @@ var _ = 1e5, v = class extends t {
 	}
 	async init(e, t) {
 		this.view = e;
-		let { assetId: n, accessToken: r, endpoint: i = y } = this.config, a = `${i}/${encodeURIComponent(String(n))}/endpoint?access_token=${encodeURIComponent(r)}`, o = await fetch(a);
+		let { assetId: n, accessToken: r, endpoint: i = x } = this.config, a = `${i}/${encodeURIComponent(String(n))}/endpoint?access_token=${encodeURIComponent(r)}`, o = await fetch(a);
 		if (!o.ok) throw Error(`CesiumIonPlugin: failed to fetch asset ${n} endpoint (${o.status} ${o.statusText})`);
 		let s = await o.json();
 		this.endpoint = {
@@ -489,12 +489,19 @@ var _ = 1e5, v = class extends t {
 		});
 		return l.once("deleted", () => c.delete()), l;
 	}
-}, x = /^3\.\d+\.\d+$/;
-function S(e) {
-	if (typeof e.tilejson != "string" || !x.test(e.tilejson)) throw Error(`TileJsonPlugin: invalid or missing "tilejson" version field (got ${JSON.stringify(e.tilejson)}).`);
+}, C = /^3\.\d+\.\d+$/, w = 512, T = "mapbox";
+function E(e) {
+	if (typeof e.tilejson != "string" || !C.test(e.tilejson)) throw Error(`TileJsonPlugin: invalid or missing "tilejson" version field (got ${JSON.stringify(e.tilejson)}).`);
 	if (!Array.isArray(e.tiles) || e.tiles.length === 0) throw Error("TileJsonPlugin: \"tiles\" must be a non-empty array of URL templates.");
 }
-var C = class extends t {
+function D(e) {
+	switch (e) {
+		case "mapbox": return t();
+		case "terrarium": return r();
+		default: throw Error(`TileJsonPlugin: unsupported raster-dem encoding ${JSON.stringify(e)}. Supported encodings: "mapbox", "terrarium".`);
+	}
+}
+var O = class extends n {
 	view;
 	events = new e();
 	credits = [];
@@ -514,27 +521,34 @@ var C = class extends t {
 		let t = this.view;
 		if (!t) throw Error("TileJsonPlugin: addSource() must be called after view.init().");
 		let n = await this.fetchTileJson(e.url);
-		S(n);
+		E(n);
 		let [r, ...i] = n.tiles;
 		i.length > 0 && console.warn(`TileJsonPlugin: TileJSON at ${e.url} lists ${n.tiles.length} mirror tile endpoints; Navara sources use a single URL, so only the first is used.`);
-		let { minzoom: a, maxzoom: o, scheme: s } = n, c = e.id, l = e.type === "raster-tile" ? t.addSource({
-			type: "raster-tile",
+		let a = e.minzoom ?? n.minzoom, o = e.maxzoom ?? n.maxzoom, s = e.scheme ?? n.scheme, c = e.id, l = {
 			url: r,
 			...c === void 0 ? {} : { id: c },
+			...o === void 0 ? {} : { maxZoom: o }
+		}, u = {
+			...l,
 			...a === void 0 ? {} : { minZoom: a },
-			...o === void 0 ? {} : { maxZoom: o },
 			...s === "tms" ? { tms: !0 } : {}
+		}, d;
+		return d = e.type === "raster-tile" ? t.addSource({
+			type: "raster-tile",
+			...u
+		}) : e.type === "raster-dem" ? t.addSource({
+			type: "raster-dem",
+			...u,
+			tileSize: e.tileSize ?? n.tileSize ?? w,
+			elevationDecoder: D(e.encoding ?? n.encoding ?? T)
 		}) : t.addSource({
 			type: "vector-tile",
-			url: r,
-			...c === void 0 ? {} : { id: c },
-			...o === void 0 ? {} : { maxZoom: o }
-		});
-		return n.attribution && this.addCredit(n.attribution), this.events.emit("loaded", {
-			source: l,
+			...l
+		}), n.attribution && this.addCredit(n.attribution), this.events.emit("loaded", {
+			source: d,
 			tilejson: n,
 			attribution: n.attribution
-		}), l;
+		}), d;
 	}
 	dispose() {
 		let e = this.view?.attribution;
@@ -550,4 +564,4 @@ var C = class extends t {
 	}
 };
 //#endregion
-export { b as CesiumIonPlugin, v as OverlayPlugin, h as PersonViewPlugin, C as TileJsonPlugin, g as moveOverlayElement };
+export { S as CesiumIonPlugin, b as OverlayPlugin, _ as PersonViewPlugin, O as TileJsonPlugin, v as moveOverlayElement };

package/dist/index.umd.cjs

@@ -1 +1 @@
-(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports,require("@navaramap/three"),require("three")):typeof define==`function`&&define.amd?define([`exports`,`@navaramap/three`,`three`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.NavaraThreePlugins={},e._navaramap_three,e.three))})(this,function(e,t,n){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});var r=Object.create,i=Object.defineProperty,a=Object.getOwnPropertyDescriptor,o=Object.getOwnPropertyNames,s=Object.getPrototypeOf,c=Object.prototype.hasOwnProperty,l=(e,t,n,r)=>{if(t&&typeof t==`object`||typeof t==`function`)for(var s=o(t),l=0,u=s.length,d;l<u;l++)d=s[l],!c.call(e,d)&&d!==n&&i(e,d,{get:(e=>t[e]).bind(null,d),enumerable:!(r=a(t,d))||r.enumerable});return e};t=((e,t,n)=>(n=e==null?{}:r(s(e)),l(t||!e||!e.__esModule?i(n,`default`,{value:e,enumerable:!0}):n,e)))(t,1);var u={x:0,y:0,z:0},d={forward:[`KeyW`],backward:[`KeyS`],turnLeft:[`KeyA`],turnRight:[`KeyD`],ascend:[`ArrowUp`,`Space`],descend:[`ArrowDown`,`ControlLeft`,`ControlRight`],dash:[`ShiftLeft`,`ShiftRight`],orbitCamera:[`AltLeft`,`AltRight`],toggleView:[`KeyV`]},f={allowCameraControl:!1,initialView:`tpv`,moveSpeed:50,rotationSpeed:3,altSpeed:30,minAlt:50,maxAlt:5e3,cameraDistance:50,cameraPitch:0,cameraLerpSpeed:3,fpvForwardOffset:0,fpvHeightOffset:1,fpvPitch:0,startLat:35.6812,startLng:139.7671,startHeight:500,startHeading:Math.PI*1.3},p=3,m=1e3,h=class extends t.Plugin{view;config;character;keys;keyToAction;handle=null;modelRef=null;animId=null;lastTime=0;state;listeners=new Set;heldActions=new Set;dashMultiplier=1;orbitKeyHeld=!1;orbitLatched=!1;currentAnimState;modelHeading;cameraHeading;viewMode;movementSuppressed=!1;boundKeyDown;boundKeyUp;_curPos=new n.Vector3;_east=new n.Vector3;_north=new n.Vector3;_worldForward=new n.Vector3;_offset=new n.Vector3;_headingMatrix=new n.Matrix4;_characterFrame=new n.Matrix4;constructor(e={}){super();let{character:t,keys:n,...r}=e;this.config={...f,...r},this.character=t?this.resolveCharacter(t):null,this.keys={...d,...n},this.keyToAction=this.buildKeyMap(this.keys),this.modelHeading=this.config.startHeading,this.cameraHeading=this.config.startHeading,this.viewMode=this.config.initialView,this.currentAnimState=this.character?this.character.animation.idleClip:null,this.boundKeyDown=this.onKeyDown.bind(this),this.boundKeyUp=this.onKeyUp.bind(this)}async init(e,t){this.view=e,this.state={lng:this.config.startLng,lat:this.config.startLat,alt:this.config.startHeight,heading:this.config.startHeading,speed:0,animationState:this.currentAnimState,mode:this.viewMode}}start(){if(!this.view||this.animId!=null)return;this.animId=-1;let{startLat:e,startLng:n,startHeight:r,startHeading:i}=this.config,a=(0,t.geodeticToVector3)({lat:(0,t.degreeToRadian)(e),lng:(0,t.degreeToRadian)(n),height:r});if(this.modelHeading=i,this.cameraHeading=i,this.character){let{animation:e,modelRotationOffset:t,modelScale:n,castShadow:r,receiveShadow:o}=this.character;this.handle=this.view.addMesh({gltfModel:{url:this.character.modelUrl,castShadow:r,receiveShadow:o,animationEnabled:!0,animationAutoPlay:!0,animationActiveClip:e.idleClip,animationSpeed:e.speed,animationLoop:!0,animationCrossfadeDuration:e.crossfadeDuration},matrixWorld:this.composeCharacterFrame(a,i),rotation:{x:t.x,y:t.y,z:t.z},scale:{x:n,y:n,z:n}}),this.modelRef=this.handle.ref,this.modelRef.on(`load`,()=>{this.view&&(this.lastTime=performance.now(),this.animId=requestAnimationFrame(this.tick))})}else this.lastTime=performance.now(),this.animId=requestAnimationFrame(this.tick);this.applyInitialCamera(),this.applyModelVisibility(),document.addEventListener(`keydown`,this.boundKeyDown),document.addEventListener(`keyup`,this.boundKeyUp)}teleport(e){if(!this.view)return;let{lng:n,lat:r,alt:i}=e,a=e.heading==null?this.cameraHeading:e.heading;if(this.handle&&this.character){let e=(0,t.geodeticToVector3)({lat:(0,t.degreeToRadian)(r),lng:(0,t.degreeToRadian)(n),height:i});this.handle.update({matrixWorld:this.composeCharacterFrame(e,a)})}this.modelHeading=a,this.cameraHeading=a,this.placeChaseCamera(r,n,i,a),this.state={lng:n,lat:r,alt:i,heading:a,speed:0,animationState:this.currentAnimState,mode:this.viewMode},this.notify()}getState(){return this.state}onStateChange(e){return this.listeners.add(e),()=>this.listeners.delete(e)}setViewMode(e){this.viewMode!==e&&(this.viewMode=e,this.state={...this.state,mode:e},this.applyModelVisibility(),this.placeChaseCamera(this.state.lat,this.state.lng,this.state.alt,this.cameraHeading),this.notify())}toggleViewMode(){this.setViewMode(this.viewMode===`tpv`?`fpv`:`tpv`)}setAllowCameraControl(e){this.config.allowCameraControl=e}setHeading(e){if(!this.view)return;let{lat:n,lng:r,alt:i}=this.state;if(this.modelHeading=e,this.cameraHeading=e,this.handle&&this.character){let a=(0,t.geodeticToVector3)({lat:(0,t.degreeToRadian)(n),lng:(0,t.degreeToRadian)(r),height:i});this.handle.update({matrixWorld:this.composeCharacterFrame(a,e)})}this.isFreeCamera()||this.placeChaseCamera(n,r,i,e),this.state={...this.state,heading:e},this.notify()}getHeading(){return this.state.heading}setCameraPitch(e){this.config.cameraPitch=e,this.isFreeCamera()||this.placeChaseCamera(this.state.lat,this.state.lng,this.state.alt,this.cameraHeading)}getCameraPitch(){return this.config.cameraPitch}setFpvPitch(e){this.config.fpvPitch=e,this.isFreeCamera()||this.placeChaseCamera(this.state.lat,this.state.lng,this.state.alt,this.cameraHeading)}getFpvPitch(){return this.config.fpvPitch}setFpvHeightOffset(e){this.config.fpvHeightOffset=e,this.isFreeCamera()||this.placeChaseCamera(this.state.lat,this.state.lng,this.state.alt,this.cameraHeading)}getFpvHeightOffset(){return this.config.fpvHeightOffset}dispose(){this.animId!=null&&cancelAnimationFrame(this.animId),this.animId=null,document.removeEventListener(`keydown`,this.boundKeyDown),document.removeEventListener(`keyup`,this.boundKeyUp),this.handle&&=(this.handle.delete(),null),this.modelRef=null,this.heldActions.clear(),this.listeners.clear(),this.orbitKeyHeld=!1,this.orbitLatched=!1,this.dashMultiplier=1,this.view=void 0}resolveCharacter(e){return{modelUrl:e.modelUrl,animation:e.animation,modelRotationOffset:e.modelRotationOffset?{...u,...e.modelRotationOffset}:u,modelScale:e.modelScale??p,hideModelInFpv:e.hideModelInFpv??!0,castShadow:e.castShadow??!1,receiveShadow:e.receiveShadow??!1}}buildKeyMap(e){let t=new Map,n=(e,n)=>{for(let r of e)t.set(r,n)};return n(e.forward,`forward`),n(e.backward,`backward`),n(e.turnLeft,`turnLeft`),n(e.turnRight,`turnRight`),n(e.ascend,`ascend`),n(e.descend,`descend`),n(e.dash,`dash`),n(e.orbitCamera,`orbitCamera`),n(e.toggleView,`toggleView`),t}isFreeCamera(){return this.config.allowCameraControl||this.orbitKeyHeld||this.orbitLatched}isMovementAction(e){return e===`forward`||e===`backward`||e===`turnLeft`||e===`turnRight`||e===`ascend`||e===`descend`}applyModelVisibility(){if(!this.handle||!this.character)return;let e=this.viewMode===`fpv`&&this.character.hideModelInFpv;this.handle.visible=!e}applyInitialCamera(){let{startLat:e,startLng:t,startHeight:n,startHeading:r}=this.config;this.placeChaseCamera(e,t,n,r)}placeChaseCamera(e,t,n,r){if(!this.view)return;let{cameraDistance:i,cameraPitch:a,fpvPitch:o,fpvHeightOffset:s,fpvForwardOffset:c}=this.config,l=this.viewMode===`fpv`,u=n+s;if(l){let n=m,i=c+m,a=Math.tan(o)*n,s=this.advanceLatLng(e,t,r,i);this._offset.set(-Math.sin(r)*n,-Math.cos(r)*n,a),this.view.cameraFollow(!0,{lat:s.lat,lng:s.lng,height:u-a},this._offset);return}let d=i*Math.cos(a),f=i*Math.sin(a);this._offset.set(-Math.sin(r)*d,-Math.cos(r)*d,f),this.view.cameraFollow(!0,{lat:e,lng:t,height:u},this._offset)}composeCharacterFrame(e,n){let r=(0,t.eastNorthUpToFixedFrame)(e);return this._headingMatrix.makeRotationZ(-n),this._characterFrame.multiplyMatrices(r,this._headingMatrix)}advanceLatLng(e,n,r,i){let a=(0,t.geodeticToVector3)({lat:(0,t.degreeToRadian)(e),lng:(0,t.degreeToRadian)(n),height:0}),o=(0,t.eastNorthUpToFixedFrame)(a);this._east.setFromMatrixColumn(o,0).normalize(),this._north.setFromMatrixColumn(o,1).normalize(),this._worldForward.copy(this._east).multiplyScalar(Math.sin(r)).addScaledVector(this._north,Math.cos(r)),a.addScaledVector(this._worldForward,i);let s=(0,t.vector3ToGeodetic)(a);return{lat:(0,t.radianToDegree)(s.lat),lng:(0,t.radianToDegree)(s.lng)}}notify(){for(let e of this.listeners)e(this.state)}onKeyDown(e){let t=e.target;if(t.tagName===`INPUT`||t.tagName===`TEXTAREA`||t.isContentEditable)return;let n=this.keyToAction.get(e.code);if(n!==void 0){if(n===`toggleView`){if(e.repeat)return;this.toggleViewMode();return}if(n===`orbitCamera`){this.orbitKeyHeld=!0,this.orbitLatched=!0;return}if(!this.movementSuppressed){if(n===`dash`){this.dashMultiplier=2.5;return}this.isMovementAction(n)&&(this.orbitLatched=!1),this.heldActions.add(n)}}}onKeyUp(e){let t=this.keyToAction.get(e.code);if(t!==void 0&&t!==`toggleView`){if(t===`orbitCamera`){this.orbitKeyHeld=!1;return}if(t===`dash`){this.dashMultiplier=1;return}this.heldActions.delete(t)}}tick=e=>{if(!this.view)return;this.animId=requestAnimationFrame(this.tick);let n=Math.min((e-this.lastTime)/1e3,.1);this.lastTime=e;let r=0,i=0,a=0;this.heldActions.has(`forward`)&&(i+=1),this.heldActions.has(`backward`)&&--i,this.heldActions.has(`turnLeft`)&&--r,this.heldActions.has(`turnRight`)&&(r+=1),this.heldActions.has(`ascend`)&&(a+=1),this.heldActions.has(`descend`)&&--a;let{moveSpeed:o,rotationSpeed:s,altSpeed:c,minAlt:l,maxAlt:u,cameraLerpSpeed:d}=this.config;r!==0&&(this.modelHeading+=(0,t.degreeToRadian)(s*r));let f=this._curPos;if(this.handle&&this.modelRef){let e=this.modelRef.getWorldPosition();if(!e)return;f.copy(e)}else f.copy((0,t.geodeticToVector3)({lat:(0,t.degreeToRadian)(this.state.lat),lng:(0,t.degreeToRadian)(this.state.lng),height:this.state.alt}));let p=(0,t.eastNorthUpToFixedFrame)(f);this._east.setFromMatrixColumn(p,0).normalize(),this._north.setFromMatrixColumn(p,1).normalize();let m=(0,t.vector3ToGeodetic)(f);this._worldForward.copy(this._east).multiplyScalar(Math.sin(this.modelHeading)).addScaledVector(this._north,Math.cos(this.modelHeading)),i!==0&&f.addScaledVector(this._worldForward,o*this.dashMultiplier*n*i);let h=(0,t.vector3ToGeodetic)(f),g=m.height+a*c*n,_=Math.max(l,Math.min(u,g)),v=(0,t.radianToDegree)(h.lat),y=(0,t.radianToDegree)(h.lng),b=_;if(this.handle&&this.character){let e=(0,t.geodeticToVector3)({lat:h.lat,lng:h.lng,height:_});this.handle.update({matrixWorld:this.composeCharacterFrame(e,this.modelHeading)})}let x=this.modelHeading-this.cameraHeading;if(x-=Math.round(x/(Math.PI*2))*(Math.PI*2),this.cameraHeading+=x*Math.min(n*d,1),this.isFreeCamera())if(this.viewMode===`fpv`){let e=this.advanceLatLng(v,y,this.cameraHeading,this.config.fpvForwardOffset);this.view.cameraFreeLook(!0,{lat:e.lat,lng:e.lng,height:b+this.config.fpvHeightOffset})}else this.view.cameraFollow(!0,{lat:v,lng:y,height:b+this.config.fpvHeightOffset});else this.placeChaseCamera(v,y,b,this.cameraHeading);let S=i!==0||r!==0||a!==0,C=S&&this.dashMultiplier>1,w=this.currentAnimState;if(this.character&&this.modelRef){let{animation:e}=this.character,t=e.walkClip??e.idleClip,n;n=C?e.dashClip:S?t:e.idleClip,n!==this.currentAnimState&&(this.modelRef.crossFadeAnimation(this.currentAnimState??``,n,e.crossfadeDuration),this.currentAnimState=n),w=n}let T={lng:y,lat:v,alt:b,heading:this.modelHeading,speed:o*this.dashMultiplier,animationState:w,mode:this.viewMode};this.hasStateChanged(this.state,T)&&(this.state=T,this.notify())};hasStateChanged(e,t){return e.lng!==t.lng||e.lat!==t.lat||e.alt!==t.alt||e.heading!==t.heading||e.speed!==t.speed||e.animationState!==t.animationState||e.mode!==t.mode}};function g(e,t,n){e.style.transform=`translate(${t}px, ${n}px)`,e.style.willChange=`transform`}var _=1e5,v=class extends t.Plugin{view;maxDistance;positions=[];projected=new Map;listeners=new Set;boundHandler;constructor(e){super(),this.maxDistance=e?.maxDistance??_,this.boundHandler=this.handlePreRender.bind(this)}async init(e,t){this.view=e,e.on(`preRender`,this.boundHandler)}setPositions(e){this.positions=e}onUpdate(e){return this.listeners.add(e),()=>this.listeners.delete(e)}dispose(){this.view&&this.view.off(`preRender`,this.boundHandler),this.listeners.clear(),this.positions=[],this.projected.clear()}worldToScreen(e,n,r){if(!this.view)return null;let i=(0,t.geodeticToVector3)({lng:(0,t.degreeToRadian)(e),lat:(0,t.degreeToRadian)(n),height:r}),a=(0,t.convertWorldToScreen)({width:this.view.screenSize.x,height:this.view.screenSize.y,pixelRatio:this.view.pixelRatio},this.view.camera.raw,i);return a?{x:a.x,y:a.y}:null}handlePreRender(){if(!this.view)return;let e=this.view.camera.positionGeographic,n=(0,t.geodeticToVector3)({lng:(0,t.degreeToRadian)(e.lng),lat:(0,t.degreeToRadian)(e.lat),height:e.height}),r=new Map;for(let e of this.positions){let i=(0,t.geodeticToVector3)({lng:(0,t.degreeToRadian)(e.lng),lat:(0,t.degreeToRadian)(e.lat),height:e.alt}),a=n.distanceTo(i);if(a>this.maxDistance)continue;let o=this.worldToScreen(e.lng,e.lat,e.alt);o&&r.set(e.id,{...o,distance:a})}this.projected=r;let i={projected:this.projected};for(let e of this.listeners)e(i)}},y=`https://api.cesium.com/v1/assets`,b=class extends t.Plugin{view;config;endpoint;constructor(e){super(),this.config=e}async init(e,t){this.view=e;let{assetId:n,accessToken:r,endpoint:i=y}=this.config,a=`${i}/${encodeURIComponent(String(n))}/endpoint?access_token=${encodeURIComponent(r)}`,o=await fetch(a);if(!o.ok)throw Error(`CesiumIonPlugin: failed to fetch asset ${n} endpoint (${o.status} ${o.statusText})`);let s=await o.json();this.endpoint={url:s.url,accessToken:s.accessToken}}addTerrain(e={}){if(!this.view||!this.endpoint)throw Error(`CesiumIonPlugin: addTerrain() must be called after view.init().`);let{castShadow:t,receiveShadow:n,show:r,showBoundingBox:i,skirt:a,skirtExaggeration:o,...s}=e,c=this.view.addSource({type:`quantized-mesh`,url:`${this.endpoint.url}{z}/{x}/{y}.terrain`,token:this.endpoint.accessToken,...s}),l=this.view.addLayer({type:`terrain`,source:c,terrain:{castShadow:t,receiveShadow:n,show:r,showBoundingBox:i,skirt:a,skirtExaggeration:o}});return l.once(`deleted`,()=>c.delete()),l}},x=/^3\.\d+\.\d+$/;function S(e){if(typeof e.tilejson!=`string`||!x.test(e.tilejson))throw Error(`TileJsonPlugin: invalid or missing "tilejson" version field (got ${JSON.stringify(e.tilejson)}).`);if(!Array.isArray(e.tiles)||e.tiles.length===0)throw Error(`TileJsonPlugin: "tiles" must be a non-empty array of URL templates.`)}var C=class extends t.Plugin{view;events=new t.EventHandler;credits=[];async init(e,t){this.view=e}on(e,t){this.events.on(e,t)}once(e,t){this.events.once(e,t)}off(e,t){this.events.off(e,t)}async addSource(e){let t=this.view;if(!t)throw Error(`TileJsonPlugin: addSource() must be called after view.init().`);let n=await this.fetchTileJson(e.url);S(n);let[r,...i]=n.tiles;i.length>0&&console.warn(`TileJsonPlugin: TileJSON at ${e.url} lists ${n.tiles.length} mirror tile endpoints; Navara sources use a single URL, so only the first is used.`);let{minzoom:a,maxzoom:o,scheme:s}=n,c=e.id,l=e.type===`raster-tile`?t.addSource({type:`raster-tile`,url:r,...c===void 0?{}:{id:c},...a===void 0?{}:{minZoom:a},...o===void 0?{}:{maxZoom:o},...s===`tms`?{tms:!0}:{}}):t.addSource({type:`vector-tile`,url:r,...c===void 0?{}:{id:c},...o===void 0?{}:{maxZoom:o}});return n.attribution&&this.addCredit(n.attribution),this.events.emit(`loaded`,{source:l,tilejson:n,attribution:n.attribution}),l}dispose(){let e=this.view?.attribution;e&&this.credits.length>0&&e.remove(this.credits.map(e=>({attributionHtml:e}))),this.credits.length=0,this.events.clear(`loaded`),this.view=void 0}async fetchTileJson(e){let t=await fetch(e);if(!t.ok)throw Error(`TileJsonPlugin: failed to fetch TileJSON from ${e} (${t.status} ${t.statusText})`);return await t.json()}addCredit(e){this.credits.includes(e)||(this.credits.push(e),this.view?.attribution?.add([{attributionHtml:e}]))}};e.CesiumIonPlugin=b,e.OverlayPlugin=v,e.PersonViewPlugin=h,e.TileJsonPlugin=C,e.moveOverlayElement=g});
+(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports,require("@navaramap/three"),require("three")):typeof define==`function`&&define.amd?define([`exports`,`@navaramap/three`,`three`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.NavaraThreePlugins={},e._navaramap_three,e.three))})(this,function(e,t,n){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});var r=Object.create,i=Object.defineProperty,a=Object.getOwnPropertyDescriptor,o=Object.getOwnPropertyNames,s=Object.getPrototypeOf,c=Object.prototype.hasOwnProperty,l=(e,t,n,r)=>{if(t&&typeof t==`object`||typeof t==`function`)for(var s=o(t),l=0,u=s.length,d;l<u;l++)d=s[l],!c.call(e,d)&&d!==n&&i(e,d,{get:(e=>t[e]).bind(null,d),enumerable:!(r=a(t,d))||r.enumerable});return e};t=((e,t,n)=>(n=e==null?{}:r(s(e)),l(t||!e||!e.__esModule?i(n,`default`,{value:e,enumerable:!0}):n,e)))(t,1);var u={x:0,y:0,z:0},d={forward:[`KeyW`],backward:[`KeyS`],turnLeft:[`KeyA`],turnRight:[`KeyD`],ascend:[`ArrowUp`,`Space`],descend:[`ArrowDown`,`ControlLeft`,`ControlRight`],dash:[`ShiftLeft`,`ShiftRight`],orbitCamera:[`AltLeft`,`AltRight`],toggleView:[`KeyV`]},f={allowCameraControl:!1,initialView:`tpv`,moveSpeed:50,rotationSpeed:3,altSpeed:30,minAlt:50,maxAlt:5e3,cameraDistance:50,cameraPitch:0,cameraLerpSpeed:3,fpvForwardOffset:0,fpvHeightOffset:1,fpvPitch:0,startLat:35.6812,startLng:139.7671,startHeight:500,startHeading:Math.PI*1.3},p=3,m=1e3,h=class extends t.Plugin{view;config;character;keys;keyToAction;handle=null;modelRef=null;animId=null;lastTime=0;state;listeners=new Set;heldActions=new Set;dashMultiplier=1;orbitKeyHeld=!1;orbitLatched=!1;currentAnimState;modelHeading;cameraHeading;viewMode;movementSuppressed=!1;boundKeyDown;boundKeyUp;_curPos=new n.Vector3;_east=new n.Vector3;_north=new n.Vector3;_worldForward=new n.Vector3;_offset=new n.Vector3;_headingMatrix=new n.Matrix4;_characterFrame=new n.Matrix4;constructor(e={}){super();let{character:t,keys:n,...r}=e;this.config={...f,...r},this.character=t?this.resolveCharacter(t):null,this.keys={...d,...n},this.keyToAction=this.buildKeyMap(this.keys),this.modelHeading=this.config.startHeading,this.cameraHeading=this.config.startHeading,this.viewMode=this.config.initialView,this.currentAnimState=this.character?this.character.animation.idleClip:null,this.boundKeyDown=this.onKeyDown.bind(this),this.boundKeyUp=this.onKeyUp.bind(this)}async init(e,t){this.view=e,this.state={lng:this.config.startLng,lat:this.config.startLat,alt:this.config.startHeight,heading:this.config.startHeading,speed:0,animationState:this.currentAnimState,mode:this.viewMode}}start(){if(!this.view||this.animId!=null)return;this.animId=-1;let{startLat:e,startLng:n,startHeight:r,startHeading:i}=this.config,a=(0,t.geodeticToVector3)({lat:(0,t.degreeToRadian)(e),lng:(0,t.degreeToRadian)(n),height:r});if(this.modelHeading=i,this.cameraHeading=i,this.character){let{animation:e,modelRotationOffset:t,modelScale:n,castShadow:r,receiveShadow:o}=this.character;this.handle=this.view.addMesh({gltfModel:{url:this.character.modelUrl,castShadow:r,receiveShadow:o,animationEnabled:!0,animationAutoPlay:!0,animationActiveClip:e.idleClip,animationSpeed:e.speed,animationLoop:!0,animationCrossfadeDuration:e.crossfadeDuration},matrixWorld:this.composeCharacterFrame(a,i),rotation:{x:t.x,y:t.y,z:t.z},scale:{x:n,y:n,z:n}}),this.modelRef=this.handle.ref,this.modelRef.on(`load`,()=>{this.view&&(this.lastTime=performance.now(),this.animId=requestAnimationFrame(this.tick))})}else this.lastTime=performance.now(),this.animId=requestAnimationFrame(this.tick);this.applyInitialCamera(),this.applyModelVisibility(),document.addEventListener(`keydown`,this.boundKeyDown),document.addEventListener(`keyup`,this.boundKeyUp)}teleport(e){if(!this.view)return;let{lng:n,lat:r,alt:i}=e,a=e.heading==null?this.cameraHeading:e.heading;if(this.handle&&this.character){let e=(0,t.geodeticToVector3)({lat:(0,t.degreeToRadian)(r),lng:(0,t.degreeToRadian)(n),height:i});this.handle.update({matrixWorld:this.composeCharacterFrame(e,a)})}this.modelHeading=a,this.cameraHeading=a,this.placeChaseCamera(r,n,i,a),this.state={lng:n,lat:r,alt:i,heading:a,speed:0,animationState:this.currentAnimState,mode:this.viewMode},this.notify()}getState(){return this.state}onStateChange(e){return this.listeners.add(e),()=>this.listeners.delete(e)}setViewMode(e){this.viewMode!==e&&(this.viewMode=e,this.state={...this.state,mode:e},this.applyModelVisibility(),this.placeChaseCamera(this.state.lat,this.state.lng,this.state.alt,this.cameraHeading),this.notify())}toggleViewMode(){this.setViewMode(this.viewMode===`tpv`?`fpv`:`tpv`)}setAllowCameraControl(e){this.config.allowCameraControl=e}setHeading(e){if(!this.view)return;let{lat:n,lng:r,alt:i}=this.state;if(this.modelHeading=e,this.cameraHeading=e,this.handle&&this.character){let a=(0,t.geodeticToVector3)({lat:(0,t.degreeToRadian)(n),lng:(0,t.degreeToRadian)(r),height:i});this.handle.update({matrixWorld:this.composeCharacterFrame(a,e)})}this.isFreeCamera()||this.placeChaseCamera(n,r,i,e),this.state={...this.state,heading:e},this.notify()}getHeading(){return this.state.heading}setCameraPitch(e){this.config.cameraPitch=e,this.isFreeCamera()||this.placeChaseCamera(this.state.lat,this.state.lng,this.state.alt,this.cameraHeading)}getCameraPitch(){return this.config.cameraPitch}setFpvPitch(e){this.config.fpvPitch=e,this.isFreeCamera()||this.placeChaseCamera(this.state.lat,this.state.lng,this.state.alt,this.cameraHeading)}getFpvPitch(){return this.config.fpvPitch}setFpvHeightOffset(e){this.config.fpvHeightOffset=e,this.isFreeCamera()||this.placeChaseCamera(this.state.lat,this.state.lng,this.state.alt,this.cameraHeading)}getFpvHeightOffset(){return this.config.fpvHeightOffset}dispose(){this.animId!=null&&cancelAnimationFrame(this.animId),this.animId=null,document.removeEventListener(`keydown`,this.boundKeyDown),document.removeEventListener(`keyup`,this.boundKeyUp),this.handle&&=(this.handle.delete(),null),this.modelRef=null,this.heldActions.clear(),this.listeners.clear(),this.orbitKeyHeld=!1,this.orbitLatched=!1,this.dashMultiplier=1,this.view=void 0}resolveCharacter(e){return{modelUrl:e.modelUrl,animation:e.animation,modelRotationOffset:e.modelRotationOffset?{...u,...e.modelRotationOffset}:u,modelScale:e.modelScale??p,hideModelInFpv:e.hideModelInFpv??!0,castShadow:e.castShadow??!1,receiveShadow:e.receiveShadow??!1}}buildKeyMap(e){let t=new Map,n=(e,n)=>{for(let r of e)t.set(r,n)};return n(e.forward,`forward`),n(e.backward,`backward`),n(e.turnLeft,`turnLeft`),n(e.turnRight,`turnRight`),n(e.ascend,`ascend`),n(e.descend,`descend`),n(e.dash,`dash`),n(e.orbitCamera,`orbitCamera`),n(e.toggleView,`toggleView`),t}isFreeCamera(){return this.config.allowCameraControl||this.orbitKeyHeld||this.orbitLatched}isMovementAction(e){return e===`forward`||e===`backward`||e===`turnLeft`||e===`turnRight`||e===`ascend`||e===`descend`}applyModelVisibility(){if(!this.handle||!this.character)return;let e=this.viewMode===`fpv`&&this.character.hideModelInFpv;this.handle.visible=!e}applyInitialCamera(){let{startLat:e,startLng:t,startHeight:n,startHeading:r}=this.config;this.placeChaseCamera(e,t,n,r)}placeChaseCamera(e,t,n,r){if(!this.view)return;let{cameraDistance:i,cameraPitch:a,fpvPitch:o,fpvHeightOffset:s,fpvForwardOffset:c}=this.config,l=this.viewMode===`fpv`,u=n+s;if(l){let n=m,i=c+m,a=Math.tan(o)*n,s=this.advanceLatLng(e,t,r,i);this._offset.set(-Math.sin(r)*n,-Math.cos(r)*n,a),this.view.cameraFollow(!0,{lat:s.lat,lng:s.lng,height:u-a},this._offset);return}let d=i*Math.cos(a),f=i*Math.sin(a);this._offset.set(-Math.sin(r)*d,-Math.cos(r)*d,f),this.view.cameraFollow(!0,{lat:e,lng:t,height:u},this._offset)}composeCharacterFrame(e,n){let r=(0,t.eastNorthUpToFixedFrame)(e);return this._headingMatrix.makeRotationZ(-n),this._characterFrame.multiplyMatrices(r,this._headingMatrix)}advanceLatLng(e,n,r,i){let a=(0,t.geodeticToVector3)({lat:(0,t.degreeToRadian)(e),lng:(0,t.degreeToRadian)(n),height:0}),o=(0,t.eastNorthUpToFixedFrame)(a);this._east.setFromMatrixColumn(o,0).normalize(),this._north.setFromMatrixColumn(o,1).normalize(),this._worldForward.copy(this._east).multiplyScalar(Math.sin(r)).addScaledVector(this._north,Math.cos(r)),a.addScaledVector(this._worldForward,i);let s=(0,t.vector3ToGeodetic)(a);return{lat:(0,t.radianToDegree)(s.lat),lng:(0,t.radianToDegree)(s.lng)}}notify(){for(let e of this.listeners)e(this.state)}onKeyDown(e){let t=e.target;if(t.tagName===`INPUT`||t.tagName===`TEXTAREA`||t.isContentEditable)return;let n=this.keyToAction.get(e.code);if(n!==void 0){if(n===`toggleView`){if(e.repeat)return;this.toggleViewMode();return}if(n===`orbitCamera`){this.orbitKeyHeld=!0,this.orbitLatched=!0;return}if(!this.movementSuppressed){if(n===`dash`){this.dashMultiplier=2.5;return}this.isMovementAction(n)&&(this.orbitLatched=!1),this.heldActions.add(n)}}}onKeyUp(e){let t=this.keyToAction.get(e.code);if(t!==void 0&&t!==`toggleView`){if(t===`orbitCamera`){this.orbitKeyHeld=!1;return}if(t===`dash`){this.dashMultiplier=1;return}this.heldActions.delete(t)}}tick=e=>{if(!this.view)return;this.animId=requestAnimationFrame(this.tick);let n=Math.min((e-this.lastTime)/1e3,.1);this.lastTime=e;let r=0,i=0,a=0;this.heldActions.has(`forward`)&&(i+=1),this.heldActions.has(`backward`)&&--i,this.heldActions.has(`turnLeft`)&&--r,this.heldActions.has(`turnRight`)&&(r+=1),this.heldActions.has(`ascend`)&&(a+=1),this.heldActions.has(`descend`)&&--a;let{moveSpeed:o,rotationSpeed:s,altSpeed:c,minAlt:l,maxAlt:u,cameraLerpSpeed:d}=this.config;r!==0&&(this.modelHeading+=(0,t.degreeToRadian)(s*r));let f=this._curPos;if(this.handle&&this.modelRef){let e=this.modelRef.getWorldPosition();if(!e)return;f.copy(e)}else f.copy((0,t.geodeticToVector3)({lat:(0,t.degreeToRadian)(this.state.lat),lng:(0,t.degreeToRadian)(this.state.lng),height:this.state.alt}));let p=(0,t.eastNorthUpToFixedFrame)(f);this._east.setFromMatrixColumn(p,0).normalize(),this._north.setFromMatrixColumn(p,1).normalize();let m=(0,t.vector3ToGeodetic)(f);this._worldForward.copy(this._east).multiplyScalar(Math.sin(this.modelHeading)).addScaledVector(this._north,Math.cos(this.modelHeading)),i!==0&&f.addScaledVector(this._worldForward,o*this.dashMultiplier*n*i);let h=(0,t.vector3ToGeodetic)(f),g=m.height+a*c*n,_=Math.max(l,Math.min(u,g)),v=(0,t.radianToDegree)(h.lat),y=(0,t.radianToDegree)(h.lng),b=_;if(this.handle&&this.character){let e=(0,t.geodeticToVector3)({lat:h.lat,lng:h.lng,height:_});this.handle.update({matrixWorld:this.composeCharacterFrame(e,this.modelHeading)})}let x=this.modelHeading-this.cameraHeading;if(x-=Math.round(x/(Math.PI*2))*(Math.PI*2),this.cameraHeading+=x*Math.min(n*d,1),this.isFreeCamera())if(this.viewMode===`fpv`){let e=this.advanceLatLng(v,y,this.cameraHeading,this.config.fpvForwardOffset);this.view.cameraFreeLook(!0,{lat:e.lat,lng:e.lng,height:b+this.config.fpvHeightOffset})}else this.view.cameraFollow(!0,{lat:v,lng:y,height:b+this.config.fpvHeightOffset});else this.placeChaseCamera(v,y,b,this.cameraHeading);let S=i!==0||r!==0||a!==0,C=S&&this.dashMultiplier>1,w=this.currentAnimState;if(this.character&&this.modelRef){let{animation:e}=this.character,t=e.walkClip??e.idleClip,n;n=C?e.dashClip:S?t:e.idleClip,n!==this.currentAnimState&&(this.modelRef.crossFadeAnimation(this.currentAnimState??``,n,e.crossfadeDuration),this.currentAnimState=n),w=n}let T={lng:y,lat:v,alt:b,heading:this.modelHeading,speed:o*this.dashMultiplier,animationState:w,mode:this.viewMode};this.hasStateChanged(this.state,T)&&(this.state=T,this.notify())};hasStateChanged(e,t){return e.lng!==t.lng||e.lat!==t.lat||e.alt!==t.alt||e.heading!==t.heading||e.speed!==t.speed||e.animationState!==t.animationState||e.mode!==t.mode}};function g(e,t,n){e.style.transform=`translate(${t}px, ${n}px)`,e.style.willChange=`transform`}var _=1e5,v=class extends t.Plugin{view;maxDistance;positions=[];projected=new Map;listeners=new Set;boundHandler;constructor(e){super(),this.maxDistance=e?.maxDistance??_,this.boundHandler=this.handlePreRender.bind(this)}async init(e,t){this.view=e,e.on(`preRender`,this.boundHandler)}setPositions(e){this.positions=e}onUpdate(e){return this.listeners.add(e),()=>this.listeners.delete(e)}dispose(){this.view&&this.view.off(`preRender`,this.boundHandler),this.listeners.clear(),this.positions=[],this.projected.clear()}worldToScreen(e,n,r){if(!this.view)return null;let i=(0,t.geodeticToVector3)({lng:(0,t.degreeToRadian)(e),lat:(0,t.degreeToRadian)(n),height:r}),a=(0,t.convertWorldToScreen)({width:this.view.screenSize.x,height:this.view.screenSize.y,pixelRatio:this.view.pixelRatio},this.view.camera.raw,i);return a?{x:a.x,y:a.y}:null}handlePreRender(){if(!this.view)return;let e=this.view.camera.positionGeographic,n=(0,t.geodeticToVector3)({lng:(0,t.degreeToRadian)(e.lng),lat:(0,t.degreeToRadian)(e.lat),height:e.height}),r=new Map;for(let e of this.positions){let i=(0,t.geodeticToVector3)({lng:(0,t.degreeToRadian)(e.lng),lat:(0,t.degreeToRadian)(e.lat),height:e.alt}),a=n.distanceTo(i);if(a>this.maxDistance)continue;let o=this.worldToScreen(e.lng,e.lat,e.alt);o&&r.set(e.id,{...o,distance:a})}this.projected=r;let i={projected:this.projected};for(let e of this.listeners)e(i)}},y=`https://api.cesium.com/v1/assets`,b=class extends t.Plugin{view;config;endpoint;constructor(e){super(),this.config=e}async init(e,t){this.view=e;let{assetId:n,accessToken:r,endpoint:i=y}=this.config,a=`${i}/${encodeURIComponent(String(n))}/endpoint?access_token=${encodeURIComponent(r)}`,o=await fetch(a);if(!o.ok)throw Error(`CesiumIonPlugin: failed to fetch asset ${n} endpoint (${o.status} ${o.statusText})`);let s=await o.json();this.endpoint={url:s.url,accessToken:s.accessToken}}addTerrain(e={}){if(!this.view||!this.endpoint)throw Error(`CesiumIonPlugin: addTerrain() must be called after view.init().`);let{castShadow:t,receiveShadow:n,show:r,showBoundingBox:i,skirt:a,skirtExaggeration:o,...s}=e,c=this.view.addSource({type:`quantized-mesh`,url:`${this.endpoint.url}{z}/{x}/{y}.terrain`,token:this.endpoint.accessToken,...s}),l=this.view.addLayer({type:`terrain`,source:c,terrain:{castShadow:t,receiveShadow:n,show:r,showBoundingBox:i,skirt:a,skirtExaggeration:o}});return l.once(`deleted`,()=>c.delete()),l}},x=/^3\.\d+\.\d+$/,S=512,C=`mapbox`;function w(e){if(typeof e.tilejson!=`string`||!x.test(e.tilejson))throw Error(`TileJsonPlugin: invalid or missing "tilejson" version field (got ${JSON.stringify(e.tilejson)}).`);if(!Array.isArray(e.tiles)||e.tiles.length===0)throw Error(`TileJsonPlugin: "tiles" must be a non-empty array of URL templates.`)}function T(e){switch(e){case`mapbox`:return(0,t.MAPBOX_ELEVATION_DECODER)();case`terrarium`:return(0,t.TERRARIUM_ELEVATION_DECODER)();default:throw Error(`TileJsonPlugin: unsupported raster-dem encoding ${JSON.stringify(e)}. Supported encodings: "mapbox", "terrarium".`)}}var E=class extends t.Plugin{view;events=new t.EventHandler;credits=[];async init(e,t){this.view=e}on(e,t){this.events.on(e,t)}once(e,t){this.events.once(e,t)}off(e,t){this.events.off(e,t)}async addSource(e){let t=this.view;if(!t)throw Error(`TileJsonPlugin: addSource() must be called after view.init().`);let n=await this.fetchTileJson(e.url);w(n);let[r,...i]=n.tiles;i.length>0&&console.warn(`TileJsonPlugin: TileJSON at ${e.url} lists ${n.tiles.length} mirror tile endpoints; Navara sources use a single URL, so only the first is used.`);let a=e.minzoom??n.minzoom,o=e.maxzoom??n.maxzoom,s=e.scheme??n.scheme,c=e.id,l={url:r,...c===void 0?{}:{id:c},...o===void 0?{}:{maxZoom:o}},u={...l,...a===void 0?{}:{minZoom:a},...s===`tms`?{tms:!0}:{}},d;return d=e.type===`raster-tile`?t.addSource({type:`raster-tile`,...u}):e.type===`raster-dem`?t.addSource({type:`raster-dem`,...u,tileSize:e.tileSize??n.tileSize??S,elevationDecoder:T(e.encoding??n.encoding??C)}):t.addSource({type:`vector-tile`,...l}),n.attribution&&this.addCredit(n.attribution),this.events.emit(`loaded`,{source:d,tilejson:n,attribution:n.attribution}),d}dispose(){let e=this.view?.attribution;e&&this.credits.length>0&&e.remove(this.credits.map(e=>({attributionHtml:e}))),this.credits.length=0,this.events.clear(`loaded`),this.view=void 0}async fetchTileJson(e){let t=await fetch(e);if(!t.ok)throw Error(`TileJsonPlugin: failed to fetch TileJSON from ${e} (${t.status} ${t.statusText})`);return await t.json()}addCredit(e){this.credits.includes(e)||(this.credits.push(e),this.view?.attribution?.add([{attributionHtml:e}]))}};e.CesiumIonPlugin=b,e.OverlayPlugin=v,e.PersonViewPlugin=h,e.TileJsonPlugin=E,e.moveOverlayElement=g});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@navaramap/three-plugins",
   "type": "module",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "main": "dist/index.umd.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,14 +20,14 @@
   },
   "peerDependencies": {
     "three": ">=0.183.0",
-    "@navaramap/three": "0.0.4",
-    "@navaramap/three-default-plugin": "0.0.4"
+    "@navaramap/three": "0.0.5",
+    "@navaramap/three-default-plugin": "0.0.5"
   },
   "devDependencies": {
     "@types/three": "0.185.1",
     "three": "0.185.1",
-    "@navaramap/three-default-plugin": "0.0.4",
-    "@navaramap/three": "0.0.4"
+    "@navaramap/three": "0.0.5",
+    "@navaramap/three-default-plugin": "0.0.5"
   },
   "scripts": {
     "type-check": "tsc && tsc -p tsconfig.node.json",

package/src/TileJsonPlugin.test.ts

@@ -3,13 +3,17 @@ import { describe, it, expect, vi, afterEach } from "vitest";
 import { TileJsonPlugin, type TileJson } from "./TileJsonPlugin";
 
 // Importing the real @navaramap/three touches WASM/os at module load, which fails
-// in the test environment. TileJsonPlugin only needs `Plugin` and `EventHandler`
-// as runtime values (everything else it imports from there is type-only), so
-// stub the module. The EventHandler stub mirrors the real on/once/off/emit/clear.
+// in the test environment. TileJsonPlugin only needs `Plugin`, `EventHandler`,
+// and the elevation decoder factories as runtime values (everything else it
+// imports from there is type-only), so stub the module. The decoder factories
+// return sentinels the tests can assert on; the EventHandler stub mirrors the
+// real on/once/off/emit/clear.
 /* eslint-disable @typescript-eslint/no-extraneous-class */
 vi.mock("@navaramap/three", () => ({
   default: class ThreeView {},
   Plugin: class Plugin {},
+  MAPBOX_ELEVATION_DECODER: () => ({ decoder: "mapbox" }),
+  TERRARIUM_ELEVATION_DECODER: () => ({ decoder: "terrarium" }),
   EventHandler: class EventHandler {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     private listeners = new Map<string, Set<(...a: any[]) => void>>();
@@ -192,6 +196,118 @@ describe("TileJsonPlugin.addSource", () => {
     expect(desc).not.toHaveProperty("tms");
   });
 
+  it("creates a raster-dem source with MapLibre defaults (tileSize 512, mapbox encoding)", async () => {
+    const { view } = makeFakeView();
+    const plugin = initPlugin(view);
+    stubTileJson({
+      tilejson: "3.0.0",
+      tiles: ["https://a/{z}/{x}/{y}.png"],
+      minzoom: 2,
+      maxzoom: 12,
+    } satisfies TileJson);
+
+    await plugin.addSource({ type: "raster-dem", id: "dem", url: DOC_URL });
+
+    expect(view.addSource).toHaveBeenCalledWith({
+      type: "raster-dem",
+      url: "https://a/{z}/{x}/{y}.png",
+      id: "dem",
+      minZoom: 2,
+      maxZoom: 12,
+      tileSize: 512,
+      elevationDecoder: { decoder: "mapbox" },
+    });
+  });
+
+  it("honors the document's MapLibre-compatible tileSize/encoding for raster-dem", async () => {
+    const { view } = makeFakeView();
+    const plugin = initPlugin(view);
+    stubTileJson({
+      tilejson: "3.0.0",
+      tiles: ["https://a/{z}/{x}/{y}.png"],
+      tileSize: 256,
+      encoding: "terrarium",
+    } satisfies TileJson);
+
+    await plugin.addSource({ type: "raster-dem", url: DOC_URL });
+
+    expect(view.addSource).toHaveBeenCalledWith(
+      expect.objectContaining({
+        tileSize: 256,
+        elevationDecoder: { decoder: "terrarium" },
+      }),
+    );
+  });
+
+  it("rejects an unsupported raster-dem encoding", async () => {
+    const { view } = makeFakeView();
+    const plugin = initPlugin(view);
+    stubTileJson({
+      tilejson: "3.0.0",
+      tiles: ["https://a/{z}/{x}/{y}.png"],
+      encoding: "custom" as never,
+    } satisfies TileJson);
+
+    await expect(
+      plugin.addSource({ type: "raster-dem", url: DOC_URL }),
+    ).rejects.toThrow(/unsupported raster-dem encoding/);
+    expect(view.addSource).not.toHaveBeenCalled();
+  });
+
+  it("prefers description-level fields over the fetched document", async () => {
+    const { view } = makeFakeView();
+    const plugin = initPlugin(view);
+    stubTileJson({
+      tilejson: "3.0.0",
+      tiles: ["https://a/{z}/{x}/{y}.png"],
+      minzoom: 0,
+      maxzoom: 10,
+      scheme: "xyz",
+      tileSize: 512,
+      encoding: "mapbox",
+    } satisfies TileJson);
+
+    await plugin.addSource({
+      type: "raster-dem",
+      url: DOC_URL,
+      minzoom: 3,
+      maxzoom: 15,
+      scheme: "tms",
+      tileSize: 256,
+      encoding: "terrarium",
+    });
+
+    expect(view.addSource).toHaveBeenCalledWith({
+      type: "raster-dem",
+      url: "https://a/{z}/{x}/{y}.png",
+      minZoom: 3,
+      maxZoom: 15,
+      tms: true,
+      tileSize: 256,
+      elevationDecoder: { decoder: "terrarium" },
+    });
+  });
+
+  it("applies description-level fields even when the document omits them", async () => {
+    const { view } = makeFakeView();
+    const plugin = initPlugin(view);
+    stubTileJson({
+      tilejson: "3.0.0",
+      tiles: ["https://a/{z}/{x}/{y}.png"],
+    } satisfies TileJson);
+
+    await plugin.addSource({
+      type: "raster-tile",
+      url: DOC_URL,
+      minzoom: 4,
+      maxzoom: 8,
+    });
+
+    expect(view.addSource).toHaveBeenCalledWith(
+      expect.objectContaining({ minZoom: 4, maxZoom: 8 }),
+    );
+  });
+
   it("throws when the TileJSON fetch fails", async () => {
     const { view } = makeFakeView();
     const plugin = initPlugin(view);

package/src/TileJsonPlugin.ts

@@ -6,7 +6,10 @@
  * document and registers it as a single Navara source. {@link TileJsonPlugin.addSource}
  * mirrors {@link ThreeView.addSource}: a discriminated `type` plus an optional
  * `id`, with `url` pointing at the TileJSON document. The plugin derives the tile
- * URL, `minzoom`/`maxzoom`, and `scheme` from the document.
+ * URL, `minzoom`/`maxzoom`, and `scheme` from the document, plus — for
+ * `raster-dem` sources — the MapLibre-compatible `tileSize` and `encoding`
+ * fields. Each derived field can also be set on the description itself, which
+ * takes precedence over the document.
  *
  * Each document's `attribution` is surfaced automatically through the view's
  * built-in attribution UI (`view.attribution`). Callers who want a custom credit
@@ -36,6 +39,16 @@
  * view.addLayer({ type: "raster", source });
  * // ...or directly by the id passed above.
  * view.addLayer({ type: "raster", source: "basemap" });
+ *
+ * // Raster-DEM terrain. The MapLibre-compatible `tileSize`/`encoding` fields
+ * // are honored from the document (or the description below), defaulting to
+ * // MapLibre's 512 / "mapbox".
+ * const dem = await tilejson.addSource({
+ *   type: "raster-dem",
+ *   url: "https://example.com/terrain.json",
+ *   encoding: "terrarium", // takes precedence over the document
+ * });
+ * view.addLayer({ type: "terrain", source: dem, terrain: {} });
  * ```
  *
  * ### Custom attribution UI
@@ -55,6 +68,8 @@
 import ThreeView, {
   Plugin,
   EventHandler,
+  MAPBOX_ELEVATION_DECODER,
+  TERRARIUM_ELEVATION_DECODER,
   type Source,
   type ViewContext,
 } from "@navaramap/three";
@@ -65,6 +80,17 @@ type View = ThreeView<DefaultDescriptions>;
 /** Matches a TileJSON version such as "3.0.0" (major.minor.patch). */
 const TILEJSON_VERSION = /^3\.\d+\.\d+$/;
 
+/** MapLibre's raster-dem defaults, applied when neither the description nor the document sets them. */
+const DEFAULT_DEM_TILE_SIZE = 512;
+const DEFAULT_DEM_ENCODING: TileJsonDemEncoding = "mapbox";
+
+/**
+ * How a `raster-dem` document's RGB tiles encode elevation, matching MapLibre's
+ * `encoding` values. MapLibre's `"custom"` (free-form decode factors) is not
+ * supported.
+ */
+export type TileJsonDemEncoding = "mapbox" | "terrarium";
+
 /**
  * The subset of a TileJSON 3.0.0 document this plugin consumes. Other spec
  * fields (`bounds`, `center`, `grids`, ...) are ignored.
@@ -82,24 +108,34 @@ export type TileJson = {
   maxzoom?: number;
   /** Tiling scheme. `"tms"` flips the Y axis (raster sources only). @defaultValue "xyz" */
   scheme?: "xyz" | "tms";
+  /**
+   * Tile size in pixels. Not part of the TileJSON spec, but emitted by
+   * MapLibre-oriented tile servers; applied to `raster-dem` sources only.
+   * @defaultValue 512
+   */
+  tileSize?: number;
+  /**
+   * Elevation encoding of DEM tiles. Not part of the TileJSON spec, but
+   * emitted by MapLibre-oriented tile servers; applied to `raster-dem` sources
+   * only.
+   * @defaultValue "mapbox"
+   */
+  encoding?: TileJsonDemEncoding;
 };
 
 /**
  * Which Navara source type a TileJSON document is materialized into. Declared by
  * the caller because TileJSON has no field that reliably distinguishes raster
- * imagery from vector tiles.
+ * imagery from vector or elevation tiles.
  */
-export type TileJsonSourceType = "raster-tile" | "vector-tile";
+export type TileJsonSourceType = "raster-tile" | "vector-tile" | "raster-dem";
 
 /**
- * Describes a TileJSON tile source to register via {@link TileJsonPlugin.addSource}.
- * Mirrors the shape of {@link ThreeView.addSource}, except `url` is the TileJSON
- * document URL (not a tile template) — the plugin fetches it and derives the tile
- * URL, zoom range, and attribution from the document.
+ * Fields shared by every {@link TileJsonSourceDescription} variant. Alongside
+ * `url` and `id`, it accepts the same optional fields the TileJSON document
+ * carries; a field set here takes precedence over the fetched document's value.
  */
-export type TileJsonSourceDescription = {
-  /** Navara source type to create, as in `addSource`. */
-  type: TileJsonSourceType;
+type TileJsonSourceDescriptionBase = {
   /** URL of the TileJSON 3.0.0 document to fetch and expand. */
   url: string;
   /**
@@ -108,8 +144,49 @@ export type TileJsonSourceDescription = {
    * handle. When omitted, the engine generates one.
    */
   id?: string;
+  /** Overrides the document's `minzoom` when set. */
+  minzoom?: number;
+  /** Overrides the document's `maxzoom` when set. */
+  maxzoom?: number;
+  /** Overrides the document's `scheme` when set. */
+  scheme?: "xyz" | "tms";
 };
 
+/** Registers a TileJSON document as a `raster-tile` (imagery) source. */
+export type TileJsonRasterTileSourceDescription =
+  TileJsonSourceDescriptionBase & {
+    type: "raster-tile";
+  };
+
+/** Registers a TileJSON document as a `vector-tile` (MVT) source. */
+export type TileJsonVectorTileSourceDescription =
+  TileJsonSourceDescriptionBase & {
+    type: "vector-tile";
+  };
+
+/** Registers a TileJSON document as a `raster-dem` (elevation) source. */
+export type TileJsonRasterDemSourceDescription =
+  TileJsonSourceDescriptionBase & {
+    type: "raster-dem";
+    /** Overrides the document's `tileSize` when set. @defaultValue 512 */
+    tileSize?: number;
+    /** Overrides the document's `encoding` when set. @defaultValue "mapbox" */
+    encoding?: TileJsonDemEncoding;
+  };
+
+/**
+ * Describes a TileJSON tile source to register via {@link TileJsonPlugin.addSource}.
+ * Mirrors the shape of {@link ThreeView.addSource}, except `url` is the TileJSON
+ * document URL (not a tile template) — the plugin fetches it and derives the tile
+ * URL, zoom range, and attribution from the document. Document-derived fields
+ * (`minzoom`, `maxzoom`, `scheme` — plus `tileSize` and `encoding` for
+ * `raster-dem`) can also be set here to take precedence over the document.
+ */
+export type TileJsonSourceDescription =
+  | TileJsonRasterTileSourceDescription
+  | TileJsonVectorTileSourceDescription
+  | TileJsonRasterDemSourceDescription;
+
 /** Detail passed to the {@link TileJsonPlugin} `loaded` event. */
 export type TileJsonLoadedEvent = {
   /** The Navara source created for the document. */
@@ -153,6 +230,26 @@ function validateTileJson(doc: TileJson): void {
   }
 }
 
+/**
+ * Map a MapLibre `encoding` value to the engine's elevation decoder. Throws for
+ * unknown encodings (including MapLibre's `"custom"`, whose free-form decode
+ * factors have no TileJSON representation) so a raster-dem source is never
+ * silently created with a wrong decoder.
+ */
+function resolveElevationDecoder(encoding: TileJsonDemEncoding) {
+  switch (encoding) {
+    case "mapbox":
+      return MAPBOX_ELEVATION_DECODER();
+    case "terrarium":
+      return TERRARIUM_ELEVATION_DECODER();
+    default:
+      throw new Error(
+        `TileJsonPlugin: unsupported raster-dem encoding ${JSON.stringify(encoding)}. ` +
+          'Supported encodings: "mapbox", "terrarium".',
+      );
+  }
+}
+
 export class TileJsonPlugin extends Plugin<View, ViewContext> {
   private view?: View;
   private readonly events = new EventHandler<TileJsonPluginEventMap>();
@@ -195,9 +292,13 @@ export class TileJsonPlugin extends Plugin<View, ViewContext> {
    *
    * `desc.url` is the TileJSON document URL; the plugin fetches it, then creates
    * one source of the requested `desc.type` using the document's first tile
-   * endpoint, `minzoom`/`maxzoom`, and `scheme`. The document's `attribution` is
-   * surfaced through the view's built-in attribution UI (`view.attribution`), and
-   * a `loaded` event is emitted carrying the source, document, and attribution.
+   * endpoint, `minzoom`/`maxzoom`, and `scheme` — plus, for `raster-dem`, the
+   * MapLibre-compatible `tileSize` and `encoding` fields (defaulting to
+   * MapLibre's 512 and `"mapbox"`). Each of those fields can also be set on
+   * `desc` itself, taking precedence over the document. The document's
+   * `attribution` is surfaced through the view's built-in attribution UI
+   * (`view.attribution`), and a `loaded` event is emitted carrying the source,
+   * document, and attribution.
    *
    * A TileJSON `tiles` array lists mirror endpoints for the same tileset (as in
    * MapLibre, which shards requests across them). Navara sources take a single
@@ -228,26 +329,38 @@ export class TileJsonPlugin extends Plugin<View, ViewContext> {
       );
     }
 
-    const { minzoom, maxzoom, scheme } = doc;
+    // Description-level fields take precedence over the fetched document.
+    const minzoom = desc.minzoom ?? doc.minzoom;
+    const maxzoom = desc.maxzoom ?? doc.maxzoom;
+    const scheme = desc.scheme ?? doc.scheme;
     const id = desc.id;
-    const source =
-      desc.type === "raster-tile"
-        ? view.addSource({
-            type: "raster-tile",
-            url,
-            ...(id !== undefined ? { id } : {}),
-            ...(minzoom !== undefined ? { minZoom: minzoom } : {}),
-            ...(maxzoom !== undefined ? { maxZoom: maxzoom } : {}),
-            ...(scheme === "tms" ? { tms: true } : {}),
-          })
-        : // vector-tile sources have no minZoom / tms fields in the engine, so
-          // only maxzoom carries over.
-          view.addSource({
-            type: "vector-tile",
-            url,
-            ...(id !== undefined ? { id } : {}),
-            ...(maxzoom !== undefined ? { maxZoom: maxzoom } : {}),
-          });
+    const shared = {
+      url,
+      ...(id !== undefined ? { id } : {}),
+      ...(maxzoom !== undefined ? { maxZoom: maxzoom } : {}),
+    };
+    const rasterShared = {
+      ...shared,
+      ...(minzoom !== undefined ? { minZoom: minzoom } : {}),
+      ...(scheme === "tms" ? { tms: true } : {}),
+    };
+    let source: Source;
+    if (desc.type === "raster-tile") {
+      source = view.addSource({ type: "raster-tile", ...rasterShared });
+    } else if (desc.type === "raster-dem") {
+      source = view.addSource({
+        type: "raster-dem",
+        ...rasterShared,
+        tileSize: desc.tileSize ?? doc.tileSize ?? DEFAULT_DEM_TILE_SIZE,
+        elevationDecoder: resolveElevationDecoder(
+          desc.encoding ?? doc.encoding ?? DEFAULT_DEM_ENCODING,
+        ),
+      });
+    } else {
+      // vector-tile sources have no minZoom / tms fields in the engine, so
+      // only maxzoom carries over.
+      source = view.addSource({ type: "vector-tile", ...shared });
+    }
 
     if (doc.attribution) {
       this.addCredit(doc.attribution);

package/src/index.ts

@@ -28,8 +28,12 @@ export {
 export {
   TileJsonPlugin,
   type TileJson,
+  type TileJsonDemEncoding,
   type TileJsonSourceType,
   type TileJsonSourceDescription,
+  type TileJsonRasterTileSourceDescription,
+  type TileJsonVectorTileSourceDescription,
+  type TileJsonRasterDemSourceDescription,
   type TileJsonLoadedEvent,
   type TileJsonPluginEventMap,
 } from "./TileJsonPlugin";