@microsoft/power-apps-native-host 0.2.22

package/lib/module/provider/PowerAppsProvider.js

@@ -0,0 +1,345 @@
+"use strict";
+
+/*!
+ * power-apps-native-host — PowerAppsProvider
+ *
+ * A single provider that composes all infrastructure required to run a
+ * Power Apps canvas app inside an Expo shell:
+ *
+ *   GestureHandlerRootView
+ *   └── TamaguiProvider  (defaults to @tamagui/config/v3)
+ *       └── PortalProvider  (required by ToastViewport)
+ *           └── ToastProvider + ToastViewport
+ *               └── QueryClientProvider  (own QueryClient, wired to NetInfo + AppState)
+ *                   └── AuthProvider
+ *                       └── PowerAppsHostProvider  (connected via useAuth)
+ *                           └── children
+ *
+ * Usage:
+ *
+ *   <PowerAppsProvider
+ *     msalConfig={authConfig.msal}
+ *     powerConfig={powerConfig}
+ *     schemaMap={schemaMap}
+ *   >
+ *     <StatusBar style="auto" />
+ *     <Slot />
+ *   </PowerAppsProvider>
+ */
+
+import React, { useCallback, useEffect, useMemo, useRef } from 'react';
+import { AppState, Platform } from 'react-native';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import { createTamagui, TamaguiProvider } from '@tamagui/core';
+import { PortalProvider } from '@tamagui/portal';
+import { config as tamaguiDefaultConfig } from '@tamagui/config/v3';
+import { ToastProvider, ToastViewport } from '@tamagui/toast';
+import { QueryClient, QueryClientProvider, focusManager, onlineManager } from '@tanstack/react-query';
+import NetInfo from '@react-native-community/netinfo';
+import { AuthProvider, useAuth } from "../auth/AuthContext.js";
+import { PowerAppsHostProvider } from "./PowerAppsHostProvider.js";
+import { fetchInstanceUrl } from "../platform/PowerPlatformEnvironmentApi.js";
+import { ThemeProvider } from "../theme/ThemeProvider.js";
+import { ErrorBoundary } from "../ErrorBoundary.js";
+import Constants from 'expo-constants';
+import { configureAppLogger, getAppLogger, Logger, OneDsTelemetryProvider, resolveDeviceId, resolveTelemetryLocation, regionToClusterCategory, suppressKnownWarnings } from '@microsoft/power-apps-native-common';
+suppressKnownWarnings();
+import { useOfflineIntegration } from '@microsoft/power-apps-native-offline';
+
+// ---- React-Query wiring (runs once at module load) ----
+
+// Wire onlineManager to NetInfo so refetchOnReconnect fires on mobile
+// (the default browser-event-based detection is a no-op in React Native).
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+onlineManager.setEventListener(setOnline => {
+  return NetInfo.addEventListener(state => setOnline(!!state.isConnected));
+});
+
+// Wire focusManager to AppState so queries refetch when the app foregrounds.
+focusManager.setEventListener(handleFocus => {
+  const sub = AppState.addEventListener('change', status => {
+    if (Platform.OS !== 'web') handleFocus(status === 'active');
+  });
+  return () => sub.remove();
+});
+
+// ---- Singletons ----
+
+// The app's tamagui.config.ts (generated by /tamagui-design-system) is always
+// passed as the `tamaguiConfig` prop and owns all $surface* / $accent* tokens.
+// The bare @tamagui/config/v3 preset is only a last-resort fallback for tests
+// and storybook — it will not resolve custom $surface* tokens.
+const defaultTamaguiConfig = createTamagui(tamaguiDefaultConfig);
+
+// Whether the offline SDK will actually orchestrate for this app. Mirrors the
+// resolution that @microsoft/power-apps-native-offline's useOfflineIntegration
+// performs (offlineProfile prop → expo manifest `extra.__offlineProfile`;
+// enabled defaults true unless the profile's `appConfig.enabled` is explicitly
+// false), but computed synchronously here because the QueryClient's networkMode
+// must be fixed BEFORE the first query runs. The SDK's own `isEnabled` is only
+// known deep inside the tree (below QueryClientProvider), which is too late to
+// configure the client without a race. Kept deliberately narrow: it only
+// decides networkMode below.
+function isOfflineEnabled(offlineProfile) {
+  // Only honour the prop when it carries a profileId — this mirrors the SDK's
+  // useOfflineIntegration, which ignores a profileId-less prop and falls through
+  // to the manifest. Without this guard a truthy-but-invalid prop (no profileId)
+  // short-circuits to `false` here while the SDK still resolves enabled from the
+  // manifest, leaving networkMode on 'online' (blank offline lists).
+  const propProfile = offlineProfile;
+  let profile = propProfile && propProfile.profileId ? propProfile : undefined;
+  if (!profile) {
+    const fromManifest = Constants.expoConfig?.extra?.__offlineProfile;
+    if (fromManifest && typeof fromManifest === 'object' && fromManifest.profileId) {
+      profile = fromManifest;
+    }
+  }
+  if (profile) {
+    // Honour an explicit `appConfig.enabled: false`. This mirrors the SDK's
+    // useOfflineIntegration, whose validateConfig classifies `enabled === false`
+    // as "explicitly-disabled" and stays inert. A host shell's placeholder
+    // profile (e.g. Power Apps Dev Player's offline-profile.json, enabled:false)
+    // must NOT flip networkMode to 'always' for the loaded app — otherwise every
+    // scanned app gets paused queries / blank lists. Any other resolved profile
+    // (enabled true, or omitted → SDK defaults to true) enables offline.
+    const appConfig = profile.appConfig;
+    if (appConfig && appConfig.enabled === false) {
+      return false;
+    }
+    return true;
+  }
+  return false;
+}
+
+// Builds the app's QueryClient. networkMode is gated on whether offline is
+// actually enabled:
+//   • Offline enabled → 'always': the host is offline-first, so reads/writes are
+//     served by the offline SDK from local SQLite regardless of connectivity.
+//     onlineManager is wired to NetInfo (above) for refetchOnReconnect, but that
+//     same wiring makes the default 'online' mode PAUSE every query/mutation while
+//     offline (queryFn never runs → blank lists with WiFi off). 'always' makes
+//     React Query ignore connectivity for both the initial attempt AND retries, so
+//     local-SQLite reads/writes never get paused. ('offlineFirst' would still pause
+//     *retries* offline — wrong for a purely-local SDK where a transient first
+//     attempt error, e.g. SDK-not-ready at cold boot, would leave the query stuck
+//     'paused' until reconnect.)
+//   • Offline disabled → undefined: React Query keeps its default 'online' mode,
+//     i.e. the exact pre-offline behaviour for online-only apps.
+function createQueryClient(offlineEnabled) {
+  const networkMode = offlineEnabled ? 'always' : undefined;
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60_000,
+        retry: 2,
+        networkMode
+      },
+      mutations: {
+        retry: 0,
+        networkMode
+      }
+    }
+  });
+}
+
+// ---- Types ----
+
+/** Shape of power.config.json consumed by the provider. */
+
+// ---- Inner component ----
+// Separate from PowerAppsProvider only because useAuth() must be called inside
+// AuthProvider. All auth-dependent wiring lives here.
+
+function InnerProviders({
+  msalConfig,
+  powerConfig,
+  schemaMap,
+  renderOAuthWebView,
+  onDisambiguationNeeded,
+  offlineProfile,
+  children
+}) {
+  const {
+    acquireToken,
+    isSignedIn,
+    hasRealAccount
+  } = useAuth();
+  const connectionReferences = useMemo(() => powerConfig.connectionReferences ?? {}, [powerConfig.connectionReferences]);
+
+  // ---- Offline (all logic lives in the SDK) ----
+  // Adapter over the host's fetchInstanceUrl: the offline SDK's contract passes a
+  // 4th `signal?: AbortSignal` arg (which fetchInstanceUrl treats as bearerToken)
+  // and expects a `string | null` return, so drop the extra arg and normalise
+  // `undefined` -> `null`.
+  const resolveInstanceUrlForOffline = useCallback(async (environmentId, region, acqToken, _signal) => {
+    const url = await fetchInstanceUrl(environmentId, region, acqToken);
+    return url ?? null;
+  }, []);
+
+  // Gate offline engagement on a REAL account (`hasRealAccount`), not the
+  // `isSignedIn` flag — `isSignedIn` is inflated by noAuthMode (login-bypassed /
+  // demo sessions report signed-in but have no account, so `acquireToken` always
+  // returns null). Passing the inflated flag makes the SDK orchestrator engage
+  // and then spin in a perpetual "waiting-for-auth" 3s retry loop (each retry
+  // re-renders the provider subtree). With no obtainable token offline cannot
+  // sync anyway, so we only engage once a usable token exists.
+  const offline = useOfflineIntegration({
+    powerConfig,
+    offlineProfile,
+    acquireToken,
+    isSignedIn: hasRealAccount,
+    fetchInstanceUrl: resolveInstanceUrlForOffline
+  });
+  return /*#__PURE__*/_jsxs(PowerAppsHostProvider, {
+    acquireToken: acquireToken,
+    isSignedIn: isSignedIn,
+    appId: powerConfig.appId ?? undefined,
+    environmentId: powerConfig.environmentId ?? '',
+    region: powerConfig.region ?? 'prod',
+    connectionReferences: connectionReferences,
+    schemaMap: schemaMap,
+    databaseReferences: powerConfig.databaseReferences,
+    isvClientId: msalConfig.clientId,
+    renderOAuthWebView: renderOAuthWebView,
+    onDisambiguationNeeded: onDisambiguationNeeded,
+    children: [children, offline.StatusOverlay && /*#__PURE__*/_jsx(offline.StatusOverlay, {})]
+  });
+}
+
+// ---- Public component ----
+
+/**
+ * Top-level provider for Power Apps canvas apps running inside an Expo shell.
+ *
+ * Composes GestureHandlerRootView, TamaguiProvider, ToastProvider,
+ * QueryClientProvider, AuthProvider, and PowerAppsHostProvider into a single
+ * component, eliminating all provider boilerplate from the consuming app's
+ * root layout.
+ */
+export function PowerAppsProvider({
+  msalConfig,
+  intuneConfig,
+  powerConfig,
+  schemaMap,
+  tamaguiConfig = defaultTamaguiConfig,
+  // override with app's tamagui.config.ts
+  defaultTheme = 'light',
+  theme,
+  darkTheme,
+  followSystemTheme = true,
+  renderOAuthWebView,
+  onDisambiguationNeeded,
+  appName,
+  logger: loggerProp,
+  offlineProfile,
+  children
+}) {
+  // Capture the logger-prop identity at mount time so the effect dep array
+  // is stable (loggerProp is an object reference; re-running on every render
+  // would reconfigure and leak the previous provider).
+  const loggerPropRef = useRef(loggerProp);
+
+  // Gate the offline-first networkMode on whether offline is actually enabled
+  // for this app. Keyed on the resolved boolean (not the prop object refs) so the
+  // QueryClient identity stays stable across renders even if the caller passes
+  // fresh offlineProfile literals.
+  const offlineEnabled = useMemo(() => isOfflineEnabled(offlineProfile), [offlineProfile]);
+  const queryClient = useMemo(() => createQueryClient(offlineEnabled), [offlineEnabled]);
+
+  // Configure the app logger exactly once per mount inside useEffect so that
+  // side effects (provider construction, async resolveDeviceId) never run
+  // during the render phase. This is safe because AppLogger.ts starts with a
+  // silent no-op Logger, so any telemetry emitted before the first commit is
+  // silently dropped rather than crashing.
+  useEffect(() => {
+    const lp = loggerPropRef.current;
+    if (lp === null) {
+      // Explicit opt-out — replace with a silent no-op Logger.
+      configureAppLogger(new Logger());
+    } else if (lp !== undefined) {
+      // Caller supplied their own fully-configured logger.
+      configureAppLogger(lp);
+    } else {
+      // Default: auto-wire the 1DS JS adapter so telemetry flows out of the
+      // box without any boilerplate in the consuming app.
+      const providerConfig = {
+        clusterCategory: regionToClusterCategory(powerConfig.region ?? 'dev'),
+        clientType: appName ?? 'PowerAppsNative',
+        appVersion: Constants.expoConfig?.version,
+        minSeverity: __DEV__ ? 'verbose' : 'info',
+        telemetryLocation: resolveTelemetryLocation(powerConfig.geoRegion)
+      };
+      // Resolve the stable device ID first so every event — including the
+      // very first — carries the real GUID rather than the 'react-native'
+      // fallback. Events emitted while this resolves are silently dropped
+      // by the no-op Logger that is active until configureAppLogger is called.
+      resolveDeviceId().then(deviceId => {
+        const provider = new OneDsTelemetryProvider({
+          ...providerConfig,
+          deviceId
+        });
+        configureAppLogger(new Logger({
+          providers: [provider]
+        }));
+      }).catch(_err => {
+        // SecureStore unavailable — fall back to a provider without a stable ID.
+        const provider = new OneDsTelemetryProvider(providerConfig);
+        configureAppLogger(new Logger({
+          providers: [provider]
+        }));
+      });
+    }
+
+    // Flush any queued telemetry when this component unmounts (dev reload /
+    // process exit). Placed inside this effect so the cleanup is paired with
+    // the setup — if the effect re-runs (which it won't here, empty deps),
+    // the previous provider is flushed before the new one is configured.
+    return () => {
+      void getAppLogger().flush();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []); // intentionally empty — logger is configured once per mount
+  return /*#__PURE__*/_jsx(ErrorBoundary, {
+    children: /*#__PURE__*/_jsx(GestureHandlerRootView, {
+      style: {
+        flex: 1
+      },
+      children: /*#__PURE__*/_jsx(ThemeProvider, {
+        theme: theme,
+        darkTheme: darkTheme,
+        followSystem: followSystemTheme,
+        children: /*#__PURE__*/_jsx(TamaguiProvider, {
+          config: tamaguiConfig,
+          defaultTheme: defaultTheme,
+          children: /*#__PURE__*/_jsx(PortalProvider, {
+            shouldAddRootHost: true,
+            children: /*#__PURE__*/_jsxs(ToastProvider, {
+              swipeDirection: "horizontal",
+              duration: 3000,
+              children: [/*#__PURE__*/_jsx(QueryClientProvider, {
+                client: queryClient,
+                children: /*#__PURE__*/_jsx(AuthProvider, {
+                  msalConfig: msalConfig,
+                  intuneConfig: intuneConfig,
+                  children: /*#__PURE__*/_jsx(InnerProviders, {
+                    msalConfig: msalConfig,
+                    powerConfig: powerConfig,
+                    schemaMap: schemaMap,
+                    renderOAuthWebView: renderOAuthWebView,
+                    onDisambiguationNeeded: onDisambiguationNeeded,
+                    offlineProfile: offlineProfile,
+                    children: children
+                  })
+                })
+              }), /*#__PURE__*/_jsx(ToastViewport, {
+                top: 50,
+                left: 0,
+                right: 0
+              })]
+            })
+          })
+        })
+      })
+    })
+  });
+}

package/lib/module/telemetry/index.js

@@ -0,0 +1,55 @@
+"use strict";
+
+/*!
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ *
+ * power-apps-native-host — package telemetry
+ *
+ * The shared logger singleton lives in `@microsoft/power-apps-native-common`
+ * (`getAppLogger` / `configureAppLogger`). This module re-exports those
+ * alongside the canonical host operation-name constants.
+ */
+
+export { getAppLogger, configureAppLogger } from '@microsoft/power-apps-native-common';
+
+/**
+ * Canonical operation names for host package telemetry.
+ * Follow the `PowerAppsHost.<Subsystem>.<Action>` convention so events are
+ * filterable in Kusto by prefix.
+ */
+export const HostOperationNames = {
+  // ── Auth ─────────────────────────────────────────────────────────────────
+  /** MSAL PublicClientApplication.init() + initial account resolution. */
+  AuthInit: 'PowerAppsHost.Auth.Init',
+  /** Interactive sign-in (acquireToken interactive). */
+  AuthSignIn: 'PowerAppsHost.Auth.SignIn',
+  /** Sign-out (token cache clear + broker logout). */
+  AuthSignOut: 'PowerAppsHost.Auth.SignOut',
+  /** Silent token acquisition. Recorded only on failure. */
+  AuthAcquireTokenSilentFailed: 'PowerAppsHost.Auth.AcquireTokenSilent.Failed',
+  /** Intune MAM enrollment after sign-in. */
+  AuthIntuneEnroll: 'PowerAppsHost.Auth.Intune.Enroll',
+  /** Intune MAM unenrollment during sign-out. */
+  AuthIntuneUnenroll: 'PowerAppsHost.Auth.Intune.Unenroll',
+  // ── Bridge / HTTP ─────────────────────────────────────────────────────────
+  /** SDK-originated HTTP request relayed through NativePowerAppsBridge. */
+  BridgeHttpRequest: 'PowerAppsHost.Bridge.HttpRequest',
+  /** Plugin call forwarded through NativePowerAppsBridge (verbose; also used for unhandled). */
+  BridgeUnhandledPlugin: 'PowerAppsHost.Bridge.PluginCall',
+  /** Connector/Dataverse token acquisition for the bridge. Recorded only on failure. */
+  BridgeTokenAcquireFailed: 'PowerAppsHost.Bridge.TokenAcquire.Failed',
+  // ── Runtime ───────────────────────────────────────────────────────────────
+  /** Top-level React error boundary caught an unhandled JS error. */
+  RuntimeUnhandledJsError: 'PowerAppsHost.Runtime.UnhandledJsError',
+  // ── Platform APIs ─────────────────────────────────────────────────────────
+  /** Resolve Dataverse instanceUrl from Power Platform environment API. */
+  PlatformFetchInstanceUrl: 'PowerAppsHost.Platform.FetchInstanceUrl',
+  /** useConnectionRefs failed to resolve connections (recoverable). Recorded only on failure. */
+  PlatformLoadConnectionsFailed: 'PowerAppsHost.Platform.LoadConnections.Failed',
+  /** Create a new Power Platform connection. */
+  PlatformCreateConnection: 'PowerAppsHost.Platform.CreateConnection',
+  /** Resolve app connection references for the current launch. */
+  PlatformResolveConnectionRefs: 'PowerAppsHost.Platform.ResolveConnectionRefs',
+  /** Grant this app access to a Power Platform connection ACL. */
+  PlatformConnectionAclGrant: 'PowerAppsHost.Platform.ConnectionAclGrant'
+};

package/lib/module/theme/ThemeProvider.js

@@ -0,0 +1,63 @@
+"use strict";
+
+/**
+ * ThemeProvider — distributes {@link ThemeTokens} through the component tree.
+ *
+ * `PowerAppsProvider` mounts this automatically. Use directly only when
+ * composing providers manually.
+ */
+
+import React, { createContext, useContext, useMemo, useState } from 'react';
+import { useColorScheme } from 'react-native';
+import { lightTheme as defaultLightTheme, darkTheme as defaultDarkTheme } from "./tokens.js";
+
+// ── Contexts ─────────────────────────────────────────────────────────────────
+import { jsx as _jsx } from "react/jsx-runtime";
+const ThemeContext = /*#__PURE__*/createContext(defaultLightTheme);
+const ThemeControlContext = /*#__PURE__*/createContext({
+  setTheme: () => {},
+  resetTheme: () => {}
+});
+
+// ── Provider ─────────────────────────────────────────────────────────────────
+
+export function ThemeProvider({
+  theme = defaultLightTheme,
+  darkTheme = defaultDarkTheme,
+  followSystem = true,
+  children
+}) {
+  const colorScheme = useColorScheme();
+  const [override, setOverride] = useState(null);
+  const resolved = useMemo(() => {
+    if (override !== null) return override;
+    return followSystem && colorScheme === 'dark' ? darkTheme : theme;
+  }, [theme, darkTheme, followSystem, colorScheme, override]);
+  const control = useMemo(() => ({
+    setTheme: tokens => setOverride(tokens),
+    resetTheme: () => setOverride(null)
+  }), []);
+  return /*#__PURE__*/_jsx(ThemeControlContext.Provider, {
+    value: control,
+    children: /*#__PURE__*/_jsx(ThemeContext.Provider, {
+      value: resolved,
+      children: children
+    })
+  });
+}
+
+// ── Hooks ─────────────────────────────────────────────────────────────────────
+
+/** Returns current {@link ThemeTokens} from the nearest ThemeProvider. */
+export function useThemeTokens() {
+  return useContext(ThemeContext);
+}
+
+/**
+ * Returns `{ setTheme, resetTheme }` for imperative theme overrides.
+ * Stable reference — does not re-render consumers on theme change.
+ */
+export function useThemeControl() {
+  return useContext(ThemeControlContext);
+}
+export { lightTheme, darkTheme } from "./tokens.js";

package/lib/module/theme/tokens.js

@@ -0,0 +1,46 @@
+"use strict";
+
+/**
+ * Theme token schema and built-in palettes for power-apps-native-host.
+ *
+ * Pass a custom {@link ThemeTokens} object to `PowerAppsProvider` to override
+ * the default Microsoft blue palette.
+ */
+
+// ── Built-in themes ──────────────────────────────────────────────────────────
+
+/** Microsoft blue light palette (default). */
+export const lightTheme = {
+  surface0: '#ffffff',
+  surface1: '#f7f7f8',
+  surface2: '#efeff1',
+  surface3: '#e3e3e7',
+  surface4: '#d0d0d6',
+  text0: '#111113',
+  text1: '#2e2e33',
+  text2: '#696969',
+  text3: '#9e9e9e',
+  accentDeep: '#004578',
+  accentBase: '#0078d4',
+  accentSoft: '#deecf9',
+  accentOnAccent: '#ffffff',
+  isDark: false
+};
+
+/** Microsoft blue dark palette (default). */
+export const darkTheme = {
+  surface0: '#111113',
+  surface1: '#1c1c1f',
+  surface2: '#28282c',
+  surface3: '#333338',
+  surface4: '#404047',
+  text0: '#ededef',
+  text1: '#c8c8cc',
+  text2: '#9898a0',
+  text3: '#6b6b75',
+  accentDeep: '#82c7ff',
+  accentBase: '#2899f5',
+  accentSoft: '#0a2238',
+  accentOnAccent: '#ffffff',
+  isDark: true
+};

package/lib/module/utils/dataverseUtils.js

@@ -0,0 +1,90 @@
+"use strict";
+
+/**
+ * Utilities for reading local file:// URIs and converting them into the binary
+ * format expected by the Dataverse upload endpoint via NativePowerAppsBridge.
+ *
+ * Background:
+ *  - `fetch('file://')` fails silently on Android.
+ *  - `fetch('data:...')` throws "Network request failed" on Android.
+ *  - `new Blob([Uint8Array])` crashes Hermes ("ArrayBufferView not supported").
+ *  - NativePowerAppsBridge accepts `Uint8Array` and extracts `.buffer` as the
+ *    fetch body, which React Native sends as raw bytes correctly.
+ *
+ * Solution: read via `readAsStringAsync` (base64) → `atob` → `Uint8Array`.
+ */
+
+import { readAsStringAsync, EncodingType } from 'expo-file-system/legacy';
+
+/**
+ * Read a local `file://` URI and return its contents as a `Uint8Array`.
+ * Safe on both Android and iOS.
+ */
+export async function readFileAsUint8Array(uri) {
+  const base64 = await readAsStringAsync(uri, {
+    encoding: EncodingType.Base64
+  });
+  return base64ToUint8Array(base64);
+}
+
+/**
+ * Detect the image MIME type from the first bytes of a base64-encoded string.
+ * Returns 'image/jpeg' as a safe default.
+ */
+export function detectImageMime(base64) {
+  const normalized = normalizeBase64(base64);
+  if (normalized.startsWith('iVBOR')) return 'image/png';
+  if (normalized.startsWith('R0lG')) return 'image/gif';
+  if (normalized.startsWith('Qk')) return 'image/bmp';
+  if (normalized.startsWith('UklGR')) return 'image/webp';
+  return 'image/jpeg';
+}
+function normalizeBase64(base64) {
+  return base64.includes('base64,') ? base64.slice(base64.indexOf('base64,') + 'base64,'.length) : base64;
+}
+
+/** Convert a base64 string into bytes suitable for Dataverse binary upload APIs. */
+export function base64ToUint8Array(base64) {
+  const normalized = normalizeBase64(base64);
+  const binaryString = atob(normalized);
+  const uint8 = new Uint8Array(binaryString.length);
+  for (let i = 0; i < binaryString.length; i++) {
+    uint8[i] = binaryString.charCodeAt(i);
+  }
+  return uint8;
+}
+function uint8ArrayToArrayBuffer(bytes) {
+  const copy = new Uint8Array(bytes.byteLength);
+  copy.set(bytes);
+  return copy.buffer;
+}
+
+/**
+ * Create a lightweight File-compatible object for generated Dataverse upload methods.
+ * React Native does not consistently provide a browser File implementation, but the
+ * generated services only require `name` and `arrayBuffer()`.
+ */
+export function createDataverseUploadFile(name, mimeType, bytes) {
+  return {
+    name,
+    type: mimeType,
+    size: bytes.byteLength,
+    arrayBuffer: async () => uint8ArrayToArrayBuffer(bytes)
+  };
+}
+
+/** Create a File-compatible image object from Dataverse-style base64 image content. */
+export function base64ToDataverseUploadFile(base64, name = 'image') {
+  const bytes = base64ToUint8Array(base64);
+  const mimeType = detectImageMime(base64);
+  const extension = mimeType.slice('image/'.length).replace('jpeg', 'jpg');
+  return createDataverseUploadFile(name.includes('.') ? name : `${name}.${extension}`, mimeType, bytes);
+}
+
+/**
+ * Build a `data:<mime>;base64,<data>` URI from a raw base64 string returned
+ * by Dataverse for an image column.
+ */
+export function base64ToDataUri(base64) {
+  return `data:${detectImageMime(base64)};base64,${base64}`;
+}

package/lib/module/utils/isDevPlayer.js

@@ -0,0 +1,23 @@
+"use strict";
+
+import { NativeModules } from 'react-native';
+import Constants from 'expo-constants';
+
+/**
+ * True when the JS bundle is running inside the Power Apps Dev Player shell.
+ *
+ * Two signals are combined to cover both execution paths:
+ *
+ * 1. `Constants.expoConfig.extra.isDevPlayer` — set in apps/dev-player/app.config.js.
+ *    Fires when the dev-player's **own** JS bundle is active (e.g. the launcher screen).
+ *
+ * 2. `NativeModules.PowerAppsDevLauncher` — the dev-player's Expo native module,
+ *    registered in the dev-player APK/IPA regardless of which JS bundle is loaded.
+ *    Fires when a template bundle is loaded via QR-code/URL into the dev-player shell,
+ *    because expo-constants then reflects the template's manifest (no isDevPlayer flag)
+ *    but the native module is still present in the host binary.
+ *
+ * Neither signal fires in a standalone release APK generated from the template, so
+ * `isDevPlayer` is false there and all debug logging is silenced.
+ */
+export const isDevPlayer = Constants.expoConfig?.extra?.isDevPlayer === true || !!NativeModules.PowerAppsDevLauncher;

package/lib/typescript/commonjs/ErrorBoundary.d.ts

@@ -0,0 +1,30 @@
+import React from 'react';
+interface Props {
+    children: React.ReactNode;
+}
+interface State {
+    hasError: boolean;
+    error: Error | null;
+    componentStack: string | null;
+}
+/**
+ * Top-level React error boundary.
+ *
+ * Catches any unhandled JS exception thrown during rendering / lifecycle and
+ * displays a diagnostic screen.  All error details are written to the native
+ * log via debugLog so diagnostics stay consistent with the host package logger.
+ *
+ * Place this component at the very root of the component tree so it captures
+ * failures in any screen.
+ *
+ * Exported from power-apps-native-host so it can be used in the template and
+ * in any custom app without duplicating the implementation.
+ */
+export declare class ErrorBoundary extends React.Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): Partial<State>;
+    componentDidCatch(error: Error, info: React.ErrorInfo): void;
+    render(): React.ReactNode;
+}
+export {};
+//# sourceMappingURL=ErrorBoundary.d.ts.map