@faclon-labs/app-sdk 0.2.0 → 0.4.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';
 

package/dist/IOSenseApp.js

@@ -1,10 +1,11 @@
 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';
 import { SignIn } from './SignIn.js';
+import { startHostLook } from './host-look.js';
 /**
  * The root of an IOSense app: the session, and the sign-in screen when there is none.
  *
@@ -18,12 +19,34 @@ export function IOSenseApp({ name, auth = 'required', sample, apiBaseUrl, signIn
     const api = getConfig().apiBaseUrl;
     // Once, before the first child renders, so the first paint already has the session.
     const [phase, setPhase] = useState(() => {
+        // Framed in I/O Sense, the app may wear its look (chosen in the sidebar): asked for at once.
+        startHostLook();
         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 +78,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/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/host-look.d.ts

@@ -0,0 +1,29 @@
+/**
+ * I/O Sense's look, worn over the app's own design system when the person chose it for this app in
+ * their sidebar. The host works out the variables for the app's own library (shadcn's `--primary`,
+ * MUI's `--mui-palette-primary-main`, a company library's own token names) and sends them; this puts
+ * them on the page over the library's, and follows each change the host sends, with no reload.
+ * Outside I/O Sense, or with the app's own look chosen, it does nothing.
+ */
+export interface HostLook {
+    mode: 'light' | 'dark';
+    vars: Record<string, string>;
+    /** More selectors that hold the library's variables themselves (Ant Design's `.css-var-*`). */
+    scope?: string[];
+    /** The `data-theme` the library's own light/dark switch reads. */
+    theme?: string;
+    /** A Google Fonts stylesheet. */
+    fonts?: string;
+}
+/** Read and clean a look from the host; null for "its own look", undefined for nonsense. */
+export declare function hostLookOf(raw: unknown): HostLook | null | undefined;
+/** The stylesheet a look makes: its variables over the library's, whatever the library's selectors. */
+export declare function hostLookCss(look: HostLook): string;
+/** Put a look on the page, or take it off (null). */
+export declare function wearHostLook(look: HostLook | null): void;
+/**
+ * Ask the host for its look and follow what it sends. Once per page; `<IOSenseApp>` calls it before
+ * its first render. The question carries nothing, so it may go to any parent; only a trusted host's
+ * answer is worn.
+ */
+export declare function startHostLook(): void;

package/dist/host-look.js

@@ -0,0 +1,115 @@
+import { isEmbedded, isTrustedHostOrigin } from './auth.js';
+const STYLE_ID = 'iosense-host-look';
+const FONTS_ID = 'iosense-host-look-fonts';
+const NAME = /^--[\w-]+$/;
+/** A value can say a colour, a length or a font stack; never end the rule or open another. */
+const VALUE = /^[^;{}<>\\]*$/;
+const SELECTOR = /^[\w\s\-[\]="*^$.:#>+~(),]+$/;
+let started = false;
+let worn = null;
+/** What the page had before the look, put back when it is taken off. */
+let before = null;
+let guard = null;
+/** Read and clean a look from the host; null for "its own look", undefined for nonsense. */
+export function hostLookOf(raw) {
+    if (raw === null)
+        return null;
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const look = raw;
+    if (look.mode !== 'light' && look.mode !== 'dark')
+        return undefined;
+    const vars = {};
+    for (const [name, value] of Object.entries(look.vars ?? {}))
+        if (NAME.test(name) && typeof value === 'string' && VALUE.test(value))
+            vars[name] = value;
+    const scope = Array.isArray(look.scope) ? look.scope.filter((s) => typeof s === 'string' && SELECTOR.test(s)) : [];
+    const theme = typeof look.theme === 'string' && /^[\w-]+$/.test(look.theme) ? look.theme : undefined;
+    const fonts = typeof look.fonts === 'string' && look.fonts.startsWith('https://fonts.googleapis.com/') ? look.fonts : undefined;
+    return { mode: look.mode, vars, ...(scope.length ? { scope } : {}), ...(theme ? { theme } : {}), ...(fonts ? { fonts } : {}) };
+}
+/** The stylesheet a look makes: its variables over the library's, whatever the library's selectors. */
+export function hostLookCss(look) {
+    const body = Object.entries(look.vars)
+        .map(([name, value]) => `  ${name}: ${value} !important;`)
+        .join('\n');
+    return body ? `${[':root', ...(look.scope ?? [])].join(',\n')} {\n${body}\n}\n` : '';
+}
+function setMode(look) {
+    const root = document.documentElement;
+    root.classList.toggle('dark', look.mode === 'dark');
+    root.classList.toggle('light', look.mode === 'light');
+    root.style.colorScheme = look.mode;
+    if (look.theme && root.getAttribute('data-theme') !== look.theme)
+        root.setAttribute('data-theme', look.theme);
+}
+/** Put a look on the page, or take it off (null). */
+export function wearHostLook(look) {
+    const root = document.documentElement;
+    if (look) {
+        if (!before)
+            before = { theme: root.getAttribute('data-theme'), dark: root.classList.contains('dark'), light: root.classList.contains('light'), scheme: root.style.colorScheme };
+        let style = document.getElementById(STYLE_ID);
+        if (!style) {
+            style = document.createElement('style');
+            style.id = STYLE_ID;
+        }
+        style.textContent = hostLookCss(look);
+        // Last in <head>, after the library's own sheets (a dev server adds them later; they still lose to !important).
+        document.head.appendChild(style);
+        const fonts = document.getElementById(FONTS_ID);
+        if (look.fonts && fonts?.href !== look.fonts) {
+            const link = fonts ?? document.createElement('link');
+            link.id = FONTS_ID;
+            link.rel = 'stylesheet';
+            link.href = look.fonts;
+            document.head.appendChild(link);
+        }
+        else if (!look.fonts)
+            fonts?.remove();
+        worn = look;
+        setMode(look);
+        // The app's own switch (main.tsx follows the computer's light or dark) must not undo the host's.
+        if (!guard && typeof MutationObserver !== 'undefined') {
+            guard = new MutationObserver(() => worn && setMode(worn));
+            guard.observe(root, { attributes: true, attributeFilter: ['class', 'data-theme'] });
+        }
+        return;
+    }
+    guard?.disconnect();
+    guard = null;
+    worn = null;
+    document.getElementById(STYLE_ID)?.remove();
+    document.getElementById(FONTS_ID)?.remove();
+    if (before) {
+        if (before.theme === null)
+            root.removeAttribute('data-theme');
+        else
+            root.setAttribute('data-theme', before.theme);
+        root.classList.toggle('dark', before.dark);
+        root.classList.toggle('light', before.light);
+        root.style.colorScheme = before.scheme;
+        before = null;
+    }
+}
+/**
+ * Ask the host for its look and follow what it sends. Once per page; `<IOSenseApp>` calls it before
+ * its first render. The question carries nothing, so it may go to any parent; only a trusted host's
+ * answer is worn.
+ */
+export function startHostLook() {
+    if (started || typeof window === 'undefined' || !isEmbedded())
+        return;
+    started = true;
+    window.addEventListener('message', (event) => {
+        if (event.source !== window.parent || !isTrustedHostOrigin(event.origin))
+            return;
+        const data = event.data;
+        if (!data || data.source !== 'iolens-studio' || data.type !== 'look')
+            return;
+        const look = hostLookOf(data.look);
+        if (look !== undefined)
+            wearHostLook(look);
+    });
+    window.parent.postMessage({ source: 'iosense-app', type: 'look-request', v: 1 }, '*');
+}

package/dist/index.d.ts

@@ -13,4 +13,5 @@ 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';
+export { startHostLook, wearHostLook, type HostLook } from './host-look.js';

package/dist/index.js

@@ -13,4 +13,5 @@ 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';
+export { startHostLook, wearHostLook } from './host-look.js';

package/dist/map/source.d.ts

@@ -2,8 +2,8 @@ import type { AuthContext, JournalProvider, LinkProvider, OntologySpatialResolve
 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;
+    /** 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`. */
@@ -11,8 +11,10 @@ export interface UnsMapSourceOptions {
     /** 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.
+     * 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>;
 }

package/dist/map/source.js

@@ -1,4 +1,4 @@
-import { useMemo, useRef } from 'react';
+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';
@@ -8,12 +8,13 @@ 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;
+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
@@ -24,18 +25,21 @@ function sampleOntology(records) {
  * pass-through that allows it.
  */
 export function useUnsMapSource(options) {
-    const { token, apiBaseUrl, sample } = useIOSense();
+    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(/\/$/, '');
-    // Sample records are read once per switch into sample mode; a new array each render does not rebuild the map.
+    // 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, ontology: new MockOntologyResolver(sampleOntology(records)), uns: null };
+            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({
@@ -44,8 +48,23 @@ export function useUnsMapSource(options) {
             ...(options.workspaceName ? { workspaceName: options.workspaceName } : {}),
             ...(options.pollMs ? { pollMs: options.pollMs } : {}),
         });
-        return { data: uns, ontology: uns.ontology, uns };
+        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]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faclon-labs/app-sdk",
-  "version": "0.2.0",
+  "version": "0.4.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",

package/vendor/SOURCE.txt

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