#Web API

Import browser-only helpers from @theaiplatform/miniapp-sdk/web. Use this entry point only in a webview target because editor and theme helpers depend on browser APIs.

#Platform Compatibility

app is a browser-oriented alias for the public sdk export. getPlatform returns that same lazy proxy as MiniAppPlatform, which is an alias of MiniAppPlatformApi.

import {
  getPlatform,
  platformSatisfiesApp,
} from '@theaiplatform/miniapp-sdk/web';

const platform = getPlatform();
const canOpenEditor = platformSatisfiesApp(platform, ['editorView']);

platformSatisfiesApp recognizes the public editorView and hostHttpRequest feature names. Unknown requirements fail closed. Prefer importing sdk from /sdk in shared target code; the web names are useful when all code in a module is browser-only.

#Open a Project in the Editor

openEditorProject accepts OpenEditorProjectOptions. It sends an authenticated request from the exact miniapp frame to its parent host and resolves after the host accepts the action.

import { openEditorProject } from '@theaiplatform/miniapp-sdk/web';

await openEditorProject({
  conversationId,
  projectId,
  mode: 'embedded',
  files: [{ path: 'README.md', selection: { line: 1, column: 1 } }],
});

The call rejects when the frame identity, document identity, host origin, host authority, input, or response is unavailable. Handle the error in the surface without retrying indefinitely.

#Specialist Events

SpecialistEvent is the union of SpecialistTurnCompletedEvent and SpecialistTurnErrorEvent. Use its type discriminator before reading outcome-specific fields.

function handleSpecialistEvent(event: SpecialistEvent) {
  if (event.type === 'turnCompleted') {
    renderParts(event.parts ?? []);
  } else {
    renderError(event.error ?? 'The specialist turn failed.');
  }
}

These are event payload types, not subscriptions. Receive them through the event source provided by your surface or contribution contract.

#Appearance Synchronization

MiniAppTheme is either light or dark. getMiniAppThemeFromSearch reads the initial theme from a query string or URLSearchParams, while applyMiniAppTheme writes it to the current document.

installMiniAppThemeSync accepts InstallMiniAppThemeSyncOptions, applies the initial theme, listens for supported host theme events, and returns a cleanup function.

import { installMiniAppThemeSync } from '@theaiplatform/miniapp-sdk/web';

const stopThemeSync = installMiniAppThemeSync();

export function unmount() {
  stopThemeSync();
}

Live theme messages are accepted only from the exact parent window and concrete host origin selected for the frame. If no exact origin is available, the initial query-string theme is still applied but no listener is installed. Theme data is cosmetic: it never conveys host authority, identity, permission, or trusted application state.

Call the returned cleanup function during every unmount. An unsupported theme value is ignored; browser-less calls return a no-op cleanup function.

UI component consumers should use installMiniAppAppearanceSync. It preserves the theme behavior and also applies the host's bounded appUiScale as --app-font-size on the document root. Valid UI scales are integers from MINIAPP_UI_SCALE_MIN through MINIAPP_UI_SCALE_MAX; missing or invalid input uses MINIAPP_UI_SCALE_DEFAULT.

import { installMiniAppAppearanceSync } from '@theaiplatform/miniapp-sdk/web';

const stopAppearanceSync = installMiniAppAppearanceSync();

installMiniAppThemeSync remains available for miniapps that need only theme synchronization.

#Public Export Contract