@microsoft/power-apps-native-host 0.2.22

package/lib/commonjs/platform/useConnectionRefs.js

@@ -0,0 +1,270 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useConnectionRefs = useConnectionRefs;
+var _react = require("react");
+var _isDevPlayer = require("../utils/isDevPlayer.js");
+var _PowerPlatformEnvironmentApi = require("./PowerPlatformEnvironmentApi.js");
+var _types = require("../connections/types.js");
+var _PowerPlatformConnectionApi = require("./PowerPlatformConnectionApi.js");
+var _resolveConnections = require("./resolveConnections.js");
+var _logger = require("../logger.js");
+var _index = require("../telemetry/index.js");
+var _NativePowerAppsBridge = require("../bridge/NativePowerAppsBridge.js");
+/*!
+ * power-apps-native-host — useConnectionRefs
+ *
+ * Resolves per-user connectionIds from the Power Platform environment-scoped
+ * connectivity API, then builds a fully-populated connection-references map
+ * ready to pass to <PowerAppsHostProvider connections={...} />.
+ *
+ * Now supports connection disambiguation: when multiple Connected connections
+ * exist for the same connector, the `onDisambiguationNeeded` callback lets the
+ * consuming app present a native picker UI (e.g. a bottom sheet) so the user
+ * can choose which connection to use.  When no connection exists for a connector
+ * the `onMissingConnection` callback fires so the consuming app can guide the
+ * user to create one.
+ *
+ * Usage:
+ *   import { useConnectionRefs } from '@microsoft/power-apps-native-host';
+ *   import powerConfig from '../power.config.json';
+ *   import { schemaMap } from '../src/connectorSchemas';
+ *
+ *   const { connectionRefs, isReady, error, missingConnectors } = useConnectionRefs({
+ *     isSignedIn,
+ *     acquireToken,
+ *     environmentId: authConfig.powerPlatform.environmentId,
+ *     region: authConfig.powerPlatform.region,
+ *     connectionReferences: powerConfig.connectionReferences,
+ *     schemaMap,
+ *     onDisambiguationNeeded: async ({ localRefId, apiId, candidates }) => {
+ *       // Show a picker sheet and return the selected connectionId, or null to skip.
+ *       return showConnectionPicker(candidates);
+ *     },
+ *   });
+ */
+
+// Re-exported for backward compatibility with consumers that import ConnectorSchema
+// from this module (e.g. via the package index).
+
+/**
+ * Resolves Power Platform connection references for the current user, with
+ * disambiguation support for environments where multiple connections exist for
+ * the same connector.
+ *
+ * On sign-in this hook:
+ *  1. If `appId` is set (production template), fetches connection references
+ *     from the PowerApps RP `/apps/{appId}/launch` endpoint and uses those
+ *     in place of the static `connectionReferences` from power.config.json.
+ *  2. Acquires a Power Platform API token.
+ *  3. In parallel: fetches the Dataverse instanceUrl and ALL connections for
+ *     each configured connector.
+ *  4. Runs disambiguation: resolves single matches, invokes `onDisambiguationNeeded`
+ *     for multiple matches, and invokes `onMissingConnection` for absent ones.
+ *  5. Pre-warms the Dataverse token in the MSAL cache.
+ *  6. Sets isReady=true with the fully-populated connections map.
+ */
+function useConnectionRefs({
+  isSignedIn,
+  acquireToken,
+  appId,
+  environmentId,
+  region = 'prod',
+  connectionReferences,
+  schemaMap,
+  onDisambiguationNeeded,
+  onMissingConnection,
+  isvClientId
+}) {
+  const [connectionRefs, setConnectionRefs] = (0, _react.useState)({});
+  const [isReady, setIsReady] = (0, _react.useState)(false);
+  const [error, setError] = (0, _react.useState)(null);
+  const [missingConnectors, setMissingConnectors] = (0, _react.useState)([]);
+  const [dataverseOrgUrl, setDataverseOrgUrl] = (0, _react.useState)('');
+
+  // Bounded re-resolution for the transient null-token case. A null token at
+  // cold boot is usually a silent-auth miss (the account exists, but MSAL hasn't
+  // produced a token yet); without a retry the effect — keyed on isSignedIn —
+  // would never re-resolve once a token becomes available, leaving the bridge on
+  // the static fallback refs (no runtimeUrl) for the whole session. retryTick
+  // re-runs the effect; tokenRetryCountRef caps the attempts so it can never loop.
+  const [retryTick, setRetryTick] = (0, _react.useState)(0);
+  const tokenRetryCountRef = (0, _react.useRef)(0);
+  // True only when this effect run was triggered by the bounded background
+  // retry below (not an initial resolution or a sign-in). Used to avoid
+  // clobbering an already-ready UI: a retry must re-resolve in the background
+  // without dropping isReady, which would otherwise unmount the whole signed-in
+  // subtree (spinner) on every tick.
+  const isBackgroundRetryRef = (0, _react.useRef)(false);
+  const MAX_TOKEN_RETRIES = 5;
+  const TOKEN_RETRY_DELAY_MS = 2000;
+  (0, _react.useEffect)(() => {
+    if (!isSignedIn) {
+      tokenRetryCountRef.current = 0;
+      isBackgroundRetryRef.current = false;
+      return;
+    }
+
+    // Consume the background-retry flag once per run so a later initial run or
+    // sign-in can never inherit a stale value.
+    const isBackgroundRetry = isBackgroundRetryRef.current;
+    isBackgroundRetryRef.current = false;
+    const hasConnectionRefs = Object.keys(connectionReferences).length > 0;
+
+    // The Dev Player shell has no connection references of its own. However,
+    // a played app loaded inside Dev Player can have required connections OR an
+    // environmentId it needs resolved (the appId-null / empty-refs path used by
+    // offline-first apps running online). Only skip when there is genuinely
+    // nothing to resolve — no refs AND no environment to fetch the Dataverse
+    // instanceUrl from. Otherwise fall through to the slow path so
+    // fetchInstanceUrl(environmentId) can populate dataverseOrgUrl; without this
+    // an online (offline-disabled) played app never resolves its instanceUrl in
+    // the Dev Player and every Dataverse read fails with "No instanceUrl found".
+    if (_isDevPlayer.isDevPlayer && !hasConnectionRefs && !environmentId) {
+      setIsReady(true);
+      return;
+    }
+
+    // Nothing to resolve — no connection references and no environment to query
+    // (and no appId to fetch from the launch API).
+    // Mark ready immediately so the bridge can initialise without any network calls.
+    if (!environmentId && !appId) {
+      setIsReady(true);
+      return;
+    }
+    let cancelled = false;
+    let retryTimer;
+    // Skip the reset on a background-retry run: the UI is already mounted with
+    // static fallback refs, so re-resolution must happen in the background. The
+    // full-resolution path below still sets missingConnectors/error from the
+    // real result. Resetting here would drop isReady → unmount the subtree.
+    if (!isBackgroundRetry) {
+      setIsReady(false);
+      setError(null);
+      setMissingConnectors([]);
+    }
+    async function loadConnections() {
+      const token = await acquireToken([(0, _PowerPlatformEnvironmentApi.powerPlatformScope)(region)]);
+      if (cancelled) return;
+      if (!token) {
+        // Cold boot before an auth token is available (e.g. silent-token miss or
+        // offline launch). The per-user runtimeUrl/connectionName can't be
+        // resolved yet, but seed the bridge with whatever static apiId entries can
+        // be derived from connectionReferences so the runtime fields populate on
+        // the next resolution. NOTE: when connectionReferences is empty (the
+        // appId-only fast path) this seed is itself empty, so the bridge starts
+        // with no connections until the bounded retry below resolves a token.
+        // That gap is transient as long as a retry succeeds within
+        // MAX_TOKEN_RETRIES; if the budget is exhausted the bridge stays seeded
+        // with the empty map until the next sign-out/in resets the retry count.
+        // Still mark ready so the host mounts the UI (the offline SDK serves local
+        // SQLite without a token) instead of gating on !isReady forever.
+        setConnectionRefs((0, _NativePowerAppsBridge.buildConnectionReferences)(connectionReferences));
+        setIsReady(true);
+        // Schedule a bounded re-resolution so a transient silent-auth miss
+        // recovers once a token is available, instead of staying on the static
+        // fallback refs for the rest of the session. Capped by MAX_TOKEN_RETRIES
+        // so it can never spin.
+        if (tokenRetryCountRef.current < MAX_TOKEN_RETRIES) {
+          tokenRetryCountRef.current += 1;
+          retryTimer = setTimeout(() => {
+            if (!cancelled) {
+              isBackgroundRetryRef.current = true;
+              setRetryTick(t => t + 1);
+            }
+          }, TOKEN_RETRY_DELAY_MS);
+        }
+        return;
+      }
+      // A token was obtained — reset the retry budget so a later token loss
+      // (e.g. across a sign-out/in cycle) gets a fresh set of attempts.
+      tokenRetryCountRef.current = 0;
+
+      // Fast path: single launch API call — production APKs only.
+      // Skipped for the Dev Player (always uses static refs so any app can be
+      // loaded without being published first).
+      let result = null;
+      if (appId && environmentId && !_isDevPlayer.isDevPlayer) {
+        result = await (0, _PowerPlatformConnectionApi.fetchAppLaunchData)(appId, environmentId, region, token);
+        if (result && isvClientId) {
+          await (0, _resolveConnections.applyAclGrants)(result.connectionRefs, environmentId, isvClientId, acquireToken);
+        } else {
+          (0, _logger.debugWarn)('[useConnectionRefs] could not verify connection ACLs; treating existing connections as setup-required');
+          (0, _index.getAppLogger)().trackErrorEvent(_index.HostOperationNames.PlatformConnectionAclGrant, {
+            phase: 'launchAclVerify',
+            reason: result ? 'missingIsvClientId' : 'launchDataUnavailable',
+            connectionRefCount: result ? Object.keys(result.connectionRefs).length : 0
+          });
+          for (const r of result ? Object.values(result.connectionRefs) : []) {
+            for (const inst of r.instances || []) {
+              if (r.status === _types.ConnectionStatus.Connected) {
+                r.status = _types.ConnectionStatus.NeedsAclGrant;
+              }
+            }
+          }
+        }
+      }
+
+      // Slow path: per-connector resolution.
+      // Used when: running in Dev Player, no appId (local dev), or launch API failed.
+      if (!result) {
+        result = await (0, _resolveConnections.resolveViaStaticRefs)({
+          connectionReferences,
+          schemaMap,
+          environmentId,
+          region,
+          acquireToken,
+          token,
+          isvClientId,
+          onDisambiguationNeeded,
+          onMissingConnection
+        });
+      }
+      if (cancelled) return;
+
+      // Pre-warm the Dataverse token while the user waits.
+      if (result.dataverseOrgUrl) {
+        void acquireToken([`${result.dataverseOrgUrl}/.default`]);
+      }
+      if (!cancelled) {
+        setConnectionRefs(result.connectionRefs);
+        setMissingConnectors(result.missingConnectors);
+        setDataverseOrgUrl(result.dataverseOrgUrl);
+        setIsReady(true);
+      }
+    }
+    loadConnections().catch(e => {
+      if (!cancelled) {
+        // Recoverable transport failure (e.g. offline cold boot). Record a
+        // telemetry error event — matching every other failure path in the
+        // host (AuthContext, bridge, provider) — so it is always visible in
+        // production without raising a __DEV__ LogBox redbox over the
+        // otherwise-working UI. We still recover via setIsReady below.
+        (0, _logger.debugLog)('[useConnectionRefs] Failed to load connections:', e);
+        (0, _index.getAppLogger)().trackErrorEvent(_index.HostOperationNames.PlatformLoadConnectionsFailed, {
+          error: String(e),
+          hasAppId: Boolean(appId),
+          hasEnvironmentId: Boolean(environmentId),
+          connectionReferenceCount: Object.keys(connectionReferences).length,
+          runningInDevPlayer: _isDevPlayer.isDevPlayer
+        });
+        setError(String(e));
+        setIsReady(true);
+      }
+    });
+    return () => {
+      cancelled = true;
+      if (retryTimer) clearTimeout(retryTimer);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isSignedIn, retryTick]);
+  return {
+    connectionRefs,
+    isReady,
+    error,
+    missingConnectors,
+    dataverseOrgUrl
+  };
+}

package/lib/commonjs/provider/PowerAppsHostProvider.js

@@ -0,0 +1,336 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.PowerAppsHostProvider = PowerAppsHostProvider;
+var _react = _interopRequireWildcard(require("react"));
+var _reactNative = require("react-native");
+var _reactNativeSafeAreaContext = require("react-native-safe-area-context");
+var _setupNativeHost = require("../bridge/setupNativeHost.js");
+var _NativePowerAppsBridge = require("../bridge/NativePowerAppsBridge.js");
+var _useConnectionRefs = require("../platform/useConnectionRefs.js");
+var _PowerPlatformEnvironmentApi = require("../platform/PowerPlatformEnvironmentApi.js");
+var _ConnectionSetupScreen = require("../connections/ConnectionSetupScreen.js");
+var _logger = require("../logger.js");
+var _index = require("../telemetry/index.js");
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+/*!
+ * power-apps-native-host — PowerAppsHostProvider
+ *
+ * A React component that owns the full pre-launch pipeline:
+ *
+ *   1. Waits for the user to be signed in.
+ *   2. Resolves connection references via useConnectionRefs (with
+ *      disambiguation support).
+ *   3. If any connections are missing, renders ConnectionSetupScreen — which
+ *      the user MUST complete before the app opens.  There is no skip path.
+ *   4. Once all connections are resolved, initialises NativePowerAppsBridge
+ *      and renders children.
+ *
+ * The consuming app passes raw config (connectionReferences, schemaMap,
+ * databaseReferences) and never touches connection resolution logic.
+ *
+ *   <PowerAppsHostProvider
+ *     acquireToken={acquireToken}
+ *     isSignedIn={isSignedIn}
+ *     environmentId="..."
+ *     region="prod"
+ *     connectionReferences={powerConfig.connectionReferences}
+ *     schemaMap={schemaMap}
+ *     databaseReferences={powerConfig.databaseReferences}
+ *   >
+ *     <Slot />
+ *   </PowerAppsHostProvider>
+ */
+
+// Entra ID token scope for the APIM connector proxy (API Hub).
+const CONNECTOR_SCOPE = 'https://apihub.azure.com/.default';
+const EMPTY_DATABASE_REFERENCES = {};
+/**
+ * Initialises the NativePowerAppsBridge and manages the full pre-launch
+ * pipeline — connection resolution, disambiguation, and creation — before
+ * rendering children.
+ *
+ * Children are never rendered until all required connections are resolved.
+ */
+function PowerAppsHostProvider({
+  acquireToken,
+  isSignedIn,
+  appId,
+  environmentId,
+  region = 'prod',
+  connectionReferences,
+  schemaMap,
+  databaseReferences,
+  renderOAuthWebView,
+  isvClientId,
+  onDisambiguationNeeded,
+  children
+}) {
+  // Extra refs produced by ConnectionSetupScreen for newly-created connections.
+  const [extraConnectionRefs, setExtraConnectionRefs] = (0, _react.useState)({});
+
+  // setupDone is derived — true as soon as extraConnectionRefs is populated.
+  const setupDone = Object.keys(extraConnectionRefs).length > 0;
+  const {
+    connectionRefs,
+    isReady,
+    missingConnectors,
+    dataverseOrgUrl
+  } = (0, _useConnectionRefs.useConnectionRefs)({
+    isSignedIn,
+    acquireToken,
+    appId,
+    environmentId,
+    region,
+    connectionReferences,
+    schemaMap,
+    onDisambiguationNeeded,
+    isvClientId
+  });
+
+  // Reset setup gate when the user signs out.
+  (0, _react.useEffect)(() => {
+    if (!isSignedIn) {
+      (0, _logger.debugLog)('[PAHost] user signed out — resetting bridge state');
+      setExtraConnectionRefs({});
+    }
+  }, [isSignedIn]);
+
+  // Merge hook refs with anything the setup screen created.
+  const mergedRefs = (0, _react.useMemo)(() => ({
+    ...connectionRefs,
+    ...extraConnectionRefs
+  }), [connectionRefs, extraConnectionRefs]);
+  const staticConnectionRefs = (0, _react.useMemo)(() => (0, _NativePowerAppsBridge.buildConnectionReferences)(connectionReferences), [connectionReferences]);
+
+  // dataverseOrgUrl comes directly from useConnectionRefs (fetched from the
+  // environment metadata regardless of whether a commondataserviceforapps
+  // connection reference is configured).  This allows Dataverse calls to work
+  // even when there is no explicit Dataverse connection in connectionReferences.
+  const cdsDataSources = (0, _react.useMemo)(() => (0, _PowerPlatformEnvironmentApi.buildCdsDataSources)(databaseReferences ?? EMPTY_DATABASE_REFERENCES, dataverseOrgUrl), [databaseReferences, dataverseOrgUrl]);
+
+  // Build the missing-connector entries for ConnectionSetupScreen.
+  const missingEntries = (0, _react.useMemo)(() => missingConnectors.map(apiId => {
+    const localRefId = Object.keys(connectionReferences).find(k => connectionReferences[k].id === apiId) ?? apiId;
+    return {
+      apiId,
+      localRefId
+    };
+  }), [missingConnectors, connectionReferences]);
+
+  // Called by ConnectionSetupScreen once every missing connector is resolved.
+  const handleSetupComplete = (0, _react.useCallback)(resolvedIds => {
+    const refs = {};
+    for (const [apiId, connectionId] of Object.entries(resolvedIds)) {
+      const localRefId = Object.keys(connectionReferences).find(k => connectionReferences[k].id === apiId);
+      if (!localRefId) continue;
+      const dataSources = connectionReferences[localRefId].dataSources;
+      const runtimeUrl = dataSources.map(ds => schemaMap[ds]?.properties?.primaryRuntimeUrl).find(Boolean) ?? '';
+      for (const ds of dataSources) {
+        refs[ds] = {
+          apiId,
+          runtimeUrl,
+          connectionName: connectionId,
+          // Preserve datasetName from the resolved connectionRefs (e.g. the
+          // Dataverse org URL that useConnectionRefs fetches via fetchInstanceUrl,
+          // which exists even when the connection itself was missing).
+          datasetName: connectionRefsRef.current[ds]?.datasetName ?? ''
+        };
+      }
+    }
+    setExtraConnectionRefs(refs);
+  }, [connectionReferences, schemaMap]);
+
+  // ---- Bridge wiring ----
+
+  const acquireTokenRef = (0, _react.useRef)(acquireToken);
+  acquireTokenRef.current = acquireToken;
+  const dataverseOrgUrlRef = (0, _react.useRef)(dataverseOrgUrl);
+  dataverseOrgUrlRef.current = dataverseOrgUrl;
+  const connectionRefsRef = (0, _react.useRef)(connectionRefs);
+  connectionRefsRef.current = connectionRefs;
+  const configuredBridgeInputsRef = (0, _react.useRef)(undefined);
+  const [, setBridgeRegistrationVersion] = (0, _react.useState)(0);
+  const hasResolvedConnections = isSignedIn && isReady && (missingConnectors.length === 0 || setupDone);
+  const isBridgeConfiguredFor = (connections, dataSources) => {
+    const currentInputs = configuredBridgeInputsRef.current;
+    return currentInputs?.connections === connections && currentInputs.dataSources === dataSources;
+  };
+  const configureBridgeNow = (0, _react.useCallback)((connections, dataSources) => {
+    const previousInputs = configuredBridgeInputsRef.current;
+    const shouldConfigureBridge = !previousInputs || previousInputs.connections !== connections || previousInputs.dataSources !== dataSources;
+    if (!shouldConfigureBridge) return;
+    (0, _logger.debugLog)(`[PAHost] setupNativeHost: isReady=${isReady} missingConnectors=${missingConnectors.length} setupDone=${setupDone} connections=${Object.keys(connections).join(', ') || '(none)'}`);
+    (0, _setupNativeHost.setupNativeHost)({
+      getConnectorToken: async _apiId => {
+        (0, _logger.debugLog)(`[PAHost] getConnectorToken: acquiring token for apiId="${_apiId}"`);
+        let token;
+        try {
+          token = await acquireTokenRef.current([CONNECTOR_SCOPE]);
+        } catch (err) {
+          (0, _logger.debugLog)(`[PAHost] getConnectorToken: acquireToken threw for apiId="${_apiId}":`, err);
+          (0, _index.getAppLogger)().trackErrorEvent(_index.HostOperationNames.BridgeTokenAcquireFailed, {
+            tokenKind: 'connector',
+            reason: 'exception',
+            error: String(err)
+          });
+          throw err;
+        }
+        if (!token) {
+          (0, _logger.debugLog)(`[PAHost] getConnectorToken: acquireToken returned null for apiId="${_apiId}"`);
+          (0, _index.getAppLogger)().trackErrorEvent(_index.HostOperationNames.BridgeTokenAcquireFailed, {
+            tokenKind: 'connector',
+            reason: 'nullToken'
+          });
+          throw new Error('NativePowerAppsBridge: failed to acquire connector token (acquireToken returned null)');
+        }
+        (0, _logger.debugLog)(`[PAHost] getConnectorToken: token acquired for apiId="${_apiId}"`);
+        return token;
+      },
+      getDataverseToken: async datasetName => {
+        const orgUrl = datasetName.startsWith('https://') ? datasetName : dataverseOrgUrlRef.current || datasetName;
+        (0, _logger.debugLog)(`[PAHost] getDataverseToken: acquiring token for orgUrl="${orgUrl}"`);
+        let token;
+        try {
+          token = await acquireTokenRef.current([`${orgUrl}/.default`]);
+        } catch (err) {
+          (0, _logger.debugLog)(`[PAHost] getDataverseToken: acquireToken threw for orgUrl="${orgUrl}":`, err);
+          (0, _index.getAppLogger)().trackErrorEvent(_index.HostOperationNames.BridgeTokenAcquireFailed, {
+            tokenKind: 'dataverse',
+            reason: 'exception',
+            error: String(err)
+          });
+          throw err;
+        }
+        if (!token) {
+          (0, _logger.debugLog)(`[PAHost] getDataverseToken: acquireToken returned null for orgUrl="${orgUrl}"`);
+          (0, _index.getAppLogger)().trackErrorEvent(_index.HostOperationNames.BridgeTokenAcquireFailed, {
+            tokenKind: 'dataverse',
+            reason: 'nullToken'
+          });
+          throw new Error(`NativePowerAppsBridge: failed to acquire Dataverse token for ${orgUrl} (acquireToken returned null)`);
+        }
+        (0, _logger.debugLog)(`[PAHost] getDataverseToken: token acquired for orgUrl="${orgUrl}"`);
+        return token;
+      },
+      dataSources,
+      connections
+    });
+    configuredBridgeInputsRef.current = {
+      connections,
+      dataSources
+    };
+    setBridgeRegistrationVersion(version => version + 1);
+    (0, _logger.debugLog)('[PAHost] bridge registered');
+  }, [isReady, missingConnectors.length, setupDone]);
+  const staticBridgeRegistered = isBridgeConfiguredFor(staticConnectionRefs, cdsDataSources);
+  const resolvedBridgeRegistered = hasResolvedConnections && isBridgeConfiguredFor(mergedRefs, cdsDataSources);
+
+  // @microsoft/power-apps caches the first bridge returned by getBridge().
+  // Register our native bridge with static manifest refs, then update the same
+  // bridge instance with resolved per-user refs. Child mounting is gated by the
+  // render guards below (staticBridgeRegistered / resolvedBridgeRegistered), so
+  // children never mount before the bridge is configured; useLayoutEffect is
+  // used so the bridge is registered synchronously before paint, avoiding a
+  // one-frame window where a child could read an unconfigured bridge.
+  (0, _react.useLayoutEffect)(() => {
+    if (!staticBridgeRegistered && !hasResolvedConnections) {
+      configureBridgeNow(staticConnectionRefs, cdsDataSources);
+    }
+  }, [configureBridgeNow, staticBridgeRegistered, hasResolvedConnections, staticConnectionRefs, cdsDataSources]);
+  (0, _react.useLayoutEffect)(() => {
+    if (hasResolvedConnections && !resolvedBridgeRegistered) {
+      configureBridgeNow(mergedRefs, cdsDataSources);
+    }
+  }, [configureBridgeNow, hasResolvedConnections, resolvedBridgeRegistered, mergedRefs, cdsDataSources]);
+
+  // Log UI-phase transitions once per state change, not on every render.
+  (0, _react.useEffect)(() => {
+    if (isSignedIn && !isReady) {
+      (0, _logger.debugLog)('[PAHost] render: waiting for connection resolution (spinner)');
+    }
+  }, [isSignedIn, isReady]);
+  (0, _react.useEffect)(() => {
+    if (isSignedIn && isReady && missingConnectors.length > 0 && !setupDone) {
+      (0, _logger.debugLog)(`[PAHost] render: showing ConnectionSetupScreen for ${missingConnectors.length} missing connector(s):`, missingConnectors.join(', '));
+    }
+  }, [isSignedIn, isReady, missingConnectors, setupDone]);
+
+  // ---- Render ----
+
+  // First mount: register the native bridge with static manifest refs before
+  // any route children can mount and call into @microsoft/power-apps.
+  if (!staticBridgeRegistered && !hasResolvedConnections) {
+    return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+      style: {
+        flex: 1,
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: '#F8F8F8'
+      },
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.ActivityIndicator, {
+        size: "large"
+      })
+    });
+  }
+
+  // While resolving connections, show a spinner.
+  if (isSignedIn && !isReady) {
+    return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+      style: {
+        flex: 1,
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: '#F8F8F8'
+      },
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.ActivityIndicator, {
+        size: "large"
+      })
+    });
+  }
+
+  // Connections resolved but some are missing — gate on setup screen.
+  // Wrapped in SafeAreaProvider so useSafeAreaInsets() works even when the
+  // consuming app hasn't mounted its own SafeAreaProvider yet.  Nesting is
+  // safe — react-native-safe-area-context treats inner providers as no-ops.
+  if (isSignedIn && isReady && missingConnectors.length > 0 && !setupDone) {
+    return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeSafeAreaContext.SafeAreaProvider, {
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_ConnectionSetupScreen.ConnectionSetupScreen, {
+        missingConnectors: missingEntries,
+        schemaMap: schemaMap,
+        environmentId: environmentId,
+        region: region,
+        acquireToken: acquireToken,
+        isvClientId: isvClientId,
+        onAllConnected: handleSetupComplete,
+        renderOAuthWebView: renderOAuthWebView
+        // No onSkip — connections are required.
+      })
+    });
+  }
+
+  // Keep signed-in app content gated until user-specific connection refs have
+  // resolved and the already-cached bridge has been updated in-place.
+  // Only block when signed in — when signed out, isReady never becomes true
+  // (useConnectionRefs skips fetching when !isSignedIn), so the login screen
+  // would otherwise never render.
+  if (isSignedIn && (!hasResolvedConnections || !resolvedBridgeRegistered)) {
+    return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+      style: {
+        flex: 1,
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: '#F8F8F8'
+      },
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.ActivityIndicator, {
+        size: "large"
+      })
+    });
+  }
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_jsxRuntime.Fragment, {
+    children: children
+  });
+}