@sybilion/uilib 1.0.29 → 1.0.31

package/dist/esm/index.js

@@ -1,4 +1,5 @@
-export { MINIAPP_CHANNEL, MINIAPP_VERSION, applyThemeToDocument, buildReadyMessage, parseThemeSyncMessage, resolveParentOriginFromReferrer } from './mini-app/miniAppProtocol.js';
+export { MINIAPP_CHANNEL, MINIAPP_VERSION, applyThemeToDocument, buildDataRequestMessage, buildReadyMessage, isTrustedMiniAppParentMessage, parseDataResponseMessage, parseThemeSyncMessage, resolveParentOriginFromReferrer } from './mini-app/miniAppProtocol.js';
+export { createMiniAppDataClient } from './mini-app/miniAppDataClient.js';
 export { getDefaultMiniAppThemeConfig } from './mini-app/miniAppThemeConfig.js';
 export { MiniAppRoot, useMiniAppShellTheme } from './mini-app/MiniAppRoot.js';
 export { ChatContext, ChatProvider, useChat, useChats, useChatsForDataset, useChatsForScopeId, useCurrentChat } from './contexts/chat-context.js';

package/dist/esm/mini-app/MiniAppRoot.js

@@ -3,7 +3,7 @@ import cn from 'classnames';
 import { createContext, useContext, useState, useRef, useMemo, useCallback, useEffect } from 'react';
 import { Theme, Scroll } from '@homecode/ui';
 import S from './MiniAppRoot.styl.js';
-import { resolveParentOriginFromReferrer, applyThemeToDocument, buildReadyMessage, parseThemeSyncMessage } from './miniAppProtocol.js';
+import { resolveParentOriginFromReferrer, applyThemeToDocument, buildReadyMessage, isTrustedMiniAppParentMessage, parseThemeSyncMessage } from './miniAppProtocol.js';
 import { getDefaultMiniAppThemeConfig } from './miniAppThemeConfig.js';
 
 const defaultTheme = {
@@ -30,22 +30,6 @@ function useMiniAppShellTheme() {
     }
     return v;
 }
-/**
- * Accept only messages that appear to come from the real embedding parent:
- * - `source` must be `window.parent` (same as shell’s iframe target).
- * - When `document.referrer` is present, `origin` must match it (Sybilion page that loaded this iframe).
- *   If referrer was stripped (Referrer-Policy), we only rely on `source` matching `parent`.
- */
-function isTrustedParentMessage(event) {
-    // Ignore messages from other windows (e.g. popups, other iframes).
-    if (event.source !== window.parent)
-        return false;
-    const fromReferrer = resolveParentOriginFromReferrer();
-    // Tighten to embedder origin when the browser exposes it.
-    if (fromReferrer && event.origin !== fromReferrer)
-        return false;
-    return true;
-}
 function MiniAppRoot({ children, className, appId, onThemeChange, getThemeConfig, }) {
     const [theme, setTheme] = useState(() => isEmbeddedMiniApp() ? defaultTheme : themeFromDocument());
     const onThemeChangeRef = useRef(onThemeChange);
@@ -73,7 +57,7 @@ function MiniAppRoot({ children, className, appId, onThemeChange, getThemeConfig
     }, [theme.mode]);
     useEffect(() => {
         const onMessage = (event) => {
-            if (!isTrustedParentMessage(event))
+            if (!isTrustedMiniAppParentMessage(event))
                 return;
             const parsed = parseThemeSyncMessage(event.data);
             if (!parsed)

package/dist/esm/mini-app/miniAppDataClient.js

@@ -0,0 +1,98 @@
+import { buildDataRequestMessage, resolveParentOriginFromReferrer, isTrustedMiniAppParentMessage, parseDataResponseMessage } from './miniAppProtocol.js';
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+/** One listener per browsing context; tracks in-flight bridge requests by `requestId`. */
+function createMiniAppDataClient(options) {
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const pending = new Map();
+    let listening = false;
+    const settle = (rid, fn) => {
+        const p = pending.get(rid);
+        if (!p)
+            return;
+        clearTimeout(p.timer);
+        pending.delete(rid);
+        fn(p);
+    };
+    function ensureListener() {
+        if (listening || typeof window === 'undefined')
+            return;
+        listening = true;
+        window.addEventListener('message', (event) => {
+            if (!isTrustedMiniAppParentMessage(event))
+                return;
+            const msg = parseDataResponseMessage(event.data);
+            if (!msg)
+                return;
+            settle(msg.requestId, p => {
+                if (msg.ok) {
+                    p.resolve(msg.result);
+                }
+                else {
+                    p.reject(new Error(typeof msg.error === 'string'
+                        ? msg.error
+                        : 'Mini-app data request failed'));
+                }
+            });
+        });
+    }
+    function request(payload) {
+        if (typeof window === 'undefined' || window.parent === window) {
+            throw new Error('MiniAppDataClient works only inside an iframe embed');
+        }
+        ensureListener();
+        const requestId = typeof crypto !== 'undefined' && 'randomUUID' in crypto
+            ? crypto.randomUUID()
+            : `miniapp-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        const envelope = buildDataRequestMessage({
+            ...payload,
+            requestId,
+        });
+        const target = resolveParentOriginFromReferrer();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                settle(requestId, p => {
+                    p.reject(new Error('Mini-app data request timed out'));
+                });
+            }, timeoutMs);
+            pending.set(requestId, {
+                resolve,
+                reject,
+                timer,
+            });
+            try {
+                if (target) {
+                    window.parent.postMessage(envelope, target);
+                }
+                else {
+                    window.parent.postMessage(envelope, '*');
+                }
+            }
+            catch (e) {
+                settle(requestId, p => {
+                    p.reject(e instanceof Error ? e : new Error('Mini-app postMessage failed'));
+                });
+            }
+        });
+    }
+    async function rq(op, params) {
+        return request({ op, params });
+    }
+    return {
+        getDatasets: () => rq('getDatasets'),
+        getDataset: id => rq('getDataset', { id }),
+        getForecasts: datasetId => rq('getForecasts', { datasetId }),
+        getForecast: (datasetId, analysisId) => rq('getForecast', { datasetId, analysisId }),
+        getDrivers: (datasetId, analysisId) => rq('getDrivers', { datasetId, analysisId }),
+        getPerformanceData: (datasetId, analysisId) => rq('getPerformanceData', {
+            datasetId,
+            analysisId,
+        }),
+        getDriversComparisonData: (datasetId, analysisId) => rq('getDriversComparisonData', {
+            datasetId,
+            analysisId,
+        }),
+    };
+}
+
+export { createMiniAppDataClient };

package/dist/esm/mini-app/miniAppProtocol.js

@@ -53,5 +53,54 @@ function applyThemeToDocument(mode) {
     root.classList.remove('light', 'dark');
     root.classList.add(mode);
 }
+/** Only accept shell messages that appear to come from the real embedding parent. */
+function isTrustedMiniAppParentMessage(event) {
+    if (event.source !== window.parent)
+        return false;
+    const fromReferrer = resolveParentOriginFromReferrer();
+    if (fromReferrer && event.origin !== fromReferrer)
+        return false;
+    return true;
+}
+function buildDataRequestMessage(payload) {
+    return {
+        channel: MINIAPP_CHANNEL,
+        version: MINIAPP_VERSION,
+        type: 'DATA_REQUEST',
+        payload,
+    };
+}
+/** Parse parent → child DATA_RESPONSE. */
+function parseDataResponseMessage(data) {
+    if (!isRecord(data))
+        return null;
+    if (data.channel !== MINIAPP_CHANNEL)
+        return null;
+    if (data.version !== MINIAPP_VERSION)
+        return null;
+    if (data.type !== 'DATA_RESPONSE')
+        return null;
+    const payload = data.payload;
+    if (!isRecord(payload))
+        return null;
+    const requestId = payload.requestId;
+    if (typeof requestId !== 'string' || requestId.length === 0)
+        return null;
+    const ok = payload.ok === true;
+    const errOk = payload.ok === false;
+    if (!ok && !errOk)
+        return null;
+    const base = {
+        requestId,
+        ok,
+    };
+    if ('result' in payload) {
+        base.result = payload.result;
+    }
+    if (typeof payload.error === 'string') {
+        base.error = payload.error;
+    }
+    return base;
+}
 
-export { MINIAPP_CHANNEL, MINIAPP_VERSION, applyThemeToDocument, buildReadyMessage, parseThemeSyncMessage, resolveParentOriginFromReferrer };
+export { MINIAPP_CHANNEL, MINIAPP_VERSION, applyThemeToDocument, buildDataRequestMessage, buildReadyMessage, isTrustedMiniAppParentMessage, parseDataResponseMessage, parseThemeSyncMessage, resolveParentOriginFromReferrer };

package/dist/esm/types/src/mini-app/index.d.ts

@@ -1,5 +1,8 @@
-export { applyThemeToDocument, buildReadyMessage, MINIAPP_CHANNEL, MINIAPP_VERSION, parseThemeSyncMessage, resolveParentOriginFromReferrer, } from './miniAppProtocol';
-export type { MiniAppMessageReady, MiniAppMessageThemeSync, ThemeSyncPayload, } from './miniAppProtocol';
+export { applyThemeToDocument, buildDataRequestMessage, buildReadyMessage, MINIAPP_CHANNEL, MINIAPP_VERSION, parseDataResponseMessage, parseThemeSyncMessage, isTrustedMiniAppParentMessage, resolveParentOriginFromReferrer, } from './miniAppProtocol';
+export type { MiniAppMessageReady, MiniAppMessageThemeSync, MiniAppMessageDataRequest, MiniAppMessageDataResponse, MiniAppDataRequestPayload, MiniAppDataResponsePayload, MiniAppDataOp, ThemeSyncPayload, } from './miniAppProtocol';
+export { createMiniAppDataClient } from './miniAppDataClient';
+export type { MiniAppDataClientOptions, MiniAppDataClient, } from './miniAppDataClient';
+export type { MiniAppDataset, MiniAppDriversComparisonSnapshot, MiniAppForecastMap, MiniAppPerformanceBundle, } from './miniAppDataTypes';
 export { getDefaultMiniAppThemeConfig } from './miniAppThemeConfig';
 export type { MiniAppThemeConfig } from './miniAppThemeConfig';
 export { MiniAppRoot, useMiniAppShellTheme } from './MiniAppRoot';

package/dist/esm/types/src/mini-app/miniAppDataClient.d.ts

@@ -0,0 +1,16 @@
+import type { MiniAppDataset, MiniAppDriversComparisonSnapshot, MiniAppForecastMap, MiniAppPerformanceBundle } from './miniAppDataTypes';
+export type MiniAppDataClientOptions = {
+    /** Default 10000 ms. */
+    timeoutMs?: number;
+};
+export type MiniAppDataClient = {
+    getDatasets(): Promise<MiniAppDataset[]>;
+    getDataset(id: number): Promise<MiniAppDataset | null>;
+    getForecasts(datasetId: number): Promise<MiniAppForecastMap>;
+    getForecast(datasetId: number, analysisId: number): Promise<unknown | null>;
+    getDrivers(datasetId: number, analysisId: number): Promise<unknown[]>;
+    getPerformanceData(datasetId: number, analysisId: number): Promise<MiniAppPerformanceBundle>;
+    getDriversComparisonData(datasetId: number, analysisId: number): Promise<MiniAppDriversComparisonSnapshot>;
+};
+/** One listener per browsing context; tracks in-flight bridge requests by `requestId`. */
+export declare function createMiniAppDataClient(options?: MiniAppDataClientOptions): MiniAppDataClient;

package/dist/esm/types/src/mini-app/miniAppDataTypes.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Serializable shapes returned by the shell for mini-app data getters.
+ * Subset of Sybilion `Dataset` / API types — use `unknown` where payloads are large or evolving.
+ */
+export type MiniAppDataset = {
+    id: number;
+    user_id?: number;
+    name: string;
+    description?: string;
+    status: string;
+    created_at: string;
+    updated_at: string;
+    keywords: string;
+    category: {
+        id: number;
+        name: string;
+    };
+    target_type_id: number;
+    target_type: {
+        id: number;
+        name: string;
+    };
+    trend: number;
+    regular_price: string;
+    sale_price: string;
+    regions: {
+        id: number;
+        name: string;
+    }[];
+    unit: {
+        id: number;
+        name: string;
+    };
+    version?: number;
+};
+/** `forecastData` slice: analysis id (string) → forecast series blob. */
+export type MiniAppForecastMap = Record<string, unknown>;
+export type MiniAppPerformanceBundle = {
+    /** Cached Performance-tab API payload, or null if user never opened Performance / cache empty. */
+    table: unknown;
+    /** In-memory spaghetti lines from shell context, or null. */
+    spaghetti: unknown;
+};
+export type MiniAppDriversComparisonSnapshot = {
+    byRegion: unknown;
+    byCountry: unknown;
+    byCategory: unknown;
+    byImportance: unknown;
+    driversCount: number | null;
+};

package/dist/esm/types/src/mini-app/miniAppProtocol.d.ts

@@ -22,9 +22,38 @@ export type MiniAppMessageThemeSync = {
     type: 'THEME_SYNC';
     payload: ThemeSyncPayload;
 };
+export type MiniAppDataOp = 'getDatasets' | 'getDataset' | 'getForecasts' | 'getForecast' | 'getDrivers' | 'getPerformanceData' | 'getDriversComparisonData';
+export type MiniAppDataRequestPayload = {
+    requestId: string;
+    op: MiniAppDataOp;
+    params?: Record<string, number>;
+};
+export type MiniAppMessageDataRequest = {
+    channel: typeof MINIAPP_CHANNEL;
+    version: typeof MINIAPP_VERSION;
+    type: 'DATA_REQUEST';
+    payload: MiniAppDataRequestPayload;
+};
+export type MiniAppDataResponsePayload = {
+    requestId: string;
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+};
+export type MiniAppMessageDataResponse = {
+    channel: typeof MINIAPP_CHANNEL;
+    version: typeof MINIAPP_VERSION;
+    type: 'DATA_RESPONSE';
+    payload: MiniAppDataResponsePayload;
+};
 /** Parse parent → child THEME_SYNC (shell uses `buildThemeSyncMessage`). */
 export declare function parseThemeSyncMessage(data: unknown): ThemeSyncPayload | null;
 /** Child → parent READY (optional `appId` for telemetry). */
 export declare function buildReadyMessage(payload?: Record<string, unknown>): MiniAppMessageReady;
 export declare function resolveParentOriginFromReferrer(): string | null;
 export declare function applyThemeToDocument(mode: 'light' | 'dark'): void;
+/** Only accept shell messages that appear to come from the real embedding parent. */
+export declare function isTrustedMiniAppParentMessage(event: MessageEvent): boolean;
+export declare function buildDataRequestMessage(payload: MiniAppDataRequestPayload): MiniAppMessageDataRequest;
+/** Parse parent → child DATA_RESPONSE. */
+export declare function parseDataResponseMessage(data: unknown): MiniAppDataResponsePayload | null;

package/docs/workspace-mini-apps.md

@@ -2,6 +2,14 @@
 
 The Sybilion client embeds mini-apps in an **iframe** and syncs theme with `postMessage`. Use **`MiniAppRoot`** so this document’s `<html>` gets **`light` / `dark`** (uilib uses `.dark { … }` for tokens), and so **`@homecode/ui`’s `<Theme />`** runs with vars matching that mode (`getDefaultMiniAppThemeConfig`; override via props if needed).
 
+## Design system (`@sybilion/uilib`)
+
+**Prefer exported components from `@sybilion/uilib`** for structure, typography, forms, feedback, data display, and charts **when they fit the need**. That keeps spacing, tokens, and behavior aligned with Sybilion and avoids one-off layouts. Use custom markup or CSS **only** when uilib has no suitable primitive.
+
+**For humans and coding agents:** Default to uilib as the component library—do not invent new layout patterns or duplicate design tokens when an existing uilib component (or composition of a few) can do the job. Browse the uilib docs app / package exports before building bespoke UI.
+
+**Page inset:** Do **not** add your own **left/right** padding or margin on the root page or a full-viewport wrapper (no random `px-*` / `mx-*` / `container` max-width hacks for “page margins”). Use uilib layout primitives and spacing tokens—or patterns documented for mini-apps—so horizontal gutters and max width stay consistent with the shell.
+
 1. Import **`@sybilion/uilib/mini-app-global.css`** (slim tokens + font imports; ships in this package).
 2. Wrap the React root:
 
@@ -21,3 +29,23 @@ createRoot(document.getElementById('root')!).render(
 4. Optional: **`getThemeConfig`** on **`MiniAppRoot`** — passed **`(isDarkMode) => config`** like the Sybilion app’s **`getThemeConfig`** from **`src/lib/theme.ts`**, so iframe UI matches host accent/danger tokens.
 
 **Bridge:** `MiniAppRoot` handles `THEME_SYNC`, sends `READY` on mount/load, and checks `event.source === window.parent` plus `document.referrer` origin when present. If the referrer is missing (strict `Referrer-Policy`), `READY` may use `targetOrigin` `*` — document that for your host.
+
+## Cached data from the host (no extra APIs)
+
+The Sybilion shell can answer read-only **data getters** over the same `postMessage` channel (`DATA_REQUEST` / `DATA_RESPONSE`). Use this when a mini-app should render **the user’s existing Sybilion data** (datasets, forecasts, drivers, performance, drivers comparison) **without** building duplicate backend calls.
+
+- **Cache-only:** The shell returns whatever is **already in memory** (dataset context) or in the **same localStorage cache** the main app uses for Performance (e.g. `performance-<analysisId>`). It does **not** trigger network fetches. If the user never opened a dataset tab or the blob was never loaded, you get **empty objects, `null`, or `[]`** — handle that in UI.
+- **Performance bundle:** `getPerformanceData` returns `{ table, spaghetti }`. `table` is the cached Performance-tab payload (often `null` until the user has opened Performance for that analysis). `spaghetti` is in-memory backtest lines from the host when present.
+- **Usage:** Create one client (e.g. module singleton) with **`createMiniAppDataClient()`** from `@sybilion/uilib`. It only works **inside the iframe** (throws if `window.parent === window`). Methods: **`getDatasets()`**, **`getDataset(id)`**, **`getForecasts(datasetId)`**, **`getForecast(datasetId, analysisId)`**, **`getDrivers(datasetId, analysisId)`**, **`getPerformanceData(datasetId, analysisId)`**, **`getDriversComparisonData(datasetId, analysisId)`**. Types **`MiniAppDataset`**, **`MiniAppForecastMap`**, **`MiniAppPerformanceBundle`**, **`MiniAppDriversComparisonSnapshot`** describe the returned JSON loosely.
+
+**For coding agents:** Prefer these getters when the task is “show the user’s current Sybilion data in the mini-app” so the iframe stays aligned with the host session and avoids inventing parallel data loading.
+
+```tsx
+import { createMiniAppDataClient } from '@sybilion/uilib';
+
+const data = createMiniAppDataClient();
+
+// inside an effect or loader (iframe only)
+const datasets = await data.getDatasets();
+const forecasts = await data.getForecasts(datasetId);
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sybilion/uilib",
-  "version": "1.0.29",
+  "version": "1.0.31",
   "description": "Sybilion Design System — React UI components (Webpack + Stylus)",
   "publishConfig": {
     "access": "public",

package/src/mini-app/MiniAppRoot.tsx

@@ -17,6 +17,7 @@ import {
   type ThemeSyncPayload,
   applyThemeToDocument,
   buildReadyMessage,
+  isTrustedMiniAppParentMessage,
   parseThemeSyncMessage,
   resolveParentOriginFromReferrer,
 } from './miniAppProtocol';
@@ -59,21 +60,6 @@ export function useMiniAppShellTheme(): MiniAppShellContextValue {
   return v;
 }
 
-/**
- * Accept only messages that appear to come from the real embedding parent:
- * - `source` must be `window.parent` (same as shell’s iframe target).
- * - When `document.referrer` is present, `origin` must match it (Sybilion page that loaded this iframe).
- *   If referrer was stripped (Referrer-Policy), we only rely on `source` matching `parent`.
- */
-function isTrustedParentMessage(event: MessageEvent): boolean {
-  // Ignore messages from other windows (e.g. popups, other iframes).
-  if (event.source !== window.parent) return false;
-  const fromReferrer = resolveParentOriginFromReferrer();
-  // Tighten to embedder origin when the browser exposes it.
-  if (fromReferrer && event.origin !== fromReferrer) return false;
-  return true;
-}
-
 export type MiniAppRootProps = {
   children: ReactNode;
   className?: string;
@@ -127,7 +113,7 @@ export function MiniAppRoot({
 
   useEffect(() => {
     const onMessage = (event: MessageEvent) => {
-      if (!isTrustedParentMessage(event)) return;
+      if (!isTrustedMiniAppParentMessage(event)) return;
       const parsed = parseThemeSyncMessage(event.data);
       if (!parsed) return;
       setTheme(parsed);

package/src/mini-app/index.ts

@@ -1,16 +1,35 @@
 export {
   applyThemeToDocument,
+  buildDataRequestMessage,
   buildReadyMessage,
   MINIAPP_CHANNEL,
   MINIAPP_VERSION,
+  parseDataResponseMessage,
   parseThemeSyncMessage,
+  isTrustedMiniAppParentMessage,
   resolveParentOriginFromReferrer,
 } from './miniAppProtocol';
 export type {
   MiniAppMessageReady,
   MiniAppMessageThemeSync,
+  MiniAppMessageDataRequest,
+  MiniAppMessageDataResponse,
+  MiniAppDataRequestPayload,
+  MiniAppDataResponsePayload,
+  MiniAppDataOp,
   ThemeSyncPayload,
 } from './miniAppProtocol';
+export { createMiniAppDataClient } from './miniAppDataClient';
+export type {
+  MiniAppDataClientOptions,
+  MiniAppDataClient,
+} from './miniAppDataClient';
+export type {
+  MiniAppDataset,
+  MiniAppDriversComparisonSnapshot,
+  MiniAppForecastMap,
+  MiniAppPerformanceBundle,
+} from './miniAppDataTypes';
 export { getDefaultMiniAppThemeConfig } from './miniAppThemeConfig';
 export type { MiniAppThemeConfig } from './miniAppThemeConfig';
 export { MiniAppRoot, useMiniAppShellTheme } from './MiniAppRoot';

package/src/mini-app/miniAppDataClient.ts

@@ -0,0 +1,165 @@
+import type {
+  MiniAppDataset,
+  MiniAppDriversComparisonSnapshot,
+  MiniAppForecastMap,
+  MiniAppPerformanceBundle,
+} from './miniAppDataTypes';
+import {
+  type MiniAppDataOp,
+  type MiniAppDataRequestPayload,
+  buildDataRequestMessage,
+  isTrustedMiniAppParentMessage,
+  parseDataResponseMessage,
+  resolveParentOriginFromReferrer,
+} from './miniAppProtocol';
+
+export type MiniAppDataClientOptions = {
+  /** Default 10000 ms. */
+  timeoutMs?: number;
+};
+
+export type MiniAppDataClient = {
+  getDatasets(): Promise<MiniAppDataset[]>;
+  getDataset(id: number): Promise<MiniAppDataset | null>;
+  getForecasts(datasetId: number): Promise<MiniAppForecastMap>;
+  getForecast(datasetId: number, analysisId: number): Promise<unknown | null>;
+  getDrivers(datasetId: number, analysisId: number): Promise<unknown[]>;
+  getPerformanceData(
+    datasetId: number,
+    analysisId: number,
+  ): Promise<MiniAppPerformanceBundle>;
+  getDriversComparisonData(
+    datasetId: number,
+    analysisId: number,
+  ): Promise<MiniAppDriversComparisonSnapshot>;
+};
+
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+type Pending = {
+  resolve: (value: unknown) => void;
+  reject: (err: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+};
+
+/** One listener per browsing context; tracks in-flight bridge requests by `requestId`. */
+export function createMiniAppDataClient(
+  options?: MiniAppDataClientOptions,
+): MiniAppDataClient {
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const pending = new Map<string, Pending>();
+  let listening = false;
+
+  const settle = (rid: string, fn: (p: Pending) => void): void => {
+    const p = pending.get(rid);
+    if (!p) return;
+    clearTimeout(p.timer);
+    pending.delete(rid);
+    fn(p);
+  };
+
+  function ensureListener(): void {
+    if (listening || typeof window === 'undefined') return;
+    listening = true;
+    window.addEventListener('message', (event: MessageEvent) => {
+      if (!isTrustedMiniAppParentMessage(event)) return;
+      const msg = parseDataResponseMessage(event.data);
+      if (!msg) return;
+      settle(msg.requestId, p => {
+        if (msg.ok) {
+          p.resolve(msg.result);
+        } else {
+          p.reject(
+            new Error(
+              typeof msg.error === 'string'
+                ? msg.error
+                : 'Mini-app data request failed',
+            ),
+          );
+        }
+      });
+    });
+  }
+
+  function request(
+    payload: Omit<MiniAppDataRequestPayload, 'requestId'>,
+  ): Promise<unknown> {
+    if (typeof window === 'undefined' || window.parent === window) {
+      throw new Error('MiniAppDataClient works only inside an iframe embed');
+    }
+    ensureListener();
+
+    const requestId =
+      typeof crypto !== 'undefined' && 'randomUUID' in crypto
+        ? crypto.randomUUID()
+        : `miniapp-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+
+    const envelope = buildDataRequestMessage({
+      ...payload,
+      requestId,
+    });
+    const target = resolveParentOriginFromReferrer();
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        settle(requestId, p => {
+          p.reject(new Error('Mini-app data request timed out'));
+        });
+      }, timeoutMs);
+
+      pending.set(requestId, {
+        resolve,
+        reject,
+        timer,
+      });
+
+      try {
+        if (target) {
+          window.parent.postMessage(envelope, target);
+        } else {
+          window.parent.postMessage(envelope, '*');
+        }
+      } catch (e) {
+        settle(requestId, p => {
+          p.reject(
+            e instanceof Error ? e : new Error('Mini-app postMessage failed'),
+          );
+        });
+      }
+    });
+  }
+
+  async function rq<R>(
+    op: MiniAppDataOp,
+    params?: Record<string, number>,
+  ): Promise<R> {
+    return request({ op, params }) as Promise<R>;
+  }
+
+  return {
+    getDatasets: () => rq<MiniAppDataset[]>('getDatasets'),
+
+    getDataset: id => rq<MiniAppDataset | null>('getDataset', { id }),
+
+    getForecasts: datasetId =>
+      rq<MiniAppForecastMap>('getForecasts', { datasetId }),
+
+    getForecast: (datasetId, analysisId) =>
+      rq<unknown | null>('getForecast', { datasetId, analysisId }),
+
+    getDrivers: (datasetId, analysisId) =>
+      rq<unknown[]>('getDrivers', { datasetId, analysisId }),
+
+    getPerformanceData: (datasetId, analysisId) =>
+      rq<MiniAppPerformanceBundle>('getPerformanceData', {
+        datasetId,
+        analysisId,
+      }),
+
+    getDriversComparisonData: (datasetId, analysisId) =>
+      rq<MiniAppDriversComparisonSnapshot>('getDriversComparisonData', {
+        datasetId,
+        analysisId,
+      }),
+  };
+}

package/src/mini-app/miniAppDataTypes.ts

@@ -0,0 +1,42 @@
+/**
+ * Serializable shapes returned by the shell for mini-app data getters.
+ * Subset of Sybilion `Dataset` / API types — use `unknown` where payloads are large or evolving.
+ */
+
+export type MiniAppDataset = {
+  id: number;
+  user_id?: number;
+  name: string;
+  description?: string;
+  status: string;
+  created_at: string;
+  updated_at: string;
+  keywords: string;
+  category: { id: number; name: string };
+  target_type_id: number;
+  target_type: { id: number; name: string };
+  trend: number;
+  regular_price: string;
+  sale_price: string;
+  regions: { id: number; name: string }[];
+  unit: { id: number; name: string };
+  version?: number;
+};
+
+/** `forecastData` slice: analysis id (string) → forecast series blob. */
+export type MiniAppForecastMap = Record<string, unknown>;
+
+export type MiniAppPerformanceBundle = {
+  /** Cached Performance-tab API payload, or null if user never opened Performance / cache empty. */
+  table: unknown;
+  /** In-memory spaghetti lines from shell context, or null. */
+  spaghetti: unknown;
+};
+
+export type MiniAppDriversComparisonSnapshot = {
+  byRegion: unknown;
+  byCountry: unknown;
+  byCategory: unknown;
+  byImportance: unknown;
+  driversCount: number | null;
+};

package/src/mini-app/miniAppProtocol.ts

@@ -25,6 +25,42 @@ export type MiniAppMessageThemeSync = {
   payload: ThemeSyncPayload;
 };
 
+export type MiniAppDataOp =
+  | 'getDatasets'
+  | 'getDataset'
+  | 'getForecasts'
+  | 'getForecast'
+  | 'getDrivers'
+  | 'getPerformanceData'
+  | 'getDriversComparisonData';
+
+export type MiniAppDataRequestPayload = {
+  requestId: string;
+  op: MiniAppDataOp;
+  params?: Record<string, number>;
+};
+
+export type MiniAppMessageDataRequest = {
+  channel: typeof MINIAPP_CHANNEL;
+  version: typeof MINIAPP_VERSION;
+  type: 'DATA_REQUEST';
+  payload: MiniAppDataRequestPayload;
+};
+
+export type MiniAppDataResponsePayload = {
+  requestId: string;
+  ok: boolean;
+  result?: unknown;
+  error?: string;
+};
+
+export type MiniAppMessageDataResponse = {
+  channel: typeof MINIAPP_CHANNEL;
+  version: typeof MINIAPP_VERSION;
+  type: 'DATA_RESPONSE';
+  payload: MiniAppDataResponsePayload;
+};
+
 function isRecord(v: unknown): v is Record<string, unknown> {
   return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
@@ -77,3 +113,52 @@ export function applyThemeToDocument(mode: 'light' | 'dark'): void {
   root.classList.remove('light', 'dark');
   root.classList.add(mode);
 }
+
+/** Only accept shell messages that appear to come from the real embedding parent. */
+export function isTrustedMiniAppParentMessage(event: MessageEvent): boolean {
+  if (event.source !== window.parent) return false;
+  const fromReferrer = resolveParentOriginFromReferrer();
+  if (fromReferrer && event.origin !== fromReferrer) return false;
+  return true;
+}
+
+export function buildDataRequestMessage(
+  payload: MiniAppDataRequestPayload,
+): MiniAppMessageDataRequest {
+  return {
+    channel: MINIAPP_CHANNEL,
+    version: MINIAPP_VERSION,
+    type: 'DATA_REQUEST',
+    payload,
+  };
+}
+
+/** Parse parent → child DATA_RESPONSE. */
+export function parseDataResponseMessage(
+  data: unknown,
+): MiniAppDataResponsePayload | null {
+  if (!isRecord(data)) return null;
+  if (data.channel !== MINIAPP_CHANNEL) return null;
+  if (data.version !== MINIAPP_VERSION) return null;
+  if (data.type !== 'DATA_RESPONSE') return null;
+  const payload = data.payload;
+  if (!isRecord(payload)) return null;
+  const requestId = payload.requestId;
+  if (typeof requestId !== 'string' || requestId.length === 0) return null;
+  const ok = payload.ok === true;
+  const errOk = payload.ok === false;
+  if (!ok && !errOk) return null;
+
+  const base: MiniAppDataResponsePayload = {
+    requestId,
+    ok,
+  };
+
+  if ('result' in payload) {
+    base.result = payload.result;
+  }
+  if (typeof payload.error === 'string') {
+    base.error = payload.error;
+  }
+  return base;
+}