feat(image): manually register host and promote optimizer to default

Author: mfkrause

apps/docs/content/docs/configuration/configure.mdx

@@ -23,20 +23,14 @@ module.exports = {
         optimizations: {
           text: true,
           view: true,
-          image: false,
+          image: true,
         },
       },
     ],
   ],
 };
 ```
 
-`Image` optimization is currently **opt-in** because it depends on deprecated React Native import paths. Enabling it will log React Native import deprecation warnings to the console. To enable it, explicitly flip it to `true`:
-
-```js
-['react-native-boost/plugin', { optimizations: { image: true } }];
-```
-
 ## Plugin Options
 
 <AutoOptionSections path="../../packages/react-native-boost/src/plugin/types/index.ts" name="PluginOptions" idPrefix="plugin-options" />

apps/docs/content/docs/index.mdx

@@ -9,7 +9,7 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs'
 
 React Native Boost consists of two pieces:
 
-- A Babel plugin that statically analyzes your source code and replaces safe `Text` and `View` components with their direct native counterparts, leading to significant performance improvements compared to the JS-based wrapper components.
+- A Babel plugin that statically analyzes your source code and replaces safe `Text`, `View`, and `Image` components with their direct native counterparts, leading to significant performance improvements compared to the JS-based wrapper components.
 - A runtime package used internally by the plugin for cross-platform-safe imports and helper utilities.
 
 The analyzer is intentionally strict and skips any optimizations that may lead to user-facing bugs and behavioral changes.

apps/docs/content/docs/information/deep-dive.mdx

@@ -210,9 +210,9 @@ Fewer fibers means less for React to build, diff, and commit on every frame (som
 
 ## What Boost emits
 
-Boost's core move is to swap the JSX element's type from `Text`/`View` to `NativeText`/`NativeView`
-(imported from `react-native-boost/runtime`), after reproducing (at *build time*) whatever inescapable
-work the wrapper would have done for the specific element.
+Boost's core move is to swap the JSX element's type from `Text`/`View`/`Image` to
+`NativeText`/`NativeView`/`NativeImage` (imported from `react-native-boost/runtime`), after reproducing
+(at *build time*) whatever inescapable work the wrapper would have done for the specific element.
 
 ### Text
 
@@ -284,21 +284,27 @@ Dynamic values, or `aria-*` state/value groups that the wrapper merges, are rout
 <_NativeView {..._processViewAccessibilityProps(Object.assign({}, { 'aria-label': label }))} />;
 ```
 
+### Image
+
+`Image` source, style, and accessibility props are normalized before Boost swaps the wrapper for
+`NativeImage`. Static values are processed at build time. Dynamic values use small runtime helpers.
+Compared to `Text` and `View`, the host component for `Image` is not imported directly. React Native does not export it through a supported interface, and only exports it through deprecated deep imports which log warnings when used. The plugin therefore registers the `RCTImageView` host directly.
+
 For the complete matrix of what's optimized, translated, and skipped, see
 [Coverage & Bailouts](/docs/information/optimization-coverage).
 
 ## Inside the plugin
 
-The plugin is a single Babel visitor on `JSXOpeningElement`. For each element it runs the `Text`
-optimizer and the `View` optimizer; each follows the same shape.
+The plugin is a single Babel visitor on `JSXOpeningElement`. For each element it runs the `Text`,
+`View`, and `Image` optimizers; each follows the same shape.
 
 <Mermaid
   chart={`flowchart TD
-  el["JSXOpeningElement (Text or View)"] --> g{"Resolves to the react-native component?"}
+  el["JSXOpeningElement (Text, View, or Image)"] --> g{"Resolves to the react-native component?"}
   g -- no --> skip["Leave unchanged"]
   g -- yes --> b{"Does any bailout check fail?"}
   b -- "yes, and no @boost-force" --> skip
-  b -- "no, or @boost-force" --> rw["Rewrite props, swap type to NativeText / NativeView"]
+  b -- "no, or @boost-force" --> rw["Rewrite props, swap type to its native host"]
   rw --> imp["Inject the runtime import (cached once per file)"]`}
 />
 
@@ -323,9 +329,9 @@ to a string/number; `<Text>{maybeJSX()}</Text>` is not.
 
 ### Ancestor classification
 
-The most intricate check is shared by both optimizers. An element nested inside a `Text` must render as
-the *inline* host (`RCTVirtualText`), not the *block* host — so before optimizing, the plugin walks **up**
-the tree and classifies the ancestor chain as one of:
+The most intricate check is shared by all three optimizers. Components under a `Text` can need different
+host semantics. A nested `Text` uses `RCTVirtualText`, and Android uses a separate inline Image host.
+Before optimizing, the plugin therefore walks **up** the tree and classifies the ancestor chain as one of:
 
 - `safe` — no `Text` ancestor anywhere up the chain → optimize.
 - `text` — a `react-native` `Text` is an ancestor → skip.
@@ -338,8 +344,8 @@ it can't prove safety, it returns `unknown` and bails. False-positives (a missed
 false-negatives (a regression).
 
 The `unknown` case is *often* safe in practice (third-party components rarely wrap children in `Text`), but there are still cases where optimizing components with an `unknown` ancestor could genuinely cause regressions. Therefore, Boost provides
-explicit opt-in escape hatches: `dangerouslyOptimizeViewWithUnknownAncestors` and
-`dangerouslyOptimizeTextWithUnknownAncestors` (see [Configuration](/docs/configuration/configure)).
+explicit opt-in escape hatches: `dangerouslyOptimizeViewWithUnknownAncestors`, 
+`dangerouslyOptimizeTextWithUnknownAncestors` and `dangerouslyOptimizeImageWithUnknownAncestors` (see [Configuration](/docs/configuration/configure)).
 
 ### Rewriting and import injection
 
@@ -353,6 +359,7 @@ even though the visitor fires thousands of times, each runtime symbol is importe
 API lives on the [Runtime Library](/docs/runtime-library) page. The most load-bearing pieces are:
 
 - **`NativeText` / `NativeView`** resolve `unstable_NativeText` / `unstable_NativeView` from `react-native` at module load, and **gracefully fall back** to the standard `Text`/`View` on web or any runtime where these exports are missing.
+- **`NativeImage`** loads React Native's public `Image` module to register its host, then renders the registered `RCTImageView` name directly. Web uses the standard `Image` component.
 - **`processTextStyle(style)`** does the same flatten-and-normalize work as the wrapper, with one small difference: it **caches by reference in a `WeakMap`**. When you pass a `StyleSheet.create` reference, the first call flattens it and every later call returns the cached result. The wrapper re-flattens on every render. (Only stable references hit the cache; an inline `style={{…}}` is a fresh reference each render, so it re-flattens either way.)
 - **`processAccessibilityProps(props)`** mirrors `Text`'s `aria-*` translation, `accessibilityState` merge, `disabled` reconciliation, and platform `accessible` default. It runs only when the element actually has accessibility props.
 - **`processViewAccessibilityProps(props)`** does the same for `View`'s ARIA cluster (`aria-labelledby` split, live-region mapping, state/value aggregation, `tabIndex` → `focusable`).

apps/docs/content/docs/information/how-it-works.mdx

@@ -3,15 +3,15 @@ title: How It Works
 description: Why React Native Boost makes your app faster (the short version).
 ---
 
-In React Native, `Text` and `View` aren't quite what they appear to be. They look like basic building blocks, but each one is a small JavaScript component that runs **every time it renders**, wrapping a lower-level native component underneath.
+In React Native, `Text`, `View`, and `Image` aren't quite what they appear to be. They look like basic building blocks, but each one is a small JavaScript component that runs **every time it renders**, wrapping a lower-level native component underneath.
 
-That wrapper is genuinely useful. It handles a lot of edge cases and powers conveniences like `aria-*` props, `userSelect`, and clamping `numberOfLines`. But most of the time your `Text` or `View` uses none of that, and the wrapper's work is pure overhead. On a busy screen with hundreds of these components, that overhead adds up and starts costing you frames.
+That wrapper is genuinely useful. It handles edge cases and powers conveniences such as accessibility props, style normalization, and Image source processing. But many elements do not need that runtime work, so the wrapper becomes pure overhead. On a busy screen with hundreds of these components, that overhead adds up and starts costing you frames.
 
 React Native Boost removes the wrapper when it isn't needed.
 
 ## The one-sentence version
 
-At build time, Boost rewrites `Text` and `View` elements into the native components they were going to render anyway. The work the wrapper used to repeat on every render is either gone completely, or moved from the user's device to build-time.
+At build time, Boost rewrites `Text`, `View`, and `Image` elements into the native components they were going to render anyway. The work the wrapper used to repeat on every render is either gone completely, or moved from the user's device to build-time.
 
 ## A quick before and after
 
@@ -29,7 +29,7 @@ These optimized components are imported from `react-native-boost/runtime` rather
 
 ## Only when it's safe
 
-Boost never changes how your app looks or behaves. It rewrites a component only when it can **prove** that doing so is safe. For each `Text` or `View` it checks a lot of things. For example:
+Boost never changes how your app looks or behaves. It rewrites a component only when it can **prove** that doing so is safe. For each supported component it checks a lot of things. For example:
 
 - Is this really the `react-native` component, or some other `Text` from another library?
 - Are its props fully compatible with the underlying native component?

apps/docs/content/docs/information/optimization-coverage.mdx

@@ -11,7 +11,7 @@ React Native Boost is conservative by design. If it cannot prove an optimization
 | --- | --- | --- |
 | `Text` | Imported from `react-native`, no blacklisted props, primitive children, safe ancestor chain | `contains blacklisted props`, `has Text ancestor`, `has unresolved ancestor and dangerous optimization is disabled`, `contains non-primitive children`, `is a direct child of expo-router Link with asChild` |
 | `View` | Imported from `react-native`, safe ancestor chain, no spread that may carry a translated prop | `has a spread that may carry a translated prop`, `has both a dynamic id and a nativeID (ambiguous precedence)`, `has Text ancestor`, `has unresolved ancestor and dangerous optimization is disabled` |
-| `Image` | Opted in with `optimizations.image: true`, imported from `react-native`, native platform known, supported source/style props, safe ancestor chain | `target platform is unknown`, `has a Unistyles style and there is no lean Image host to route to`, `has an unresolved style source that may be a Unistyles style`, `contains unsupported Image props`, `has a spread that may carry Image wrapper props`, `has Text ancestor`, `has unresolved ancestor and dangerous optimization is disabled` |
+| `Image` | Imported from `react-native`, native platform known, supported source/style props, safe ancestor chain | `target platform is unknown`, `has a Unistyles style and there is no lean Image host to route to`, `has an unresolved style source that may be a Unistyles style`, `contains unsupported Image props`, `has a spread that may carry Image wrapper props`, `has Text ancestor`, `has unresolved ancestor and dangerous optimization is disabled` |
 
 ## Global Bailouts
 
@@ -113,9 +113,7 @@ Set `dangerouslyOptimizeViewWithUnknownAncestors: true` to optimize `unknown` an
 
 ## Image Coverage
 
-`Image` optimization is opt-in for now because it uses deprecated React Native deep imports, which may print deprecation warnings. See [Configure the Babel Plugin](/docs/configuration/configure).
-
-The optimizer rewrites supported `Image` elements when the target platform is known (`ios` or `android`) and the
+The `Image` optimizer rewrites supported `Image` elements when the target platform is known (`ios` or `android`) and the
 source/style/accessibility props can be reproduced safely.
 
 In Unistyles mode, an Image is skipped when its `style` is (or may be) a Unistyles style.

packages/react-native-boost/src/plugin/__tests__/parity/boost.ts

@@ -32,7 +32,7 @@ function transformBoostCase(os: PlatformOS, jsxBody: string, preamble = ''): str
     filename: 'boost-case.jsx',
     caller: { name: 'metro', platform: os } as TransformCaller,
     presets: [['@babel/preset-react', { runtime: 'automatic' }]],
-    plugins: [[boostPlugin, { silent: true, optimizations: { image: true } }]],
+    plugins: [[boostPlugin, { silent: true }]],
   });
   return out!.code!;
 }

packages/react-native-boost/src/plugin/index.ts

@@ -50,7 +50,7 @@ export default declare((api, rawOptions, dirname?: string) => {
         if (isIgnoredFile(path, options.ignores ?? [])) return;
         if (options.optimizations?.text !== false) textOptimizer(path, logger, options, platform, unistylesEnabled);
         if (options.optimizations?.view !== false) viewOptimizer(path, logger, options, platform, unistylesEnabled);
-        if (options.optimizations?.image === true) imageOptimizer(path, logger, options, platform, unistylesEnabled);
+        if (options.optimizations?.image !== false) imageOptimizer(path, logger, options, platform, unistylesEnabled);
       },
     },
   };

packages/react-native-boost/src/plugin/optimizers/image/__tests__/index.test.ts

@@ -132,35 +132,6 @@ pluginTester({
   ],
 });
 
-describe('image plugin option', () => {
-  it('keeps Image optimization opt-in in the full plugin', async () => {
-    const source = `
-      import { Image } from 'react-native';
-      <Image source={{ uri: 'logo.png', width: 16, height: 16 }} />;
-    `;
-
-    const defaultOutput = await formatTestResult(
-      transformSync(source, {
-        configFile: false,
-        babelrc: false,
-        caller: { name: 'metro', platform: 'ios' } as TransformCaller,
-        plugins: ['@babel/plugin-syntax-jsx', [boostPlugin, { silent: true }]],
-      })!.code!
-    );
-    const enabledOutput = await formatTestResult(
-      transformSync(source, {
-        configFile: false,
-        babelrc: false,
-        caller: { name: 'metro', platform: 'ios' } as TransformCaller,
-        plugins: ['@babel/plugin-syntax-jsx', [boostPlugin, { silent: true, optimizations: { image: true } }]],
-      })!.code!
-    );
-
-    expect(defaultOutput).not.toContain('NativeImage');
-    expect(enabledOutput).toContain('NativeImage');
-  });
-});
-
 describe('image android output', () => {
   it('emits Android top-level empty headers for src sources', async () => {
     const output = await transformImage(

packages/react-native-boost/src/plugin/types/index.ts

@@ -13,10 +13,7 @@ export interface PluginOptimizationOptions {
   view?: boolean;
   /**
    * Whether to optimize the `Image` component.
-   *
-   * Uses deprecated React Native deep imports and may print React Native deep-import deprecation
-   * warnings, so it is opt-in for now.
-   * @default false
+   * @default true
    */
   image?: boolean;
 }
@@ -48,7 +45,7 @@ export interface PluginOptions {
   /**
    * Toggle individual optimizers.
    *
-   * If omitted, `Text` and `View` are enabled and `Image` stays disabled.
+   * If omitted, all optimizers are enabled.
    */
   optimizations?: PluginOptimizationOptions;
   /**

packages/react-native-boost/src/plugin/utils/generate-test-plugin.ts

@@ -49,7 +49,7 @@ export const generateCombinedTestPlugin = (options: PluginOptions = {}, platform
         JSXOpeningElement(path) {
           textOptimizer(path, logger, options, platform, unistylesEnabled);
           viewOptimizer(path, logger, options, platform, unistylesEnabled);
-          if (options.optimizations?.image === true) imageOptimizer(path, logger, options, platform, unistylesEnabled);
+          if (options.optimizations?.image !== false) imageOptimizer(path, logger, options, platform, unistylesEnabled);
         },
       },
     };