@faclon-labs/app-sdk 0.1.0 → 0.2.0

package/README.md

@@ -51,4 +51,37 @@ const { data, loading, error } = useRequest(url, { auth: 'iosense' });
 
 `auth: 'iosense'` adds the viewer's token and is refused for any host that is not IOSense's.
 
-Peer dependency: React 18 or later.
+## Maps (`@faclon-labs/app-sdk/map`)
+
+The IO Studio Map Engine on UNS data: a declarative `MapConfig`, the React `MapView`, the MapLibre renderer, the
+UNS provider, and the agent commands. Install MapLibre next to the SDK:
+
+```bash
+npm install @faclon-labs/app-sdk maplibre-gl
+```
+
+```tsx
+import 'maplibre-gl/dist/maplibre-gl.css';
+import { MapView, MapLibreRenderer, useUnsMapSource, type MapConfig } from '@faclon-labs/app-sdk/map';
+// Vite: without this line the map stays empty (the engine warns after 8 s).
+import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
+
+function PlantMap({ config }: { config: MapConfig }) {
+  const source = useUnsMapSource({ workspace: 'ws_…' }); // the viewer's session; the UNS decides what they see
+  return <MapView style={{ height: '100vh' }} config={config} {...source.props} createRenderer={() => new MapLibreRenderer({ workerUrl })} />;
+}
+```
+
+- `source.uns.listDatasets()` lists every spatial class in the workspace with its properties.
+- On sample data (`auth="optional"`, nobody signed in) the map shows `sample` records you pass to
+  `useUnsMapSource`. `@faclon-labs/app-sdk/map/testing` has fixtures and an in-memory provider.
+- The UNS host is `configure({ unsBaseUrl })`, else worked out from `apiBaseUrl`
+  (`appserver.X` → `uns-backend-server.X`). **The UNS backend answers only IOSense's own origins (CORS)**: an app
+  served from elsewhere needs a pass-through that allows it, set as `unsBaseUrl`.
+- 3D globe: `npm install cesium`, then `import { CesiumRenderer } from '@faclon-labs/app-sdk/map/globe'` and
+  `createRenderer={() => new CesiumRenderer()}`. A 2D app never downloads Cesium.
+
+The engine comes from the MapEngine repo: `npm run build` copies it into `vendor/` (set `MAP_ENGINE_DIR` if the
+checkout is not next to io-lens-mfe). `scripts/smoke-map.sh` installs the packed SDK into a fresh app and checks it.
+
+Peer dependencies: React 18 or later; `maplibre-gl` (v5+) for `./map`; `cesium` for `./map/globe`.

package/dist/SignIn.js

@@ -40,7 +40,7 @@ export function SignIn({ appName, apiBaseUrl, onSignedIn }) {
             }
             catch (err) {
                 // The server's own words ("Invalid or expired token.") say what to do: mint a new one.
-                setError(`${err instanceof Error ? err.message : 'IOSense did not accept this token.'} An SSO token works once — copy a fresh one.`);
+                setError(`${err instanceof Error ? err.message : 'IOSense did not accept this token.'} An SSO token works once. Copy a fresh one.`);
             }
             finally {
                 setBusy(false);
@@ -68,5 +68,5 @@ export function SignIn({ appName, apiBaseUrl, onSignedIn }) {
         onSignedIn(value);
     }
     const canSubmit = !busy && token.trim().length > 0;
-    return (_jsx("div", { "data-iosense-signin": true, style: { minHeight: '100vh', display: 'grid', placeItems: 'center', padding: 24, background: 'var(--background, #f7f7f4)', color: 'var(--foreground, #161616)', fontFamily: 'inherit' }, children: _jsxs("form", { onSubmit: submit, style: { width: 'min(380px, 100%)', display: 'flex', flexDirection: 'column', gap: 12, padding: 24, borderRadius: 12, background: 'var(--card, #fff)', border: '1px solid var(--border, #e2e0da)' }, children: [_jsxs("div", { children: [_jsxs("h1", { style: { margin: 0, fontSize: 18, fontWeight: 600 }, children: ["Sign in to ", appName] }), _jsx("p", { style: { margin: '4px 0 0', fontSize: 13, color: 'var(--muted-foreground, #5c5c5c)' }, children: "This app reads your plant through IOSense. Paste an SSO token from your IOSense session." })] }), _jsxs("label", { style: { display: 'flex', flexDirection: 'column', gap: 4, fontSize: 13, fontWeight: 500 }, children: ["SSO token", _jsx("input", { name: "token", autoComplete: "off", autoFocus: true, spellCheck: false, placeholder: "Paste an SSO token from IOSense", value: token, onChange: (e) => setToken(e.target.value), disabled: busy, style: { width: '100%', boxSizing: 'border-box', height: 40, padding: '0 12px', border: '1px solid var(--border, #d4d4d8)', borderRadius: 8, background: 'var(--background, #fff)', color: 'inherit', font: 'inherit' } })] }), error && (_jsx("p", { role: "alert", style: { margin: 0, fontSize: 13, color: 'var(--destructive, #b4302c)' }, children: error })), _jsx("button", { type: "submit", disabled: !canSubmit, style: { height: 40, border: 0, borderRadius: 999, background: 'var(--primary, #1364f1)', color: 'var(--primary-foreground, #fff)', font: 'inherit', fontWeight: 500, cursor: busy ? 'progress' : 'pointer', opacity: canSubmit ? 1 : 0.6 }, children: busy ? 'Checking…' : 'Continue' }), _jsx("p", { style: { margin: 0, fontSize: 12, color: 'var(--muted-foreground, #5c5c5c)' }, children: "Opened from the IOSense launchpad, this app signs you in on its own \u2014 this screen is for opening it by its own address." })] }) }));
+    return (_jsx("div", { "data-iosense-signin": true, style: { minHeight: '100vh', display: 'grid', placeItems: 'center', padding: 24, background: 'var(--background, #f7f7f4)', color: 'var(--foreground, #161616)', fontFamily: 'inherit' }, children: _jsxs("form", { onSubmit: submit, style: { width: 'min(380px, 100%)', display: 'flex', flexDirection: 'column', gap: 12, padding: 24, borderRadius: 12, background: 'var(--card, #fff)', border: '1px solid var(--border, #e2e0da)' }, children: [_jsxs("div", { children: [_jsxs("h1", { style: { margin: 0, fontSize: 18, fontWeight: 600 }, children: ["Sign in to ", appName] }), _jsx("p", { style: { margin: '4px 0 0', fontSize: 13, color: 'var(--muted-foreground, #5c5c5c)' }, children: "This app reads your plant through IOSense. Paste an SSO token from your IOSense session." })] }), _jsxs("label", { style: { display: 'flex', flexDirection: 'column', gap: 4, fontSize: 13, fontWeight: 500 }, children: ["SSO token", _jsx("input", { name: "token", autoComplete: "off", autoFocus: true, spellCheck: false, placeholder: "Paste an SSO token from IOSense", value: token, onChange: (e) => setToken(e.target.value), disabled: busy, style: { width: '100%', boxSizing: 'border-box', height: 40, padding: '0 12px', border: '1px solid var(--border, #d4d4d8)', borderRadius: 8, background: 'var(--background, #fff)', color: 'inherit', font: 'inherit' } })] }), error && (_jsx("p", { role: "alert", style: { margin: 0, fontSize: 13, color: 'var(--destructive, #b4302c)' }, children: error })), _jsx("button", { type: "submit", disabled: !canSubmit, style: { height: 40, border: 0, borderRadius: 999, background: 'var(--primary, #1364f1)', color: 'var(--primary-foreground, #fff)', font: 'inherit', fontWeight: 500, cursor: busy ? 'progress' : 'pointer', opacity: canSubmit ? 1 : 0.6 }, children: busy ? 'Checking…' : 'Continue' }), _jsx("p", { style: { margin: 0, fontSize: 12, color: 'var(--muted-foreground, #5c5c5c)' }, children: "Opened from the IOSense launchpad, this app signs you in on its own. This screen is for opening it by its own address." })] }) }));
 }

package/dist/config.d.ts

@@ -12,6 +12,11 @@ export interface IOSenseConfig {
     tokenCookie: string;
     /** Where the session is kept in this browser. */
     storageKey: string;
+    /**
+     * The UNS backend the map reads (`@faclon-labs/app-sdk/map`). Empty: worked out from `apiBaseUrl`
+     * (`appserver.X` → `uns-backend-server.X`).
+     */
+    unsBaseUrl: string;
 }
 export declare function configure(next: Partial<IOSenseConfig>): void;
 export declare const getConfig: () => Readonly<IOSenseConfig>;

package/dist/config.js

@@ -3,6 +3,7 @@ const config = {
     ssoExchangeUrl: 'https://connector.iosense.io/api/retrieve-sso-token',
     tokenCookie: 'AccessToken',
     storageKey: 'bearer_token',
+    unsBaseUrl: '',
 };
 export function configure(next) {
     for (const [key, value] of Object.entries(next)) {

package/dist/map/globe.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @faclon-labs/app-sdk/map/globe — the 3D globe renderer (Cesium). Install `cesium` next to the SDK; pass
+ * `createRenderer={() => new CesiumRenderer()}` to `MapView`. Everything else comes from `@faclon-labs/app-sdk/map`.
+ */
+export * from '../../vendor/map-engine/cesium/index.js';

package/dist/map/globe.js

@@ -0,0 +1,5 @@
+/**
+ * @faclon-labs/app-sdk/map/globe — the 3D globe renderer (Cesium). Install `cesium` next to the SDK; pass
+ * `createRenderer={() => new CesiumRenderer()}` to `MapView`. Everything else comes from `@faclon-labs/app-sdk/map`.
+ */
+export * from '../../vendor/map-engine/cesium/index.js';

package/dist/map/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @faclon-labs/app-sdk/map — maps on UNS data.
+ *
+ * The IO Studio Map Engine (runtime, contracts, spatial API, commands, agent transports), its React view and
+ * MapLibre renderer, and the UNS provider — plus `useUnsMapSource`, which connects the provider to the viewer's
+ * session. The 3D globe (Cesium) is a separate entry, `@faclon-labs/app-sdk/map/globe`, so a 2D app never
+ * downloads it.
+ *
+ * ```tsx
+ * import { MapView, MapLibreRenderer, useUnsMapSource } from '@faclon-labs/app-sdk/map';
+ * import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
+ *
+ * const source = useUnsMapSource({ workspace: 'ws_…' });
+ * <MapView {...source.props} config={config} createRenderer={() => new MapLibreRenderer({ workerUrl })} />
+ * ```
+ */
+export * from '../../vendor/map-engine/index.js';
+export * from '../../vendor/map-engine/react/index.js';
+export * from '../../vendor/map-engine/maplibre/index.js';
+export * from '../../vendor/map-provider-uns/index.js';
+export { useUnsMapSource, unsBaseUrlFor, type UnsMapSource, type UnsMapSourceOptions, type UnsMapSourceProps } from './source.js';

package/dist/map/index.js

@@ -0,0 +1,21 @@
+/**
+ * @faclon-labs/app-sdk/map — maps on UNS data.
+ *
+ * The IO Studio Map Engine (runtime, contracts, spatial API, commands, agent transports), its React view and
+ * MapLibre renderer, and the UNS provider — plus `useUnsMapSource`, which connects the provider to the viewer's
+ * session. The 3D globe (Cesium) is a separate entry, `@faclon-labs/app-sdk/map/globe`, so a 2D app never
+ * downloads it.
+ *
+ * ```tsx
+ * import { MapView, MapLibreRenderer, useUnsMapSource } from '@faclon-labs/app-sdk/map';
+ * import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
+ *
+ * const source = useUnsMapSource({ workspace: 'ws_…' });
+ * <MapView {...source.props} config={config} createRenderer={() => new MapLibreRenderer({ workerUrl })} />
+ * ```
+ */
+export * from '../../vendor/map-engine/index.js';
+export * from '../../vendor/map-engine/react/index.js';
+export * from '../../vendor/map-engine/maplibre/index.js';
+export * from '../../vendor/map-provider-uns/index.js';
+export { useUnsMapSource, unsBaseUrlFor } from './source.js';

package/dist/map/source.d.ts

@@ -0,0 +1,46 @@
+import type { AuthContext, JournalProvider, LinkProvider, OntologySpatialResolver, RealtimeProvider, SpatialDataProvider, SpatialObject, TrackProvider } from '../../vendor/map-engine/index.js';
+import { UnsSpatialProvider } from '../../vendor/map-provider-uns/index.js';
+import { type MockRecord } from '../../vendor/map-engine/testing/index.js';
+export interface UnsMapSourceOptions {
+    /** The UNS workspace id (`ws_…`) whose spatial nodes the map shows. */
+    workspace: string;
+    /** Shown as the datasets' source. */
+    workspaceName?: string;
+    /** The UNS backend. Default: `configure({ unsBaseUrl })`, else worked out from the session's `apiBaseUrl`. */
+    unsBaseUrl?: string;
+    /** How often live values are read. Default 3000 ms. */
+    pollMs?: number;
+    /**
+     * What the map shows while the app is on sample data (nobody signed in with `auth="optional"`). Give each record
+     * the `ontologyType` your layers ask for. Default: nothing — the layers stay empty.
+     */
+    sample?: Array<MockRecord | SpatialObject>;
+}
+/** Spread into `<MapView>`: the data side of a map. */
+export interface UnsMapSourceProps {
+    provider: SpatialDataProvider;
+    realtime: RealtimeProvider;
+    history: TrackProvider;
+    ontology: OntologySpatialResolver;
+    journal: JournalProvider;
+    links: LinkProvider;
+    auth: AuthContext | null;
+}
+export interface UnsMapSource {
+    props: UnsMapSourceProps;
+    /** The UNS provider (null on sample data): `listDatasets()` gives every spatial class with its properties. */
+    uns: UnsSpatialProvider | null;
+    /** True while the map shows the app's sample records rather than the plant's. */
+    sample: boolean;
+}
+/** `https://appserver.X` → `https://uns-backend-server.X`. Any other host: IOSense's production UNS. */
+export declare function unsBaseUrlFor(apiBaseUrl: string): string;
+/**
+ * The UNS as a map data source, on the viewer's session: the token is read on every request, so a refreshed
+ * session is used at once, and handed to the engine as `auth` so the UNS decides what is visible. Inside
+ * `<IOSenseApp>` only.
+ *
+ * The UNS backend answers only IOSense's own origins (CORS). An app served from elsewhere sets `unsBaseUrl` to a
+ * pass-through that allows it.
+ */
+export declare function useUnsMapSource(options: UnsMapSourceOptions): UnsMapSource;

package/dist/map/source.js

@@ -0,0 +1,54 @@
+import { useMemo, useRef } from 'react';
+import { UnsClient, UnsSpatialProvider } from '../../vendor/map-provider-uns/index.js';
+import { MockOntologyResolver, MockSpatialProvider } from '../../vendor/map-engine/testing/index.js';
+import { getConfig } from '../config.js';
+import { useIOSense } from '../session.js';
+/** `https://appserver.X` → `https://uns-backend-server.X`. Any other host: IOSense's production UNS. */
+export function unsBaseUrlFor(apiBaseUrl) {
+    const m = /^(https?:\/\/)appserver\.(.+?)\/?$/.exec(apiBaseUrl);
+    return m ? `${m[1]}uns-backend-server.${m[2]}` : 'https://uns-backend-server.iosense.io';
+}
+function sampleOntology(records) {
+    const out = {};
+    for (const r of records)
+        if ('object' in r && r.ontologyType)
+            out[r.ontologyType] = r.object.geometry.type;
+    return out;
+}
+/**
+ * The UNS as a map data source, on the viewer's session: the token is read on every request, so a refreshed
+ * session is used at once, and handed to the engine as `auth` so the UNS decides what is visible. Inside
+ * `<IOSenseApp>` only.
+ *
+ * The UNS backend answers only IOSense's own origins (CORS). An app served from elsewhere sets `unsBaseUrl` to a
+ * pass-through that allows it.
+ */
+export function useUnsMapSource(options) {
+    const { token, apiBaseUrl, sample } = useIOSense();
+    const tokenRef = useRef(token);
+    tokenRef.current = token;
+    const base = (options.unsBaseUrl || getConfig().unsBaseUrl || unsBaseUrlFor(apiBaseUrl)).replace(/\/$/, '');
+    // Sample records are read once per switch into sample mode; a new array each render does not rebuild the map.
+    const sampleRef = useRef(options.sample);
+    sampleRef.current = options.sample;
+    const built = useMemo(() => {
+        if (sample) {
+            const records = sampleRef.current ?? [];
+            const mock = new MockSpatialProvider(records, { latencyMs: 0 });
+            return { data: mock, ontology: new MockOntologyResolver(sampleOntology(records)), uns: null };
+        }
+        const client = new UnsClient({ baseUrl: base, token: () => tokenRef.current });
+        const uns = new UnsSpatialProvider({
+            client,
+            workspace: options.workspace,
+            ...(options.workspaceName ? { workspaceName: options.workspaceName } : {}),
+            ...(options.pollMs ? { pollMs: options.pollMs } : {}),
+        });
+        return { data: uns, ontology: uns.ontology, uns };
+    }, [sample, base, options.workspace, options.workspaceName, options.pollMs]);
+    // No dispose on unmount: polling stops by itself when the map's runtime unsubscribes, and React's dev double
+    // effects would otherwise cut a live map's subscription.
+    const auth = useMemo(() => (token && !sample ? { token } : null), [token, sample]);
+    const props = useMemo(() => ({ provider: built.data, realtime: built.data, history: built.data, ontology: built.ontology, journal: built.data, links: built.data, auth }), [built, auth]);
+    return { props, uns: built.uns, sample };
+}

package/dist/map/testing.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @faclon-labs/app-sdk/map/testing — an in-memory provider, a renderer that draws nothing, fixtures and contract
+ * checks, for tests and sample data.
+ */
+export * from '../../vendor/map-engine/testing/index.js';

package/dist/map/testing.js

@@ -0,0 +1,5 @@
+/**
+ * @faclon-labs/app-sdk/map/testing — an in-memory provider, a renderer that draws nothing, fixtures and contract
+ * checks, for tests and sample data.
+ */
+export * from '../../vendor/map-engine/testing/index.js';

package/dist/session.d.ts

@@ -13,7 +13,7 @@ export interface IOSenseSession {
     /** Forget the session in this browser and show the sign-in screen again. */
     signOut: () => void;
 }
-export declare const SAMPLE_NOTICE = "Sample data \u2014 not live plant readings";
+export declare const SAMPLE_NOTICE = "Sample data: not live plant readings";
 export declare const SessionContext: import("react").Context<IOSenseSession | null>;
 /** The session of the nearest `<IOSenseApp>`. Throws outside one. */
 export declare function useIOSense(): IOSenseSession;

package/dist/session.js

@@ -1,5 +1,5 @@
 import { createContext, useContext } from 'react';
-export const SAMPLE_NOTICE = 'Sample data — not live plant readings';
+export const SAMPLE_NOTICE = 'Sample data: not live plant readings';
 export const SessionContext = createContext(null);
 /** The session of the nearest `<IOSenseApp>`. Throws outside one. */
 export function useIOSense() {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@faclon-labs/app-sdk",
-  "version": "0.1.0",
-  "description": "IOSense sign-in and plant data for React apps: the launchpad SSO session, UNS latest values and series, the signed-in user, and requests to IOSense's APIs.",
+  "version": "0.2.0",
+  "description": "IOSense sign-in, plant data and maps for React apps: the launchpad SSO session, UNS latest values and series, the signed-in user, requests to IOSense's APIs, and the Map Engine on UNS (./map).",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -10,28 +10,78 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./map": {
+      "types": "./dist/map/index.d.ts",
+      "import": "./dist/map/index.js"
+    },
+    "./map/globe": {
+      "types": "./dist/map/globe.d.ts",
+      "import": "./dist/map/globe.js"
+    },
+    "./map/testing": {
+      "types": "./dist/map/testing.d.ts",
+      "import": "./dist/map/testing.js"
     }
   },
   "files": [
     "dist",
+    "vendor",
     "README.md"
   ],
   "sideEffects": false,
+  "dependencies": {
+    "@deck.gl/core": "~9.4.0",
+    "@deck.gl/layers": "~9.4.0",
+    "@deck.gl/mapbox": "~9.4.0",
+    "@deck.gl/mesh-layers": "~9.4.0",
+    "@loaders.gl/core": "^4.5.2",
+    "@loaders.gl/gltf": "^4.5.2",
+    "@luma.gl/core": "~9.4.2",
+    "@turf/area": "^7.4.0",
+    "@turf/boolean-contains": "^7.4.0",
+    "@turf/boolean-intersects": "^7.4.0",
+    "@turf/boolean-within": "^7.4.0",
+    "@turf/circle": "^7.4.0",
+    "@turf/distance": "^7.4.0",
+    "@turf/kinks": "^7.4.0",
+    "@turf/line-intersect": "^7.4.0",
+    "@turf/point-on-feature": "^7.4.0",
+    "@turf/point-to-line-distance": "^7.4.0",
+    "@turf/point-to-polygon-distance": "^7.4.0",
+    "@types/geojson": "7946.0.16",
+    "maplibre-contour": "^0.1.1",
+    "pmtiles": "^4.5.0",
+    "rbush": "^4.0.1"
+  },
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "maplibre-gl": ">=5.0.0",
+    "cesium": ">=1.120.0"
+  },
+  "peerDependenciesMeta": {
+    "maplibre-gl": {
+      "optional": true
+    },
+    "cesium": {
+      "optional": true
+    }
   },
   "keywords": [
     "iosense",
     "faclon",
     "uns",
     "react",
-    "sso"
+    "sso",
+    "map",
+    "maplibre"
   ],
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json"
+    "vendor": "node scripts/vendor-map-engine.mjs",
+    "build": "node scripts/vendor-map-engine.mjs && rm -rf dist && tsc -p tsconfig.json"
   }
 }

package/vendor/SOURCE.txt

@@ -0,0 +1 @@
+Built from MapEngine bcf2a34 — do not edit; run npm run vendor.

package/vendor/map-engine/cesium/camera.d.ts

@@ -0,0 +1,10 @@
+/** Ground metres per screen pixel at a zoom and latitude (web-map convention). */
+export declare function metresPerPixel(zoom: number, latitude: number): number;
+/** Distance from the camera to the centre that shows `viewHeightPx` pixels of ground at `zoom` (vertical FOV in radians). */
+export declare function rangeForZoom(zoom: number, latitude: number, viewHeightPx: number, fovY: number): number;
+/** The inverse of rangeForZoom. */
+export declare function zoomForRange(range: number, latitude: number, viewHeightPx: number, fovY: number): number;
+/** Engine pitch (0 = looking straight down, up to 85) → camera pitch in degrees (−90 = straight down). */
+export declare const cameraPitch: (pitch: number | undefined) => number;
+/** Camera pitch in degrees → engine pitch. */
+export declare const enginePitch: (cameraPitchDeg: number) => number;

package/vendor/map-engine/cesium/camera.js

@@ -0,0 +1,25 @@
+/**
+ * The engine's viewport (centre, zoom, bearing, pitch) ↔ a 3D camera (Cesium). Pure maths, testable without WebGL.
+ *
+ * Zoom keeps its web-map meaning: at zoom z the ground under the centre measures 2π·R·cos(lat) / (256·2^z) metres
+ * per pixel. A camera that frames the view height at that scale stands `range` metres from the centre.
+ */
+const EARTH_RADIUS = 6_378_137;
+/** Ground metres per screen pixel at a zoom and latitude (web-map convention). */
+export function metresPerPixel(zoom, latitude) {
+    return (2 * Math.PI * EARTH_RADIUS * Math.cos((latitude * Math.PI) / 180)) / (256 * 2 ** zoom);
+}
+/** Distance from the camera to the centre that shows `viewHeightPx` pixels of ground at `zoom` (vertical FOV in radians). */
+export function rangeForZoom(zoom, latitude, viewHeightPx, fovY) {
+    return (metresPerPixel(zoom, latitude) * viewHeightPx) / 2 / Math.tan(fovY / 2);
+}
+/** The inverse of rangeForZoom. */
+export function zoomForRange(range, latitude, viewHeightPx, fovY) {
+    const mpp = (2 * range * Math.tan(fovY / 2)) / Math.max(1, viewHeightPx);
+    const z = Math.log2((2 * Math.PI * EARTH_RADIUS * Math.cos((latitude * Math.PI) / 180)) / (256 * mpp));
+    return Math.max(0, Math.min(24, z));
+}
+/** Engine pitch (0 = looking straight down, up to 85) → camera pitch in degrees (−90 = straight down). */
+export const cameraPitch = (pitch) => -90 + Math.max(0, Math.min(85, pitch ?? 0));
+/** Camera pitch in degrees → engine pitch. */
+export const enginePitch = (cameraPitchDeg) => Math.max(0, Math.min(85, 90 + cameraPitchDeg));

package/vendor/map-engine/cesium/index.d.ts

@@ -0,0 +1,2 @@
+export { CesiumRenderer, DEFAULT_CESIUM_THEME, type CesiumRendererOptions, type CesiumTheme } from './renderer.js';
+export { metresPerPixel, rangeForZoom, zoomForRange } from './camera.js';

package/vendor/map-engine/cesium/index.js

@@ -0,0 +1,2 @@
+export { CesiumRenderer, DEFAULT_CESIUM_THEME } from './renderer.js';
+export { metresPerPixel, rangeForZoom, zoomForRange } from './camera.js';

package/vendor/map-engine/cesium/renderer.d.ts

@@ -0,0 +1,149 @@
+/**
+ * CesiumRenderer — the full-3D renderer (ADR-027, phase 3D): a true globe with terrain, objects at their real height,
+ * models and extrusions, behind the same Renderer contract as MapLibre. The runtime can switch to it and back
+ * (setRenderer) keeping layers, camera, selection and time.
+ *
+ * - No Cesium Ion and no cloud service: imagery from the basemap's tile URL, terrain from the same DEM tiles MapLibre
+ *   uses (terrarium.ts), static assets served from `baseUrl` (self-hostable).
+ * - One Cesium entity per scene object; markers stay visible over terrain; areas and lines drape on the ground.
+ * - Heights (ADR-028): msl as-is in the same frame as the (sea-level) terrain, agl relative to the ground,
+ *   ellipsoid warned once (no geoid model). Scene vertical exaggeration applies to terrain and heights alike.
+ * No business logic, no data queries; picks report stable objectIds.
+ */
+import type * as CesiumNS from 'cesium';
+import type { BasemapConfig, MapConfig, MapViewport, Position, RendererCapabilities, ScenePatch, SceneState, Size, TerrainConfig, TilesetConfig, Unsubscribe } from '../core/types.js';
+import type { MapClickEvent, PickEvent, Renderer, RendererOptions } from '../render/renderer.js';
+type C = typeof CesiumNS;
+type Listener<T> = (value: T) => void;
+export interface CesiumTheme {
+    markerColor: string;
+    lineColor: string;
+    fillColor: string;
+    trackColor: string;
+    selectionColor: string;
+    hoverColor: string;
+    labelColor: string;
+    labelHalo: string;
+    background: string;
+}
+export declare const DEFAULT_CESIUM_THEME: CesiumTheme;
+export interface CesiumRendererOptions {
+    /** Inject the module (tests, or apps that loaded it). Default: lazy `import('cesium')`. */
+    cesium?: C;
+    /** Where Cesium's static assets (Workers, Assets, Widgets, ThirdParty) are served from. Required in the browser. */
+    baseUrl?: string;
+    theme?: Partial<CesiumTheme>;
+    /** Heightmap samples per terrain tile edge. Default 65. */
+    terrainSamples?: number;
+}
+export declare class CesiumRenderer implements Renderer {
+    private readonly options;
+    private lib;
+    private viewer;
+    private handler;
+    private readonly offs;
+    private gen;
+    private readonly theme;
+    private readonly layers;
+    private readonly objects;
+    /** Every entity id drawn for an object (shape, stem, outline, parts, label), so removal is complete. */
+    private readonly drawn;
+    /** How each point object was drawn, apart from where: when only its position changes it is moved, not rebuilt. */
+    private readonly looks;
+    private hoverKey;
+    private fontName;
+    private terrain;
+    /** Loaded 3D Tiles by id, with the config they were loaded from. */
+    private readonly tilesets;
+    private warnedEllipsoid;
+    private warnedStyleBasemap;
+    /** Longest side of each model file once measured (sizeMeters). */
+    private readonly extents;
+    private readonly measuring;
+    /** Ground under volume origins, as drawn (exaggerated metres), by position; filled by one batched terrain sample. */
+    private readonly grounds;
+    private readonly groundQueue;
+    private readonly listeners;
+    /** A true globe: heights, models, extrusions, sensor volumes and 3D Tiles. */
+    readonly capabilities: RendererCapabilities;
+    constructor(options?: CesiumRendererOptions);
+    initialize(container: HTMLElement, options: RendererOptions): Promise<void>;
+    setViewport(viewport: MapViewport, options?: {
+        animate?: boolean;
+    }): void;
+    render(scene: SceneState): void;
+    update(patch: ScenePatch): void;
+    /**
+     * Draws objects again, in batches. Cesium merges a removal and an add of the same entity id within one batch
+     * into "nothing changed", and its visualizers keep drawing the old entity — so all removals go in one batch,
+     * which is flushed before the adds.
+     */
+    private redraw;
+    /** What a point object looks like apart from its position (layer, selection, properties). */
+    private lookOf;
+    /**
+     * Moves an already drawn point object when only its position changed (the common live update): the entity and
+     * its stem get the new position; nothing is rebuilt. False when it must be drawn again.
+     */
+    private move;
+    resize(): void;
+    getSize(): Size;
+    project(position: Position): {
+        x: number;
+        y: number;
+    } | null;
+    onCameraMove(l: () => void): Unsubscribe;
+    setBasemap(basemap: BasemapConfig): Promise<void>;
+    /** Cesium always draws a globe; a flat (mercator) request keeps the globe, which reads the same up close. */
+    setProjection(_projection: NonNullable<MapConfig['projection']>): void;
+    setTerrain(terrain: TerrainConfig | null): void;
+    /** 3D Tiles scenery from URLs (no Cesium Ion): added, replaced, shown/hidden and removed by id. */
+    setTilesets(tilesets: TilesetConfig[]): void;
+    sampleElevation(positions: Position[]): Promise<Array<number | null>>;
+    destroy(): void;
+    onViewportChange(l: Listener<MapViewport>): Unsubscribe;
+    onPick(l: Listener<PickEvent>): Unsubscribe;
+    onMapClick(l: Listener<MapClickEvent>): Unsubscribe;
+    onHover(l: Listener<PickEvent | null>): Unsubscribe;
+    onError(l: Listener<Error>): Unsubscribe;
+    /** The basemap as Cesium imagery: a tile URL works as is; a vector style URL needs a raster fallback. */
+    private imageryLayer;
+    /** Terrain from the configured DEM tiles (same as MapLibre), or a smooth ellipsoid. */
+    private terrainProvider;
+    /** Takes the new layer list; returns the objects to draw again and the keys to drop (their layer went away). */
+    private applyLayers;
+    private drop;
+    /** Adds or replaces the entities of one scene object. */
+    private put;
+    /** Draws one scene object (nothing of it may be drawn yet). */
+    private draw;
+    /**
+     * A height as drawn (ADR-028): Cesium's vertical exaggeration scales the terrain but not absolute heights, so heights
+     * are scaled the same way to keep an aircraft's true relation to the (exaggerated) ground. `lift` multiplies the
+     * height above the ground; `relative` (agl) heights are measured from the ground Cesium places them on.
+     */
+    /**
+     * How things on the ground are placed: clamped to the terrain when there is one; without terrain the ground is
+     * the ellipsoid, so height 0 directly — Cesium updates clamped billboards lazily, and a moving one lagged behind.
+     */
+    private groundReference;
+    /**
+     * Contour lines (doc 28 G11) as Cesium's elevation-contour material on the globe. This renderer exaggerates the
+     * terrain itself, so the spacing is exaggerated the same way and the lines still sit on true heights.
+     */
+    private applyContours;
+    /** The drawn ground height under a point: cached, else the loaded tiles' guess now and a precise sample soon. */
+    private groundHeight;
+    private sampleGrounds;
+    private drawnHeight;
+    /** Measures a model file once (its longest side), then redraws the objects that use it (sizeMeters). */
+    private measure;
+    private bindEvents;
+    private hitTest;
+    /** The ground (terrain, else ellipsoid) under a screen point. */
+    private groundAt;
+    private currentViewport;
+    private emitError;
+    private add;
+}
+export {};