@honua/app-platform 0.1.2-beta.0 → 0.1.4-beta.0

package/scene-workspace/cesium-adapter.js

@@ -7,20 +7,30 @@
  * when a live {@link CesiumSceneRuntimeTarget} is actually driven.
  *
  * As of honua-server#1197 the adapter renders Honua 3D content end-to-end:
- * 3D-Tiles tilesets (add/remove/visibility), terrain providers (quantized-mesh
- * via `CesiumTerrainProvider`, with vertical exaggeration), and glTF/GLB model
- * layers placed with heading/pitch/roll + scale. It also resolves a picked
- * 3D-Tiles feature's attributes (batch properties / `EXT_structural_metadata`).
+ * 3D-Tiles tilesets (add/remove/visibility, including point clouds with bounded
+ * shading), terrain providers (quantized-mesh via `CesiumTerrainProvider`, with
+ * vertical exaggeration), imagery providers, and glTF/GLB model layers placed
+ * with heading/pitch/roll + scale. It also resolves a picked 3D-Tiles feature's
+ * attributes (batch properties / `EXT_structural_metadata`).
+ *
+ * Every model/imagery binding is validated before the peer loads, so an
+ * unrenderable primitive fails closed with a stable diagnostic instead of
+ * reaching a Cesium factory or silently rendering nothing.
  *
  * The provider wiring is still kept Cesium-mockable: every CesiumJS symbol the
  * adapter touches is read off the lazily-imported module, so the wiring is
  * exercised against a `vi.mock("cesium")` stub without a live WebGL `Viewer`.
  *
- * @experimental Part of the experimental `scene-workspace` surface; not yet
- *   covered by the SDK's semver contract prior to `1.0.0`.
+ * @beta Part of the beta `@honua/app-platform/scene-workspace` surface: the
+ *   adapter's exports are not renamed or removed through 0.1.x, and diagnostic
+ *   codes and renderer capability flags grow additively. The `cesium` peer floor
+ *   may rise within 0.1.x, and the server-authored 3D style types track the
+ *   Honua Server styling contract. See the surface tiers table in
+ *   `docs/standalone-capability-matrix.md`.
  * @module
  */
-import { createSceneRuntimeAdapter, diagnoseScenePrimitives, summarizeDiagnosticStatus, } from "./primitives.js";
+import { applyCesiumSceneTime, restoreCesiumClock, } from "./cesium-time.js";
+import { RENDERER_WGS84_SPATIAL_CAPABILITIES, createSceneRuntimeAdapter, diagnoseScenePrimitives, summarizeDiagnosticStatus, } from "./primitives.js";
 /**
  * Capabilities advertised by the Cesium adapter. Unlike the MapLibre 2.5D
  * adapter, Cesium is a true globe renderer: full 3D camera with
@@ -35,15 +45,25 @@ export const CESIUM_SCENE_CAPABILITIES = {
         protocols: ["quantized-mesh", "terrain-rgb", "raster-dem", "image-service", "custom"],
         supportsExaggeration: true,
     },
+    imagery: {
+        protocols: ["url-template", "wms", "wmts", "single-tile", "arcgis-imagery"],
+    },
     extrusion: true,
     modelLayer: {
-        // glTF/glb single models and 3D Tiles tilesets (incl. point clouds) are
-        // rendered live by this adapter as of #1197. I3S scene layers remain
-        // declared-capable (Cesium can consume them) but Honua's server does not yet
-        // emit i3s model-layer primitives, so they fall through to diagnostics only.
+        // CesiumJS itself can consume all four formats. `materializedFormats` is the
+        // narrower set this adapter actually attaches to a live scene: glTF/GLB
+        // single models and 3D-Tiles tilesets (point clouds ride the tileset path).
+        // I3S stays declared-capable but unmaterialized, so an i3s primitive fails
+        // closed with `scene-primitive-model-format-not-materialized` instead of
+        // reporting `supported` and then rendering nothing.
         formats: ["gltf", "glb", "3d-tiles", "i3s"],
+        materializedFormats: ["gltf", "glb", "3d-tiles"],
     },
     sceneLayerMetadata: true,
+    // The globe is the WGS84 ellipsoid. Web Mercator bindings are accepted
+    // because Cesium reprojects them onto that globe itself; nothing else is,
+    // because this adapter never reinterprets coordinates or heights.
+    spatial: RENDERER_WGS84_SPATIAL_CAPABILITIES,
 };
 const DEG2RAD = Math.PI / 180;
 const RAD2DEG = 180 / Math.PI;
@@ -147,6 +167,16 @@ export function modelLayerToCesiumPlacement(primitive) {
         scale: resolveCesiumModelScale(primitive.scale),
     };
 }
+const ownedCesiumTerrainProviders = new WeakSet();
+function disposeOwnedCesiumTerrainProvider(resource) {
+    if (resource && typeof resource === "object" && ownedCesiumTerrainProviders.has(resource)) {
+        const destroy = resource.destroy;
+        if (typeof destroy === "function") {
+            destroy.call(resource);
+            ownedCesiumTerrainProviders.delete(resource);
+        }
+    }
+}
 /**
  * Lazily import the CesiumJS runtime. Kept in its own function so the dynamic
  * `import("cesium")` is the *only* reference to the package in `src/`, which is
@@ -302,23 +332,53 @@ export async function applyTilesetServerStyle(tileset, tilesetUrl, cesium, fetch
  * (no fetch), so existing callers are unaffected.
  */
 export async function addCesium3DTileset(scene, primitive, cesium, options = {}) {
+    assertRenderableModelLayer(primitive);
+    options.signal?.throwIfAborted();
     const mod = cesium ?? (await loadCesium());
-    const tileset = await mod.Cesium3DTileset.fromUrl(primitive.uri);
-    if (primitive.position) {
-        tileset.modelMatrix = placementToModelMatrix(mod, modelLayerToCesiumPlacement(primitive));
+    const pointCloudShading = normalizePointCloudShading(primitive.pointCloudShading);
+    // Attribution reaches every materialized asset, not just imagery (#1049
+    // REQ-005): a tileset drawn without its credit is an attribution gap the user
+    // cannot see, and Cesium's `CreditDisplay` is the only place it can land.
+    const tilesetOptions = {
+        ...(pointCloudShading ? { pointCloudShading } : {}),
+        ...(primitive.attribution ? { credit: primitive.attribution } : {}),
+    };
+    const tileset = await (Object.keys(tilesetOptions).length > 0
+        ? mod.Cesium3DTileset.fromUrl(primitive.uri, tilesetOptions)
+        : mod.Cesium3DTileset.fromUrl(primitive.uri));
+    // From here on the tileset is adapter-owned. A placement, style-sidecar, or
+    // collection failure must not strand it: nothing else holds a reference, so
+    // it would otherwise retain its GPU/worker resources for the process lifetime.
+    // An abort settled while the load was in flight lands here too, which is what
+    // keeps a cancelled tileset out of the scene entirely rather than attached and
+    // then detached.
+    try {
+        options.signal?.throwIfAborted();
+        if (primitive.position) {
+            tileset.modelMatrix = placementToModelMatrix(mod, modelLayerToCesiumPlacement(primitive));
+        }
+        if (options.applyServerStyle !== false) {
+            await applyTilesetServerStyle(tileset, primitive.uri, mod, options.fetchImpl ?? fetch.bind(globalThis));
+            options.signal?.throwIfAborted();
+        }
+        scene.primitives.add(tileset);
     }
-    if (options.applyServerStyle !== false) {
-        await applyTilesetServerStyle(tileset, primitive.uri, mod, options.fetchImpl ?? fetch.bind(globalThis));
+    catch (error) {
+        if (scene.primitives.contains(tileset))
+            scene.primitives.remove(tileset);
+        destroyOwnedCesiumPrimitive(tileset);
+        throw error;
     }
-    scene.primitives.add(tileset);
-    return makeLayerHandle(scene, primitive.id, tileset, "model-layer", primitive.format);
+    return makeLayerHandle(scene, primitive.id, tileset, primitive.format);
 }
 /**
  * Materialize a glTF/GLB model from a model-layer primitive, placing it at the
  * primitive's position/rotation/scale, and add it to the scene. Returns a
- * handle for visibility / teardown.
+ * handle for visibility / opacity / teardown.
  */
-export async function addCesiumModel(scene, primitive, cesium) {
+export async function addCesiumModel(scene, primitive, cesium, options = {}) {
+    assertRenderableModelLayer(primitive);
+    options.signal?.throwIfAborted();
     const mod = cesium ?? (await loadCesium());
     const placement = modelLayerToCesiumPlacement(primitive);
     // `placementToModelMatrix` already folds the uniform scale into the model
@@ -328,9 +388,363 @@ export async function addCesiumModel(scene, primitive, cesium) {
     const model = await mod.Model.fromGltfAsync({
         url: primitive.uri,
         modelMatrix: placementToModelMatrix(mod, placement),
+        ...(primitive.attribution ? { credit: primitive.attribution } : {}),
     });
-    scene.primitives.add(model);
-    return makeLayerHandle(scene, primitive.id, model, "model-layer", primitive.format);
+    try {
+        options.signal?.throwIfAborted();
+        scene.primitives.add(model);
+    }
+    catch (error) {
+        destroyOwnedCesiumPrimitive(model);
+        throw error;
+    }
+    return makeLayerHandle(scene, primitive.id, model, primitive.format, mod);
+}
+/**
+ * Destroy an adapter-owned tileset/model exactly once. Cesium's
+ * `PrimitiveCollection.remove` normally destroys what it removes, but a
+ * collection configured with `destroyPrimitives = false` — and any failure
+ * before the primitive reaches a collection at all — would otherwise leak it.
+ */
+function destroyOwnedCesiumPrimitive(primitive) {
+    if (typeof primitive.destroy === "function" && primitive.isDestroyed?.() !== true)
+        primitive.destroy();
+}
+/**
+ * Fail closed on an unrenderable model layer *before* the optional Cesium peer
+ * is loaded, mirroring {@link addCesiumImageryLayer}. A missing/invalid/signed
+ * asset URI, an impossible placement, or out-of-range point-cloud shading must
+ * never reach a Cesium factory: `Cesium3DTileset.fromUrl("")` throws opaquely
+ * and `Cartesian3.fromDegrees(NaN, …)` produces a silently broken model matrix.
+ */
+function assertRenderableModelLayer(primitive) {
+    const validation = diagnoseScenePrimitives([primitive], CESIUM_SCENE_CAPABILITIES).find((diagnostic) => diagnostic.status === "unsupported");
+    if (validation)
+        throw new Error(`${validation.code}: ${validation.message}`);
+}
+/**
+ * Fail closed on an unrenderable elevation source *before* the scene's terrain
+ * provider or vertical exaggeration is touched, mirroring
+ * {@link assertRenderableModelLayer}.
+ *
+ * Every terrain protocol reaches Cesium through `CesiumTerrainProvider.fromUrl`,
+ * which rejects opaquely on a missing or malformed endpoint — and an elevation
+ * source in an unhonorable CRS or vertical datum would place the whole globe's
+ * heights wrong while reporting success. Neither may reach a live scene.
+ */
+function assertRenderableTerrain(primitive) {
+    const validation = diagnoseScenePrimitives([primitive], CESIUM_SCENE_CAPABILITIES).find((diagnostic) => diagnostic.status === "unsupported");
+    if (validation)
+        throw new Error(`${validation.code}: ${validation.message}`);
+}
+/**
+ * Project validated point-cloud shading onto Cesium's `PointCloudShading`
+ * option bag, dropping absent fields so Cesium keeps its own defaults instead
+ * of receiving explicit `undefined`s. Returns `undefined` when nothing is set.
+ */
+function normalizePointCloudShading(shading) {
+    if (!shading)
+        return undefined;
+    const options = {};
+    if (shading.attenuation !== undefined)
+        options.attenuation = shading.attenuation;
+    if (shading.maximumAttenuation !== undefined)
+        options.maximumAttenuation = shading.maximumAttenuation;
+    if (shading.geometricErrorScale !== undefined)
+        options.geometricErrorScale = shading.geometricErrorScale;
+    if (shading.eyeDomeLighting !== undefined)
+        options.eyeDomeLighting = shading.eyeDomeLighting;
+    if (shading.eyeDomeLightingStrength !== undefined) {
+        options.eyeDomeLightingStrength = shading.eyeDomeLightingStrength;
+    }
+    if (shading.eyeDomeLightingRadius !== undefined)
+        options.eyeDomeLightingRadius = shading.eyeDomeLightingRadius;
+    return Object.keys(options).length > 0 ? options : undefined;
+}
+/**
+ * Materialize one renderer-neutral imagery primitive through Cesium's matching
+ * provider and add it to the scene's imagery collection.
+ *
+ * The returned handle owns the provider and layer it creates. Removal is
+ * idempotent, releases the layer's GPU resources through Cesium, and calls an
+ * optional provider `destroy()` exactly once.
+ */
+export async function addCesiumImageryLayer(scene, primitive, cesium, options = {}) {
+    const validation = diagnoseScenePrimitives([primitive], CESIUM_SCENE_CAPABILITIES).find((diagnostic) => diagnostic.status === "unsupported");
+    if (validation)
+        throw new Error(`${validation.code}: ${validation.message}`);
+    if (!scene.imageryLayers) {
+        throw new Error("scene-primitive-imagery-target-missing: Cesium imageryLayers unavailable.");
+    }
+    options.signal?.throwIfAborted();
+    const mod = cesium ?? (await loadCesium());
+    const provider = await createCesiumImageryProvider(primitive, mod);
+    let layer;
+    try {
+        options.signal?.throwIfAborted();
+        layer = scene.imageryLayers.addImageryProvider(provider);
+        layer.alpha = primitive.opacity ?? 1;
+    }
+    catch (error) {
+        if (layer && scene.imageryLayers.contains(layer))
+            scene.imageryLayers.remove(layer, true);
+        disposeCesiumImageryProvider(provider);
+        throw error;
+    }
+    let removed = false;
+    return {
+        id: primitive.id,
+        kind: "imagery-layer",
+        protocol: primitive.protocol,
+        setVisible(visible) {
+            if (!removed)
+                layer.show = visible;
+        },
+        setOpacity(opacity) {
+            if (!Number.isFinite(opacity) || opacity < 0 || opacity > 1) {
+                throw new RangeError("Imagery opacity must be a finite number between 0 and 1.");
+            }
+            if (!removed)
+                layer.alpha = opacity;
+        },
+        remove() {
+            if (removed)
+                return;
+            removed = true;
+            try {
+                if (scene.imageryLayers?.contains(layer))
+                    scene.imageryLayers.remove(layer, true);
+            }
+            finally {
+                disposeCesiumImageryProvider(provider);
+            }
+        },
+    };
+}
+function disposeCesiumImageryProvider(provider) {
+    if (typeof provider.destroy === "function" && provider.isDestroyed?.() !== true)
+        provider.destroy();
+}
+async function createCesiumImageryProvider(primitive, cesium) {
+    const commonOptions = {
+        ...(primitive.attribution ? { credit: primitive.attribution } : {}),
+        ...(primitive.minimumLevel !== undefined ? { minimumLevel: primitive.minimumLevel } : {}),
+        ...(primitive.maximumLevel !== undefined ? { maximumLevel: primitive.maximumLevel } : {}),
+    };
+    switch (primitive.protocol) {
+        case "url-template":
+            return new cesium.UrlTemplateImageryProvider({
+                url: urlWithServiceParameters(primitive.url, primitive.parameters),
+                ...commonOptions,
+                ...(primitive.subdomains ? { subdomains: primitive.subdomains } : {}),
+            });
+        case "wms":
+            return new cesium.WebMapServiceImageryProvider({
+                url: normalizedWmsUrl(primitive.url, primitive.parameters),
+                layers: primitive.layer,
+                ...commonOptions,
+                ...(primitive.subdomains ? { subdomains: primitive.subdomains } : {}),
+                ...(primitive.parameters || primitive.format || primitive.style
+                    ? {
+                        parameters: normalizedWmsParameters(primitive.parameters, primitive.format, primitive.style),
+                    }
+                    : {}),
+            });
+        case "wmts":
+            return new cesium.WebMapTileServiceImageryProvider({
+                url: normalizedWmtsUrl(primitive.url, primitive.parameters),
+                layer: primitive.layer,
+                style: primitive.style,
+                tileMatrixSetID: primitive.tileMatrixSetId,
+                format: primitive.format ?? "image/png",
+                ...commonOptions,
+                ...(primitive.subdomains ? { subdomains: primitive.subdomains } : {}),
+                ...(primitive.parameters ? { dimensions: primitive.parameters } : {}),
+            });
+        case "single-tile":
+            return cesium.SingleTileImageryProvider.fromUrl(urlWithServiceParameters(resolveConfiguredSubdomainUrl(primitive), primitive.parameters), {
+                ...(primitive.attribution ? { credit: primitive.attribution } : {}),
+            });
+        case "arcgis-imagery":
+            if (isArcGisImageServerUrl(primitive.url)) {
+                return new cesium.UrlTemplateImageryProvider({
+                    url: arcGisImageServerExportUrl(primitive.url, primitive.parameters),
+                    ...commonOptions,
+                    ...(primitive.subdomains ? { subdomains: primitive.subdomains } : {}),
+                });
+            }
+            return cesium.ArcGisMapServerImageryProvider.fromUrl(urlWithoutQueryKeys(resolveConfiguredSubdomainUrl(primitive), [...ARCGIS_IMAGE_SERVER_RESERVED_PARAMETERS, "layers", ...Object.keys(primitive.parameters ?? {})], true), {
+                ...commonOptions,
+                ...arcGisMapServerOptions(primitive.parameters),
+            });
+    }
+}
+function resolveConfiguredSubdomainUrl(primitive) {
+    const subdomain = primitive.subdomains?.[0];
+    return subdomain === undefined ? primitive.url : primitive.url.replaceAll("{s}", subdomain);
+}
+function normalizedWmsUrl(url, parameters) {
+    return urlWithoutQueryKeys(url, [...WMS_PROVIDER_QUERY_KEYS, ...Object.keys(parameters ?? {})]);
+}
+function normalizedWmtsUrl(url, parameters) {
+    return urlWithoutQueryKeys(url, [...WMTS_PROVIDER_QUERY_KEYS, ...Object.keys(parameters ?? {})]);
+}
+function urlWithServiceParameters(url, parameters) {
+    const entries = Object.entries(parameters ?? {});
+    if (entries.length === 0)
+        return url;
+    const normalizedUrl = urlWithoutQueryKeys(url, entries.map(([key]) => key));
+    const hashIndex = normalizedUrl.indexOf("#");
+    const withoutFragment = hashIndex === -1 ? normalizedUrl : normalizedUrl.slice(0, hashIndex);
+    const fragment = hashIndex === -1 ? "" : normalizedUrl.slice(hashIndex);
+    const encodedParameters = entries
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
+        .join("&");
+    return `${withoutFragment}${withoutFragment.includes("?") ? "&" : "?"}${encodedParameters}${fragment}`;
+}
+function urlWithoutQueryKeys(url, keys, canonical = false) {
+    const overriddenKeys = new Set(keys.map((key) => (canonical ? key.toLowerCase().replaceAll(/[^a-z0-9]/g, "") : key.toLowerCase())));
+    const hashIndex = url.indexOf("#");
+    const withoutFragment = hashIndex === -1 ? url : url.slice(0, hashIndex);
+    const fragment = hashIndex === -1 ? "" : url.slice(hashIndex);
+    const queryIndex = withoutFragment.indexOf("?");
+    if (queryIndex === -1)
+        return url;
+    const endpoint = withoutFragment.slice(0, queryIndex);
+    const query = withoutFragment.slice(queryIndex + 1);
+    const preserved = query.split("&").filter((entry) => {
+        if (entry === "")
+            return false;
+        const separatorIndex = entry.indexOf("=");
+        const rawKey = separatorIndex === -1 ? entry : entry.slice(0, separatorIndex);
+        try {
+            const decodedKey = decodeURIComponent(rawKey.replaceAll("+", " ")).toLowerCase();
+            return !overriddenKeys.has(canonical ? decodedKey.replaceAll(/[^a-z0-9]/g, "") : decodedKey);
+        }
+        catch {
+            return true;
+        }
+    });
+    return `${endpoint}${preserved.length > 0 ? `?${preserved.join("&")}` : ""}${fragment}`;
+}
+function arcGisMapServerOptions(parameters) {
+    const options = {};
+    for (const [key, value] of Object.entries(parameters ?? {})) {
+        switch (key.toLowerCase().replaceAll(/[^a-z0-9]/g, "")) {
+            case "layers":
+                options.layers = normalizeArcGisMapServerLayers(value);
+                break;
+            case "enablepickfeatures":
+                options.enablePickFeatures = value;
+                break;
+            case "useprecachedtilesifavailable":
+                options.usePreCachedTilesIfAvailable = value;
+                break;
+            case "tilewidth":
+                options.tileWidth = value;
+                break;
+            case "tileheight":
+                options.tileHeight = value;
+                break;
+        }
+    }
+    return options;
+}
+function normalizeArcGisMapServerLayers(value) {
+    const trimmed = String(value).trim();
+    const layerList = trimmed.toLowerCase().startsWith("show:") ? trimmed.slice(5) : trimmed;
+    return layerList
+        .split(",")
+        .map((layerId) => layerId.trim())
+        .join(",");
+}
+function normalizedWmsParameters(parameters, format, style) {
+    const entries = Object.entries(parameters ?? {}).filter(([key]) => key.toLowerCase() !== "layers" &&
+        (format === undefined || key.toLowerCase() !== "format") &&
+        (style === undefined || key.toLowerCase() !== "styles"));
+    return {
+        ...Object.fromEntries(entries),
+        ...(format !== undefined ? { format } : {}),
+        ...(style !== undefined ? { styles: style } : {}),
+    };
+}
+function isArcGisImageServerUrl(url) {
+    const endpoint = url.split(/[?#]/, 1)[0] ?? "";
+    return trimTrailingSlashes(endpoint).toLowerCase().endsWith("/imageserver");
+}
+function arcGisImageServerExportUrl(url, parameters) {
+    const [withoutFragment] = url.split("#", 1);
+    const queryIndex = withoutFragment.indexOf("?");
+    const endpoint = trimTrailingSlashes(queryIndex === -1 ? withoutFragment : withoutFragment.slice(0, queryIndex));
+    const existingQuery = queryIndex === -1 ? "" : withoutFragment.slice(queryIndex + 1);
+    const primitiveParameters = new Map();
+    for (const [key, value] of Object.entries(parameters ?? {})) {
+        if (!ARCGIS_IMAGE_SERVER_RESERVED_PARAMETERS.has(key.toLowerCase())) {
+            primitiveParameters.set(key.toLowerCase(), [key, String(value)]);
+        }
+    }
+    const preservedParameters = new URLSearchParams();
+    for (const [key, value] of new URLSearchParams(existingQuery)) {
+        const normalizedKey = key.toLowerCase();
+        if (!ARCGIS_IMAGE_SERVER_RESERVED_PARAMETERS.has(normalizedKey) && !primitiveParameters.has(normalizedKey)) {
+            preservedParameters.append(key, value);
+        }
+    }
+    for (const [key, value] of primitiveParameters.values())
+        preservedParameters.set(key, value);
+    const requestParameters = [
+        "f=image",
+        "bbox={westProjected}%2C{southProjected}%2C{eastProjected}%2C{northProjected}",
+        "bboxSR=3857",
+        "imageSR=3857",
+        "size={width}%2C{height}",
+        "format=png32",
+        "transparent=true",
+    ];
+    const preservedQuery = preservedParameters.toString();
+    return `${endpoint}/exportImage?${preservedQuery ? `${preservedQuery}&` : ""}${requestParameters.join("&")}`;
+}
+const ARCGIS_IMAGE_SERVER_RESERVED_PARAMETERS = new Set([
+    "f",
+    "bbox",
+    "bboxsr",
+    "imagesr",
+    "size",
+    "format",
+    "transparent",
+]);
+const WMS_PROVIDER_QUERY_KEYS = [
+    "bbox",
+    "crs",
+    "format",
+    "height",
+    "layers",
+    "request",
+    "service",
+    "srs",
+    "styles",
+    "transparent",
+    "version",
+    "width",
+];
+const WMTS_PROVIDER_QUERY_KEYS = [
+    "format",
+    "layer",
+    "request",
+    "service",
+    "style",
+    "tilecol",
+    "tilematrix",
+    "tilematrixset",
+    "tilematrixsetid",
+    "tilerow",
+    "version",
+];
+function trimTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47)
+        end -= 1;
+    return value.slice(0, end);
 }
 /**
  * Wire a terrain provider from an elevation-source primitive onto the scene.
@@ -343,6 +757,11 @@ export async function addCesiumModel(scene, primitive, cesium) {
  * is applied via the scene's `verticalExaggeration`.
  */
 export async function applyCesiumTerrain(scene, primitive, cesium) {
+    return applyCesiumTerrainInternal(scene, primitive, cesium, true);
+}
+async function applyCesiumTerrainInternal(scene, primitive, cesium, disposePreviousProvider, signal) {
+    signal?.throwIfAborted();
+    assertRenderableTerrain(primitive);
     const url = typeof primitive.url === "string" && primitive.url.trim() !== "" ? primitive.url : undefined;
     if (primitive.exaggeration !== undefined && Number.isFinite(primitive.exaggeration)) {
         scene.verticalExaggeration = primitive.exaggeration;
@@ -350,8 +769,21 @@ export async function applyCesiumTerrain(scene, primitive, cesium) {
     if (!url)
         return undefined;
     const mod = cesium ?? (await loadCesium());
-    const provider = await mod.CesiumTerrainProvider.fromUrl(url);
+    const provider = await mod.CesiumTerrainProvider.fromUrl(url, primitive.attribution ? { credit: primitive.attribution } : {});
+    if (provider && typeof provider === "object")
+        ownedCesiumTerrainProviders.add(provider);
+    if (signal?.aborted) {
+        // The provider resolved into a scene the host has already abandoned. Release
+        // it here rather than installing it and relying on a rollback to notice.
+        disposeOwnedCesiumTerrainProvider(provider);
+        signal.throwIfAborted();
+    }
+    const previousProvider = scene.terrainProvider;
     scene.terrainProvider = provider;
+    if (disposePreviousProvider && previousProvider && previousProvider !== provider) {
+        disposeOwnedCesiumTerrainProvider(previousProvider);
+    }
+    let removed = false;
     return {
         id: primitive.id,
         kind: "elevation-source",
@@ -359,28 +791,69 @@ export async function applyCesiumTerrain(scene, primitive, cesium) {
             /* terrain is always on once set; visibility is a no-op for the provider. */
         },
         remove() {
+            if (removed)
+                return;
             // Only tear down if *this* handle's provider is still the active one. If a
             // newer elevation source has since replaced `scene.terrainProvider`,
             // removing this (now-stale) handle must be a no-op so we don't clobber the
             // active terrain/exaggeration.
-            if (scene.terrainProvider !== provider)
+            if (scene.terrainProvider !== provider) {
+                disposeOwnedCesiumTerrainProvider(provider);
+                removed = true;
                 return;
+            }
             scene.terrainProvider = undefined;
             scene.verticalExaggeration = 1;
+            disposeOwnedCesiumTerrainProvider(provider);
+            removed = true;
         },
     };
 }
-function makeLayerHandle(scene, id, primitive, kind, format) {
+/**
+ * Wrap an adapter-owned tileset/model in a bounded handle.
+ *
+ * Ownership rules mirror {@link addCesiumImageryLayer}: `remove()` is idempotent
+ * and destroys the object exactly once (see
+ * {@link destroyOwnedCesiumPrimitive}), and post-removal control calls are
+ * no-ops rather than mutations of a destroyed object.
+ *
+ * `setOpacity` is only wired for glTF/GLB models, where `Model.color`'s alpha is
+ * the adapter-owned opacity channel. Tilesets omit it — see
+ * {@link CesiumLayerHandle}.
+ */
+function makeLayerHandle(scene, id, primitive, format, cesium) {
+    let removed = false;
+    const model = cesium && (format === "gltf" || format === "glb") ? primitive : undefined;
     return {
         id,
-        kind,
+        kind: "model-layer",
         format,
         setVisible(visible) {
-            primitive.show = visible;
+            if (!removed)
+                primitive.show = visible;
         },
+        ...(model && cesium
+            ? {
+                setOpacity(opacity) {
+                    if (!Number.isFinite(opacity) || opacity < 0 || opacity > 1) {
+                        throw new RangeError("Model opacity must be a finite number between 0 and 1.");
+                    }
+                    if (!removed)
+                        model.color = cesium.Color.WHITE.withAlpha(opacity);
+                },
+            }
+            : {}),
         remove() {
-            if (scene.primitives.contains(primitive))
-                scene.primitives.remove(primitive);
+            if (removed)
+                return;
+            removed = true;
+            try {
+                if (scene.primitives.contains(primitive))
+                    scene.primitives.remove(primitive);
+            }
+            finally {
+                destroyOwnedCesiumPrimitive(primitive);
+            }
         },
     };
 }
@@ -421,60 +894,272 @@ export function pickCesiumFeatureAttributes(scene, windowPosition) {
  * As of #1197 this lands the full 3D stack against `target.scene`:
  *  - `camera` → `Camera.setView` (via the lazily-loaded `Cartesian3`).
  *  - `elevation-source` → `scene.terrainProvider` + `verticalExaggeration`.
+ *  - `imagery-layer` → a protocol-specific provider added to `scene.imageryLayers`.
  *  - `model-layer` (`3d-tiles`) → `Cesium3DTileset.fromUrl` added to
  *    `scene.primitives`; (`gltf`/`glb`) → `Model.fromGltfAsync` placed by
  *    position/rotation/scale.
  *
  * Returns the diagnostics plus the live layer handles keyed by primitive id so
  * callers can toggle visibility / tear layers down. Layer rendering is skipped
- * (gracefully) when no `scene` is attached or when a primitive diagnoses as
- * unsupported. I3S model layers and extrusions are declared-capable but not yet
- * materialized here (no Honua server primitives emit them); point clouds ride
- * the 3D-Tiles path and are gated on server ingest (honua-server#1201).
+ * when no `scene` is attached or when a primitive diagnoses as unsupported —
+ * and every skip is accounted for by a diagnostic, so nothing is silently
+ * dropped. Point clouds ride the 3D-Tiles path with optional
+ * `pointCloudShading`. I3S is declared-capable but unmaterialized, so it
+ * diagnoses `scene-primitive-model-format-not-materialized`; extrusions remain
+ * a MapLibre-path concern.
+ *
+ * As of #1048 `state` is load-bearing: its `timeline` slice is bound to the
+ * target's clock when the host opted into one (see
+ * {@link CesiumSceneRuntimeTarget}), and every arm — applied, host-owned,
+ * unbound, uninterpretable — reports itself as a `scene-time-*` diagnostic.
+ * Binding time constructs no renderer resource, so it never displaces a
+ * primitive: the mount's reuse diff is untouched by a moving clock.
  */
-export async function applyCesiumScenePrimitives(target, primitives, _state) {
-    const diagnostics = diagnoseScenePrimitives(primitives, CESIUM_SCENE_CAPABILITIES);
+export async function applyCesiumScenePrimitives(target, primitives, state) {
+    const application = await applyCesiumScenePrimitivesInternal(target, primitives, {
+        ...(state ? { state } : {}),
+    });
+    return {
+        status: application.status,
+        diagnostics: application.diagnostics,
+        layers: application.layers,
+    };
+}
+/**
+ * Stable identity of a scene primitive within one mount: its kind and id.
+ *
+ * Identity is deliberately kind-qualified. Two primitives of different kinds may
+ * legitimately share an id (a terrain source and the imagery draped over it, for
+ * instance), and they own different renderer resources, so they must never be
+ * treated as revisions of one another.
+ *
+ * @internal
+ */
+export function scenePrimitiveMountKey(primitive) {
+    return `${primitive.kind}${primitive.id}`;
+}
+/**
+ * A stable, order-independent fingerprint of a primitive's configuration, used
+ * to decide whether a revised plan's primitive is the *same* binding as the one
+ * already mounted.
+ *
+ * Returns `undefined` when the primitive cannot be fingerprinted deterministically
+ * (a cycle, or a non-serializable value smuggled through `metadata`). An absent
+ * fingerprint means "assume changed": the binding is rebuilt rather than reused,
+ * which costs a rebuild but can never leave a stale renderer resource claiming to
+ * satisfy a plan it no longer matches.
+ *
+ * @internal
+ */
+export function scenePrimitiveFingerprint(primitive) {
+    try {
+        return stableStringify(primitive, new Set());
+    }
+    catch {
+        return undefined;
+    }
+}
+function stableStringify(value, seen) {
+    if (value === undefined)
+        return "undefined";
+    if (value === null)
+        return "null";
+    if (typeof value === "function" || typeof value === "symbol") {
+        throw new TypeError("Scene primitives must be serializable to be fingerprinted.");
+    }
+    if (typeof value !== "object")
+        return JSON.stringify(value) ?? "undefined";
+    const container = value;
+    if (seen.has(container))
+        throw new TypeError("Scene primitives must be acyclic to be fingerprinted.");
+    seen.add(container);
+    try {
+        if (Array.isArray(value))
+            return `[${value.map((entry) => stableStringify(entry, seen)).join(",")}]`;
+        const entries = Object.entries(value)
+            .filter(([, entryValue]) => entryValue !== undefined)
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+        return `{${entries.map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue, seen)}`).join(",")}}`;
+    }
+    finally {
+        seen.delete(container);
+    }
+}
+/**
+ * The application engine behind both the one-shot
+ * {@link applyCesiumScenePrimitives} and the {@link CesiumLayerHandle}-owning
+ * mount lifecycle.
+ *
+ * Two properties hold regardless of how it is driven:
+ *
+ * - **Transactional.** Any failure — including an abort — removes every handle
+ *   this application created, in reverse construction order, and restores the
+ *   terrain provider, vertical exaggeration, and clock the scene had on entry.
+ *   Handles carried in through `reuse` are never touched, so a failed revision
+ *   leaves the previously applied plan intact.
+ * - **Ownership-complete.** Every renderer resource it constructs is either
+ *   returned in `mounted` or destroyed before the call returns. Nothing is
+ *   reachable only from a discarded local.
+ *
+ * @internal
+ */
+export async function applyCesiumScenePrimitivesInternal(target, primitives, options = {}) {
+    const { signal, reuse, state } = options;
+    signal?.throwIfAborted();
+    const diagnostics = [...diagnoseScenePrimitives(primitives, CESIUM_SCENE_CAPABILITIES)];
     const cesium = await loadCesium();
+    signal?.throwIfAborted();
+    // Time first: entity availability, time-dynamic tileset content, and clock-
+    // driven properties are all evaluated against the clock, so a resource that
+    // attaches below should attach under the application's own time rather than
+    // under whatever instant the viewer happened to be showing.
+    const time = applyCesiumSceneTime(target, state?.timeline, cesium);
+    diagnostics.push(...time.diagnostics);
     const toCartesian = (longitude, latitude, height) => cesium.Cartesian3.fromDegrees(longitude, latitude, height);
-    const unsupportedIds = new Set(diagnostics.filter((diagnostic) => diagnostic.status === "unsupported").map((diagnostic) => diagnostic.primitiveId));
+    const unsupportedPrimitives = new Set(primitives.filter((primitive) => diagnoseScenePrimitives([primitive], CESIUM_SCENE_CAPABILITIES).some((diagnostic) => diagnostic.status === "unsupported")));
     const layers = new Map();
+    const mounted = new Map();
+    const created = [];
+    const reused = [];
+    const appliedHandles = [];
+    const deferredTerrainProviders = [];
     const scene = target.scene;
-    for (const primitive of primitives) {
-        if (primitive.kind === "camera") {
-            applyCameraStateToCesiumCamera(target.camera, primitive.camera, toCartesian);
-            continue;
+    const originalTerrainProvider = scene?.terrainProvider;
+    const originalVerticalExaggeration = scene?.verticalExaggeration;
+    let terrainWasApplied = false;
+    const registerHandle = (key, handle) => {
+        appliedHandles.push(handle);
+        layers.get(handle.id)?.remove();
+        layers.set(handle.id, handle);
+        mounted.set(key, handle);
+        created.push(handle.id);
+    };
+    try {
+        for (const primitive of primitives) {
+            signal?.throwIfAborted();
+            const key = scenePrimitiveMountKey(primitive);
+            if (reuse?.has(key)) {
+                // Unchanged since the last application: skip materialization entirely so
+                // the live resource — and any visibility/opacity the host set on it —
+                // survives the revision.
+                const carried = reuse.get(key);
+                mounted.set(key, carried);
+                if (carried) {
+                    layers.set(carried.id, carried);
+                    reused.push(carried.id);
+                }
+                continue;
+            }
+            if (primitive.kind === "camera") {
+                applyCameraStateToCesiumCamera(target.camera, primitive.camera, toCartesian);
+                mounted.set(key, undefined);
+                continue;
+            }
+            if (!scene || unsupportedPrimitives.has(primitive)) {
+                mounted.set(key, undefined);
+                continue;
+            }
+            if (primitive.kind === "elevation-source") {
+                const previousProvider = scene.terrainProvider;
+                terrainWasApplied = true;
+                const handle = await applyCesiumTerrainInternal(scene, primitive, cesium, false, signal);
+                if (handle) {
+                    if (previousProvider && previousProvider !== scene.terrainProvider) {
+                        deferredTerrainProviders.push(previousProvider);
+                    }
+                    registerHandle(key, handle);
+                }
+                else {
+                    mounted.set(key, undefined);
+                }
+                continue;
+            }
+            if (primitive.kind === "imagery-layer") {
+                if (!scene.imageryLayers) {
+                    diagnostics.push({
+                        code: "scene-primitive-imagery-target-missing",
+                        severity: "error",
+                        status: "unsupported",
+                        primitiveId: primitive.id,
+                        primitiveKind: primitive.kind,
+                        renderer: "cesium",
+                        message: "Cesium imageryLayers unavailable.",
+                        fallback: "Attach a complete Cesium scene target before applying imagery.",
+                    });
+                    mounted.set(key, undefined);
+                    continue;
+                }
+                registerHandle(key, await addCesiumImageryLayer(scene, primitive, cesium, { ...(signal ? { signal } : {}) }));
+                continue;
+            }
+            if (primitive.kind === "model-layer") {
+                // Only materialized formats reach here: anything else already diagnosed
+                // as unsupported above and was filtered into `unsupportedPrimitives`.
+                const materializationOptions = { ...(signal ? { signal } : {}) };
+                if (primitive.format === "3d-tiles") {
+                    registerHandle(key, await addCesium3DTileset(scene, primitive, cesium, materializationOptions));
+                }
+                else {
+                    registerHandle(key, await addCesiumModel(scene, primitive, cesium, materializationOptions));
+                }
+                continue;
+            }
+            mounted.set(key, undefined);
+        }
+        signal?.throwIfAborted();
+        for (const provider of [...deferredTerrainProviders].reverse())
+            disposeOwnedCesiumTerrainProvider(provider);
+    }
+    catch (cause) {
+        const rollbackErrors = [];
+        for (const handle of appliedHandles.reverse()) {
+            try {
+                handle.remove();
+            }
+            catch (error) {
+                rollbackErrors.push(error);
+            }
         }
-        if (!scene || unsupportedIds.has(primitive.id))
-            continue;
-        if (primitive.kind === "elevation-source") {
-            const handle = await applyCesiumTerrain(scene, primitive, cesium);
-            if (handle)
-                layers.set(handle.id, handle);
-            continue;
+        if (scene && terrainWasApplied) {
+            try {
+                scene.terrainProvider = originalTerrainProvider;
+                scene.verticalExaggeration = originalVerticalExaggeration;
+            }
+            catch (error) {
+                rollbackErrors.push(error);
+            }
         }
-        if (primitive.kind === "model-layer") {
-            if (primitive.format === "3d-tiles") {
-                layers.set(primitive.id, await addCesium3DTileset(scene, primitive, cesium));
+        if (target.clock && time.previous) {
+            try {
+                restoreCesiumClock(target.clock, time.previous);
             }
-            else if (primitive.format === "gltf" || primitive.format === "glb") {
-                layers.set(primitive.id, await addCesiumModel(scene, primitive, cesium));
+            catch (error) {
+                rollbackErrors.push(error);
             }
-            // i3s / obj / custom: declared-capable but not materialized here.
         }
+        if (rollbackErrors.length > 0) {
+            throw new AggregateError([cause, ...rollbackErrors], "Cesium scene primitive application failed and layer rollback was incomplete.", { cause });
+        }
+        throw cause;
     }
     return {
         status: summarizeDiagnosticStatus(diagnostics),
         diagnostics,
         layers,
+        mounted,
+        created,
+        reused,
+        time,
     };
 }
 /**
  * Create a {@link SceneRuntimeAdapter} backed by CesiumJS.
  *
  * When `options.target` (a live Cesium `Viewer`/`Scene` surface — a `camera`
- * plus an optional `scene`) is supplied, `apply` drives the live globe: camera
- * sync plus, when a `scene` is attached, terrain providers, 3D-Tiles tilesets,
- * and glTF/GLB model layers (#1197). Without a target the adapter still
+ * plus an optional `scene` and an optional `clock`) is supplied, `apply` drives
+ * the live globe: camera sync plus, when a `scene` is attached, terrain and
+ * imagery providers, 3D-Tiles tilesets, and glTF/GLB model layers, and, when a
+ * `clock` is attached, the workspace `timeline` slice. Without a target the adapter still
  * diagnoses primitives against Cesium's true-3D capabilities — useful for
  * migration analysis before a viewer exists. CesiumJS itself is only imported
  * lazily when `apply` runs.