@jitto/analyze-embed 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,72 @@
+JamLabs Proprietary License
+
+Copyright (c) 2026 JamLabs. All rights reserved.
+
+This software, including its source code, compiled code, documentation, API
+definitions and examples (the "Software"), is the proprietary property of
+JamLabs. It is not open source.
+
+"Redistributable Code" means only the runtime code of the @jitto/analyze-embed package
+as JamLabs publishes it on npm, including copies of it that you have bundled,
+minified, transpiled or tree-shaken while building your application, and the
+changes Section 1 allows. It does not include this repository's other files,
+such as its specifications, API definitions, documentation, examples and
+checks.
+
+1. Permitted use. You may use the Software only if you, or the organisation you
+   work for, have a current written agreement with JamLabs for Jitto (the
+   "Agreement"), and only to embed Jitto in your own applications for the
+   purposes and term that the Agreement allows. You may copy and modify the
+   Software only as far as needed for that integration, and you may build the
+   Redistributable Code into your application with your usual build tools.
+
+2. Restrictions. Unless the Agreement or JamLabs in writing expressly allows it,
+   you may not:
+   a. distribute, publish, sublicense, sell, rent or lend the Software, or make
+      it available to any third party, except that you may deliver the
+      Redistributable Code to your own end users as part of your own
+      application (for example in the JavaScript a browser loads), but not on
+      its own, and not as a library or kit for others to build with;
+   b. use the Software to embed or access any service other than Jitto;
+   c. reverse engineer, decompile or disassemble the Software or the Jitto
+      service, except to the extent applicable law expressly permits it despite
+      this limitation;
+   d. use the Software to build, train or benchmark a product or service that
+      competes with Jitto;
+   e. remove or alter any copyright, licence or proprietary notice.
+
+3. Ownership. JamLabs and its licensors keep all rights, title and interest in
+   the Software. No rights are granted except those stated here.
+
+4. Confidentiality. Parts of the Software that JamLabs has not made public are
+   JamLabs confidential information, and the confidentiality terms of the
+   Agreement apply to them. Parts that JamLabs has made public (the package as
+   published on npm and documentation JamLabs publishes) are not confidential,
+   but this licence still governs their use. Code you deliver to end users
+   under Section 2a is not a breach of confidentiality.
+
+4a. Third-party components. Any third-party component included in the Software,
+   if any, is licensed under its own terms, which are shipped with that
+   component. This licence does not limit the rights those terms grant you in
+   that component.
+
+5. Termination. Your rights under this licence end automatically when the
+   Agreement ends or if you breach this licence. You must then stop using the
+   Software and delete all copies, except copies you must keep by law.
+
+6. No warranty. Except as the Agreement states otherwise, the Software is
+   provided "as is", without warranty of any kind, express or implied, including
+   merchantability, fitness for a particular purpose and non-infringement.
+
+7. Limitation of liability. Except as the Agreement states otherwise, JamLabs is
+   not liable for any indirect, incidental, special or consequential damages, or
+   for loss of profits, revenue or data, arising from the Software. JamLabs'
+   total liability arising from the Software is limited as the Agreement states;
+   if the Agreement sets no limit, it will not exceed the fees you paid JamLabs
+   under the Agreement in the 12 months before the event that gave rise to the
+   claim.
+
+8. Precedence. If this licence and the Agreement conflict, the Agreement
+   prevails.
+
+For licensing questions, contact your JamLabs account contact.

package/README.md

@@ -1,3 +1,325 @@
-# Temporary Holding Version
+# @jitto/analyze-embed
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Show a Jitto dashboard inside your own web app, for your own signed-in users, in React or plain JavaScript.
+Each user sees only the rows Jitto's row rules allow them; your page never holds a Jitto password or secret.
+
+> **Status: 0.2, first public release.** Expect small changes before 1.0.
+>
+> **Not available yet:** `filters`, `setFilters` and the `filterChanged` and `filterRejected` events are specified but not built in
+> this version. The `filters` option is ignored with a console warning, and `setFilters` rejects. Everything else in this
+> README works as described.
+
+## Install
+
+```sh
+npm install @jitto/analyze-embed
+```
+
+One package, two entry points: `@jitto/analyze-embed` (plain JavaScript) and `@jitto/analyze-embed/react` (React).
+Both run on the same core, so the same options give the same events. TypeScript declarations are included.
+
+## Quickstart
+
+1. **Get three things from your Jitto tenant administrator:** your tenant's Jitto host (for example
+   `https://example-tenant.jittocloud.com`; `-uat` and `-dev` hosts for the other environments), the id of the dashboard, and confirmation that your website's origin (for example
+   `https://portal.client.example`) is on the tenant's allowed origins. Origins are exact: `https://`, host, optional
+   port.
+2. **Install:** `npm install @jitto/analyze-embed`.
+3. **Write `fetchToken`** (see [Tokens](#tokens)): it asks Jitto for a dashboard token with the signed-in user's own
+   access token from your sign-in library.
+4. **Mount the dashboard:**
+
+```tsx
+import { JittoDashboard } from '@jitto/analyze-embed/react';
+
+export function DeskOverview() {
+  return (
+    <JittoDashboard
+      dashboardId="3f0c6a52-8d1e-4b7a-9c2f-5e8d71a4b6c0"
+      embedOrigin="https://example-tenant.jittocloud.com"
+      fetchToken={fetchToken} // see Tokens: it sends the user's own access token
+      style={{ height: 600 }}
+    />
+  );
+}
+```
+
+Open the page as a test user. You see that user's rows.
+
+## React: `<JittoDashboard>`
+
+```tsx
+import { useRef } from 'react';
+import { JittoDashboard } from '@jitto/analyze-embed/react';
+import type { JittoDashboardHandle } from '@jitto/analyze-embed';
+
+export function Report() {
+  const dashboard = useRef<JittoDashboardHandle>(null);
+  return (
+    <JittoDashboard
+      ref={dashboard}
+      dashboardId="3f0c6a52-8d1e-4b7a-9c2f-5e8d71a4b6c0"
+      embedOrigin="https://example-tenant.jittocloud.com"
+      fetchToken={fetchToken}
+      theme={{ mode: 'light', colorPrimary: '#0b7a75' }}
+      onLoaded={({ durationMs }) => console.log(`loaded in ${durationMs} ms`)}
+      onFailed={({ reason, message }) => console.warn(reason, message)}
+      onSizeChanged={({ height }) => console.log('content height', height)}
+      className="report"
+    />
+  );
+}
+```
+
+| Prop | Type | Required | What it does |
+|---|---|---|---|
+| `dashboardId` | `string` | yes | The Jitto dashboard id your tenant administrator gave you. |
+| `embedOrigin` | `string` | yes | Your tenant's Jitto host, as an origin (`https://example-tenant.jittocloud.com`). The SDK frames only this origin followed by `/embed` (the API's `embed_url`) and talks only to this origin. It derives no host from anything else. |
+| `fetchToken` | `(dashboardId, signal) => Promise<EmbedTokenResponse>` | yes | Gets a dashboard token for the signed-in user with their own access token. See [Tokens](#tokens). |
+| `filters` | `Filters` | no | Filters applied before the first render, by filter name. See [Filters](#filters). **Not available yet in this version.** |
+| `theme` | `ThemeTokens` | no | Colours, font, light or dark. See [Theme](#theme). |
+| `tokenDeadlineMs` | `number` | no | Deadline for one token request. Default `20000`. |
+| `loadDeadlineMs` | `number` | no | How long the frame may stay silent before `failed` fires with reason `network`. Default `30000`. |
+| `retryDelaysMs` | `readonly number[]` | no | Waits before each retry of a retryable token failure (429, 500, 502, deadline, network). Default `[2000, 5000, 15000]`. |
+| `onLoaded` | `(e) => void` | no | The dashboard rendered. See [Events](#events). |
+| `onFailed` | `(e) => void` | no | The dashboard could not load, or stopped working. |
+| `onFilterChanged` | `(e) => void` | no | The filters in effect changed. **Not available yet in this version.** |
+| `onFilterRejected` | `(e) => void` | no | The dashboard refused filters from `setFilters`. Nothing was applied. **Not available yet in this version.** |
+| `onSizeChanged` | `(e) => void` | no | The dashboard's content size changed. |
+| `className` | `string` | no | Class of the container element. |
+| `style` | `Record<string, string \| number>` | no | Style of the container element. Give it a height. |
+| `ref` | `Ref<JittoDashboardHandle>` | no | The same handle `mountJittoDashboard` returns. |
+
+How prop changes apply:
+
+- A change to `dashboardId` or `embedOrigin` remounts the dashboard.
+- `theme` is compared by value. An equal value does nothing, so an inline object is safe. A different value is
+  applied in place, as `setTheme` would. `filters` is not available yet in this version: it is ignored, also when it
+  changes after the mount.
+- Callbacks, the token function and the deadlines are read when used. A new function takes effect from its next use,
+  with no remount.
+
+The component mounts in the browser only. In a server-rendered app, render it on the client.
+
+## Plain JavaScript: `mountJittoDashboard`
+
+```js
+import { mountJittoDashboard } from '@jitto/analyze-embed';
+
+const element = document.getElementById('dashboard');
+if (!element) throw new Error('no #dashboard element on the page');
+
+const dashboard = mountJittoDashboard(element, {
+  dashboardId: '3f0c6a52-8d1e-4b7a-9c2f-5e8d71a4b6c0',
+  embedOrigin: 'https://example-tenant.jittocloud.com',
+  fetchToken,
+  onFailed: ({ reason, message }) => console.warn(reason, message),
+});
+
+const stop = dashboard.on('loaded', ({ durationMs }) => console.log(`loaded in ${durationMs} ms`));
+
+// Later, when your app's own controls change:
+export function useDarkTheme() {
+  dashboard.setTheme({ mode: 'dark' });
+}
+
+// When your page or view goes away:
+export function teardown() {
+  stop();
+  dashboard.unmount();
+}
+```
+
+`mountJittoDashboard(element, options)` takes the same options and callbacks as the React props (except `className`,
+`style` and `ref`) and returns a handle:
+
+| Member | What it does |
+|---|---|
+| `dashboardId` | The dashboard id this mount shows. |
+| `setFilters(filters)` | Replaces the filters your app set. Returns a promise that resolves once the dashboard applied them; then `filterChanged` fires with `source: 'host'`. See [Filters](#filters). **Not available yet in this version.** |
+| `setTheme(theme)` | Replaces the theme tokens in place. The frame does not reload. |
+| `on(event, handler)` | Subscribes to an event. Returns a function that unsubscribes. |
+| `unmount()` | Removes the dashboard and cancels pending token requests and timers. Safe to call twice. |
+
+> Not available yet: in this version `setFilters` always rejects with a plain `Error`, so the outcomes and `FilterError`
+> described below do not occur yet.
+
+The `setFilters` promise always settles. It rejects with a `SetFiltersError` whose `outcome` is:
+
+- `deadline`: the filters were not applied within `loadDeadlineMs`. `failed` fires with reason `network` and the
+  mount ends.
+- `ended`: the mount ended first, or had already ended.
+- `replaced`: a later `setFilters` call came before this one was applied.
+
+If the dashboard refuses a name or a value, `setFilters` rejects with a `FilterError` instead and applies nothing.
+Its `code` is `unknown_filter` or `invalid_filter_value`, `filterNames` lists the refused names and
+`knownFilterNames` lists every filter the dashboard has. `filterRejected` fires with the same error.
+
+## Tokens
+
+Your page asks Jitto for a short-lived dashboard token with the signed-in user's own access token, the one your
+sign-in library already holds. That token is the user's identity: there is no token endpoint on your backend, no
+shared account and no secret, and your code never states who the user is or what they may see.
+
+1. The SDK calls your `fetchToken(dashboardId, signal)` on mount and again at 80 % of the token's lifetime (at most
+   about 24.8 days later, the longest delay a browser timer holds).
+2. Your `fetchToken` sends the user's own access token to Jitto, from the browser:
+
+   ```http
+   POST /api/v1/embed-tokens HTTP/1.1
+   Host: example-tenant.jittocloud.com
+   Origin: https://portal.client.example
+   Authorization: Bearer <the user's own access token>
+   Content-Type: application/json
+
+   {"dashboard_id": "3f0c6a52-8d1e-4b7a-9c2f-5e8d71a4b6c0"}
+   ```
+
+3. Jitto checks the token against your tenant's identity provider (issuer, signature, audience, expiry), reads the
+   user's groups from it, and applies the row rules your tenant administrator stored in Jitto. It checks the `Origin`
+   against your tenant's allowed origins, and answers the browser's CORS preflight only for those origins.
+4. Jitto answers with a dashboard token that lives 5 minutes. The answer has `Cache-Control: no-store`:
+
+   ```json
+   {
+     "token": "<opaque>",
+     "dashboard_id": "3f0c6a52-8d1e-4b7a-9c2f-5e8d71a4b6c0",
+     "embed_url": "https://example-tenant.jittocloud.com/embed",
+     "expires_in": 300
+   }
+   ```
+
+5. Your `fetchToken` hands it to the SDK with the SDK's field names (`dashboardId`, `embedUrl`, `expiresIn`), values
+   unchanged. The SDK checks the answer itself and refuses a wrong one with reason `token`.
+
+On an error Jitto answers with an HTTP status and a problem body (`code`, `correlation_id`), and with `Retry-After`
+on a 429. A token that is expired, for another audience or from another issuer is refused with 401
+`unauthenticated` (reason `token`); a user in no group the row rules read gets 403 `no_group` (reason `permission`).
+Your tenant administrator registers your identity provider with Jitto once.
+
+Your `fetchToken` rejects on an HTTP error with the status and the API's `code`. This exact code is tested against
+401, 403, 422, 429, 502 and malformed answers. `getAccessToken()` is your sign-in library's:
+
+<!-- example: fetchToken -->
+```js
+async function fetchToken(dashboardId, signal) {
+  const r = await fetch('https://example-tenant.jittocloud.com/api/v1/embed-tokens', {
+    method: 'POST',
+    signal,
+    cache: 'no-store',
+    headers: {
+      Authorization: `Bearer ${await getAccessToken()}`, // the signed-in user's own token, from your sign-in library
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ dashboard_id: dashboardId }), // nothing else: Jitto reads who the user is from the token
+  });
+  const body = await r.json().catch(() => null);
+  if (!r.ok) {
+    const retryAfter = Number(r.headers.get('Retry-After'));
+    throw Object.assign(new Error(`token request failed with HTTP ${r.status}`), {
+      status: r.status,
+      code: body?.code,
+      correlationId: body?.correlation_id,
+      retryAfterSeconds: retryAfter > 0 ? retryAfter : undefined,
+    });
+  }
+  if (!body || typeof body !== 'object') return body; // the SDK refuses it with reason `token`
+  const answer = { token: body.token, dashboardId: body.dashboard_id, embedUrl: body.embed_url };
+  if ('expires_in' in body) answer.expiresIn = body.expires_in;
+  return answer; // the SDK checks it and refuses a wrong answer with reason `token`
+}
+```
+
+## Events
+
+Subscribe with the `on…` props or callbacks, or with `handle.on(name, handler)`.
+
+| Event | Callback | Payload | When |
+|---|---|---|---|
+| `loaded` | `onLoaded` | `{ dashboardId, durationMs }` | The dashboard rendered for the first time after a mount. |
+| `failed` | `onFailed` | `{ dashboardId, reason, message, status?, code?, correlationId? }` | The dashboard could not load, a token refresh failed for good, or a `setFilters` reload did not render in time. Fires at most once per mount; the mount is then finished and the SDK shows a short Jitto message in its place. Mount again to retry. |
+| `filterChanged` | `onFilterChanged` | `{ dashboardId, filters, source }` | The filters in effect changed. `source` is `'user'` (the filter bar) or `'host'` (your `setFilters` or `filters`). **Not available yet in this version.** |
+| `filterRejected` | `onFilterRejected` | `{ dashboardId, error }` | The dashboard refused filters from `setFilters`. `error` is the `FilterError` the call rejects with. Nothing was applied and the dashboard was not reloaded. **Not available yet in this version.** |
+| `sizeChanged` | `onSizeChanged` | `{ dashboardId, width, height }` | The dashboard's content size changed. Resize your container to fit if you want no inner scroll bar. |
+
+`reason` is one of `token`, `permission`, `network` and `not_found`.
+
+## Filters
+
+> Not available yet: this section describes the specified behaviour. See the note at the top of this README.
+
+Filters set what the dashboard shows first, by the names its filter bar uses (for example `Currency`, `Report date`).
+
+- Set them on mount with `filters`, and later with `setFilters` (or a new `filters` prop).
+- A value is a string, number or boolean, a list (several values), a date range `{ from, to }` (ISO dates such as
+  `2026-06-30`, or relative forms such as `Last week`), or `null` to clear the filter.
+- **Filters narrow the view. They are not security.** A user can change them in the filter bar. What a user may see
+  is decided only by the row rules in Jitto.
+- Today `setFilters` reloads the dashboard inside the frame. Your page stays mounted and no new token is requested,
+  but the user's own filter-bar changes and scroll position are reset. Set filters on mount when you can.
+
+## Theme
+
+Theme tokens change colours, font and light or dark. Jitto keeps the layout; there is no CSS hook.
+
+| Token | What it changes |
+|---|---|
+| `mode` | `'light'` or `'dark'`. |
+| `colorPrimary` | Buttons, selected states, links. |
+| `colorBackground` | The dashboard's page background. |
+| `colorSurface` | Chart and filter card background. |
+| `colorText` | Body text. |
+| `colorBorder` | Borders and dividers. |
+| `fontFamily` | A CSS `font-family` list. The font must already be loadable by the dashboard host. |
+
+Colours are CSS colour strings (`#1a73e8`, `rgb(…)`). Anything else is ignored with a console warning. `setTheme`
+never reloads the frame.
+
+## Errors and troubleshooting
+
+Every failure arrives as one `failed` event with one of four reasons. `status`, `code` and `correlationId` come from
+the API when it answered; quote the `correlationId` when you ask Jitto for help.
+
+| Reason | Common causes | What to do |
+|---|---|---|
+| `token` | The user's token was refused (401 `unauthenticated`: expired, wrong audience, wrong issuer); too many token requests (429 `rate_limited`, retried first); no token within `tokenDeadlineMs`; an answer for another dashboard or with an `embedUrl` that is not your `embedOrigin` followed by `/embed`. | Check the user is signed in and your sign-in library returns a current token. Check `embedOrigin`. Request a token once per page view and let the SDK refresh. |
+| `permission` | The dashboard is not on your tenant's embeddable list (403 `not_embeddable`); your origin is not allowed (403 `origin_not_allowed`); the user is in no group the row rules read (403 `no_group`); a dataset of the dashboard has no row rule (422 `row_rules_incomplete`); embedding is not switched on (503 `embedding_not_configured`). | Ask your tenant administrator to fix the setting the `code` names. |
+| `not_found` | No dashboard with this id (404 `unknown_dashboard`). | Check `dashboardId`. |
+| `network` | No answer, a server error (500, 502, retried first), a refused CORS preflight, or the frame stayed silent for `loadDeadlineMs`. A CORS error on the token request, or a `frame-ancestors` error, in the browser console means the page's origin is not allowed. | Check the network. For a CORS or `frame-ancestors` error, ask for your origin to be added exactly as the browser shows it (`localhost` and `127.0.0.1` differ, and so do ports). |
+
+Other symptoms:
+
+| You see | Cause | Fix |
+|---|---|---|
+| The dashboard loads with no rows | The user's groups match no row rule | Ask your tenant administrator which groups the row rules read. |
+| A blank area with no error | The container has no height | Give the container (`style` or `className`) a height. |
+| Your own CSP blocks the frame or the token request | Your `frame-src` or `connect-src` does not allow your tenant's Jitto host | Add your `embedOrigin` (for example `https://example-tenant.jittocloud.com`) to both `frame-src` and `connect-src`. |
+
+## Supported browsers and frameworks
+
+Proposed for 1.0.0; the end-to-end tests confirm the list before release.
+
+- **Browsers:** the current and previous major versions of Chrome, Edge, Firefox and Safari.
+  Pages must be served over `https://`, including local development (for example `https://localhost:5173`).
+- **React:** 18 and 19, through `@jitto/analyze-embed/react`.
+- **Everything else** (Angular, Vue, server-rendered pages, no framework): use `mountJittoDashboard` from
+  `@jitto/analyze-embed`. Dedicated wrappers may follow on the same core.
+- **TypeScript:** declarations are included. Every option, event and payload is typed.
+
+## Versioning
+
+- The package follows [semantic versioning](https://semver.org). A breaking change to an option, event, payload or
+  failure reason is a new major version.
+- The package's major version matches the embed API's path version: `@jitto/analyze-embed` 1.x talks to
+  `/api/v1/` only. Additive API changes stay in v1.
+- A deprecated API version answers with `Deprecation`, `Sunset` and `Link` headers for at least 90 days before it is
+  removed.
+
+## Full guide and API reference
+
+- [Embedding guide](../docs/embedding-guide.md): the whole flow, the tenant administrator's settings, and a security
+  checklist.
+- [API reference](../docs/api/index.html), generated from the OpenAPI 3.1 contract
+  ([`openapi/embed.yaml`](../openapi/embed.yaml)).
+
+Both move to the Jitto docs site before 1.0.0, and these links then point there.

package/dist/core/embed-target.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Which `embedUrl` the SDK may frame and send a token to: only the tenant's embed host. The answer comes from
+ * Jitto (`embed_url`); the only thing the SDK compares it with is the host app's own `embedOrigin`. No host pattern
+ * lives here: no tenant name is turned into a host, and no Jitto domain is named.
+ */
+/** True when `value` is a bare `https` origin in canonical form: `https://host[:port]`, nothing else. */
+export declare function isCanonicalHttpsOrigin(value: string): boolean;
+/**
+ * True only when `embedUrl` is exactly `embedOrigin` followed by `/embed`: same scheme, host and port, no user or
+ * password, the path exactly `/embed`, no query, no fragment. False for every other value, and for an `embedOrigin`
+ * that is not a canonical `https` origin.
+ */
+export declare function isExpectedEmbedTarget(embedUrl: string, embedOrigin: string): boolean;

package/dist/core/embed-target.js

@@ -0,0 +1,35 @@
+/**
+ * Which `embedUrl` the SDK may frame and send a token to: only the tenant's embed host. The answer comes from
+ * Jitto (`embed_url`); the only thing the SDK compares it with is the host app's own `embedOrigin`. No host pattern
+ * lives here: no tenant name is turned into a host, and no Jitto domain is named.
+ */
+/** True when `value` is a bare `https` origin in canonical form: `https://host[:port]`, nothing else. */
+export function isCanonicalHttpsOrigin(value) {
+    let u;
+    try {
+        u = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    return u.protocol === 'https:' && u.origin === value && u.username === '' && u.password === '';
+}
+/**
+ * True only when `embedUrl` is exactly `embedOrigin` followed by `/embed`: same scheme, host and port, no user or
+ * password, the path exactly `/embed`, no query, no fragment. False for every other value, and for an `embedOrigin`
+ * that is not a canonical `https` origin.
+ */
+export function isExpectedEmbedTarget(embedUrl, embedOrigin) {
+    if (!isCanonicalHttpsOrigin(embedOrigin))
+        return false;
+    if (embedUrl !== `${embedOrigin}/embed`)
+        return false;
+    let u;
+    try {
+        u = new URL(embedUrl);
+    }
+    catch {
+        return false;
+    }
+    return u.origin === embedOrigin && u.pathname === '/embed' && u.search === '' && u.hash === '' && u.username === '' && u.password === '';
+}

package/dist/core/frame.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The dashboard frame and its message channel. The core speaks the frame's protocol with Jitto's own code; no
+ * third-party embedding library is bundled. The frame is `embedUrl` + `/dashboard/<id>` on the tenant's
+ * own host. The SDK opens one `MessageChannel` to it, posted only to `embedOrigin`, and from then on talks over that
+ * private port: it hands the frame each token, and asks it for its size. Nothing else on the page can read or
+ * write that channel.
+ */
+export interface FrameSize {
+    width: number;
+    height: number;
+}
+export declare class DashboardFrame {
+    readonly iframe: HTMLIFrameElement;
+    private port;
+    private pending;
+    private nextId;
+    private connected;
+    constructor(container: HTMLElement, embedUrl: string, dashboardId: string, embedOrigin: string);
+    private onMessage;
+    private send;
+    /** Hand the frame a token: the first, or a refreshed one. */
+    giveToken(token: string): Promise<void>;
+    /** The frame's content size, or `undefined` when it does not answer within `timeoutMs`. */
+    size(timeoutMs: number): Promise<FrameSize | undefined>;
+    /** Apply theme tokens in place. Best effort: a frame that cannot apply them keeps its look. */
+    applyTheme(theme: Record<string, string>, mode: 'light' | 'dark' | undefined): Promise<void>;
+    remove(): void;
+}

package/dist/core/frame.js

@@ -0,0 +1,93 @@
+/**
+ * The dashboard frame and its message channel. The core speaks the frame's protocol with Jitto's own code; no
+ * third-party embedding library is bundled. The frame is `embedUrl` + `/dashboard/<id>` on the tenant's
+ * own host. The SDK opens one `MessageChannel` to it, posted only to `embedOrigin`, and from then on talks over that
+ * private port: it hands the frame each token, and asks it for its size. Nothing else on the page can read or
+ * write that channel.
+ */
+const HANDSHAKE = { type: '__embedded_comms__', handshake: 'port transfer' };
+/** The frame's display options: Jitto's choice, not the host's (the host keeps its own title). */
+const FRAME_QUERY = 'uiConfig=1&show_filters=1&expand_filters=0';
+export class DashboardFrame {
+    iframe;
+    port = null;
+    pending = new Map();
+    nextId = 0;
+    connected;
+    constructor(container, embedUrl, dashboardId, embedOrigin) {
+        const iframe = document.createElement('iframe');
+        iframe.src = `${embedUrl}/dashboard/${encodeURIComponent(dashboardId)}?${FRAME_QUERY}`;
+        iframe.title = 'Dashboard';
+        iframe.style.width = '100%';
+        iframe.style.height = '100%';
+        iframe.style.border = '0';
+        iframe.setAttribute('referrerpolicy', 'strict-origin-when-cross-origin');
+        this.iframe = iframe;
+        this.connected = new Promise((resolve) => {
+            iframe.addEventListener('load', () => {
+                const channel = new MessageChannel();
+                this.port = channel.port1;
+                this.port.addEventListener('message', (event) => this.onMessage(event.data));
+                this.port.start();
+                // Posted to the tenant's origin only: a frame that ended up anywhere else never gets the port.
+                iframe.contentWindow?.postMessage(HANDSHAKE, embedOrigin, [channel.port2]);
+                resolve();
+            }, { once: true });
+        });
+        container.appendChild(iframe);
+    }
+    onMessage(data) {
+        if (!data || typeof data !== 'object' || typeof data.messageId !== 'string')
+            return;
+        const settle = this.pending.get(data.messageId);
+        if (!settle)
+            return;
+        this.pending.delete(data.messageId);
+        settle(data.switchboardAction === 'reply' ? data.result : undefined);
+    }
+    send(message) {
+        this.port?.postMessage(message);
+    }
+    /** Hand the frame a token: the first, or a refreshed one. */
+    async giveToken(token) {
+        await this.connected;
+        this.send({ switchboardAction: 'emit', method: 'guestToken', args: { guestToken: token } });
+    }
+    /** The frame's content size, or `undefined` when it does not answer within `timeoutMs`. */
+    async size(timeoutMs) {
+        await this.connected;
+        const messageId = `jitto-${(this.nextId += 1)}`;
+        const answer = new Promise((resolve) => {
+            this.pending.set(messageId, resolve);
+            setTimeout(() => {
+                if (this.pending.delete(messageId))
+                    resolve(undefined);
+            }, timeoutMs);
+        });
+        this.send({ switchboardAction: 'get', method: 'getScrollSize', messageId, args: {} });
+        const result = (await answer);
+        const { width, height } = result ?? {};
+        const valid = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0;
+        if (!valid(width) || !valid(height))
+            return undefined;
+        return { width, height };
+    }
+    /** Apply theme tokens in place. Best effort: a frame that cannot apply them keeps its look. */
+    async applyTheme(theme, mode) {
+        await this.connected;
+        if (Object.keys(theme).length > 0) {
+            this.send({ switchboardAction: 'emit', method: 'setThemeConfig', args: { themeConfig: { token: theme } } });
+        }
+        if (mode) {
+            this.send({ switchboardAction: 'emit', method: 'setThemeMode', args: { mode: mode === 'dark' ? 'dark' : 'default' } });
+        }
+    }
+    remove() {
+        for (const settle of this.pending.values())
+            settle(undefined);
+        this.pending.clear();
+        this.port?.close();
+        this.port = null;
+        this.iframe.remove();
+    }
+}

package/dist/core/mount.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `mountJittoDashboard`: the plain JavaScript embed, on which the React wrapper sits. One package gives a React and a
+ * plain-JavaScript embed on one core.
+ *
+ * Not yet in this version: `setFilters` and the `filters` option. The dashboard's filters cannot yet be set by name
+ * from outside its frame; `setFilters` rejects and `filters` is ignored with a console warning. `setTheme` is
+ * applied in place, best effort.
+ */
+import type { MountJittoDashboard } from '../types.ts';
+export declare const mountJittoDashboard: MountJittoDashboard;