Add unstable-internals entry point (#57489)

Summary:

See [**RFC0894: Removing deep imports from react-native**](react-native-community/discussions-and-proposals#894)

Adds a `'react-native/unstable-internals-do-not-use'` entry point that acts as an explicit, opt-in escape hatch for frameworks and libraries that depend on specific React Native internals.

Follows (and supersedes) react-native-community/discussions-and-proposals#985.

Resolves T270727304.

**Motivation**

- Maintains a known list of which React Native internals are still in use.
- Decouples removal of the Strict API opt-out from the longer-term decisions about these APIs.
- Lets us relocate supporting source files freely, since consumers reference this subpath instead of deep internal paths.

**Notes**

- Reuses the runtime **object-with-getter pattern** (same as `index.js`), to avoid any native module side effects caused by loading adjacent file exports.
    - e.g. in Expo, [`hmrUtils.js`](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/src/async-require/hmrUtils.native.ts?fbclid=IwY2xjawS7GjNwZG9mA2V4dG4DYWVtAjExAGJyaWQRMTZ1ckEwU05oWUw2bDBVN21zcnRjBmFwcF9pZAEwAAEen3UuX4Ig-RD3n1ULZIHIHq21Mfk_ci9b2SxquY7UkngDs6qhnRt5YQlb8Os_aem_ylJy40egSOl1qhZ9bA9HTA) is designed to be run early in RN startup — preserve the lazy require characteristic and do not break this.
- TypeScript defs on this API are minimal, with complex internal input/handle types reduced to `unknown`. As with D110602194, these are intended to be feature-locked.

**Exposed internals and known consumers**

NOTE: The exports the community needs have reduced slightly since the spreadsheet in RFC0895 and would almost all align with `devsupport`. However, we're explicitly leaving a decision to formalise until later, and we may need to add in extra APIs quickly based on RC feedback.

| Export | Source module | Known consumers |
|---|---|---|
| `AppContainer` | `Libraries/ReactNative/AppContainer` | react-native-screens ([DebugContainer.tsx](https://github.com/software-mansion/react-native-screens/blob/6f38d76129d40cc8145d06b98f885b508fa7bf2d/src/components/DebugContainer.tsx#L5)) |
| `AssetSourceResolver` | `Libraries/Image/AssetSourceResolver` | Re.pack ([IncludeModules.ts](https://github.com/callstack/repack/blob/2498b3a426203daa4b81c7e6f7a88e86d88e77b9/packages/repack/src/modules/IncludeModules.ts#L9)) |
| `customDirectEventTypes` | `Libraries/Renderer/shims/ReactNativeViewConfigRegistry` | react-native-gesture-handler ([customDirectEventTypes.ts](https://github.com/software-mansion/react-native-gesture-handler/blob/ee147abf364bef48a02d3cf437572b4dddd30bec/packages/react-native-gesture-handler/src/handlers/customDirectEventTypes.ts#L2)) |
| `DevLoadingView` | `Libraries/Utilities/DevLoadingView` | Expo ([hmrUtils.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/src/async-require/hmrUtils.native.ts)), Re.pack ([WebpackHMRClient.ts](https://github.com/callstack/repack/blob/2498b3a426203daa4b81c7e6f7a88e86d88e77b9/packages/repack/src/modules/WebpackHMRClient.ts)) |
| `getDevServer` | `Libraries/Core/Devtools/getDevServer` | Expo ([getDevServer.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/src/async-require/getDevServer.native.ts), [hmrUtils.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/src/async-require/hmrUtils.native.ts), [base.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/src/dom/base.ts), [getDevServer.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/metro-runtime/src/getDevServer.native.ts), [devServerEndpoints.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/log-box/src/utils/devServerEndpoints.ts), [getConnectionInfo.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/devtools/src/getConnectionInfo.native.ts), [index.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo-router/src/getDevServer/index.native.ts)) |
| `HMRClient` | `Libraries/Utilities/HMRClient` | Expo ([metroServerLogs.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/metro-runtime/src/metroServerLogs.native.ts)) |
| `NativeExceptionsManager` | `Libraries/Core/NativeExceptionsManager` | Expo ([hmrUtils.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/src/async-require/hmrUtils.native.ts)), Re.pack ([WebpackHMRClient.ts](https://github.com/callstack/repack/blob/2498b3a426203daa4b81c7e6f7a88e86d88e77b9/packages/repack/src/modules/WebpackHMRClient.ts)) |
| `NativeRedBox` | `Libraries/NativeModules/specs/NativeRedBox` | Expo ([hmrUtils.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/src/async-require/hmrUtils.native.ts)), Re.pack ([WebpackHMRClient.ts](https://github.com/callstack/repack/blob/2498b3a426203daa4b81c7e6f7a88e86d88e77b9/packages/repack/src/modules/WebpackHMRClient.ts)) |
| `NativeSourceCode` | `Libraries/NativeModules/specs/NativeSourceCode` | Expo ([getBundleUrl.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/src/utils/getBundleUrl.native.ts)) |
| `PressabilityDebugView` | `Libraries/Pressability/PressabilityDebug` | react-native-gesture-handler ([PressabilityDebugView.tsx](https://github.com/software-mansion/react-native-gesture-handler/blob/ee147abf364bef48a02d3cf437572b4dddd30bec/packages/react-native-gesture-handler/src/handlers/PressabilityDebugView.tsx#L2)) |

**Alternative names**

- `unstable-frameworks`
- `unstable-devsupport`

Changelog: [Internal]

Reviewed By: rubennorte

Differential Revision: D110911864

Author: huntie

packages/react-native/package.json

@@ -49,6 +49,11 @@
       "default": "./src/asset-registry.js"
     },
     "./setup-env": "./src/setup-env.js",
+    "./unstable-internals-do-not-use": {
+      "react-native-unstable-internals": "./src/unstable-internals-do-not-use.d.ts",
+      "types": null,
+      "default": "./src/unstable-internals-do-not-use.js"
+    },
     "./src/fb_internal/*": "./src/fb_internal/*",
     "./package.json": "./package.json"
   },

packages/react-native/src/unstable-internals-do-not-use.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ */
+
+// ----------------------------------------------------------------------------
+// Types entry point for react-native/unstable-internals-do-not-use.
+//
+// IMPORTANT: Keep this file in sync with unstable-internals-do-not-use.js.
+// ----------------------------------------------------------------------------
+
+import type * as React from 'react';
+
+// #region AppContainer
+
+interface AppContainerProps {
+  children?: React.ReactNode | undefined;
+  rootTag: number;
+  initialProps?: object | undefined;
+  WrapperComponent?: React.ComponentType<any> | null | undefined;
+  rootViewStyle?: unknown | undefined;
+  internal_excludeLogBox?: boolean | undefined;
+  internal_excludeInspector?: boolean | undefined;
+}
+
+/** Root component that wraps and mounts a React Native app tree. */
+export const AppContainer: React.ComponentType<AppContainerProps>;
+
+// #endregion
+// #region AssetSourceResolver
+
+interface ResolvedAssetSource {
+  readonly __packager_asset: boolean;
+  readonly width: number | null | undefined;
+  readonly height: number | null | undefined;
+  readonly uri: string;
+  readonly scale: number;
+}
+
+/** Resolves a packager asset descriptor to a loadable source for the current platform. */
+export class AssetSourceResolver {
+  serverUrl: string | null | undefined;
+  jsbundleUrl: string | null | undefined;
+  asset: unknown;
+  constructor(
+    serverUrl: string | null | undefined,
+    jsbundleUrl: string | null | undefined,
+    asset: unknown,
+  );
+  isLoadedFromServer(): boolean;
+  isLoadedFromFileSystem(): boolean;
+  defaultAsset(): ResolvedAssetSource;
+  getAssetUsingResolver(resolver: 'android' | 'generic'): ResolvedAssetSource;
+  assetServerURL(): ResolvedAssetSource;
+  scaledAssetPath(): ResolvedAssetSource;
+  scaledAssetURLNearBundle(): ResolvedAssetSource;
+  resourceIdentifierWithoutScale(): ResolvedAssetSource;
+  drawableFolderInBundle(): ResolvedAssetSource;
+  fromSource(source: string): ResolvedAssetSource;
+  static pickScale(scales: number[], deviceScale?: number): number;
+}
+
+// #endregion
+// #region customDirectEventTypes
+
+/** Registry mapping custom direct (non-bubbling) event names to their registration names. */
+export const customDirectEventTypes: {
+  [eventName: string]: Readonly<{
+    registrationName: string;
+  }>;
+};
+
+// #endregion
+// #region DevLoadingView
+
+/** Dev-only overlay banner showing bundle load, refresh, and error status. */
+export const DevLoadingView: {
+  showMessage(
+    message: string,
+    type: 'load' | 'refresh' | 'error',
+    options?: {dismissButton?: boolean | undefined},
+  ): void;
+  hide(): void;
+};
+
+// #endregion
+// #region getDevServer
+
+interface DevServerInfo {
+  url: string;
+  fullBundleUrl: string | null;
+  bundleLoadedFromServer: boolean;
+}
+
+/** Returns information about the running dev server. */
+export function getDevServer(): DevServerInfo;
+
+// #endregion
+// #region HMRClient
+
+/** Client that receives Fast Refresh updates and applies them at runtime. */
+export class HMRClient {
+  enable(): void;
+  disable(): void;
+  registerBundle(requestUrl: string): void;
+  log(
+    level:
+      | 'trace'
+      | 'info'
+      | 'warn'
+      | 'error'
+      | 'log'
+      | 'group'
+      | 'groupCollapsed'
+      | 'groupEnd'
+      | 'debug',
+    data: ReadonlyArray<unknown>,
+  ): void;
+  setup(
+    platform: string,
+    bundleEntry: string,
+    host: string,
+    port: number | string,
+    isEnabled: boolean,
+    scheme?: string,
+  ): void;
+}
+
+// #endregion
+// #region NativeExceptionsManager
+
+interface StackFrame {
+  column: number | null;
+  file: string | null;
+  lineNumber: number | null;
+  methodName: string;
+  collapse?: boolean | undefined;
+}
+
+interface ExceptionData {
+  message: string;
+  originalMessage: string | null;
+  name: string | null;
+  componentStack: string | null;
+  stack: StackFrame[];
+  id: number;
+  isFatal: boolean;
+  extraData?: object | undefined;
+}
+
+/** Reports JS exceptions to native and manages RedBox. */
+export const NativeExceptionsManager: {
+  reportFatalException(
+    message: string,
+    stack: StackFrame[],
+    exceptionId: number,
+  ): void;
+  reportSoftException(
+    message: string,
+    stack: StackFrame[],
+    exceptionId: number,
+  ): void;
+  dismissRedbox(): void;
+  reportException(data: ExceptionData): void;
+};
+
+// #endregion
+// #region NativeRedBox
+
+interface NativeRedBoxSpec {
+  setExtraData(extraData: object, forIdentifier: string): void;
+  dismiss(): void;
+}
+
+/** Native module for the RedBox error overlay; null when unavailable. */
+export const NativeRedBox: NativeRedBoxSpec | null;
+
+// #endregion
+// #region NativeSourceCode
+
+interface SourceCodeConstants {
+  scriptURL: string;
+}
+
+/** Native module exposing source-code constants such as the bundle scriptURL. */
+export const NativeSourceCode: {
+  getConstants(): SourceCodeConstants;
+};
+
+// #endregion
+// #region PressabilityDebugView
+
+type Rect = Readonly<{
+  bottom?: number | null | undefined;
+  left?: number | null | undefined;
+  right?: number | null | undefined;
+  top?: number | null | undefined;
+}>;
+
+type RectOrSize = Rect | number;
+
+interface PressabilityDebugViewProps {
+  color: unknown;
+  hitSlop: RectOrSize | null | undefined;
+}
+
+/** Debug overlay that visualizes press targets when enabled via the Inspector. */
+export const PressabilityDebugView: React.ComponentType<PressabilityDebugViewProps>;
+
+// #endregion

packages/react-native/src/unstable-internals-do-not-use.js

@@ -0,0 +1,76 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @noflow
+ * @format
+ */
+
+'use strict';
+'use client';
+
+// ----------------------------------------------------------------------------
+// react-native/unstable-internals-do-not-use
+//
+// UNSTABLE WITH NO SEMVER GUARANTEES.
+// SHOULD NOT BE DEPENDED ON BY NEW CODE.
+//
+// This is a secondary entry point for frameworks and libraries that depend on
+// specific React Native internals, serving as a compatibility bridge.
+//
+// Consuming codebases must opt in via tsconfig.json:
+//   "customConditions": ["react-native-unstable-internals"]
+//
+// Having this entry point:
+// - Maintains a known list of which React Native internals are in use.
+// - Enables us to relocate supporting files more freely.
+// - Gives us time to decide on the future of these APIs (independent from
+//   removal of the Strict API opt out).
+//
+// The long term future of these exports is to formalize/delete them where
+// appropriate, and collapse this entry point.
+//
+// Replaces RFC0985
+// https://github.com/react-native-community/discussions-and-proposals/pull/985
+// where we reviewed internal APIs used in the ecosystem.
+//
+// IMPORTANT: Keep this file in sync with unstable-internals-do-not-use.d.ts.
+// ----------------------------------------------------------------------------
+
+// eslint-disable-next-line @react-native/monorepo/no-commonjs-exports
+module.exports = {
+  get AppContainer() {
+    return require('../Libraries/ReactNative/AppContainer').default;
+  },
+  get AssetSourceResolver() {
+    return require('../Libraries/Image/AssetSourceResolver').default;
+  },
+  get customDirectEventTypes() {
+    return require('../Libraries/Renderer/shims/ReactNativeViewConfigRegistry')
+      .customDirectEventTypes;
+  },
+  get DevLoadingView() {
+    return require('../Libraries/Utilities/DevLoadingView').default;
+  },
+  get getDevServer() {
+    return require('../Libraries/Core/Devtools/getDevServer').default;
+  },
+  get HMRClient() {
+    return require('../Libraries/Utilities/HMRClient').default;
+  },
+  get NativeExceptionsManager() {
+    return require('../Libraries/Core/NativeExceptionsManager').default;
+  },
+  get NativeRedBox() {
+    return require('../Libraries/NativeModules/specs/NativeRedBox').default;
+  },
+  get NativeSourceCode() {
+    return require('../Libraries/NativeModules/specs/NativeSourceCode').default;
+  },
+  get PressabilityDebugView() {
+    return require('../Libraries/Pressability/PressabilityDebug')
+      .PressabilityDebugView;
+  },
+};