@faclon-labs/app-sdk 0.1.0 → 0.3.0

package/README.md

@@ -12,6 +12,11 @@ Wrap the app in `<IOSenseApp>`. It takes the session IOSense hands over — the
 token (`?token=`, exchanged once), a bearer on the URL, or the `.iosense.io` cookie — takes the token
 out of the address, and keeps it in this browser. With no session it shows a sign-in screen.
 
+Inside IOSense (the Studio's view of a deployed app) the app is framed by a page that already has the
+viewer's session: from 0.3, `<IOSenseApp>` asks its parent for it (`postMessage`, about a second at
+most) and the Studio answers with the bearer, sent to the app's own origin only. No SSO token is made
+or exchanged. Only an IOSense origin (`*.iosense.io`, `*.iocompute.ai`, localhost) is believed.
+
 ```tsx
 import { IOSenseApp } from '@faclon-labs/app-sdk';
 
@@ -51,4 +56,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/IOSenseApp.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 import { useEffect, useMemo, useState } from 'react';
-import { adoptHostSession, clearToken, exchangeSsoToken, getToken, setToken, takePendingSsoToken } from './auth.js';
+import { adoptHostSession, clearToken, exchangeSsoToken, getToken, isEmbedded, requestHostSession, setToken, takePendingSsoToken } from './auth.js';
 import { configure, getConfig } from './config.js';
 import { publishSession } from './request.js';
 import { SAMPLE_NOTICE, SessionContext, useIOSense } from './session.js';
@@ -20,10 +20,30 @@ export function IOSenseApp({ name, auth = 'required', sample, apiBaseUrl, signIn
     const [phase, setPhase] = useState(() => {
         if (auth === 'none')
             return { kind: 'ready', token: null };
-        adoptHostSession();
+        const how = adoptHostSession();
         const sso = takePendingSsoToken();
-        return sso ? { kind: 'exchanging', sso } : { kind: 'ready', token: getToken() };
+        if (sso)
+            return { kind: 'exchanging', sso };
+        // Framed, with nothing handed over on the URL or in the cookie: the parent may hold the session
+        // (IOSense does). A session kept from before is asked about too — the parent's viewer wins.
+        if (isEmbedded() && (how === 'none' || how === 'stored'))
+            return { kind: 'asking' };
+        return { kind: 'ready', token: getToken() };
     });
+    useEffect(() => {
+        if (phase.kind !== 'asking')
+            return;
+        let current = true;
+        requestHostSession().then((handed) => {
+            if (handed)
+                setToken(handed);
+            if (current)
+                setPhase({ kind: 'ready', token: getToken() });
+        });
+        return () => {
+            current = false;
+        };
+    }, [phase]);
     useEffect(() => {
         if (phase.kind !== 'exchanging')
             return;
@@ -55,9 +75,9 @@ export function IOSenseApp({ name, auth = 'required', sample, apiBaseUrl, signIn
     }), [name, token, api, sample, auth]);
     // For `request()`, which is called from event handlers where there is no hook to read from.
     publishSession({ token, apiBaseUrl: api });
-    // A blank moment while the SSO token is exchanged: not the sign-in screen, which would be wrong
-    // for the half second before the session lands.
-    if (phase.kind === 'exchanging')
+    // A blank moment while the SSO token is exchanged or the parent is asked: not the sign-in screen,
+    // which would be wrong for the half second before the session lands.
+    if (phase.kind === 'exchanging' || phase.kind === 'asking')
         return null;
     if (auth === 'required' && !token) {
         const onSignedIn = (bearer) => {

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/auth.d.ts

@@ -15,6 +15,13 @@ export declare function setToken(token: string): void;
 export declare function clearToken(): void;
 /** True when this page runs inside another page's frame — the IOSense launchpad, normally. */
 export declare function isEmbedded(): boolean;
+export declare const isTrustedHostOrigin: (origin: string) => boolean;
+/**
+ * Ask the page this app is framed in for the viewer's session. Inside IOSense the parent answers at
+ * once with the bearer it already has, sent to this app's origin only; anywhere else nobody answers
+ * and this resolves null after `timeoutMs`. The question carries no secret, so it may go to any parent.
+ */
+export declare function requestHostSession(timeoutMs?: number): Promise<string | null>;
 /**
  * Take the session the host handed over, and take the token out of the URL. Called once, before
  * the first render (`<IOSenseApp>` does it). Returns how the session arrived.

package/dist/auth.js

@@ -2,7 +2,10 @@ import { getConfig } from './config.js';
 /**
  * The IOSense session: how an app gets it, and where it keeps it.
  *
- * Four ways in, in order:
+ * Five ways in, in order:
+ *  0. **Handed by the frame's parent** — inside IOSense (the Studio's view of a deployed app) the
+ *     parent already holds the viewer's bearer and posts it to this frame (`requestHostSession`):
+ *     no token to make, nothing to exchange, nothing in the URL. Only an IOSense origin is believed.
  *  1. **Launchpad, SSO mode** — IOSense opens the app as `…?token=<sso>`: a 64-hex SSO token,
  *     exchanged ONCE for the bearer (`exchangeSsoToken`) before the app renders.
  *  2. **A bearer on the URL** (`?token=<jwt>`), taken as it is.
@@ -93,6 +96,37 @@ export function isEmbedded() {
         return true;
     }
 }
+/** The pages that may hand this app a session: IOSense's own hosts, the Studio's, and a developer's machine. */
+const HOST_ORIGIN = /^https:\/\/([a-z0-9-]+\.)*(iosense\.io|iocompute\.ai)$|^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/i;
+export const isTrustedHostOrigin = (origin) => HOST_ORIGIN.test(origin);
+/**
+ * Ask the page this app is framed in for the viewer's session. Inside IOSense the parent answers at
+ * once with the bearer it already has, sent to this app's origin only; anywhere else nobody answers
+ * and this resolves null after `timeoutMs`. The question carries no secret, so it may go to any parent.
+ */
+export function requestHostSession(timeoutMs = 1000) {
+    if (typeof window === 'undefined' || !isEmbedded())
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        let timer;
+        const done = (token) => {
+            window.removeEventListener('message', heard);
+            clearTimeout(timer);
+            resolve(token);
+        };
+        const heard = (event) => {
+            if (event.source !== window.parent || !isTrustedHostOrigin(event.origin))
+                return;
+            const data = event.data;
+            if (!data || data.source !== 'iolens-studio' || data.type !== 'session')
+                return;
+            done(typeof data.token === 'string' && data.token.trim() ? data.token.trim() : null);
+        };
+        window.addEventListener('message', heard);
+        timer = setTimeout(() => done(null), timeoutMs);
+        window.parent.postMessage({ source: 'iosense-app', type: 'session-request', v: 1 }, '*');
+    });
+}
 function readCookie(name) {
     const prefix = `${name}=`;
     for (const part of document.cookie.split(';')) {

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/index.d.ts

@@ -13,4 +13,4 @@ export { useLatest, useSeries, useUser, type LatestOptions, type LatestResult, t
 export { fetchLatest, fetchSeries, isSampleTopic, type SeriesPoint } from './data.js';
 export { request, useRequest, RequestError, isIOSenseHost, type RequestOptions, type UseRequestOptions, type UseRequestResult } from './request.js';
 export { configure, getConfig, type IOSenseConfig } from './config.js';
-export { adoptHostSession, exchangeSsoToken, getToken, setToken, clearToken, isSsoToken, isEmbedded } from './auth.js';
+export { adoptHostSession, exchangeSsoToken, getToken, setToken, clearToken, isSsoToken, isEmbedded, requestHostSession, isTrustedHostOrigin } from './auth.js';

package/dist/index.js

@@ -13,4 +13,4 @@ export { useLatest, useSeries, useUser } from './hooks.js';
 export { fetchLatest, fetchSeries, isSampleTopic } from './data.js';
 export { request, useRequest, RequestError, isIOSenseHost } from './request.js';
 export { configure, getConfig } from './config.js';
-export { adoptHostSession, exchangeSsoToken, getToken, setToken, clearToken, isSsoToken, isEmbedded } from './auth.js';
+export { adoptHostSession, exchangeSsoToken, getToken, setToken, clearToken, isSsoToken, isEmbedded, requestHostSession, isTrustedHostOrigin } from './auth.js';

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,48 @@
+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. None: the map shows `sample`. */
+    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 when there is no workspace, or while the app is on sample data (nobody signed in with
+     * `auth="optional"`). Give each record the `ontologyType` your layers ask for. A new array moves the map's
+     * objects to it (added, changed and removed by `objectId`), so simulated live data is just a new array.
+     * 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,73 @@
+import { useEffect, 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';
+}
+const recordOf = (r) => ('object' in r ? r : { object: r });
+/** Classes and their geometry, written into `into` — the resolver keeps that object, so later records count too. */
+function learnOntology(records, into) {
+    for (const r of records.map(recordOf))
+        if (r.ontologyType)
+            into[r.ontologyType] = r.object.geometry.type;
+    return into;
+}
+/**
+ * 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 session = useIOSense();
+    const { token, apiBaseUrl } = session;
+    const sample = session.sample || !options.workspace;
+    const tokenRef = useRef(token);
+    tokenRef.current = token;
+    const base = (options.unsBaseUrl || getConfig().unsBaseUrl || unsBaseUrlFor(apiBaseUrl)).replace(/\/$/, '');
+    // The map is built once per switch into sample mode; later arrays are applied to it (below), never rebuilt.
+    const sampleRef = useRef(options.sample);
+    sampleRef.current = options.sample;
+    const built = useMemo(() => {
+        if (sample) {
+            const records = sampleRef.current ?? [];
+            const types = learnOntology(records, {});
+            const mock = new MockSpatialProvider(records, { latencyMs: 0 });
+            return { data: mock, mock, types, applied: records, ontology: new MockOntologyResolver(types), 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, mock: null, types: {}, applied: [], ontology: uns.ontology, uns };
+    }, [sample, base, options.workspace, options.workspaceName, options.pollMs]);
+    // A new sample array: what changed goes to the map as a live update.
+    useEffect(() => {
+        const next = options.sample;
+        if (!built.mock || !next || next === built.applied)
+            return;
+        const before = new Set(built.applied.map((r) => recordOf(r).object.objectId));
+        learnOntology(next, built.types);
+        for (const r of next.map(recordOf)) {
+            before.delete(r.object.objectId);
+            void built.mock.upsert(r.object, r.ontologyType ? { ontologyType: r.ontologyType } : undefined);
+        }
+        for (const id of before)
+            void built.mock.remove(id);
+        built.applied = next;
+    }, [built, options.sample]);
+    // 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.3.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 c5b1f59 — 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';