@map-zero/cesium 0.3.2 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcos Pérez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -6,3 +6,13 @@ See the main repository for documentation, examples, and release notes:
 
 https://github.com/mploscos/map-zero
 
+
+## Cesium 1.145 native vectors
+
+Version 0.4.0 renders native MVT with an XYZ `vectorTilesUrl`, using Cesium 1.145 `MVTDataProvider` and surface draping. The built-in server exposes PMTiles data at `/api/vector-tiles/{z}/{x}/{y}.mvt`.
+
+Native labels share the OpenLayers theme’s selection and priority rules, with deduplication and screen decluttering. Set `labels: false` or `maxLabels` (default 150), and toggle them with `controller.setLabelsVisible()`.
+
+The raster worker has been removed. Cesium no longer requires OpenLayers or PMTiles as peer dependencies. Provide an MVT endpoint for context, or `contextOverlay: false` for a static 3D Tiles-only scene. Re-export old PMTiles for label anchor metadata. See [integration details](https://github.com/mploscos/map-zero/blob/v0.4.0/docs/cesium.md).
+
+Requires Cesium 1.145.0 and Node 22+ for package consumers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@map-zero/cesium",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "description": "Cesium integration helper for map-zero 3D Tiles packages.",
   "license": "MIT",
@@ -22,11 +22,12 @@
     "README.md"
   ],
   "dependencies": {
-    "@map-zero/raster": "0.3.2"
+    "@map-zero/core": "0.4.0"
   },
   "peerDependencies": {
-    "cesium": "1.141.0",
-    "ol": "10.10.0",
-    "pmtiles": "4.4.1"
+    "cesium": "1.145.0"
+  },
+  "engines": {
+    "node": ">=22"
   }
 }

package/src/cesium-labels.js

@@ -0,0 +1,150 @@
+import {
+  Cartesian2, Cartesian3, Color, EllipsoidalOccluder, HeightReference,
+  HorizontalOrigin, LabelCollection, LabelStyle, SceneMode, SceneTransforms, VerticalOrigin
+} from 'cesium';
+import { LruCache } from '../../core/src/shared/cache.js';
+import { describeLabel } from '../../core/src/labels.js';
+import { getLayerRule, zoomMatchesRule } from '../../core/src/style.js';
+
+/** Deterministic priority placement; bounds the visible label count and overlap checks. */
+export function selectLabels(candidates, maxLabels) {
+  const selected = [];
+  const ids = new Set();
+  candidates.sort((a, b) => b.priority - a.priority || a.key.localeCompare(b.key));
+  for (const candidate of candidates) {
+    if (ids.has(candidate.key)) continue;
+    ids.add(candidate.key);
+    const a = candidate.box;
+    if (selected.some(({ box: b }) => a[0] < b[2] && a[2] > b[0] && a[1] < b[3] && a[3] > b[1])) continue;
+    selected.push(candidate);
+    if (selected.length >= maxLabels) break;
+  }
+  return selected;
+}
+
+/** Labels share the native provider's loaded tiles; no extra requests or MVT decode. */
+export function createCesiumLabels(viewer, tileset, options) {
+  const maxLabels = options.maxLabels ?? 150;
+  if (!Number.isInteger(maxLabels) || maxLabels < 1 || maxLabels > 1000) {
+    throw new Error('maxLabels must be an integer between 1 and 1000');
+  }
+  const scene = viewer.scene;
+  const collection = scene.primitives.add(new LabelCollection({ scene, show: options.labels !== false }));
+  const cache = new WeakMap();
+  const visible = new Set();
+  const active = new Map();
+  const widths = new LruCache(1024);
+  const measure = document.createElement('canvas').getContext('2d');
+  const occluder = new EllipsoidalOccluder(scene.globe?.ellipsoid);
+  let destroyed = false;
+
+  function candidatesFor(content) {
+    if (cache.has(content)) return cache.get(content);
+    const candidates = [];
+    // Cesium 1.145 vector content has one feature table per MVT source layer.
+    const tables = content.batchTables ?? [];
+    for (let table = 0; table < tables.length; table++) {
+      for (let i = 0; i < tables[table].featuresLength; i++) {
+        const feature = content.getFeature(i, table);
+        if (!feature) continue;
+        const lon = feature.getProperty('mapzero_label_lon');
+        const lat = feature.getProperty('mapzero_label_lat');
+        if (!Number.isFinite(lon) || !Number.isFinite(lat) || Math.abs(lon) > 180 || Math.abs(lat) > 90) continue;
+        const source = String(feature.getProperty('_layer') ?? feature.getProperty('layer') ?? '');
+        const layer = source === 'aviation' ? 'aip' : source;
+        const properties = Object.fromEntries(feature.getPropertyIds().map((key) => [key, feature.getProperty(key)]));
+        const adapter = { get: (key) => properties[key] };
+        // Keep data independent of the feature lifetime. Eligibility is evaluated
+        // again at the current zoom, so zoom limits in custom themes still apply.
+        const id = properties.id ?? properties.fid ?? `${lon},${lat}`;
+        candidates.push({ key: `${layer}:${id}`, layer, adapter, position: Cartesian3.fromDegrees(lon, lat) });
+      }
+    }
+    cache.set(content, candidates);
+    return candidates;
+  }
+
+  function update() {
+    if (destroyed || !collection.show) return;
+    const candidates = [];
+    const zoom = options.getZoom();
+    const width = scene.canvas.clientWidth, height = scene.canvas.clientHeight;
+    const layerRules = new Map();
+    occluder.cameraPosition = viewer.camera.positionWC;
+    for (const content of visible) {
+      for (const candidate of candidatesFor(content)) {
+        const { layer, adapter, position } = candidate;
+        if (!layerRules.has(layer)) layerRules.set(layer, getLayerRule(options.styleDocument, { id: layer }));
+        if (options.visibility.get(layer) === false || !zoomMatchesRule(zoom, layerRules.get(layer))) continue;
+        const opacity = options.opacities.get(layer) ?? options.opacity ?? 1;
+        if (opacity <= 0) continue;
+        if (candidate.zoom !== zoom) {
+          candidate.zoom = zoom;
+          candidate.descriptor = describeLabel(adapter, layer, zoom, options.styleDocument);
+          if (candidate.descriptor?.text.length > 64) {
+            candidate.descriptor.text = candidate.descriptor.text.slice(0, 61).trimEnd() + '…';
+          }
+        }
+        const descriptor = candidate.descriptor;
+        if (!descriptor) continue;
+        if (scene.mode === SceneMode.SCENE3D && !occluder.isPointVisible(position)) continue;
+        const point = SceneTransforms.worldToWindowCoordinates(scene, position);
+        if (!point || point.x < 0 || point.x > width || point.y < 0 || point.y > height) continue;
+        const measureKey = `${descriptor.font}:${descriptor.text}`;
+        let textWidth = widths.get(measureKey);
+        if (textWidth === undefined) {
+          measure.font = descriptor.font;
+          textWidth = measure.measureText(descriptor.text).width;
+          widths.set(measureKey, textWidth);
+        }
+        const halfWidth = textWidth / 2 + descriptor.haloWidth + 6;
+        const labelHeight = (Number(/([\d.]+)px/.exec(descriptor.font)?.[1]) || 12) + 2 * descriptor.haloWidth + 6;
+        candidates.push({ ...candidate, ...descriptor, opacity,
+          box: [point.x - halfWidth, point.y - labelHeight - 6, point.x + halfWidth, point.y - 6] });
+      }
+    }
+    const selected = selectLabels(candidates, maxLabels);
+    const keys = new Set(selected.map((label) => label.key));
+    let changed = false;
+    for (const [key, value] of active) {
+      if (!keys.has(key)) { collection.remove(value.label); active.delete(key); changed = true; }
+    }
+    for (const candidate of selected) {
+      const signature = JSON.stringify([candidate.text, candidate.font, candidate.fill, candidate.halo, candidate.haloWidth, candidate.opacity]);
+      const previous = active.get(candidate.key);
+      if (previous?.signature === signature) continue;
+      const fillColor = Color.fromCssColorString(candidate.fill);
+      const outlineColor = Color.fromCssColorString(candidate.halo);
+      fillColor.alpha *= candidate.opacity; outlineColor.alpha *= candidate.opacity;
+      const properties = {
+        id: { mapZeroLayer: candidate.layer, mapZeroLabel: candidate.key },
+        position: candidate.position, text: candidate.text, font: candidate.font,
+        fillColor, outlineColor, outlineWidth: candidate.haloWidth,
+        style: LabelStyle.FILL_AND_OUTLINE, horizontalOrigin: HorizontalOrigin.CENTER,
+        verticalOrigin: VerticalOrigin.BOTTOM, pixelOffset: new Cartesian2(0, -6),
+        heightReference: HeightReference.CLAMP_TO_TERRAIN, disableDepthTestDistance: Number.POSITIVE_INFINITY
+      };
+      const label = previous?.label ?? collection.add(properties);
+      if (previous) Object.assign(label, properties);
+      active.set(candidate.key, { signature, label }); changed = true;
+    }
+    if (changed) scene.requestRender();
+  }
+  const removers = [
+    scene.preRender.addEventListener(() => visible.clear()),
+    tileset.tileVisible.addEventListener((tile) => visible.add(tile.content)),
+    // Mutate primitives only after traversal; an unchanged layout requests no frame.
+    scene.postRender.addEventListener(() => queueMicrotask(update))
+  ];
+  return {
+    collection,
+    setVisible(visible) { collection.show = Boolean(visible); scene.requestRender(); },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      removers.forEach((remove) => remove());
+      visible.clear(); active.clear(); widths.clear();
+      scene.primitives.remove(collection);
+    }
+  };
+}

package/src/index.js

@@ -1,16 +1,12 @@
+import { createMapZeroVectorContext } from './vector.js';
 import {
   Cesium3DTileColorBlendMode,
   Cesium3DTileStyle,
-  Cesium3DTileset,
-  ImageryLayer
+  Cesium3DTileset
 } from 'cesium';
-import {
-  contextOverlayConfig,
-  hasMapZeroContextOverlay,
-  MapZeroCesiumImageryProvider
-} from './imagery.js';
 
-export { MapZeroCesiumImageryProvider } from './imagery.js';
+
+export { createNativeVectorStyle, vectorZoomRange } from './vector.js';
 
 let autoInstanceCounter = 0;
 
@@ -160,10 +156,12 @@ export async function createMapZeroCesiumTilesets(options) {
  *   tilesetOpacity?: number,
  *   buildingsOpacity?: number,
  *   contextOverlay?: boolean,
+ *   vectorTilesUrl?: string,
+ *   vectorMaxZoom?: number,
+ *   labels?: boolean,
+ *   maxLabels?: number,
+ *   vectorHeightReference?: import('cesium').HeightReference,
  *   contextOpacity?: number,
- *   contextOverzoomLevels?: number,
- *   contextEdgeGuardPixels?: number,
- *   workerUrl?: string | URL,
  *   buildings3d?: boolean,
  *   tilesetMaximumScreenSpaceError?: number,
  *   tilesetCacheBytes?: number,
@@ -178,8 +176,9 @@ export async function createMapZeroCesiumTilesets(options) {
  *   manifest: MapZeroManifest,
  *   style: Record<string, unknown> | null,
  *   tilesets: Record<string, Cesium3DTileset>,
- *   imageryProvider?: MapZeroCesiumImageryProvider,
- *   imageryLayer?: ImageryLayer,
+ *   vectorProvider?: import('cesium').MVTDataProvider,
+ *   labelCollection?: import('cesium').LabelCollection,
+ *   setLabelsVisible: (visible: boolean) => void,
  *   setVisible: (layerId: string, visible: boolean) => void,
  *   setOpacity: (layerId: string, opacity: number) => void,
  *   destroy: () => void
@@ -196,27 +195,18 @@ export async function addMapZeroToCesium(viewer, options) {
   const result = await createMapZeroCesiumTilesets(options);
   const uniqueTilesets = [...new Set(Object.values(result.tilesets))];
   const visibleLayers = new Set(Object.keys(result.tilesets));
-  let opacity = options.tilesetOpacity ?? options.opacity ?? 1;
-  const imageryProvider = shouldCreateContextOverlay(result.manifest, options)
-    ? new MapZeroCesiumImageryProvider({
-        manifest: result.manifest,
-        manifestUrl: options.manifestUrl,
-        styleDocument: result.style,
-        layers: contextOverlayConfig(result.manifest)?.layers,
-        overzoomLevels: options.contextOverzoomLevels,
-        edgeGuardPixels: options.contextEdgeGuardPixels,
-        workerUrl: options.workerUrl
-      })
-    : undefined;
-  const imageryLayer = imageryProvider
-    ? new ImageryLayer(imageryProvider, {
-        alpha: clamp01(Number(options.contextOpacity ?? options.opacity ?? 1)),
-        show: true
-      })
-    : undefined;
-
-  if (imageryLayer) {
-    viewer.imageryLayers?.add(imageryLayer);
+  let vectorContext;
+  try {
+    if (options.contextOverlay !== false) {
+      vectorContext = await createMapZeroVectorContext(viewer, {
+        ...options, manifest: result.manifest, styleDocument: result.style,
+        excludedLayers: Object.keys(result.tilesets)
+      });
+      viewer.scene.primitives.add(vectorContext.provider);
+    }
+  } catch (error) {
+    for (const tileset of uniqueTilesets) tileset.destroy();
+    throw error;
   }
   for (const tileset of uniqueTilesets) {
     viewer.scene.primitives.add(tileset);
@@ -233,40 +223,34 @@ export async function addMapZeroToCesium(viewer, options) {
     id: result.id,
     style: result.style,
     tilesets: result.tilesets,
-    imageryProvider,
-    imageryLayer,
+    vectorProvider: vectorContext?.provider,
+    vectorRange: vectorContext?.range,
+    labelCollection: vectorContext?.labels?.collection,
+    setLabelsVisible(visible) { vectorContext?.labels?.setVisible(visible); },
     setVisible(layerId, visible) {
+      vectorContext?.setVisible(layerId, visible);
       const tileset = result.tilesets[layerId];
-      if (tileset) {
-        if (visible) {
-          visibleLayers.add(layerId);
-        } else {
-          visibleLayers.delete(layerId);
-        }
-        applyStyleToTilesetMap(result.tilesets, result.style, {
-          opacity,
-          visibleLayers
-        });
-      }
-      imageryProvider?.setLayerVisible(layerId, visible);
-      imageryProvider?.setLayerVisible(layerId === 'aviation' ? 'aip' : layerId, visible);
+      if (tileset) tileset.show = Boolean(visible);
       viewer.scene?.requestRender?.();
     },
     setOpacity(layerId, nextOpacity) {
-      if (!result.tilesets[layerId]) return;
-      opacity = clamp01(Number(nextOpacity));
-      applyStyleToTilesetMap(result.tilesets, result.style, {
-        opacity,
+      vectorContext?.setOpacity(layerId, nextOpacity);
+      const tileset = result.tilesets[layerId];
+      if (!tileset) return;
+      tileset.style = createMapZeroCesiumStyle(result.style, {
+        layerId,
+        opacity: clamp01(Number(nextOpacity)),
         visibleLayers
       });
+      viewer.scene?.requestRender?.();
     },
     destroy() {
-      if (imageryLayer) {
-        viewer.imageryLayers?.remove(imageryLayer, true);
-      }
+      vectorContext?.destroy();
+      if (vectorContext) viewer.scene.primitives.remove(vectorContext.provider);
       for (const tileset of uniqueTilesets) {
         viewer.scene.primitives.remove(tileset);
       }
+      viewer.scene?.requestRender?.();
     }
   };
 }
@@ -352,21 +336,6 @@ function cesiumLayerMaterial(rule, layerId) {
   };
 }
 
-/**
- * @param {Record<string, Cesium3DTileset>} tilesets
- * @param {Record<string, unknown> | null} style
- * @param {{ opacity: number, visibleLayers: Set<string> }} options
- */
-function applyStyleToTilesetMap(tilesets, style, options) {
-  for (const [layerId, tileset] of Object.entries(tilesets)) {
-    tileset.style = createMapZeroCesiumStyle(style, {
-      layerId,
-      opacity: options.opacity,
-      visibleLayers: options.visibleLayers
-    });
-  }
-}
-
 /**
  * @param {string} layerId
  * @param {{ opacity?: number, tilesetOpacity?: number, buildingsOpacity?: number }} options
@@ -398,6 +367,11 @@ function layerStyle(styleJson, layerId) {
  * @returns {Array<{ layerId: string, url: string }>}
  */
 function manifestTilesetEntries(manifest, options = {}) {
+  if (manifest.tiles3d?.format === '3dtiles' && manifest.tiles3d.tilesets) {
+    return Object.entries(manifest.tiles3d.tilesets)
+      .filter(([layerId, url]) => typeof url === 'string' && isAllowedCesiumTilesetLayer(layerId, options))
+      .map(([layerId, url]) => ({ layerId, url }));
+  }
   if (manifest.tiles3d?.format === '3dtiles' && typeof manifest.tiles3d.url === 'string') {
     const layers = Array.isArray(manifest.tiles3d.layers) && manifest.tiles3d.layers.length > 0
       ? manifest.tiles3d.layers.map(String)
@@ -422,17 +396,6 @@ function isAllowedCesiumTilesetLayer(layerId, options) {
   return layerId !== 'buildings' || options.buildings3d !== false;
 }
 
-/**
- * @param {MapZeroManifest} manifest
- * @param {{ contextOverlay?: boolean }} options
- * @returns {boolean}
- */
-function shouldCreateContextOverlay(manifest, options) {
-  if (options.contextOverlay === false) {
-    return false;
-  }
-  return hasMapZeroContextOverlay(manifest);
-}
 
 /**
  * @param {Cesium3DTileset} tileset

package/src/vector.js

@@ -0,0 +1,138 @@
+import { createCesiumLabels } from './cesium-labels.js';
+import { BoundingSphere, Cartesian3, Cesium3DTileStyle, Color, HeightReference, MVTDataProvider, Rectangle } from 'cesium';
+import { getLayerRule, mergeFeatureRule, styleWidth, zoomMatchesRule } from '../../core/src/style.js';
+
+const POLYGON_LAYERS = new Set(['landuse', 'terrain', 'water', 'buildings']);
+
+/** Keep Cesium's eager runtime hierarchy bounded before allocating tile nodes. */
+export function vectorZoomRange(bbox, minZoom = 8, maxZoom = 16, maxNodes = 20000) {
+  if (!Array.isArray(bbox) || bbox.length !== 4 || !bbox.every(Number.isFinite)
+    || bbox[0] >= bbox[2] || bbox[1] >= bbox[3] || bbox[0] < -180 || bbox[2] > 180
+    || bbox[1] < -85.05112878 || bbox[3] > 85.05112878) {
+    throw new Error('Native vector rendering requires a valid Web Mercator manifest bbox');
+  }
+  if (!Number.isInteger(minZoom) || !Number.isInteger(maxZoom) || minZoom < 0 || maxZoom > 22 || minZoom > maxZoom) {
+    throw new Error('Native vector zoom range must satisfy 0 <= minZoom <= maxZoom <= 22');
+  }
+  const tileY = (lat, n) => (1 - Math.asinh(Math.tan(lat * Math.PI / 180)) / Math.PI) / 2 * n;
+  let nodes = 0;
+  let effectiveMaxZoom = minZoom;
+  for (let z = minZoom; z <= maxZoom; z++) {
+    const n = 2 ** z;
+    const columns = Math.floor((bbox[2] + 180) / 360 * n) - Math.floor((bbox[0] + 180) / 360 * n) + 1;
+    const rows = Math.floor(tileY(bbox[1], n)) - Math.floor(tileY(bbox[3], n)) + 1;
+    if (nodes + columns * rows > maxNodes) {
+      if (z === minZoom) throw new Error('Native vector extent is too large at minZoom; use a smaller package or lower minZoom');
+      break;
+    }
+    nodes += columns * rows;
+    effectiveMaxZoom = z;
+  }
+  return { minZoom, maxZoom: effectiveMaxZoom, estimatedNodes: nodes };
+}
+
+/** Translate the shared map-zero theme into native per-feature Cesium styling.
+ * Labels, glow, dashes and multi-pass road casings are not supported by MVTDataProvider.
+ */
+export function createNativeVectorStyle(styleDocument, options = {}) {
+  const zoom = options.zoom ?? 16;
+  const visibility = options.visibility ?? new Map();
+  const opacities = options.opacities ?? new Map();
+  const excludedLayers = options.excludedLayers ?? new Set();
+  const rules = new WeakMap();
+  const describe = (feature) => {
+    if (rules.has(feature)) return rules.get(feature);
+    const layer = String(feature.getProperty('_layer') ?? feature.getProperty('layer') ?? '');
+    const id = layer === 'aviation' ? 'aip' : layer;
+    const rule = mergeFeatureRule(getLayerRule(styleDocument, { id }), { get: (key) => feature.getProperty(key) });
+    const geometry = String(feature.getProperty('mapzero_geometry') ?? '');
+    const polygon = geometry ? geometry.includes('Polygon') : POLYGON_LAYERS.has(id) || id === 'boundaries';
+    const point = geometry ? geometry.includes('Point') : id === 'pois';
+    const info = { id, rule, polygon, point };
+    rules.set(feature, info);
+    return info;
+  };
+  const evaluateColor = (feature, result) => {
+    const { id, rule, polygon, point } = describe(feature);
+    const css = polygon || point ? rule.fill ?? rule.stroke : rule.stroke ?? rule.fill;
+    const color = Color.fromCssColorString(String(css ?? '#00ffff'), result) ?? Color.clone(Color.CYAN, result);
+    const alpha = polygon ? (rule.fill ? rule.fillOpacity ?? 1 : 0) : point ? rule.fillOpacity ?? 1 : rule.strokeOpacity ?? 1;
+    color.alpha *= Math.max(0, Math.min(1, Number(alpha) * (opacities.get(id) ?? options.opacity ?? 1)));
+    return color;
+  };
+  return new Cesium3DTileStyle({
+    show: { evaluate(feature) {
+      const { id, rule } = describe(feature);
+      return !excludedLayers.has(id) && visibility.get(id) !== false && zoomMatchesRule(zoom, rule);
+    } },
+    color: { evaluate: evaluateColor, evaluateColor },
+    lineWidth: { evaluate(feature) {
+      const { id, rule } = describe(feature);
+      return styleWidth(rule.strokeWidth, 1, id, zoom);
+    } },
+    pointSize: { evaluate(feature) {
+      const { id, rule } = describe(feature);
+      return 2 * styleWidth(rule.radius ?? rule.circleRadius, 3, id, zoom);
+    } }
+  });
+}
+
+/** Native MVT rendering, using the public Cesium 1.145 provider API. */
+export async function createMapZeroVectorContext(viewer, options) {
+  if (!options.vectorTilesUrl) throw new Error('Native vector rendering requires vectorTilesUrl with /{z}/{x}/{y}.mvt');
+  const template = new URL(options.vectorTilesUrl, new URL(options.manifestUrl, globalThis.location?.href ?? 'http://localhost/')).href
+    .replaceAll('%7B', '{').replaceAll('%7D', '}');
+  if (!['{z}', '{x}', '{y}'].every((token) => template.includes(token))) throw new Error('vectorTilesUrl must include {z}, {x}, and {y}');
+  const range = vectorZoomRange(options.manifest.bbox,
+    options.manifest.tiles?.minZoom ?? 8, Math.min(options.vectorMaxZoom ?? options.manifest.tiles?.maxZoom ?? 16, options.manifest.tiles?.maxZoom ?? 16));
+  const provider = await MVTDataProvider.fromUrl(template, {
+    minZoom: range.minZoom,
+    maxZoom: range.maxZoom,
+    extent: Rectangle.fromDegrees(...options.manifest.bbox),
+    heightReference: options.vectorHeightReference ?? HeightReference.CLAMP_TO_TERRAIN,
+    scene: viewer.scene
+  });
+  const visibility = new Map();
+  const opacities = new Map();
+  const excludedLayers = new Set(options.excludedLayers ?? []);
+  let zoom;
+  const bbox = options.manifest.bbox;
+  const latitude = (bbox[1] + bbox[3]) / 2;
+  const center = new BoundingSphere(Cartesian3.fromDegrees((bbox[0] + bbox[2]) / 2, latitude), 1);
+  const getZoom = () => {
+    const resolution = viewer.camera.getPixelSize(center, viewer.scene.canvas.clientWidth, viewer.scene.canvas.clientHeight);
+    return Math.max(0, Math.min(22, Math.round(Math.log2(156543.033928 * Math.cos(latitude * Math.PI / 180) / Math.max(0.001, resolution)))));
+  };
+  const refresh = () => {
+    const nextZoom = getZoom();
+    zoom = nextZoom;
+    provider.tileset.style = createNativeVectorStyle(options.styleDocument ?? {}, {
+      zoom, visibility, opacities, excludedLayers, opacity: options.contextOpacity ?? options.opacity ?? 1
+    });
+    viewer.scene.requestRender?.();
+  };
+  provider.tileset.maximumScreenSpaceError = 8;
+  provider.tileset.cacheBytes = 128 * 1024 * 1024;
+  provider.tileset.maximumCacheOverflowBytes = 64 * 1024 * 1024;
+  provider.tileset.preloadWhenHidden = false;
+  let labels;
+  try {
+    labels = createCesiumLabels(viewer, provider.tileset, {
+      ...options, styleDocument: options.styleDocument ?? {}, visibility, opacities, getZoom,
+      opacity: options.contextOpacity ?? options.opacity ?? 1
+    });
+  } catch (error) {
+    provider.destroy();
+    throw error;
+  }
+  refresh();
+  const removeCameraListener = viewer.camera?.moveEnd?.addEventListener(() => refresh());
+  return {
+    provider,
+    range,
+    labels,
+    setVisible(id, visible) { visibility.set(id === 'aviation' ? 'aip' : id, Boolean(visible)); refresh(); },
+    setOpacity(id, opacity) { opacities.set(id === 'aviation' ? 'aip' : id, Math.max(0, Math.min(1, Number(opacity)))); refresh(); },
+    destroy() { removeCameraListener?.(); labels.destroy(); }
+  };
+}

package/src/imagery.js

@@ -1,305 +0,0 @@
-import {
-  Event,
-  Rectangle,
-  WebMercatorTilingScheme
-} from 'cesium';
-
-import { WEB_MERCATOR_MAX_LAT } from '../../raster/src/shared/geo.js';
-import {
-  DEFAULT_CONTEXT_LAYERS,
-  layerAlias,
-  normalizeContextLayers,
-  sourceLayerFor
-} from '../../raster/src/shared/layers.js';
-import { pmtilesInfo } from '../../raster/src/shared/manifest.js';
-import { clampInteger } from '../../raster/src/shared/math.js';
-
-const DEFAULT_WORKER_URL = new URL('@map-zero/raster/imagery-worker.js', import.meta.url);
-const TILE_SIZE = 512;
-
-/**
- * Cesium ImageryProvider that rasterizes map-zero PMTiles/MVT tiles in a
- * dedicated worker. OffscreenCanvas is required by design so MVT decoding and
- * canvas drawing never block Cesium's main render thread.
- */
-export class MapZeroCesiumImageryProvider {
-  /**
-   * @param {{
-   *   manifest: Record<string, unknown>,
-   *   manifestUrl: string,
-   *   styleDocument?: Record<string, unknown> | null,
-   *   layers?: string[],
-   *   tileSize?: number,
-   *   minimumLevel?: number,
-   *   maximumLevel?: number,
-   *   overzoomLevels?: number,
-   *   edgeGuardPixels?: number,
-   *   workerUrl?: string | URL
-   * }} options
-   */
-  constructor(options) {
-    assertWorkerRasterSupport();
-    this.manifest = options.manifest;
-    this.manifestUrl = resolveWorkerBaseUrl(options.manifestUrl);
-    this.styleDocument = options.styleDocument ?? {};
-    this.tileWidth = Number(options.tileSize ?? TILE_SIZE);
-    this.tileHeight = Number(options.tileSize ?? TILE_SIZE);
-    this.tilingScheme = new WebMercatorTilingScheme();
-    this.rectangle = rectangleFromManifestBbox(
-      this.manifest,
-      /** @type {any} */ (this.manifest).bbox
-    );
-    this.minimumLevel = Number.isFinite(options.minimumLevel) ? Number(options.minimumLevel) : 0;
-    this.sourceMaximumLevel = Number(pmtilesInfo(this.manifest).maxZoom ?? 18);
-    const contextOverlay = contextOverlayConfig(this.manifest);
-    this.overzoomLevels = clampInteger(options.overzoomLevels ?? contextOverlay?.overzoomLevels ?? 0, 0, 4);
-    this.edgeGuardPixels = clampInteger(options.edgeGuardPixels ?? contextOverlay?.edgeGuardPixels ?? 0, 0, 8);
-    this.maximumLevel = Number.isFinite(options.maximumLevel)
-      ? Number(options.maximumLevel)
-      : this.sourceMaximumLevel + this.overzoomLevels;
-    this.ready = true;
-    this.readyPromise = Promise.resolve(true);
-    this.hasAlphaChannel = true;
-    this.errorEvent = new Event();
-    this.credit = undefined;
-    this.proxy = undefined;
-
-    this.layerIds = normalizeContextLayers(options.layers ?? contextOverlay?.layers ?? DEFAULT_CONTEXT_LAYERS);
-    this.layerVisibility = new Map(this.layerIds.map((layerId) => [layerId, true]));
-    this.cache = new Map();
-    this.pending = new Map();
-    this.nextRequestId = 1;
-    this.metrics = createImageryMetrics();
-    this.worker = new Worker(
-      options.workerUrl ?? DEFAULT_WORKER_URL,
-      { type: 'module' }
-    );
-    this.worker.addEventListener('message', (event) => this.#handleWorkerMessage(event.data));
-    this.worker.addEventListener('error', (event) => {
-      const error = new Error(event.message || 'map-zero imagery worker failed');
-      this.errorEvent.raiseEvent(error);
-      this.#rejectPending(error);
-    });
-    this.worker.postMessage({
-      type: 'init',
-      options: {
-        manifest: this.manifest,
-        manifestUrl: this.manifestUrl,
-        styleDocument: this.styleDocument,
-        layers: this.layerIds,
-        tileSize: this.tileWidth,
-        sourceMaximumLevel: this.sourceMaximumLevel,
-        overzoomLevels: this.overzoomLevels,
-        edgeGuardPixels: this.edgeGuardPixels,
-        source: String(contextOverlay?.source ?? pmtilesInfo(this.manifest).url ?? 'tiles.pmtiles')
-      }
-    });
-  }
-
-  /**
-   * @param {string} layerId
-   * @param {boolean} visible
-   */
-  setLayerVisible(layerId, visible) {
-    this.layerVisibility.set(sourceLayerFor(layerId), visible);
-    this.layerVisibility.set(layerAlias(layerId), visible);
-    this.cache.clear();
-    this.worker.postMessage({
-      type: 'visibility',
-      layerId,
-      visible
-    });
-  }
-
-  /**
-   * @param {number} x
-   * @param {number} y
-   * @param {number} level
-   * @returns {Promise<HTMLCanvasElement>}
-   */
-  async requestImage(x, y, level) {
-    const key = `${level}/${x}/${y}`;
-    const cached = this.cache.get(key);
-    if (cached) {
-      this.metrics.cacheHits++;
-      return cached;
-    }
-
-    const id = this.nextRequestId++;
-    const promise = new Promise((resolve, reject) => {
-      this.pending.set(id, { resolve, reject });
-      this.worker.postMessage({
-        type: 'render',
-        id,
-        x,
-        y,
-        z: level
-      });
-    }).catch((error) => {
-      this.errorEvent.raiseEvent(error);
-      return emptyCanvas(this.tileWidth, this.tileHeight);
-    });
-    this.cache.set(key, promise);
-    return promise;
-  }
-
-  getTileCredits() {
-    return undefined;
-  }
-
-  pickFeatures() {
-    return undefined;
-  }
-
-  destroy() {
-    this.#rejectPending(new Error('map-zero imagery provider destroyed'));
-    this.worker.terminate();
-    this.cache.clear();
-  }
-
-  #handleWorkerMessage(message) {
-    if (message?.type === 'metrics') {
-      mergeWorkerMetrics(this.metrics, message.metrics);
-      return;
-    }
-
-    if (message?.type !== 'tile') {
-      return;
-    }
-
-    if (message.metrics) {
-      mergeWorkerMetrics(this.metrics, message.metrics);
-    }
-    const pending = this.pending.get(message.id);
-    if (!pending) {
-      message.image?.close?.();
-      return;
-    }
-    this.pending.delete(message.id);
-    if (message.error) {
-      pending.reject(new Error(message.error));
-      return;
-    }
-    pending.resolve(imageToCanvas(message.image, this.tileWidth, this.tileHeight));
-  }
-
-  #rejectPending(error) {
-    for (const pending of this.pending.values()) {
-      pending.reject(error);
-    }
-    this.pending.clear();
-  }
-}
-
-function assertWorkerRasterSupport() {
-  if (typeof Worker !== 'function' || typeof OffscreenCanvas !== 'function' || typeof createImageBitmap !== 'function') {
-    throw new Error('map-zero Cesium context overlay requires Worker, OffscreenCanvas, and createImageBitmap');
-  }
-}
-
-function createImageryMetrics() {
-  const metrics = {
-    requested: 0,
-    cacheHits: 0,
-    decoded: 0,
-    features: 0,
-    overzoomed: 0,
-    requestLevels: {},
-    sourceLevels: {},
-    renderMs: { total: 0, max: 0 },
-    decodeMs: { total: 0, max: 0 }
-  };
-  const root = globalThis.__mapZeroCesiumMetrics ??= { imageryProviders: [] };
-  root.imageryProviders.push(metrics);
-  return metrics;
-}
-
-function mergeWorkerMetrics(target, patch) {
-  if (!patch) return;
-  for (const key of ['requested', 'cacheHits', 'decoded', 'features', 'overzoomed']) {
-    target[key] = Number(patch[key] ?? target[key] ?? 0);
-  }
-  target.requestLevels = { ...patch.requestLevels };
-  target.sourceLevels = { ...patch.sourceLevels };
-  target.renderMs = { ...patch.renderMs };
-  target.decodeMs = { ...patch.decodeMs };
-}
-
-/**
- * @param {Record<string, unknown>} manifest
- * @returns {{ type?: string, source?: string, layers?: string[], backend?: string, overzoomLevels?: number, edgeGuardPixels?: number } | null}
- */
-export function contextOverlayConfig(manifest) {
-  const pmtiles = pmtilesInfo(manifest);
-  if (!pmtiles.url) return null;
-  return {
-    type: 'client-rasterized-pmtiles',
-    source: pmtiles.url,
-    layers: contextLayerIds(manifest)
-  };
-}
-
-/**
- * @param {Record<string, unknown>} manifest
- * @returns {boolean}
- */
-export function hasMapZeroContextOverlay(manifest) {
-  const overlay = contextOverlayConfig(manifest);
-  return Boolean(overlay?.source || pmtilesInfo(manifest).url);
-}
-
-function contextLayerIds(manifest) {
-  const layers = Array.isArray(manifest.layers)
-    ? manifest.layers.map(String).filter((layerId) => layerId !== 'buildings')
-    : [];
-  return layers.length > 0 ? layers : DEFAULT_CONTEXT_LAYERS;
-}
-
-function rectangleFromManifestBbox(manifest, bbox) {
-  const padded = expandBboxByTileMargin(bbox, pmtilesInfo(manifest).minZoom);
-  return rectangleFromBbox(padded);
-}
-
-function rectangleFromBbox(bbox) {
-  if (Array.isArray(bbox) && bbox.length === 4) {
-    return Rectangle.fromDegrees(Number(bbox[0]), Number(bbox[1]), Number(bbox[2]), Number(bbox[3]));
-  }
-  return Rectangle.MAX_VALUE;
-}
-
-function expandBboxByTileMargin(bbox, minZoom) {
-  if (!Array.isArray(bbox) || bbox.length !== 4) return bbox;
-  const z = clampInteger(minZoom ?? 8, 0, 22);
-  const margin = 360 / 2 ** z;
-  return [
-    Math.max(-180, Number(bbox[0]) - margin),
-    Math.max(-WEB_MERCATOR_MAX_LAT, Number(bbox[1]) - margin),
-    Math.min(180, Number(bbox[2]) + margin),
-    Math.min(WEB_MERCATOR_MAX_LAT, Number(bbox[3]) + margin)
-  ];
-}
-
-function emptyCanvas(width, height) {
-  const canvas = document.createElement('canvas');
-  canvas.width = width;
-  canvas.height = height;
-  return canvas;
-}
-
-function imageToCanvas(image, width, height) {
-  const canvas = emptyCanvas(width, height);
-  if (!image) {
-    return canvas;
-  }
-
-  const ctx = canvas.getContext('2d');
-  if (ctx) {
-    ctx.drawImage(image, 0, 0, width, height);
-  }
-  image.close?.();
-  return canvas;
-}
-
-function resolveWorkerBaseUrl(url) {
-  return new URL(url, globalThis.location?.href ?? 'http://localhost/').toString();
-}