Embedded Runtime Provider -- Public API Reference

Public API surface of @picsart/runtime/providers/react/embedded.

Entry point: src/providers/react/embedded/index.ts

Overview

The embedded runtime provider ships a miniapp as a standalone SPA. Runtime and miniapp code are co-bundled, deployed together, and boot synchronously -- no manifest fetch, no iframe, no async loading.

All adapter configuration (auth, pulse, intl, design system, monetization, cookie consent) is autoconfigured internally. The consumer provides only miniapp identity, a starter function, and optional overrides.

Quick Start

import {
  EmbeddedRuntimeProvider,
  useEmbeddedRuntimeState,
} from '@picsart/runtime/providers/react/embedded';
import { starter } from './my-miniapp-starter';

const App = () => (
  <EmbeddedRuntimeProvider
    miniapp={{ packageId: 'com.picsart.my-miniapp', appVersion: '1.0.0' }}
    starter={starter}
    hostName="my-standalone-app"
    defaultContext={{ theme: 'dark', language: 'en' }}
  >
    <StatusIndicator />
  </EmbeddedRuntimeProvider>
);

const StatusIndicator = () => {
  const state = useEmbeddedRuntimeState();
  if (state.isLoading) return <div>Loading...</div>;
  if (state.error) return <div>Error: {state.error.message}</div>;
  return null;
};

Exports

Components

Export	Kind
EmbeddedRuntimeProvider	React component

Hooks

Export	Returns
useEmbeddedRuntimeState	IRuntimePublicState
useEmbeddedHostControls	IEmbeddedHostControls

Types

Export	Kind
IEmbeddedRuntimeProviderProps	Component props
IEmbeddedMiniappDescriptor	Miniapp identity
EmbeddedTemplate	Template union
ICustomEventPayload	Custom event shape
IRedirectToPackageIdParams	Re-export from SDK
ModuleFactory	Re-export from SDK
IEmbeddedHostControls	Host control methods (3 setters)
IRuntimePublicState	State shape

---

Component: EmbeddedRuntimeProvider

Single React component that wraps FullRuntimeProviders + the SDK's EmbeddedMiniapp into a synchronous co-bundled host.

Props (8 total)

Prop	Type	Required	Default	Description
miniapp	IEmbeddedMiniappDescriptor	yes	--	Miniapp identity (packageId, appVersion). Padded into full IMiniapp internally.
starter	ModuleFactory	yes	--	The miniapp's bundled starter function. Co-bundled at build time.
hostName	string	no	"picsart.com"	Host identifier used in analytics headers and Pulse tracking.
renderingEngine	IRenderingEngine	no	headless	Rendering engine adapter. Web-layering only imported when explicitly provided.
defaultContext	Partial<IRuntimePublicState["context"]>	no	--	Initial context values. Accepts theme, language, sharedStorage, user, credits, subscription, headers. Host-provided headers are merged with runtime auth headers (runtime wins).
template	EmbeddedTemplate	no	--	Host-level page template. "landing" or "create". Enables HTML attribute bridge.
onCustomEvent	(payload: ICustomEventPayload) => unknown	no	--	Callback for custom events the runtime does not handle internally.
onRedirectToPackageId	(params: IRedirectToPackageIdParams) => void	no	URL navigation	Override for miniapp-to-miniapp redirect. Default navigates to https://{host}/apps?mapp={packageId}&version={appVersion}&experience={experience}.
children	ReactNode	no	--	Host UI rendered alongside the embedded miniapp.

Autoconfigured Internally (not exposed as props)

Adapter	Configuration
intl	Language from defaultContext.language, auth headers from internal auth service
authentication	disableGoogleInit: true, disableRefreshCycle: true, isDark synced from theme
pulse	{ app: hostName }
designSystem	Sensible defaults
monetization	Always enabled (built-in path, env var defaults)
cookieConsent	Uses miniapp.packageId as GTM module ID
noNetwork	Always enabled, status exposed via IRuntimePublicState.noNetwork
permissions	All read+write (backend permissions API pending)
fetchOverride	Always on when REACT_APP_X_APP_AUTHORIZATION_TOKEN is set
errorReporting	Errors reported to Bugsnag via growth-rc's errorLogger.trigger()

---

Hook: useEmbeddedRuntimeState

const state: IRuntimePublicState = useEmbeddedRuntimeState();

Returns the current IRuntimePublicState from the enclosing EmbeddedRuntimeProvider. Uses useSyncExternalStore internally -- re-renders on every state field change.

Throws when called outside EmbeddedRuntimeProvider.

Return Shape: IRuntimePublicState

Field	Type	Description
isLoading	boolean	Whether the miniapp is currently being loaded. Starts true.
isBootstrapped	boolean	Whether at least one miniapp has successfully bootstrapped.
error	Error | null	The most recent error from load/bootstrap, or null.
noNetwork	boolean	Whether the device is offline. Initialized from navigator.onLine.
context.theme	string	Current theme. Defaults to defaultContext.theme or "light".
context.language	string	Current language code. Defaults to defaultContext.language or "en".
context.user	IContextUser | null	Current user identity. null when unauthenticated.
context.credits	ICreditsState | null	Current credits balance. null until fetched.
context.subscription	IUserSubscription | null	Current subscription details. null until fetched.
context.sharedStorage	string	Current shared storage value. Defaults to "".
context.headers	Record<string, string>	Merged headers: host-provided defaults + runtime auth headers (runtime wins). Defaults to {}.

---

Hook: useEmbeddedHostControls

const controls: IEmbeddedHostControls = useEmbeddedHostControls();

Returns host-side control methods for mutating the embedded runtime's context store. All setter signatures use SDK types from @picsart/miniapp-sdk-types (matching ITransferContext).

Throws when called outside EmbeddedRuntimeProvider.

Return Shape: IEmbeddedHostControls (3 setters)

Method	Signature
setTheme	(theme: Theme) => void
setLanguage	(language: LanguageCodes) => void
setSharedStorage	(storage: string) => void

Every setter writes to the public state store via context module lenses. Changes propagate to miniapp observers and are readable via useEmbeddedRuntimeState().

Runtime-managed fields (user, credits, subscription, headers, location, settings) are not exposed as host controls — they flow from service providers or are handled internally. Headers can be enhanced via defaultContext.headers on EmbeddedRuntimeProvider.

---

Types

IEmbeddedMiniappDescriptor

interface IEmbeddedMiniappDescriptor {
  packageId: string;  // Unique package identifier
  appVersion: string; // Semantic version string
}

name is omitted -- it is a dead field in embedded mode (SDK never reads it). buildMiniappDescriptor pads name with packageId.

EmbeddedTemplate

type EmbeddedTemplate = "landing" | "create";

ICustomEventPayload

interface ICustomEventPayload {
  event: string;
  data?: Record<string, unknown>;
  screen?: string;
}

IRedirectToPackageIdParams

Re-exported from @picsart/miniapps-platform-sdk/types. Fields: packageId, miniapp (full IMiniapp), redirectionURI.

ModuleFactory

Re-exported from @picsart/miniapps-platform-sdk/utils/loadRemote/types. The function type returned by a miniapp's bundled entry point.

---

Internal Behavior

Fetch Override (always on)

When REACT_APP_X_APP_AUTHORIZATION_TOKEN is set, a global fetch interceptor injects x-app-authorization, Authorization (from auth service), x-touchpoint (packageId), and platform: "website". Only requests to api.picsart.com and api-stage.picsartstage2.com are intercepted.

Error Reporting (Bugsnag)

Errors from miniapp loading and bootstrap are reported via errorLogger.trigger() from @picsart/growth-rc/services/errorLogger. React render errors are caught by ErrorBoundaryWrapper.

Redirect (URL navigation)

When a miniapp calls redirectToPackageId, the default handler navigates to https://{host}/apps?mapp={packageId}&version={appVersion}&experience={experience}. Host detects production vs staging from window.location.hostname. The onRedirectToPackageId prop can override this for custom handling.

Custom Event Routing

Three events are handled internally:

Miniapp Event	Action
OpenRegistrationScreen	showLogin() from LoginModalContext
OpenOfferScreen	openCheckout(options) from MonetizationModalContext
OpenCreditsInfo	openCheckout(options) from MonetizationModalContext

Unknown events are forwarded to onCustomEvent.

HTML Attribute Bridge (template mode only)

Two-way sync between DOM attributes and context stores. DOM to runtime via MutationObserver on <html class> and <html dir>. Runtime to DOM via store subscription updating classList and RC's setLocale.

Observer Wiring

On bootstrap, 8 observers connect context modules to miniapp setters and update IRuntimePublicState accordingly.