@honua/app-platform 0.0.20-alpha.0

package/runtime/style-spec-validation.js

@@ -0,0 +1,357 @@
+let loadAttempted = false;
+let loadedModule;
+let loadFailure;
+let loadPromise;
+export async function prepareRuntimeStyleSpecValidation(mode = "strict") {
+    if (mode === "renderer-deferred")
+        return [];
+    const mod = await loadMapLibreStyleSpecModule();
+    if (mod)
+        return [];
+    return [validatorUnavailableDiagnostic({ mode })];
+}
+export async function validateRuntimeStyleSpec(style, options = {}) {
+    const mode = options.mode ?? "strict";
+    if (mode === "renderer-deferred")
+        return [];
+    const mod = await loadMapLibreStyleSpecModule();
+    if (!mod)
+        return [validatorUnavailableDiagnostic({ ...options, mode })];
+    return mapStyleSpecErrors(mod.validateStyleMin(sanitizeStyle(style)), { ...options, mode }, {});
+}
+export async function validateRuntimeSourceStyleSpec(sourceId, source, options = {}) {
+    const mode = options.mode ?? "strict";
+    if (mode === "renderer-deferred" || isHonuaSourceLike(source))
+        return [];
+    const mod = await loadMapLibreStyleSpecModule();
+    if (!mod)
+        return [
+            validatorUnavailableDiagnostic({ ...options, mode, sourceId, path: options.path ?? `sources.${sourceId}` }),
+        ];
+    return mapStyleSpecErrors(mod.validateStyleMin({
+        version: 8,
+        sources: { [sourceId]: source },
+        layers: [],
+    }), { ...options, mode, sourceId, path: options.path ?? `sources.${sourceId}` }, {});
+}
+export async function validateRuntimeLayerStyleSpec(layer, options = {}) {
+    const mode = options.mode ?? "strict";
+    if (mode === "renderer-deferred")
+        return [];
+    const mod = await loadMapLibreStyleSpecModule();
+    if (!mod) {
+        return [
+            validatorUnavailableDiagnostic({
+                ...options,
+                mode,
+                layerId: options.layerId ?? layer.id,
+                sourceId: options.sourceId ?? layer.source,
+                path: options.path ?? layerPath(layer),
+            }),
+        ];
+    }
+    return mapStyleSpecErrors(mod.validateStyleMin(styleForLayerValidation(layer, options)), {
+        ...options,
+        mode,
+        layerId: options.layerId ?? layer.id,
+        sourceId: options.sourceId ?? layer.source,
+        path: options.path ?? layerPath(layer),
+    }, { layerId: layer.id });
+}
+export async function validateRuntimeStyleExpressionStyleSpec(value, options = {}) {
+    const mode = options.mode ?? "strict";
+    if (mode === "renderer-deferred")
+        return [];
+    const mod = await loadMapLibreStyleSpecModule();
+    if (!mod)
+        return [validatorUnavailableDiagnostic({ ...options, mode })];
+    return validateExpressionWithModule(mod, value, { ...options, mode });
+}
+export async function validateRuntimeFilterStyleSpec(filter, options = {}) {
+    const mode = options.mode ?? "strict";
+    if (mode === "renderer-deferred")
+        return [];
+    const mod = await loadMapLibreStyleSpecModule();
+    if (!mod)
+        return [validatorUnavailableDiagnostic({ ...options, mode })];
+    return mapStyleSpecErrors(mod.validateStyleMin(styleForFilterValidation(filter, options.layerId)), { ...options, mode, path: options.path ?? filterPath(options.layerId) }, { layerId: options.layerId ?? "__honua_filter_validation__" });
+}
+export function validateRuntimeSourceStyleSpecSync(sourceId, source, options = {}) {
+    if (!shouldRunSyncStyleSpecValidation(options.mode) || isHonuaSourceLike(source))
+        return [];
+    const mod = loadedStyleSpecModule();
+    if (!mod)
+        return [validatorUnavailableDiagnostic({ ...options, sourceId, path: options.path ?? `sources.${sourceId}` })];
+    return mapStyleSpecErrors(mod.validateStyleMin({
+        version: 8,
+        sources: { [sourceId]: source },
+        layers: [],
+    }), { ...options, sourceId, path: options.path ?? `sources.${sourceId}` }, {});
+}
+export function validateRuntimeLayerStyleSpecSync(layer, options = {}) {
+    if (!shouldRunSyncStyleSpecValidation(options.mode))
+        return [];
+    const mod = loadedStyleSpecModule();
+    if (!mod) {
+        return [
+            validatorUnavailableDiagnostic({
+                ...options,
+                layerId: options.layerId ?? layer.id,
+                sourceId: options.sourceId ?? layer.source,
+                path: options.path ?? layerPath(layer),
+            }),
+        ];
+    }
+    return mapStyleSpecErrors(mod.validateStyleMin(styleForLayerValidation(layer, options)), {
+        ...options,
+        layerId: options.layerId ?? layer.id,
+        sourceId: options.sourceId ?? layer.source,
+        path: options.path ?? layerPath(layer),
+    }, { layerId: layer.id });
+}
+export function validateRuntimeStyleExpressionStyleSpecSync(value, options = {}) {
+    if (!shouldRunSyncStyleSpecValidation(options.mode))
+        return [];
+    const mod = loadedStyleSpecModule();
+    if (!mod)
+        return [validatorUnavailableDiagnostic(options)];
+    return validateExpressionWithModule(mod, value, options);
+}
+export function validateRuntimeFilterStyleSpecSync(filter, options = {}) {
+    if (!shouldRunSyncStyleSpecValidation(options.mode))
+        return [];
+    const mod = loadedStyleSpecModule();
+    if (!mod)
+        return [validatorUnavailableDiagnostic(options)];
+    return mapStyleSpecErrors(mod.validateStyleMin(styleForFilterValidation(filter, options.layerId)), { ...options, path: options.path ?? filterPath(options.layerId) }, { layerId: options.layerId ?? "__honua_filter_validation__" });
+}
+function validateExpressionWithModule(mod, value, options) {
+    const result = mod.createExpression(value);
+    if (result.result !== "error" || !Array.isArray(result.value))
+        return [];
+    return result.value.map((error) => {
+        const mapLibrePath = pathWithExpressionKey(options.path, stringProperty(error, "key"));
+        return mapLibreDiagnostic(error, stringProperty(error, "message") ?? "Invalid MapLibre style expression.", {
+            ...options,
+            path: mapLibrePath,
+            mapLibrePath,
+        });
+    });
+}
+async function loadMapLibreStyleSpecModule() {
+    if (loadedModule)
+        return loadedModule;
+    loadAttempted = true;
+    loadPromise ??= import("@maplibre/maplibre-gl-style-spec")
+        .then((mod) => {
+        const candidate = mod;
+        if (typeof candidate.validateStyleMin !== "function" || typeof candidate.createExpression !== "function") {
+            throw new Error("@maplibre/maplibre-gl-style-spec does not expose the expected validator API.");
+        }
+        loadedModule = {
+            validateStyleMin: candidate.validateStyleMin,
+            createExpression: candidate.createExpression,
+        };
+        loadFailure = undefined;
+        return loadedModule;
+    })
+        .catch((error) => {
+        loadFailure = error;
+        loadedModule = undefined;
+        return undefined;
+    });
+    return loadPromise;
+}
+function loadedStyleSpecModule() {
+    return loadedModule;
+}
+function shouldRunSyncStyleSpecValidation(mode) {
+    return mode !== undefined && mode !== "renderer-deferred";
+}
+function mapStyleSpecErrors(errors, options, remap) {
+    return errors.map((error) => {
+        const parsed = parseMapLibreMessage(stringProperty(error, "message") ?? "Invalid MapLibre style specification.");
+        const path = parsed.path ? normalizeStylePath(parsed.path, remap) : options.path;
+        return mapLibreDiagnostic(error, parsed.message, {
+            ...options,
+            path: path ?? options.path,
+            mapLibrePath: parsed.path,
+        });
+    });
+}
+function mapLibreDiagnostic(error, message, options) {
+    const mapLibreCode = stringProperty(error, "identifier") ?? "validation-error";
+    const line = numberProperty(error, "line");
+    return {
+        code: "style-spec-invalid",
+        severity: severityForMode(options.mode),
+        message,
+        ...(options.path ? { path: options.path } : {}),
+        ...(options.sourceId ? { sourceId: options.sourceId } : {}),
+        ...(options.layerId ? { layerId: options.layerId } : {}),
+        ...(options.protocol ? { protocol: options.protocol } : {}),
+        context: {
+            ...(options.context ?? {}),
+            mapLibreCode,
+            ...(options.mapLibrePath ? { mapLibrePath: options.mapLibrePath } : {}),
+            ...(line !== undefined ? { mapLibreLine: line } : {}),
+        },
+    };
+}
+function validatorUnavailableDiagnostic(options) {
+    const cause = loadAttempted
+        ? errorMessage(loadFailure) || "unknown import failure"
+        : "validator has not been prepared";
+    return {
+        code: "style-spec-validator-unavailable",
+        severity: severityForMode(options.mode),
+        message: "MapLibre style-spec validation is unavailable. Install @maplibre/maplibre-gl-style-spec or use renderer-deferred validation.",
+        ...(options.path ? { path: options.path } : {}),
+        ...(options.sourceId ? { sourceId: options.sourceId } : {}),
+        ...(options.layerId ? { layerId: options.layerId } : {}),
+        ...(options.protocol ? { protocol: options.protocol } : {}),
+        context: {
+            ...(options.context ?? {}),
+            mapLibreCode: "validator-unavailable",
+            cause,
+        },
+    };
+}
+function sanitizeStyle(style) {
+    const sources = {};
+    for (const [sourceId, source] of Object.entries(style.sources)) {
+        sources[sourceId] = isHonuaSourceLike(source)
+            ? placeholderSourceForLayer(firstLayerForSource(style.layers, sourceId), source)
+            : source;
+    }
+    return {
+        ...style,
+        sources,
+    };
+}
+function styleForLayerValidation(layer, options) {
+    const sources = {};
+    const sourceId = typeof layer.source === "string" ? layer.source : undefined;
+    if (sourceId) {
+        const existing = options.style?.sources[sourceId];
+        if (existing) {
+            sources[sourceId] = isHonuaSourceLike(existing) ? placeholderSourceForLayer(layer, existing) : existing;
+        }
+        else if (!options.style) {
+            sources[sourceId] = placeholderSourceForLayer(layer);
+        }
+    }
+    return {
+        version: 8,
+        sources,
+        layers: [layer],
+    };
+}
+function styleForFilterValidation(filter, layerId) {
+    const sourceId = "__honua_filter_source__";
+    return {
+        version: 8,
+        sources: {
+            [sourceId]: geoJsonPlaceholderSource(),
+        },
+        layers: [
+            {
+                id: layerId ?? "__honua_filter_validation__",
+                type: "circle",
+                source: sourceId,
+                filter,
+            },
+        ],
+    };
+}
+function placeholderSourceForLayer(layer, source) {
+    const sourceType = isPlainObject(source) && typeof source.type === "string" ? source.type : undefined;
+    if (sourceType === "honua-wms" || sourceType === "honua-wmts" || sourceType === "honua-map-service") {
+        return rasterPlaceholderSource();
+    }
+    if (layer?.type === "raster")
+        return rasterPlaceholderSource();
+    if (layer?.type === "hillshade")
+        return rasterDemPlaceholderSource();
+    return geoJsonPlaceholderSource();
+}
+function geoJsonPlaceholderSource() {
+    return {
+        type: "geojson",
+        data: { type: "FeatureCollection", features: [] },
+    };
+}
+function rasterPlaceholderSource() {
+    return {
+        type: "raster",
+        tiles: ["https://example.invalid/{z}/{x}/{y}.png"],
+        tileSize: 256,
+    };
+}
+function rasterDemPlaceholderSource() {
+    return {
+        type: "raster-dem",
+        tiles: ["https://example.invalid/{z}/{x}/{y}.png"],
+        tileSize: 256,
+    };
+}
+function firstLayerForSource(layers, sourceId) {
+    return layers.find((layer) => layer.source === sourceId);
+}
+function isHonuaSourceLike(value) {
+    return isPlainObject(value) && typeof value.type === "string" && value.type.startsWith("honua-");
+}
+function parseMapLibreMessage(message) {
+    const separator = message.indexOf(": ");
+    if (separator <= 0)
+        return { path: undefined, message };
+    const path = message.slice(0, separator);
+    if (!looksLikeMapLibrePath(path))
+        return { path: undefined, message };
+    return { path, message: message.slice(separator + 2) };
+}
+function looksLikeMapLibrePath(path) {
+    return /^(version|name|metadata|center|zoom|bearing|pitch|sources|layers|sprite|glyphs|transition|light|terrain|projection|sky)(?:$|[.[\]])/.test(path);
+}
+function normalizeStylePath(path, remap) {
+    if (remap.layerId) {
+        return path.replace(/^layers\[\d+\]/, `layers.${remap.layerId}`);
+    }
+    return path;
+}
+function pathWithExpressionKey(path, key) {
+    if (!key)
+        return path;
+    if (!path)
+        return key.startsWith(".") ? key.slice(1) : key;
+    return key.startsWith("[") || key.startsWith(".") ? `${path}${key}` : `${path}.${key}`;
+}
+function filterPath(layerId) {
+    return layerId ? `layers.${layerId}.filter` : "filter";
+}
+function layerPath(layer) {
+    return layer.id ? `layers.${layer.id}` : "layers[]";
+}
+function severityForMode(mode) {
+    return mode === "warning-only" ? "warning" : "error";
+}
+function stringProperty(value, property) {
+    if (!isPlainObject(value))
+        return undefined;
+    const candidate = value[property];
+    return typeof candidate === "string" ? candidate : undefined;
+}
+function numberProperty(value, property) {
+    if (!isPlainObject(value))
+        return undefined;
+    const candidate = value[property];
+    return typeof candidate === "number" ? candidate : undefined;
+}
+function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    return typeof error === "string" ? error : undefined;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/scene-workspace/analysis-widgets.d.ts

@@ -0,0 +1,334 @@
+/**
+ * Interactive 3D analysis + measurement widgets for the scene workspace.
+ *
+ * These widgets consume the server's elevation/analysis endpoints (line-of-sight,
+ * viewshed, elevation profile) and render the results into a live Cesium
+ * `SceneView`, plus a fully client-side 3D distance/area measurement widget.
+ *
+ * Like {@link module:scene-workspace/cesium-adapter}, this module never imports
+ * CesiumJS statically: the rendering helpers pull the runtime in lazily via
+ * `await import("cesium")` so 2D-only consumers never pay the bundle cost. The
+ * pure request-shaping and client-side geometry math (haversine distance,
+ * spherical polygon area, WKT serialization) carry no Cesium dependency at all
+ * and are unit-testable without a WebGL `Viewer`.
+ *
+ * Server calls go through a caller-supplied {@link SceneAnalysisRequestExecutor}
+ * — typically `(...args) => client.pipelineRequestJson(...args)` against a
+ * `HonuaClient` — so the widgets reuse the SDK's auth / retry / timeout /
+ * interceptor pipeline instead of issuing ad-hoc `fetch` calls.
+ *
+ * @experimental Part of the experimental `scene-workspace` surface; not yet
+ *   covered by the SDK's semver contract prior to `1.0.0`.
+ * @module
+ */
+import type { QueryMethod } from "../core/types.js";
+/**
+ * The minimal request-executor the analysis widgets need. This is exactly the
+ * shape of `HonuaClient.pipelineRequestJson`, so a consumer wires the SDK's
+ * shared HTTP pipeline (auth, retries, timeouts, interceptors) in with:
+ *
+ * ```ts
+ * const executor: SceneAnalysisRequestExecutor =
+ *   (method, path, init, signal) => client.pipelineRequestJson(method, path, init, signal);
+ * ```
+ *
+ * Modelling the transport as a function rather than depending on the concrete
+ * `HonuaClient` keeps this module free of a hard `core/client` import (and keeps
+ * it equally usable from a Node backend, a worker, or a test with a mock).
+ */
+export type SceneAnalysisRequestExecutor = <T = unknown>(method: QueryMethod, path: string, init?: {
+    headers?: Record<string, string>;
+    body?: string | null;
+}, signal?: AbortSignal) => Promise<T>;
+/**
+ * A lon/lat/height position in the workspace contract units (degrees + metres).
+ * Height is optional and defaults to ground (`0`) where the server / renderer
+ * needs an explicit value.
+ */
+export interface SceneAnalysisPosition {
+    readonly longitude: number;
+    readonly latitude: number;
+    readonly height?: number;
+}
+/**
+ * Great-circle (haversine) distance in metres between two lon/lat positions,
+ * ignoring height. Pure; the basis of the horizontal leg of a 3D measurement.
+ */
+export declare function haversineMeters(a: SceneAnalysisPosition, b: SceneAnalysisPosition): number;
+/**
+ * Slant (3D) distance in metres between two positions: the horizontal
+ * great-circle distance combined with the height delta via Pythagoras. Heights
+ * default to `0`. Pure.
+ */
+export declare function slantDistanceMeters(a: SceneAnalysisPosition, b: SceneAnalysisPosition): number;
+/**
+ * Total 3D path length in metres along an ordered polyline (sum of per-segment
+ * slant distances). Returns `0` for fewer than two positions. Pure.
+ */
+export declare function pathLengthMeters(positions: readonly SceneAnalysisPosition[]): number;
+/**
+ * Spherical polygon area in square metres for a ring of lon/lat positions,
+ * using L'Huilier's spherical-excess formula projected onto the WGS84 mean
+ * sphere. The ring is auto-closed; returns `0` for fewer than three positions.
+ * The result is unsigned (absolute area). Pure; the basis of the measure
+ * widget's area readout.
+ */
+export declare function sphericalPolygonAreaSquareMeters(positions: readonly SceneAnalysisPosition[]): number;
+/**
+ * Serialize an ordered list of positions as a 2D WKT `LINESTRING` (lon lat),
+ * the geometry shape the elevation profile endpoint expects on its `line`
+ * query parameter. Height is dropped (the profile endpoint samples the surface).
+ * Pure.
+ */
+export declare function positionsToWktLineString(positions: readonly SceneAnalysisPosition[]): string;
+/** One ordered sample along an elevation profile, mirroring the server shape. */
+export interface ElevationProfileSample {
+    readonly distanceMeters: number;
+    readonly elevation: number | null;
+    readonly noData: boolean;
+}
+/** The decoded `ElevationProfileResponse` the profile endpoint returns. */
+export interface ElevationProfileResult {
+    readonly datasetId: string;
+    readonly layerId: number;
+    readonly sampleCount: number;
+    readonly lineLengthMeters: number;
+    readonly lineSrid: number;
+    readonly isAllNoData: boolean;
+    readonly samples: readonly ElevationProfileSample[];
+}
+/** Parameters for an elevation-profile request along a polyline. */
+export interface ElevationProfileRequest {
+    readonly datasetId: string;
+    /** Ordered polyline (>= 2 positions) the profile is sampled along. */
+    readonly polyline: readonly SceneAnalysisPosition[];
+    /** Number of evenly-spaced samples (server clamps to its configured max). */
+    readonly sampleCount?: number;
+    /** Sample interval in metres (mutually exclusive with `sampleCount`). */
+    readonly intervalMeters?: number;
+    /** Spatial reference of the polyline coordinates; omitted ⇒ WGS84 lon/lat. */
+    readonly srid?: number;
+    readonly mosaicRule?: string;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Build the relative request path (with query string) for an elevation-profile
+ * request, including the WKT-serialized `line`. Exported so the request shape is
+ * directly unit-testable without a transport. The profile endpoint is a `GET`.
+ */
+export declare function buildElevationProfilePath(request: ElevationProfileRequest): string;
+/**
+ * Request an elevation profile along a polyline and return the decoded samples.
+ * Charting is left to the consumer; pair this with
+ * {@link renderElevationProfilePolyline} to draw the sampled line in the scene.
+ */
+export declare function requestElevationProfile(execute: SceneAnalysisRequestExecutor, request: ElevationProfileRequest): Promise<ElevationProfileResult>;
+/** Parameters for a line-of-sight request between an observer and a target. */
+export interface LineOfSightRequest {
+    readonly datasetId: string;
+    readonly observer: SceneAnalysisPosition;
+    readonly target: SceneAnalysisPosition;
+    /**
+     * Observer height OFFSET above the terrain surface, in metres (e.g. eye
+     * height). The server's `observerHeight` is exactly this terrain-relative
+     * offset, so this value wins over `observer.height` when supplied; otherwise
+     * `observer.height` is used as the offset and finally `0`.
+     */
+    readonly observerOffsetMeters?: number;
+    /** Target height OFFSET above the terrain surface, in metres. Same precedence as the observer. */
+    readonly targetOffsetMeters?: number;
+    /** Number of range samples along the sightline (server requires >= 2 when supplied). */
+    readonly sampleCount?: number;
+    readonly mosaicRule?: string;
+    readonly signal?: AbortSignal;
+}
+/** The decoded line-of-sight result: visibility + first obstruction (if any). */
+export interface LineOfSightResult {
+    readonly datasetId: string;
+    readonly layerId?: number;
+    readonly visible: boolean;
+    /** First terrain obstruction between observer and target, when not visible. */
+    readonly obstruction?: SceneAnalysisPosition;
+    /** Distance from the observer to the first obstruction, in metres, when obstructed. */
+    readonly obstructionDistanceMeters?: number;
+    /** Great-circle distance between observer and target, in metres. */
+    readonly distanceMeters?: number;
+    /** Observer elevation (ground elevation + observer height offset), in metres. */
+    readonly observerElevation?: number;
+    /** Target elevation (ground elevation + target height offset), in metres. */
+    readonly targetElevation?: number;
+    /** Number of range samples the server took along the sightline. */
+    readonly sampleCount?: number;
+    /** Whether any sampled point fell on terrain NoData. */
+    readonly hasNoDataSamples?: boolean;
+}
+/**
+ * Build the FLAT JSON request body sent to the line-of-sight endpoint. Pure.
+ *
+ * The server contract is flat (`observerLon/observerLat/observerHeight/...`)
+ * and treats `observerHeight`/`targetHeight` as the height OFFSET above the
+ * terrain surface. We therefore fold the ergonomic offset into that field with
+ * precedence `offsetMeters ?? position.height ?? 0`.
+ */
+export declare function buildLineOfSightBody(request: LineOfSightRequest): Record<string, unknown>;
+/**
+ * Request a line-of-sight analysis between an observer and a target. Pair the
+ * result with {@link renderLineOfSight} to draw the sightline (green visible /
+ * red obstructed segments) and an obstruction marker into the scene.
+ */
+export declare function requestLineOfSight(execute: SceneAnalysisRequestExecutor, request: LineOfSightRequest): Promise<LineOfSightResult>;
+/** Parameters for a viewshed request from an observer position. */
+export interface ViewshedRequest {
+    readonly datasetId: string;
+    readonly observer: SceneAnalysisPosition;
+    /**
+     * Observer height OFFSET above the terrain surface, in metres (e.g. tower /
+     * mast height). Maps to the server's `observerHeight`. Precedence:
+     * `observerOffsetMeters ?? observer.height ?? 0`.
+     */
+    readonly observerOffsetMeters?: number;
+    /** Height offset applied to each sampled target point, in metres. Maps to the server's `targetHeight`. */
+    readonly targetHeightMeters?: number;
+    /** Analysis radius in metres. Required, must be > 0. */
+    readonly radiusMeters: number;
+    /** Number of azimuth rays cast over the full 360°. Server requires >= 1 when supplied. */
+    readonly rayCount?: number;
+    /** Range samples taken along each ray. Server requires >= 2 when supplied. */
+    readonly samplesPerRay?: number;
+    readonly mosaicRule?: string;
+    readonly signal?: AbortSignal;
+}
+/** One radial visibility sample returned by the viewshed endpoint. */
+export interface ViewshedSample {
+    /** The sampled ground point (height is the terrain elevation, or `0` for NoData). */
+    readonly position: SceneAnalysisPosition;
+    /** Azimuth of the ray this sample belongs to, in degrees. */
+    readonly azimuthDegrees: number;
+    /** Distance from the observer to this sample along the ray, in metres. */
+    readonly distanceMeters: number;
+    /** Whether the observer can see this sampled point. */
+    readonly visible: boolean;
+}
+/**
+ * The decoded viewshed result. The visible extent is returned as RADIAL POINT
+ * SAMPLES (per-ray range samples), not polygon rings.
+ */
+export interface ViewshedResult {
+    readonly datasetId: string;
+    readonly layerId?: number;
+    readonly observer: SceneAnalysisPosition;
+    readonly radiusMeters: number;
+    /** Number of azimuth rays cast. */
+    readonly rayCount?: number;
+    /** Range samples per ray. */
+    readonly samplesPerRay?: number;
+    /** Total number of samples returned. */
+    readonly sampleCount: number;
+    /** Number of samples flagged visible. */
+    readonly visibleSampleCount: number;
+    /** The radial visibility samples. */
+    readonly samples: readonly ViewshedSample[];
+}
+/**
+ * Build the FLAT JSON request body sent to the viewshed endpoint. Pure.
+ *
+ * The server runs a full-360° radial cast controlled by `rayCount` /
+ * `samplesPerRay`; there is no azimuth sweep. `observerHeight`/`targetHeight`
+ * are terrain-relative offsets (precedence `offset ?? position.height ?? 0` for
+ * the observer).
+ */
+export declare function buildViewshedBody(request: ViewshedRequest): Record<string, unknown>;
+/**
+ * Request a viewshed analysis from an observer position. Pair the result with
+ * {@link renderViewshed} to draw the visible / obstructed radial samples.
+ */
+export declare function requestViewshed(execute: SceneAnalysisRequestExecutor, request: ViewshedRequest): Promise<ViewshedResult>;
+/** A 3D measurement computed from picked / supplied scene positions. */
+export interface SceneMeasurement {
+    readonly positions: readonly SceneAnalysisPosition[];
+    /** Total 3D path length in metres (sum of slant segments). */
+    readonly lengthMeters: number;
+    /** Per-segment slant distances in metres (length === positions.length - 1). */
+    readonly segmentMeters: readonly number[];
+    /** Polygon area in m² when `mode` is `area` and there are >= 3 positions. */
+    readonly areaSquareMeters?: number;
+    readonly mode: "distance" | "area";
+}
+/**
+ * Compute a 3D distance or area measurement from an ordered list of positions
+ * (typically picked off the scene). For `distance` the result carries the total
+ * 3D path length and per-segment slant distances; for `area` it additionally
+ * carries the spherical polygon area. Pure.
+ */
+export declare function measureScenePositions(positions: readonly SceneAnalysisPosition[], mode?: "distance" | "area"): SceneMeasurement;
+/**
+ * The Cesium `EntityCollection` surface (off `viewer.entities`) the analysis
+ * renderers add/remove graphics through. Real Cesium `EntityCollection`
+ * instances satisfy this; tests pass a plain object.
+ */
+export interface CesiumEntityCollectionLike {
+    add(entity: unknown): unknown;
+    remove(entity: unknown): boolean;
+}
+/**
+ * The minimal slice of `typeof import("cesium")` the analysis renderers touch.
+ * Modelled so a `vi.mock("cesium")` stub can satisfy it without a WebGL context.
+ */
+export interface SceneAnalysisCesiumModule {
+    readonly Cartesian3: {
+        fromDegrees(longitude: number, latitude: number, height?: number): unknown;
+        fromDegreesArrayHeights(coordinates: number[]): unknown;
+    };
+    readonly Color: {
+        fromCssColorString(color: string): unknown;
+        readonly LIME: unknown;
+        readonly RED: unknown;
+        readonly YELLOW: unknown;
+    };
+}
+/**
+ * A handle over the entities one analysis render added, so a caller can clear
+ * the overlay (e.g. before re-running the analysis). Keyed by a stable kind.
+ */
+export interface SceneAnalysisOverlay {
+    readonly kind: "line-of-sight" | "viewshed" | "elevation-profile" | "measurement";
+    readonly entities: readonly unknown[];
+    remove(): void;
+}
+/**
+ * Render a line-of-sight result into the scene's entity collection: the
+ * observer→target sightline (lime when visible, red when obstructed) plus a
+ * yellow point marking the first obstruction when present. Returns an overlay
+ * handle so the caller can clear it before re-running. Cesium is loaded lazily.
+ */
+export declare function renderLineOfSight(entities: CesiumEntityCollectionLike, request: Pick<LineOfSightRequest, "observer" | "target">, result: LineOfSightResult, cesium?: SceneAnalysisCesiumModule): Promise<SceneAnalysisOverlay>;
+/**
+ * Render a viewshed result into the scene's entity collection: one point per
+ * radial sample — green (`Color.LIME`) where the observer can see the sample,
+ * red (`Color.RED`) where it is obstructed. Returns an overlay handle. Cesium
+ * is loaded lazily.
+ */
+export declare function renderViewshed(entities: CesiumEntityCollectionLike, result: ViewshedResult, cesium?: SceneAnalysisCesiumModule): Promise<SceneAnalysisOverlay>;
+/**
+ * Render an elevation profile's sampled line into the scene's entity collection
+ * as a polyline draped at the sampled positions. Because the server returns
+ * distance/elevation samples (not lon/lat), the caller passes the original
+ * `polyline` so the rendered line aligns with the requested geometry; the
+ * sample elevations are not required for the line render and charting is left to
+ * the consumer. Returns an overlay handle. Cesium is loaded lazily.
+ */
+export declare function renderElevationProfilePolyline(entities: CesiumEntityCollectionLike, polyline: readonly SceneAnalysisPosition[], cesium?: SceneAnalysisCesiumModule): Promise<SceneAnalysisOverlay>;
+/**
+ * Render a measurement into the scene's entity collection: the measured
+ * polyline (or closed polygon outline for `area`) plus a label at the last
+ * vertex with the formatted length / area. Returns an overlay handle. Cesium is
+ * loaded lazily.
+ */
+export declare function renderMeasurement(entities: CesiumEntityCollectionLike, measurement: SceneMeasurement, cesium?: SceneAnalysisCesiumModule): Promise<SceneAnalysisOverlay>;
+/**
+ * Format a human-readable label for a measurement (km/m for distance, km²/m²
+ * for area). Pure; exported so consumers can reuse the same formatting in
+ * their own UI/labels.
+ */
+export declare function formatMeasurementLabel(measurement: SceneMeasurement): string;
+//# sourceMappingURL=analysis-widgets.d.ts.map