Web Integration

The web entry point contains helpers for a browser-based miniapp surface. It does not expose a general host transport.

import {
  app,
  applyMiniAppTheme,
  getMiniAppThemeFromSearch,
  installMiniAppThemeSync,
  openEditorProject,
} from '@theaiplatform/miniapp-sdk/web';

app is an alias for the same scoped API exported as sdk. Prefer sdk in shared target code and use app where the web-oriented name makes a component clearer.

Host Frame Actions

openEditorProject requests the host-owned embedded editor for a conversation:

await openEditorProject({
  conversationId,
  projectId,
  mode: 'embedded',
  files: [
    {
      path: 'src/index.ts',
      selection: { line: 12, column: 1 },
    },
  ],
});

The helper binds the request to the current verified frame and exact host origin. It rejects if the frame identity or host is unavailable, the request times out, or the capability is denied. Do not reproduce this behavior with window.parent.postMessage.

Theme Synchronization

Read and apply the initial theme:

const theme = getMiniAppThemeFromSearch();
applyMiniAppTheme(theme);

For ongoing updates, install the managed listener and retain its cleanup function:

const uninstallThemeSync = installMiniAppThemeSync();

// During surface cleanup:
uninstallThemeSync();

applyMiniAppTheme sets data-app-theme, the matching light or dark class, and color-scheme on the document root. You can provide a custom applyTheme callback when your design system uses another theme adapter.

Compatibility Access

getPlatform returns the same narrow miniapp API for code migrating from the earlier web helper. It never exposes the host's internal platform provider.

Use platformSatisfiesApp only to check documented optional capability names. Unknown capabilities return false.

New code should normally import sdk or app directly and feature-detect optional methods at the point of use.

Specialist Events

The web entry point provides SpecialistEvent, SpecialistTurnCompletedEvent, and SpecialistTurnErrorEvent types for handling supported turn completion and error notifications. Validate IDs against the channel and specialist your surface is tracking before applying an event.