@handofclient/embed-js 0.0.0-stage → 0.1.0

package/dist/host/index.js

@@ -0,0 +1,133 @@
+import { createHocClient } from "@handofclient/api";
+import { PostMessageChannel } from "../channel.js";
+import { MessageType, } from "../protocol.js";
+import { defaultUiHandler } from "./defaultUi.js";
+import { encodePackageId } from "./packageIdEncoding.js";
+import { ReadyWatchdog } from "./watchdog.js";
+export class HocMountError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "HocMountError";
+    }
+}
+let config = null;
+export function configure(next) {
+    config = next;
+}
+function requireConfig() {
+    if (!config)
+        throw new Error("HandOfClient.configure({ apiBaseUrl, embedOrigin }) must be called before mount().");
+    return config;
+}
+const DEFAULT_READY_TIMEOUT_MS = 15_000;
+export async function mount(container, options) {
+    const { apiBaseUrl, embedOrigin } = requireConfig();
+    let tokenResponse;
+    try {
+        const response = await fetch(options.tokenUrl, { credentials: "same-origin" });
+        if (!response.ok)
+            throw new Error(`tokenUrl responded ${response.status}`);
+        tokenResponse = (await response.json());
+    }
+    catch (cause) {
+        throw new HocMountError("token-fetch-failed", `Failed to fetch embed token: ${cause.message}`);
+    }
+    const registry = createHocClient({ baseUrl: apiBaseUrl }).packageRegistry;
+    const scope = { hostId: options.hostId, tenantId: options.tenantId, packageId: options.packageId };
+    let activeVersion;
+    try {
+        activeVersion = await registry.getActiveVersion({ scope, slotId: options.slotId });
+    }
+    catch (cause) {
+        throw new HocMountError("no-active-version", `No active version for this tenant/slot: ${cause.message}`);
+    }
+    const version = activeVersion.version.version;
+    const entryPoint = activeVersion.version.manifest.bundle.entryPoints[options.slotId] ?? "index.html";
+    const packageIdB64 = encodePackageId(options.packageId);
+    const iframe = document.createElement("iframe");
+    iframe.title = activeVersion.slot?.title || options.slotId;
+    iframe.sandbox.add("allow-scripts", "allow-same-origin", "allow-forms", "allow-popups");
+    iframe.style.border = "none";
+    iframe.style.width = "100%";
+    // "/embed/" is not decorative - it's BundleEndpoints.cs's actual mapped route
+    // ("/embed/{packageIdB64}/{version}/{**path}"). Found live: docs/postmessage-protocol.md section 4's
+    // ASCII sketch (written assuming the design doc's future per-package-subdomain scheme, where the whole
+    // origin IS the embed server) omits it, and this file originally matched the sketch instead of B7's
+    // real v1 path-based route - every mount() 404'd until this was caught by actually loading a plugin in
+    // a browser. Must stay in sync with B7 until D0/the subdomain scheme lands (see packageIdEncoding.ts).
+    iframe.src = `${embedOrigin}/embed/${packageIdB64}/${version}/${entryPoint}`;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let watchdog = null;
+        const channel = new PostMessageChannel(() => (iframe.contentWindow ? { window: iframe.contentWindow, origin: embedOrigin } : null), (event) => event.source === iframe.contentWindow && event.origin === embedOrigin);
+        const fail = (reason, message) => {
+            if (settled)
+                return;
+            settled = true;
+            watchdog?.cancel();
+            channel.dispose();
+            iframe.remove();
+            const error = new HocMountError(reason, message);
+            options.onError?.(error);
+            reject(error);
+        };
+        const succeed = () => {
+            if (settled)
+                return;
+            settled = true;
+            watchdog?.cancel();
+            resolve({
+                unmount: () => {
+                    channel.dispose();
+                    iframe.remove();
+                },
+                setContext: (update) => channel.send(MessageType.ContextChanged, update),
+                navigate: (path, state) => channel.send(MessageType.Navigate, { path, state }),
+            });
+        };
+        channel.onNotification(MessageType.Hello, (_payload, event) => {
+            const initPayload = {
+                token: tokenResponse.token,
+                tokenExpiresAt: tokenResponse.expiresAt,
+                tenantContext: { hostId: options.hostId, tenantId: options.tenantId, packageId: options.packageId, slotId: options.slotId, version },
+                user: { userId: tokenResponse.userId, displayName: tokenResponse.displayName },
+                theme: options.theme,
+                locale: options.locale,
+                launchParams: options.launchParams ?? {},
+                apiBaseUrl,
+            };
+            channel.send(MessageType.Init, initPayload, event.data.msgId);
+            watchdog = new ReadyWatchdog(options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS, () => fail("timeout", "Plugin did not signal ready/error in time"));
+        });
+        channel.onNotification(MessageType.Ready, succeed);
+        channel.onNotification(MessageType.Error, (payload) => {
+            fail("plugin-error", payload.message);
+        });
+        channel.onNotification(MessageType.Resize, (payload) => {
+            iframe.style.height = `${payload.height}px`;
+        });
+        channel.onNotification(MessageType.Navigate, (payload) => {
+            options.onNavigate?.(payload.path, payload.replace ?? false);
+        });
+        channel.onNotification(MessageType.Telemetry, (payload) => {
+            options.onTelemetry?.(payload);
+        });
+        channel.onRequest(MessageType.Ui, (payload) => (options.onUi ?? defaultUiHandler)(payload));
+        channel.onRequest(MessageType.TokenRefresh, async () => {
+            try {
+                const response = await fetch(options.tokenUrl, { credentials: "same-origin" });
+                if (!response.ok)
+                    throw new Error(`tokenUrl responded ${response.status}`);
+                const refreshed = (await response.json());
+                return { token: refreshed.token, expiresAt: refreshed.expiresAt };
+            }
+            catch (cause) {
+                return { error: `Host session refresh failed: ${cause.message}` };
+            }
+        });
+        iframe.onerror = () => fail("iframe-load-failed", "The plugin iframe failed to load");
+        container.appendChild(iframe);
+    });
+}

package/dist/host/packageIdEncoding.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Mirrors services/platform/HandOfClient.Platform/Bundles/BundleEndpoints.cs's EncodePackageId exactly
+ * - packageId contains a literal "/" (design doc's own example: "acme/wms-labels"), which cannot
+ * survive as a single ASP.NET route segment. Both sides must produce byte-identical output; this is
+ * the one place that requirement is load-bearing (a mismatch here 404s every embed).
+ */
+export declare function encodePackageId(packageId: string): string;

package/dist/host/packageIdEncoding.js

@@ -0,0 +1,13 @@
+/**
+ * Mirrors services/platform/HandOfClient.Platform/Bundles/BundleEndpoints.cs's EncodePackageId exactly
+ * - packageId contains a literal "/" (design doc's own example: "acme/wms-labels"), which cannot
+ * survive as a single ASP.NET route segment. Both sides must produce byte-identical output; this is
+ * the one place that requirement is load-bearing (a mismatch here 404s every embed).
+ */
+export function encodePackageId(packageId) {
+    const bytes = new TextEncoder().encode(packageId);
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/=+$/, "").replace(/\+/g, "-").replace(/\//g, "_");
+}

package/dist/host/watchdog.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Fires exactly once, after `timeoutMs`, unless cancelled first. Deliberately dumb - see
+ * docs/postmessage-protocol.md section 4's "explicit non-heuristic rule": readiness is only ever
+ * decided by an explicit hoc:ready/hoc:error signal or this timeout, never by iframe.onload, a render
+ * count, or a MutationObserver (the false-positive-timeout lesson from DotNetShared.Extensibility's
+ * ExtensionBoundarySettled).
+ */
+export declare class ReadyWatchdog {
+    private timer;
+    constructor(timeoutMs: number, onTimeout: () => void);
+    cancel(): void;
+}

package/dist/host/watchdog.js

@@ -0,0 +1,19 @@
+/**
+ * Fires exactly once, after `timeoutMs`, unless cancelled first. Deliberately dumb - see
+ * docs/postmessage-protocol.md section 4's "explicit non-heuristic rule": readiness is only ever
+ * decided by an explicit hoc:ready/hoc:error signal or this timeout, never by iframe.onload, a render
+ * count, or a MutationObserver (the false-positive-timeout lesson from DotNetShared.Extensibility's
+ * ExtensionBoundarySettled).
+ */
+export class ReadyWatchdog {
+    timer;
+    constructor(timeoutMs, onTimeout) {
+        this.timer = setTimeout(onTimeout, timeoutMs);
+    }
+    cancel() {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+}

package/dist/plugin/index.d.ts

@@ -0,0 +1,87 @@
+import { type HocClient as GeneratedHocClient } from "@handofclient/api";
+import { type ContextChangedPayload, type NavigateHostToPluginPayload, type ThemeTokens, type UiReplyPayload } from "../protocol.js";
+export interface HocContext {
+    hostId: string;
+    tenantId: string;
+    packageId: string;
+    slotId: string;
+    version: string;
+    user: {
+        userId: string;
+        displayName?: string;
+    };
+    theme: ThemeTokens;
+    locale: string;
+    launchParams: Record<string, string>;
+}
+export type UiRequestOptions = {
+    kind: "modal";
+    title?: string;
+    body: string;
+} | {
+    kind: "toast";
+    message: string;
+    durationMs?: number;
+} | {
+    kind: "confirm";
+    title?: string;
+    message: string;
+};
+declare class HocSdk {
+    private channel;
+    private tokenProvider;
+    private _context;
+    private _api;
+    private stopAutoResize;
+    private contextListeners;
+    private navigateListeners;
+    /**
+     * Runs the handshake (docs/postmessage-protocol.md section 4), invokes `callback` with the resolved
+     * context, and signals hoc:ready/hoc:error based on whether it completes without throwing. Must be
+     * called exactly once per iframe load.
+     */
+    init(callback: (context: HocContext) => void | Promise<void>): Promise<void>;
+    get context(): HocContext;
+    /** The six generated Platform API service clients, pre-authed with the current embed token and
+     * auto-refreshing (see HostRelayTokenProvider) - design doc's "hoc.api". */
+    get api(): GeneratedHocClient;
+    private get scope();
+    storage: {
+        get: (key: string) => Promise<import("@handofclient/gen-ts/handofclient/v1/tenant_storage_pb").GetResponse>;
+        set: (key: string, value: Uint8Array<ArrayBuffer>, ifMatchEtag?: string) => Promise<import("@handofclient/gen-ts/handofclient/v1/tenant_storage_pb").SetResponse>;
+        delete: (key: string) => Promise<import("@handofclient/gen-ts/handofclient/v1/tenant_storage_pb").DeleteResponse>;
+        fileExists: (path: string) => Promise<import("@handofclient/gen-ts/handofclient/v1/tenant_storage_pb").FileExistsResponse>;
+    };
+    http: {
+        send: (request: {
+            method: number;
+            url: string;
+            headers?: {
+                name: string;
+                value: string;
+            }[];
+            body?: Uint8Array<ArrayBuffer>;
+            timeoutMs?: number;
+        }) => Promise<import("@handofclient/gen-ts/handofclient/v1/egress_proxy_pb").SendResponse>;
+    };
+    navigate(path: string, replace?: boolean): void;
+    onContextChanged(listener: (update: ContextChangedPayload) => void): () => void;
+    onHostNavigate(listener: (payload: NavigateHostToPluginPayload) => void): () => void;
+    ui: {
+        modal: (body: string, title?: string) => Promise<UiReplyPayload & {
+            closed: true;
+        }>;
+        toast: (message: string, durationMs?: number) => Promise<UiReplyPayload & {
+            shown: true;
+        }>;
+        confirm: (message: string, title?: string) => Promise<boolean>;
+    };
+    private request;
+    /** Coalesces ResizeObserver callbacks to at most one hoc:resize per animation frame - see
+     * docs/postmessage-protocol.md section 5.5. Call once, after the plugin's root element exists. */
+    resizeAuto(rootElement: HTMLElement): void;
+    private performHandshake;
+}
+/** Singleton - one plugin bundle instance runs inside exactly one iframe for exactly one mount. */
+export declare const hoc: HocSdk;
+export {};

package/dist/plugin/index.js

@@ -0,0 +1,131 @@
+import { createHocClient } from "@handofclient/api";
+import { PostMessageChannel } from "../channel.js";
+import { isEnvelope, makeEnvelope, MessageType, } from "../protocol.js";
+import { startAutoResize } from "./resize.js";
+import { HostRelayTokenProvider } from "./tokenProvider.js";
+const SDK_VERSION = "0.1.0";
+class HocSdk {
+    channel = null;
+    tokenProvider = null;
+    _context = null;
+    _api = null;
+    stopAutoResize = null;
+    contextListeners = new Set();
+    navigateListeners = new Set();
+    /**
+     * Runs the handshake (docs/postmessage-protocol.md section 4), invokes `callback` with the resolved
+     * context, and signals hoc:ready/hoc:error based on whether it completes without throwing. Must be
+     * called exactly once per iframe load.
+     */
+    async init(callback) {
+        const { initPayload, trustedOrigin } = await this.performHandshake();
+        this.channel = new PostMessageChannel(() => (this.channel ? { window: window.parent, origin: trustedOrigin } : null), (event) => event.source === window.parent && event.origin === trustedOrigin);
+        // Registered only after the handshake completes and origin is pinned - see
+        // docs/postmessage-protocol.md section 3: no application-visible callback dispatches before init.
+        this.channel.onNotification(MessageType.ContextChanged, (payload) => {
+            for (const listener of this.contextListeners)
+                listener(payload);
+        });
+        this.channel.onNotification(MessageType.Navigate, (payload) => {
+            for (const listener of this.navigateListeners)
+                listener(payload);
+        });
+        this.tokenProvider = new HostRelayTokenProvider(this.channel, initPayload.token, initPayload.tokenExpiresAt);
+        this._api = createHocClient({ baseUrl: initPayload.apiBaseUrl, tokenProvider: this.tokenProvider });
+        this._context = {
+            hostId: initPayload.tenantContext.hostId,
+            tenantId: initPayload.tenantContext.tenantId,
+            packageId: initPayload.tenantContext.packageId,
+            slotId: initPayload.tenantContext.slotId,
+            version: initPayload.tenantContext.version,
+            user: initPayload.user,
+            theme: initPayload.theme,
+            locale: initPayload.locale,
+            launchParams: initPayload.launchParams,
+        };
+        try {
+            await callback(this._context);
+            this.channel.send(MessageType.Ready, {});
+        }
+        catch (cause) {
+            const error = cause instanceof Error ? cause : new Error(String(cause));
+            this.channel.send(MessageType.Error, { message: error.message, stack: error.stack, fatal: true });
+            throw error;
+        }
+    }
+    get context() {
+        if (!this._context)
+            throw new Error("hoc.context accessed before hoc.init(callback) resolved");
+        return this._context;
+    }
+    /** The six generated Platform API service clients, pre-authed with the current embed token and
+     * auto-refreshing (see HostRelayTokenProvider) - design doc's "hoc.api". */
+    get api() {
+        if (!this._api)
+            throw new Error("hoc.api accessed before hoc.init(callback) resolved");
+        return this._api;
+    }
+    get scope() {
+        const context = this.context;
+        return { hostId: context.hostId, tenantId: context.tenantId, packageId: context.packageId };
+    }
+    storage = {
+        get: async (key) => this.api.tenantStorage.get({ scope: this.scope, key }),
+        set: async (key, value, ifMatchEtag) => this.api.tenantStorage.set({ scope: this.scope, key, value, ifMatchEtag }),
+        delete: async (key) => this.api.tenantStorage.delete({ scope: this.scope, key }),
+        fileExists: async (path) => this.api.tenantStorage.fileExists({ scope: this.scope, path }),
+    };
+    http = {
+        send: async (request) => this.api.egressProxy.send({ scope: this.scope, ...request }),
+    };
+    navigate(path, replace = false) {
+        this.channel?.send(MessageType.Navigate, { path, replace });
+    }
+    onContextChanged(listener) {
+        this.contextListeners.add(listener);
+        return () => this.contextListeners.delete(listener);
+    }
+    onHostNavigate(listener) {
+        this.navigateListeners.add(listener);
+        return () => this.navigateListeners.delete(listener);
+    }
+    ui = {
+        modal: (body, title) => this.request({ kind: "modal", options: { title, body } }),
+        toast: (message, durationMs) => this.request({ kind: "toast", options: { message, durationMs } }),
+        confirm: (message, title) => this.request({ kind: "confirm", options: { title, message } }).then((r) => r.confirmed),
+    };
+    request(payload) {
+        if (!this.channel)
+            throw new Error("hoc.ui used before hoc.init(callback) resolved");
+        return this.channel.request(MessageType.Ui, payload);
+    }
+    /** Coalesces ResizeObserver callbacks to at most one hoc:resize per animation frame - see
+     * docs/postmessage-protocol.md section 5.5. Call once, after the plugin's root element exists. */
+    resizeAuto(rootElement) {
+        if (!this.channel)
+            throw new Error("hoc.resizeAuto used before hoc.init(callback) resolved");
+        this.stopAutoResize?.();
+        this.stopAutoResize = startAutoResize(this.channel, rootElement);
+    }
+    performHandshake() {
+        return new Promise((resolve) => {
+            const helloEnvelope = makeEnvelope(MessageType.Hello, { sdkVersion: SDK_VERSION, nonce: crypto.randomUUID() });
+            function onMessage(event) {
+                // Pre-pinning: accept only from window.parent, and dispatch only for the specific hoc:init
+                // that answers *this* hello - see docs/postmessage-protocol.md section 3.
+                if (event.source !== window.parent)
+                    return;
+                if (!isEnvelope(event.data) || event.data.type !== MessageType.Init || event.data.replyTo !== helloEnvelope.msgId)
+                    return;
+                window.removeEventListener("message", onMessage);
+                resolve({ initPayload: event.data.payload, trustedOrigin: event.origin });
+            }
+            window.addEventListener("message", onMessage);
+            // "*" is the one and only legitimate use of a wildcard targetOrigin in this protocol: the plugin
+            // cannot know the host's real origin before this exact reply tells it - see section 3.
+            window.parent.postMessage(helloEnvelope, "*");
+        });
+    }
+}
+/** Singleton - one plugin bundle instance runs inside exactly one iframe for exactly one mount. */
+export const hoc = new HocSdk();

package/dist/plugin/resize.d.ts

@@ -0,0 +1,7 @@
+import { PostMessageChannel } from "../channel.js";
+/**
+ * Observes `element`'s content height and sends hoc:resize, coalesced to at most one message per
+ * animation frame - ResizeObserver can fire many times per frame during a layout thrash, and posting
+ * once per intermediate value is wasteful (see docs/postmessage-protocol.md section 5.5).
+ */
+export declare function startAutoResize(channel: PostMessageChannel, element: HTMLElement): () => void;

package/dist/plugin/resize.js

@@ -0,0 +1,26 @@
+import { MessageType } from "../protocol.js";
+/**
+ * Observes `element`'s content height and sends hoc:resize, coalesced to at most one message per
+ * animation frame - ResizeObserver can fire many times per frame during a layout thrash, and posting
+ * once per intermediate value is wasteful (see docs/postmessage-protocol.md section 5.5).
+ */
+export function startAutoResize(channel, element) {
+    let scheduled = false;
+    let lastHeight = -1;
+    const flush = () => {
+        scheduled = false;
+        const height = Math.ceil(element.getBoundingClientRect().height);
+        if (height === lastHeight)
+            return;
+        lastHeight = height;
+        channel.send(MessageType.Resize, { height });
+    };
+    const observer = new ResizeObserver(() => {
+        if (scheduled)
+            return;
+        scheduled = true;
+        requestAnimationFrame(flush);
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+}

package/dist/plugin/tokenProvider.d.ts

@@ -0,0 +1,23 @@
+import type { TokenProvider } from "@handofclient/api";
+import { PostMessageChannel } from "../channel.js";
+/**
+ * Implements @handofclient/api's TokenProvider by round-tripping hoc:token-refresh through the host
+ * page - see docs/postmessage-protocol.md section 5.7. Two independent triggers land on the same
+ * request: reactively, when the generated client's authInterceptor gets an Unauthenticated response
+ * (refreshToken()), and proactively, on a timer here at 80% of the token's remaining TTL, so a
+ * long-lived plugin session refreshes ahead of expiry instead of always paying a failed-call round
+ * trip first.
+ */
+export declare class HostRelayTokenProvider implements TokenProvider {
+    private readonly channel;
+    private token;
+    private expiresAt;
+    private refreshPromise;
+    private proactiveTimer;
+    constructor(channel: PostMessageChannel, initialToken: string, initialExpiresAt: string);
+    getToken(): Promise<string>;
+    refreshToken(): Promise<string>;
+    dispose(): void;
+    private doRefresh;
+    private scheduleProactiveRefresh;
+}

package/dist/plugin/tokenProvider.js

@@ -0,0 +1,62 @@
+import { MessageType } from "../protocol.js";
+const PROACTIVE_REFRESH_FRACTION = 0.8;
+/**
+ * Implements @handofclient/api's TokenProvider by round-tripping hoc:token-refresh through the host
+ * page - see docs/postmessage-protocol.md section 5.7. Two independent triggers land on the same
+ * request: reactively, when the generated client's authInterceptor gets an Unauthenticated response
+ * (refreshToken()), and proactively, on a timer here at 80% of the token's remaining TTL, so a
+ * long-lived plugin session refreshes ahead of expiry instead of always paying a failed-call round
+ * trip first.
+ */
+export class HostRelayTokenProvider {
+    channel;
+    token;
+    expiresAt;
+    refreshPromise = null;
+    proactiveTimer = null;
+    constructor(channel, initialToken, initialExpiresAt) {
+        this.channel = channel;
+        this.token = initialToken;
+        this.expiresAt = new Date(initialExpiresAt);
+        this.scheduleProactiveRefresh();
+    }
+    async getToken() {
+        return this.token;
+    }
+    async refreshToken() {
+        // Coalesce concurrent refresh calls (e.g. several in-flight requests all hitting 401 at once) into
+        // one hoc:token-refresh round trip rather than racing multiple requests to the host.
+        if (!this.refreshPromise) {
+            this.refreshPromise = this.doRefresh().finally(() => {
+                this.refreshPromise = null;
+            });
+        }
+        return this.refreshPromise;
+    }
+    dispose() {
+        if (this.proactiveTimer !== null)
+            clearTimeout(this.proactiveTimer);
+    }
+    async doRefresh() {
+        const reply = await this.channel.request(MessageType.TokenRefresh, {});
+        if ("error" in reply) {
+            throw new Error(reply.error);
+        }
+        this.token = reply.token;
+        this.expiresAt = new Date(reply.expiresAt);
+        this.scheduleProactiveRefresh();
+        return this.token;
+    }
+    scheduleProactiveRefresh() {
+        if (this.proactiveTimer !== null)
+            clearTimeout(this.proactiveTimer);
+        const remainingMs = this.expiresAt.getTime() - Date.now();
+        const delayMs = Math.max(remainingMs * PROACTIVE_REFRESH_FRACTION, 0);
+        this.proactiveTimer = setTimeout(() => {
+            this.refreshToken().catch(() => {
+                // A proactive refresh failure is not fatal here - the reactive path (authInterceptor retrying
+                // on Unauthenticated) is still there as a fallback for the next real API call.
+            });
+        }, delayMs);
+    }
+}

package/dist/protocol.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Wire types for the postMessage embed protocol - see docs/postmessage-protocol.md (task C1) for the
+ * normative spec. Shared verbatim between the host-side and plugin-side halves of this package so both
+ * sides can never drift on envelope/message shape.
+ */
+export declare const PROTOCOL_VERSION = 1;
+export interface Envelope<TPayload = unknown> {
+    v: 1;
+    type: string;
+    msgId: string;
+    replyTo?: string;
+    payload: TPayload;
+}
+export declare const MessageType: {
+    readonly Hello: "hoc:hello";
+    readonly Init: "hoc:init";
+    readonly Ready: "hoc:ready";
+    readonly Error: "hoc:error";
+    readonly Resize: "hoc:resize";
+    readonly Navigate: "hoc:navigate";
+    readonly TokenRefresh: "hoc:token-refresh";
+    readonly ContextChanged: "hoc:context-changed";
+    readonly Telemetry: "hoc:telemetry";
+    readonly Ui: "hoc:ui";
+};
+export declare function isEnvelope(data: unknown): data is Envelope;
+export declare function makeMsgId(): string;
+export declare function makeEnvelope<T>(type: string, payload: T, replyTo?: string): Envelope<T>;
+export interface ThemeTokens {
+    colorScheme: "light" | "dark";
+    accentColor: string;
+    backgroundColor: string;
+    textColor: string;
+    fontFamily: string;
+    borderRadius: string;
+}
+export interface TenantContext {
+    hostId: string;
+    tenantId: string;
+    packageId: string;
+    slotId: string;
+    version: string;
+}
+export interface HelloPayload {
+    sdkVersion: string;
+    nonce: string;
+}
+export interface InitPayload {
+    token: string;
+    tokenExpiresAt: string;
+    tenantContext: TenantContext;
+    user: {
+        userId: string;
+        displayName?: string;
+    };
+    theme: ThemeTokens;
+    locale: string;
+    launchParams: Record<string, string>;
+    /** Platform API base URL for hoc.api/hoc.storage/hoc.http (see plugin/index.ts) - the host already
+     * knows this from its own HandOfClient.configure() call, so the plugin never has to guess or hardcode
+     * a domain (which would break the moment embed/API origins are split across subdomains - see D0). */
+    apiBaseUrl: string;
+}
+export type ReadyPayload = Record<string, never>;
+export interface ErrorPayload {
+    message: string;
+    stack?: string;
+    fatal: boolean;
+}
+export interface ResizePayload {
+    height: number;
+}
+export interface NavigatePluginToHostPayload {
+    path: string;
+    replace?: boolean;
+}
+export interface NavigateHostToPluginPayload {
+    path: string;
+    state?: unknown;
+}
+export type TokenRefreshRequestPayload = Record<string, never>;
+export type TokenRefreshReplyPayload = {
+    token: string;
+    expiresAt: string;
+} | {
+    error: string;
+};
+export interface ContextChangedPayload {
+    tenantContext?: Partial<TenantContext>;
+    user?: {
+        userId: string;
+        displayName?: string;
+    };
+    theme?: ThemeTokens;
+    locale?: string;
+}
+export interface TelemetryPayload {
+    kind: "timing" | "error";
+    name: string;
+    value?: number;
+    detail?: Record<string, unknown>;
+}
+export type UiRequestPayload = {
+    kind: "modal";
+    options: {
+        title?: string;
+        body: string;
+    };
+} | {
+    kind: "toast";
+    options: {
+        message: string;
+        durationMs?: number;
+    };
+} | {
+    kind: "confirm";
+    options: {
+        title?: string;
+        message: string;
+    };
+};
+export type UiReplyPayload = {
+    closed: true;
+} | {
+    shown: true;
+} | {
+    confirmed: boolean;
+};