@honua/app-platform 0.1.12 → 0.1.13

package/scene-workspace/scene-discovery.js

@@ -1,24 +1,32 @@
 /**
  * HTTP scene discovery for the 3D scene workspace.
  *
- * Honua publishes 3D scenes over the `geospatial.v1` `SceneService`
- * (`ListScenes` / `GetScene`) and mirrors that catalog over plain HTTP scene
- * discovery (`GET /api/scenes`, `GET /api/scenes/{id}`) alongside the static
- * 3D-Tiles entry point (`GET /scenes/{id}/tileset.json`). This module gives the
- * SDK a typed read model over that discovery surface and maps a discovered
- * {@link HonuaScene} onto the renderer-neutral {@link SceneRuntimePrimitive}s the
- * Cesium adapter renders.
+ * Honua Server publishes three public JSON contracts, and this module
+ * normalizes those rather than the proto `sceneId` / `title` / `extent` shape:
+ *
+ * - `GET /api/scenes` — list items use `id`, `name`, `tilesetUrl`, `bounds`, `auth`
+ * - `GET /api/scenes/{sceneId}` — metadata uses `id`, `name`, `tileset`, `center`, `bounds`, `auth`
+ * - `GET /api/scenes/{sceneId}/resolve` — resolution uses `sceneId`, `endpoints`, `auth`
+ *
+ * `bounds` is `{west,south,east,north}` and is remapped onto {@link SceneExtent3D}.
+ * `center` is `{latitude,longitude,height}` and becomes the initial camera.
+ * A nested metadata `tileset` object supplies the tileset URL. The flat proto
+ * names (`sceneId`, `scene_id`, `title`, `tileset_url`, `extent`) are still
+ * accepted so older payloads do not throw; callers that need the server
+ * contract should pass the three routes above.
+ *
+ * The runtime tileset URL comes from {@link resolveScene}. Nothing in this
+ * module synthesizes `/scenes/{id}/tileset.json`. An empty id fails closed
+ * before a request is sent, and a tileset URL whose path contains `/scenes//`
+ * is rejected so a missing id cannot be requested.
+ *
+ * Auth requirements are retained on the normalized scene. This module does not
+ * refresh protected-asset credentials; that is a separate ticket.
  *
  * Discovery calls go through a caller-supplied {@link SceneDiscoveryRequestExecutor}
  * — typically `(...args) => client.pipelineRequestJson(...args)` against a
  * `HonuaClient` — so they reuse the SDK's shared auth / retry / timeout /
- * interceptor pipeline rather than issuing ad-hoc `fetch` calls. Modelling the
- * transport as a function keeps this module free of a hard `core/client` import
- * (and equally usable from a Node backend, a worker, or a unit test with a mock).
- *
- * The mapping helpers ({@link sceneToRuntimePrimitives},
- * {@link sceneCameraPrimitive}, {@link sceneViewpointBookmarks}) are pure (no
- * Cesium, no transport) and unit-testable on their own.
+ * interceptor pipeline rather than issuing ad-hoc `fetch` calls.
  *
  * @experimental Held back from the beta `@honua/app-platform/scene-workspace`
  *   tier: Honua Server scene discovery is server-attached, so it sits outside
@@ -27,107 +35,347 @@
  *   are beta.
  * @module
  */
-import { trimTrailingSlashes } from "../core/path-utils.js";
 const SCENES_BASE_PATH = "/api/scenes";
-function normalizeCamera(raw) {
-    if (!raw || raw.longitude === undefined || raw.latitude === undefined)
+const EMPTY_TILESET_PATH = "/scenes//";
+function asRecord(raw, message) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(message);
+    }
+    return raw;
+}
+function readText(value) {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+function readId(value) {
+    if (typeof value !== "string")
         return undefined;
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}
+function requireSceneId(record, message) {
+    // `id` is the list/metadata contract. `sceneId` / `scene_id` remain only so
+    // proto-shaped payloads still normalize; an empty value is never substituted.
+    const sceneId = readId(record.id) ?? readId(record.sceneId) ?? readId(record.scene_id);
+    if (!sceneId)
+        throw new Error(message);
+    return sceneId;
+}
+function readFinite(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** Reject a blank URL and the empty-id `/scenes//` path. */
+function isUsableSceneResourceUrl(url) {
+    if (!url)
+        return false;
+    const trimmed = url.trim();
+    return trimmed !== "" && !trimmed.includes(EMPTY_TILESET_PATH);
+}
+function readStringList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.filter((item) => typeof item === "string");
+}
+function readAuth(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const schemes = readStringList(record.schemes) ?? [];
+    const policy = readText(record.policy);
     return {
-        longitude: raw.longitude,
-        latitude: raw.latitude,
-        height: raw.height ?? 0,
-        ...(raw.heading !== undefined ? { heading: raw.heading } : {}),
-        ...(raw.pitch !== undefined ? { pitch: raw.pitch } : {}),
-        ...(raw.roll !== undefined ? { roll: raw.roll } : {}),
+        requiresAuthentication: record.requiresAuthentication === true,
+        schemes,
+        ...(policy !== undefined ? { policy } : {}),
     };
 }
-function normalizeExtent(raw) {
-    if (!raw)
+function readEndpoint(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const url = readText(record.url) ?? readText(record.href);
+    const kind = readText(record.kind) ?? readText(record.type) ?? readText(record.format);
+    if (!isUsableSceneResourceUrl(url) || !kind)
         return undefined;
-    const envelope = raw.extent ?? raw;
-    if (envelope.xmin === undefined ||
-        envelope.ymin === undefined ||
-        envelope.xmax === undefined ||
-        envelope.ymax === undefined) {
+    const mediaType = readText(record.mediaType);
+    const format = readText(record.format);
+    return {
+        kind,
+        url: url.trim(),
+        ...(mediaType !== undefined ? { mediaType } : {}),
+        ...(format !== undefined ? { format } : {}),
+        requiresAuthentication: record.requiresAuthentication === true,
+    };
+}
+function readEndpoints(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item) => {
+        const endpoint = readEndpoint(item);
+        return endpoint ? [endpoint] : [];
+    });
+}
+function readLinks(value) {
+    if (!Array.isArray(value))
         return undefined;
+    const links = [];
+    for (const item of value) {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const record = item;
+        const rel = readText(record.rel);
+        const href = readText(record.href);
+        if (!rel || !href)
+            continue;
+        const type = readText(record.type);
+        const title = readText(record.title);
+        links.push({
+            rel,
+            href,
+            ...(type !== undefined ? { type } : {}),
+            ...(title !== undefined ? { title } : {}),
+        });
     }
-    const minHeight = raw.minHeight ?? raw.min_height;
-    const maxHeight = raw.maxHeight ?? raw.max_height;
+    return links;
+}
+function readTilesetUrl(record) {
+    const flat = readText(record.tilesetUrl) ?? readText(record.tileset_url);
+    if (isUsableSceneResourceUrl(flat))
+        return flat.trim();
+    const tileset = record.tileset;
+    if (!tileset || typeof tileset !== "object" || Array.isArray(tileset))
+        return undefined;
+    const nested = tileset;
+    const url = readText(nested.url) ?? readText(nested.href);
+    return isUsableSceneResourceUrl(url) ? url.trim() : undefined;
+}
+function normalizeCamera(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const camera = raw;
+    const longitude = readFinite(camera.longitude);
+    const latitude = readFinite(camera.latitude);
+    if (longitude === undefined || latitude === undefined)
+        return undefined;
+    const height = readFinite(camera.height) ?? 0;
+    const heading = readFinite(camera.heading);
+    const pitch = readFinite(camera.pitch);
+    const roll = readFinite(camera.roll);
+    return {
+        longitude,
+        latitude,
+        height,
+        ...(heading !== undefined ? { heading } : {}),
+        ...(pitch !== undefined ? { pitch } : {}),
+        ...(roll !== undefined ? { roll } : {}),
+    };
+}
+/** Server `bounds` (`west`/`south`/`east`/`north`) onto the SDK extent axes. */
+function readBounds(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const bounds = raw;
+    const xmin = readFinite(bounds.west);
+    const ymin = readFinite(bounds.south);
+    const xmax = readFinite(bounds.east);
+    const ymax = readFinite(bounds.north);
+    if (xmin === undefined || ymin === undefined || xmax === undefined || ymax === undefined)
+        return undefined;
+    return { xmin, ymin, xmax, ymax };
+}
+/** Proto `extent` tolerance: a flat or nested `{xmin,ymin,xmax,ymax}` envelope. */
+function readProtoExtent(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const record = raw;
+    const nested = record.extent;
+    const envelope = nested && typeof nested === "object" && !Array.isArray(nested) ? nested : record;
+    const xmin = readFinite(envelope.xmin);
+    const ymin = readFinite(envelope.ymin);
+    const xmax = readFinite(envelope.xmax);
+    const ymax = readFinite(envelope.ymax);
+    if (xmin === undefined || ymin === undefined || xmax === undefined || ymax === undefined)
+        return undefined;
+    const minHeight = readFinite(record.minHeight) ?? readFinite(record.min_height);
+    const maxHeight = readFinite(record.maxHeight) ?? readFinite(record.max_height);
+    const spatialReference = readFinite(envelope.spatialReference);
     return {
-        xmin: envelope.xmin,
-        ymin: envelope.ymin,
-        xmax: envelope.xmax,
-        ymax: envelope.ymax,
+        xmin,
+        ymin,
+        xmax,
+        ymax,
         ...(minHeight !== undefined ? { minHeight } : {}),
         ...(maxHeight !== undefined ? { maxHeight } : {}),
-        ...(envelope.spatialReference !== undefined ? { spatialReference: envelope.spatialReference } : {}),
+        ...(spatialReference !== undefined ? { spatialReference } : {}),
+    };
+}
+function readExtent(record) {
+    return readBounds(record.bounds) ?? readProtoExtent(record.extent);
+}
+function readInitialCamera(record) {
+    const explicit = normalizeCamera(record.initialCamera) ?? normalizeCamera(record.initial_camera);
+    if (explicit)
+        return explicit;
+    return normalizeCamera(record.center);
+}
+function readViewpoints(value) {
+    if (!Array.isArray(value))
+        return [];
+    const viewpoints = [];
+    for (const item of value) {
+        if (!item || typeof item !== "object" || Array.isArray(item))
+            continue;
+        const record = item;
+        const id = readId(record.id);
+        const camera = normalizeCamera(record.camera);
+        if (!id || !camera)
+            continue;
+        const title = readText(record.title) ?? id;
+        viewpoints.push({ id, title, camera });
+    }
+    return viewpoints;
+}
+function readStyleExpression(record) {
+    const direct = readText(record.styleExpression);
+    if (direct)
+        return direct;
+    const style = record.style;
+    if (!style || typeof style !== "object" || Array.isArray(style))
+        return undefined;
+    return readText(style.expression);
+}
+function readScene(record, missingIdMessage) {
+    const sceneId = requireSceneId(record, missingIdMessage);
+    const name = readText(record.name);
+    const title = name ?? readText(record.title);
+    const description = readText(record.description);
+    const tilesetUrl = readTilesetUrl(record);
+    const terrainUrl = readText(record.terrainUrl) ?? readText(record.terrain_url);
+    const extent = readExtent(record);
+    const initialCamera = readInitialCamera(record);
+    const styleExpression = readStyleExpression(record);
+    const edition = readText(record.edition);
+    const auth = readAuth(record.auth);
+    const attribution = readStringList(record.attribution);
+    const updatedAt = readText(record.updatedAt);
+    const links = readLinks(record.links);
+    const usableTerrain = isUsableSceneResourceUrl(terrainUrl) ? terrainUrl.trim() : undefined;
+    return {
+        sceneId,
+        ...(name !== undefined ? { name } : {}),
+        ...(title !== undefined ? { title } : {}),
+        ...(description !== undefined ? { description } : {}),
+        ...(tilesetUrl !== undefined ? { tilesetUrl } : {}),
+        ...(usableTerrain !== undefined ? { terrainUrl: usableTerrain } : {}),
+        ...(extent ? { extent } : {}),
+        ...(initialCamera ? { initialCamera } : {}),
+        viewpoints: readViewpoints(record.viewpoints),
+        ...(styleExpression !== undefined ? { styleExpression } : {}),
+        ...(edition !== undefined ? { edition } : {}),
+        capabilities: readStringList(record.capabilities) ?? [],
+        ...(auth ? { auth } : {}),
+        ...(attribution ? { attribution } : {}),
+        ...(updatedAt !== undefined ? { updatedAt } : {}),
+        ...(links ? { links } : {}),
     };
 }
+function unwrapSceneEnvelope(raw) {
+    const record = asRecord(raw, "Scene response must be a JSON object.");
+    const nested = record.scene;
+    const hasOwnId = readId(record.id) ?? readId(record.sceneId) ?? readId(record.scene_id);
+    if (!hasOwnId && nested && typeof nested === "object" && !Array.isArray(nested)) {
+        return nested;
+    }
+    return record;
+}
+/**
+ * Normalize one list item from `GET /api/scenes`.
+ * Reads `id`, `name`, `tilesetUrl`, `bounds`, and `auth`.
+ */
+export function normalizeSceneSummary(raw) {
+    return readScene(asRecord(raw, "Scene list item must be a JSON object."), "Scene list item is missing an id.");
+}
 /**
- * Normalize a raw scene payload (camelCase or proto3-JSON snake_case) into a
- * {@link HonuaScene}. Exported so the normalization is unit-testable against
- * either wire shape without a transport.
+ * Normalize `GET /api/scenes/{sceneId}`.
+ * Reads `id`, `name`, `tileset`, `center`, `bounds`, and `auth`.
+ * A `{ scene }` envelope is accepted only when the root has no id of its own
+ * (proto-shaped responses). The server returns the metadata object itself.
+ */
+export function normalizeSceneMetadata(raw) {
+    return readScene(unwrapSceneEnvelope(raw), "Scene metadata is missing an id.");
+}
+/**
+ * Normalize a scene payload. Prefer {@link normalizeSceneSummary} or
+ * {@link normalizeSceneMetadata} at the route boundary. This entry point
+ * accepts either of those contracts and the documented proto field names.
  */
 export function normalizeScene(raw) {
-    const sceneId = raw.sceneId ?? raw.scene_id ?? "";
-    const tilesetUrl = raw.tilesetUrl ?? raw.tileset_url;
-    const terrainUrl = raw.terrainUrl ?? raw.terrain_url;
-    const initialCamera = normalizeCamera(raw.initialCamera ?? raw.initial_camera);
-    const viewpoints = (raw.viewpoints ?? [])
-        .map((viewpoint) => {
-        const camera = normalizeCamera(viewpoint.camera);
-        if (!camera || !viewpoint.id)
-            return undefined;
-        return { id: viewpoint.id, title: viewpoint.title ?? viewpoint.id, camera };
-    })
-        .filter((viewpoint) => viewpoint !== undefined);
-    const styleExpression = raw.styleExpression ?? raw.style?.expression;
+    return readScene(unwrapSceneEnvelope(raw), "Scene response is missing an id.");
+}
+function tilesetEndpointUrl(endpoints) {
+    const match = endpoints.find((endpoint) => endpoint.kind === "3d-tiles" || endpoint.format === "3d-tiles");
+    return match && isUsableSceneResourceUrl(match.url) ? match.url.trim() : undefined;
+}
+/**
+ * Normalize `GET /api/scenes/{sceneId}/resolve`.
+ * Reads `sceneId`, `endpoints`, and `auth`. The runtime tileset URL is the
+ * response `tilesetUrl` when usable, otherwise the `3d-tiles` endpoint.
+ */
+export function normalizeSceneResolution(raw) {
+    const record = asRecord(raw, "Scene resolution must be a JSON object.");
+    const sceneId = requireSceneId(record, "Scene resolution is missing a sceneId.");
+    const endpoints = readEndpoints(record.endpoints);
+    const flat = readText(record.tilesetUrl) ?? readText(record.tileset_url);
+    const tilesetUrl = (isUsableSceneResourceUrl(flat) ? flat.trim() : undefined) ?? tilesetEndpointUrl(endpoints);
+    const auth = readAuth(record.auth) ?? { requiresAuthentication: false, schemes: [] };
     return {
         sceneId,
-        ...(raw.title !== undefined ? { title: raw.title } : {}),
-        ...(raw.description !== undefined ? { description: raw.description } : {}),
         ...(tilesetUrl !== undefined ? { tilesetUrl } : {}),
-        ...(terrainUrl !== undefined ? { terrainUrl } : {}),
-        ...(normalizeExtent(raw.extent) ? { extent: normalizeExtent(raw.extent) } : {}),
-        ...(initialCamera ? { initialCamera } : {}),
-        viewpoints,
-        ...(styleExpression !== undefined ? { styleExpression } : {}),
-        ...(raw.edition !== undefined ? { edition: raw.edition } : {}),
-        capabilities: raw.capabilities ?? [],
+        endpoints,
+        capabilities: readStringList(record.capabilities) ?? [],
+        auth,
     };
 }
 /**
- * List the catalog of available 3D scenes from `GET /api/scenes`
- * (`SceneService.ListScenes`). Returns the normalized {@link HonuaScene}s.
+ * List the catalog of available 3D scenes from `GET /api/scenes`.
+ * Returns the normalized {@link HonuaScene}s. A list item with no id throws;
+ * it is not returned with an empty id.
  */
 export async function listScenes(execute, signal) {
     const raw = await execute("GET", SCENES_BASE_PATH, undefined, signal);
-    return (raw.scenes ?? []).map(normalizeScene);
+    const record = asRecord(raw, "Scene list response must be a JSON object.");
+    if (!Array.isArray(record.scenes)) {
+        throw new Error("Scene list response must contain a scenes array.");
+    }
+    return record.scenes.map((item) => normalizeSceneSummary(item));
 }
 /**
- * Fetch a single scene's metadata from `GET /api/scenes/{sceneId}`
- * (`SceneService.GetScene`). The response is tolerated as either the bare scene
- * object or a `{ scene }` envelope.
+ * Fetch a single scene's metadata from `GET /api/scenes/{sceneId}`.
+ * Fails closed before the request when `sceneId` is empty.
  */
 export async function getScene(execute, sceneId, signal) {
-    if (!sceneId)
+    if (typeof sceneId !== "string" || sceneId.trim() === "") {
         throw new Error("getScene requires a non-empty sceneId.");
-    const raw = await execute("GET", `${SCENES_BASE_PATH}/${encodeURIComponent(sceneId)}`, undefined, signal);
-    return normalizeScene(raw.scene ?? raw);
+    }
+    const raw = await execute("GET", `${SCENES_BASE_PATH}/${encodeURIComponent(sceneId.trim())}`, undefined, signal);
+    return normalizeSceneMetadata(raw);
 }
 /**
- * Resolve the static 3D-Tiles entry-point URL for a scene
- * (`/scenes/{sceneId}/tileset.json`). Prefers the scene's advertised
- * `tilesetUrl`; falls back to the conventional discovery path under `baseUrl`
- * when the scene omits one. Returns `undefined` when neither is available.
+ * Resolve a scene's runtime endpoints from `GET /api/scenes/{sceneId}/resolve`.
+ * Fails closed before the request when `sceneId` is empty. The returned
+ * `tilesetUrl` is taken from the server payload only.
  */
-export function resolveSceneTilesetUrl(scene, baseUrl) {
-    if (scene.tilesetUrl && scene.tilesetUrl.trim() !== "")
-        return scene.tilesetUrl;
-    if (!baseUrl)
-        return undefined;
-    const trimmed = trimTrailingSlashes(baseUrl);
-    return `${trimmed}/scenes/${encodeURIComponent(scene.sceneId)}/tileset.json`;
+export async function resolveScene(execute, sceneId, signal) {
+    if (typeof sceneId !== "string" || sceneId.trim() === "") {
+        throw new Error("resolveScene requires a non-empty sceneId.");
+    }
+    const raw = await execute("GET", `${SCENES_BASE_PATH}/${encodeURIComponent(sceneId.trim())}/resolve`, undefined, signal);
+    return normalizeSceneResolution(raw);
+}
+/**
+ * The scene's advertised 3D-Tiles entry-point URL, or `undefined` when the
+ * scene has none. Does not synthesize a `/scenes/{id}/tileset.json` path.
+ */
+export function resolveSceneTilesetUrl(scene) {
+    return isUsableSceneResourceUrl(scene.tilesetUrl) ? scene.tilesetUrl.trim() : undefined;
 }
 /**
  * Build the camera primitive for a scene's suggested initial view, or
@@ -147,8 +395,8 @@ export function sceneCameraPrimitive(scene) {
  * Build the 3D-Tiles model-layer primitive for a scene's root tileset, or
  * `undefined` when the scene has no resolvable tileset URL. Pure.
  */
-export function sceneTilesetPrimitive(scene, baseUrl) {
-    const uri = resolveSceneTilesetUrl(scene, baseUrl);
+export function sceneTilesetPrimitive(scene) {
+    const uri = resolveSceneTilesetUrl(scene);
     if (!uri)
         return undefined;
     return {
@@ -165,23 +413,23 @@ export function sceneTilesetPrimitive(scene, baseUrl) {
  * treated as a quantized-mesh endpoint (Cesium's `CesiumTerrainProvider`).
  */
 export function sceneTerrainPrimitive(scene) {
-    if (!scene.terrainUrl || scene.terrainUrl.trim() === "")
+    if (!isUsableSceneResourceUrl(scene.terrainUrl))
         return undefined;
     return {
         kind: "elevation-source",
         id: `${scene.sceneId}:terrain`,
         sourceId: `${scene.sceneId}:terrain`,
         protocol: "quantized-mesh",
-        url: scene.terrainUrl,
+        url: scene.terrainUrl.trim(),
     };
 }
 /**
  * Map a discovered scene onto the renderer-neutral primitives the Cesium
  * adapter renders: an initial-camera primitive, the terrain elevation source
- * (when present), and the 3D-Tiles tileset (when resolvable). Pure; the result
- * feeds straight into `applyCesiumScenePrimitives` / a `SceneView`.
+ * (when present), and the 3D-Tiles tileset (when the scene advertises a URL).
+ * Pure; the result feeds straight into `applyCesiumScenePrimitives` / a `SceneView`.
  */
-export function sceneToRuntimePrimitives(scene, baseUrl) {
+export function sceneToRuntimePrimitives(scene) {
     const primitives = [];
     const camera = sceneCameraPrimitive(scene);
     if (camera)
@@ -189,7 +437,7 @@ export function sceneToRuntimePrimitives(scene, baseUrl) {
     const terrain = sceneTerrainPrimitive(scene);
     if (terrain)
         primitives.push(terrain);
-    const tileset = sceneTilesetPrimitive(scene, baseUrl);
+    const tileset = sceneTilesetPrimitive(scene);
     if (tileset)
         primitives.push(tileset);
     return primitives;
@@ -199,9 +447,9 @@ export function sceneToRuntimePrimitives(scene, baseUrl) {
  * primitive), so a {@link module:scene-workspace/workspace.SceneWorkspace} can
  * seed its layer list from the scene. Pure.
  */
-export function sceneLayerStates(scene, baseUrl) {
+export function sceneLayerStates(scene) {
     const layers = [];
-    if (sceneTilesetPrimitive(scene, baseUrl)) {
+    if (sceneTilesetPrimitive(scene)) {
         layers.push({
             id: `${scene.sceneId}:tileset`,
             title: scene.title ?? scene.sceneId,

package/scene-workspace/scene-view.d.ts

@@ -43,7 +43,7 @@ import type { QueryMethod } from "../core/types.js";
 import { type CesiumEntityCollectionLike, type ElevationProfileRequest, type ElevationProfileResult, type LineOfSightRequest, type LineOfSightResult, type SceneAnalysisCesiumModule, type SceneAnalysisOverlay, type SceneAnalysisPosition, type SceneMeasurement, type ViewshedRequest, type ViewshedResult } from "./analysis-widgets.js";
 import { type CesiumSceneRuntimeTarget } from "./cesium-adapter.js";
 import type { ScenePrimitiveDiagnostic } from "./primitives.js";
-import { type HonuaScene } from "./scene-discovery.js";
+import { type HonuaScene, type HonuaSceneResolution } from "./scene-discovery.js";
 import type { SceneBookmark, SceneCameraState, SceneLayerState } from "./types.js";
 /**
  * The request transport a {@link SceneView} uses for scene discovery and
@@ -71,11 +71,6 @@ export interface SceneViewOptions {
      * rendering). Omit to load + diagnose scenes headlessly without rendering.
      */
     readonly target?: CesiumSceneRuntimeTarget;
-    /**
-     * Base URL used to resolve a scene's static `tileset.json` entry point when
-     * the scene omits an explicit `tilesetUrl`. Defaults to `client.serverBaseUrl`.
-     */
-    readonly baseUrl?: string;
 }
 /** Events emitted by a {@link SceneView}. */
 export type SceneViewEvent = {
@@ -115,6 +110,11 @@ export declare class SceneView {
     listScenes(signal?: AbortSignal): Promise<HonuaScene[]>;
     /** Fetch a single scene's metadata without loading it (`GET /api/scenes/{id}`). */
     getScene(sceneId: string, signal?: AbortSignal): Promise<HonuaScene>;
+    /**
+     * Resolve a scene's runtime endpoints (`GET /api/scenes/{id}/resolve`).
+     * The tileset URL in the result is the server's. This view does not invent one.
+     */
+    resolveScene(sceneId: string, signal?: AbortSignal): Promise<HonuaSceneResolution>;
     /**
      * Load a scene by id (or a pre-fetched {@link HonuaScene}) and render it onto
      * the live target: the initial camera, terrain provider, and 3D-Tiles

package/scene-workspace/scene-view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-view.d.ts","sourceRoot":"","sources":["../../../src/scene-workspace/scene-view.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scene-view.d.ts","sourceRoot":"","sources":["../../../src/scene-workspace/scene-view.ts"],"names":[],"mappings":"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"}

package/scene-workspace/scene-view.js

@@ -40,7 +40,7 @@
  */
 import { measureScenePositions, renderElevationProfilePolyline, renderLineOfSight, renderMeasurement, renderViewshed, requestElevationProfile, requestLineOfSight, requestViewshed, } from "./analysis-widgets.js";
 import { applyCesiumScenePrimitives, cesiumCameraToSceneState, } from "./cesium-adapter.js";
-import { getScene, listScenes, sceneLayerStates, sceneToRuntimePrimitives, sceneViewpointBookmarks, } from "./scene-discovery.js";
+import { getScene, listScenes, resolveScene as requestSceneResolution, sceneLayerStates, sceneToRuntimePrimitives, sceneViewpointBookmarks, } from "./scene-discovery.js";
 /**
  * First-class 3D scene container. Loads a Honua scene, renders it through the
  * Cesium adapter, and exposes the analysis/measurement widgets.
@@ -48,7 +48,6 @@ import { getScene, listScenes, sceneLayerStates, sceneToRuntimePrimitives, scene
 export class SceneView {
     #execute;
     #target;
-    #baseUrl;
     #listeners = new Set();
     #layerHandles = new Map();
     #scene;
@@ -62,7 +61,6 @@ export class SceneView {
         }
         this.#execute = execute;
         this.#target = options.target;
-        this.#baseUrl = options.baseUrl ?? options.client?.serverBaseUrl;
     }
     // ── Discovery ───────────────────────────────────────────────
     /** List the catalog of available 3D scenes (`GET /api/scenes`). */
@@ -73,6 +71,13 @@ export class SceneView {
     getScene(sceneId, signal) {
         return getScene(this.#discoveryExecutor(), sceneId, signal);
     }
+    /**
+     * Resolve a scene's runtime endpoints (`GET /api/scenes/{id}/resolve`).
+     * The tileset URL in the result is the server's. This view does not invent one.
+     */
+    resolveScene(sceneId, signal) {
+        return requestSceneResolution(this.#discoveryExecutor(), sceneId, signal);
+    }
     // ── Loading / rendering ─────────────────────────────────────
     /**
      * Load a scene by id (or a pre-fetched {@link HonuaScene}) and render it onto
@@ -82,13 +87,23 @@ export class SceneView {
      * rendered.
      */
     async loadScene(scene, signal) {
-        const resolved = typeof scene === "string" ? await this.getScene(scene, signal) : scene;
+        const requestedId = typeof scene === "string" ? scene : scene.sceneId;
+        if (typeof requestedId !== "string" || requestedId.trim() === "") {
+            throw new Error("loadScene requires a non-empty sceneId.");
+        }
+        const sceneId = requestedId.trim();
+        const execute = this.#discoveryExecutor();
+        const metadata = typeof scene === "string" ? await getScene(execute, sceneId, signal) : scene;
+        // Resolve is the only source of the runtime tileset URL. Do not synthesize
+        // `/scenes/{id}/tileset.json` from the client origin when the payload omits one.
+        const resolution = await requestSceneResolution(execute, sceneId, signal);
+        const resolved = sceneWithResolvedRuntime(metadata, resolution);
         this.#teardownLayers();
         this.#scene = resolved;
         this.#bookmarks = sceneViewpointBookmarks(resolved);
-        this.#layers = sceneLayerStates(resolved, this.#baseUrl);
+        this.#layers = sceneLayerStates(resolved);
         if (this.#target) {
-            const primitives = sceneToRuntimePrimitives(resolved, this.#baseUrl);
+            const primitives = sceneToRuntimePrimitives(resolved);
             const result = await applyCesiumScenePrimitives(this.#target, primitives);
             this.#diagnostics = result.diagnostics;
             for (const [id, handle] of result.layers)
@@ -268,3 +283,14 @@ function bindClientExecutor(client) {
         return undefined;
     return (method, path, init, signal) => client.pipelineRequestJson(method, path, init, signal);
 }
+/** Keep metadata for display, but take the runtime tileset URL only from resolve. */
+function sceneWithResolvedRuntime(scene, resolution) {
+    const { tilesetUrl: _metadataTilesetUrl, ...rest } = scene;
+    return {
+        ...rest,
+        sceneId: resolution.sceneId,
+        capabilities: resolution.capabilities,
+        auth: resolution.auth,
+        ...(resolution.tilesetUrl ? { tilesetUrl: resolution.tilesetUrl } : {}),
+    };
+}