From 20bfc7bca8ef9966e8bfe1efa82e96915cabe11a Mon Sep 17 00:00:00 2001
From: Sebastian Markbage <sebastian@calyptus.eu>
Date: Thu, 25 Sep 2025 09:46:00 -0400
Subject: [PATCH 1/5] Track whether we're inside a <picture> or <noscript>

---
 .../src/server/ReactFlightServerConfigDOM.js  | 27 ++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/packages/react-dom-bindings/src/server/ReactFlightServerConfigDOM.js b/packages/react-dom-bindings/src/server/ReactFlightServerConfigDOM.js
index 75ed81bf6fe42..696382cb61b80 100644
--- a/packages/react-dom-bindings/src/server/ReactFlightServerConfigDOM.js
+++ b/packages/react-dom-bindings/src/server/ReactFlightServerConfigDOM.js
@@ -62,16 +62,37 @@ export function createHints(): Hints {
   return new Set();
 }
 
-export opaque type FormatContext = null;
+const NO_SCOPE = /*         */ 0b000000;
+const NOSCRIPT_SCOPE = /*   */ 0b000001;
+const PICTURE_SCOPE = /*    */ 0b000010;
+
+export opaque type FormatContext = number;
 
 export function createRootFormatContext(): FormatContext {
-  return null;
+  return NO_SCOPE;
 }
 
+function processImg(props: Object, formatContext: FormatContext): void {}
+
+function processLink(props: Object, formatContext: FormatContext): void {}
+
 export function getChildFormatContext(
   parentContext: FormatContext,
   type: string,
   props: Object,
 ): FormatContext {
-  return parentContext;
+  switch (type) {
+    case 'img':
+      processImg(props, parentContext);
+      return parentContext;
+    case 'link':
+      processLink(props, parentContext);
+      return parentContext;
+    case 'picture':
+      return parentContext | PICTURE_SCOPE;
+    case 'noscript':
+      return parentContext | NOSCRIPT_SCOPE;
+    default:
+      return parentContext;
+  }
 }

From f917c206ebec40afdaa071b7f8aaf9d8660af504 Mon Sep 17 00:00:00 2001
From: Sebastian Markbage <sebastian@calyptus.eu>
Date: Thu, 25 Sep 2025 12:06:10 -0400
Subject: [PATCH 2/5] Preload suspensey img

---
 .../ReactDOMFlightServerHostDispatcher.js     |  6 +-
 .../src/server/ReactFlightServerConfigDOM.js  | 61 ++++++++++++++++++-
 2 files changed, 63 insertions(+), 4 deletions(-)

diff --git a/packages/react-dom-bindings/src/server/ReactDOMFlightServerHostDispatcher.js b/packages/react-dom-bindings/src/server/ReactDOMFlightServerHostDispatcher.js
index c2a9227737edf..b22519c60508c 100644
--- a/packages/react-dom-bindings/src/server/ReactDOMFlightServerHostDispatcher.js
+++ b/packages/react-dom-bindings/src/server/ReactDOMFlightServerHostDispatcher.js
@@ -79,7 +79,11 @@ function preconnect(href: string, crossOrigin?: ?CrossOriginEnum) {
   }
 }
 
-function preload(href: string, as: string, options?: ?PreloadImplOptions) {
+export function preload(
+  href: string,
+  as: string,
+  options?: ?PreloadImplOptions,
+) {
   if (typeof href === 'string') {
     const request = resolveRequest();
     if (request) {
diff --git a/packages/react-dom-bindings/src/server/ReactFlightServerConfigDOM.js b/packages/react-dom-bindings/src/server/ReactFlightServerConfigDOM.js
index 696382cb61b80..8e5df8078d088 100644
--- a/packages/react-dom-bindings/src/server/ReactFlightServerConfigDOM.js
+++ b/packages/react-dom-bindings/src/server/ReactFlightServerConfigDOM.js
@@ -17,8 +17,10 @@ import type {
 } from 'react-dom/src/shared/ReactDOMTypes';
 
 // This module registers the host dispatcher so it needs to be imported
-// but it does not have any exports
-import './ReactDOMFlightServerHostDispatcher';
+// even if no exports are used.
+import {preload} from './ReactDOMFlightServerHostDispatcher';
+
+import {getCrossOriginString} from '../shared/crossOriginStrings';
 
 // We use zero to represent the absence of an explicit precedence because it is
 // small, smaller than how we encode undefined, and is unambiguous. We could use
@@ -72,7 +74,60 @@ export function createRootFormatContext(): FormatContext {
   return NO_SCOPE;
 }
 
-function processImg(props: Object, formatContext: FormatContext): void {}
+function processImg(props: Object, formatContext: FormatContext): void {
+  // This should mirror the login of pushImg in ReactFizzConfigDOM.
+  const pictureOrNoScriptTagInScope =
+    formatContext & (PICTURE_SCOPE | NOSCRIPT_SCOPE);
+  const {src, srcSet} = props;
+  if (
+    props.loading !== 'lazy' &&
+    (src || srcSet) &&
+    (typeof src === 'string' || src == null) &&
+    (typeof srcSet === 'string' || srcSet == null) &&
+    props.fetchPriority !== 'low' &&
+    !pictureOrNoScriptTagInScope &&
+    // We exclude data URIs in src and srcSet since these should not be preloaded
+    !(
+      typeof src === 'string' &&
+      src[4] === ':' &&
+      (src[0] === 'd' || src[0] === 'D') &&
+      (src[1] === 'a' || src[1] === 'A') &&
+      (src[2] === 't' || src[2] === 'T') &&
+      (src[3] === 'a' || src[3] === 'A')
+    ) &&
+    !(
+      typeof srcSet === 'string' &&
+      srcSet[4] === ':' &&
+      (srcSet[0] === 'd' || srcSet[0] === 'D') &&
+      (srcSet[1] === 'a' || srcSet[1] === 'A') &&
+      (srcSet[2] === 't' || srcSet[2] === 'T') &&
+      (srcSet[3] === 'a' || srcSet[3] === 'A')
+    )
+  ) {
+    // We have a suspensey image and ought to preload it to optimize the loading of display blocking
+    // resumableState.
+    const sizes = typeof props.sizes === 'string' ? props.sizes : undefined;
+
+    const crossOrigin = getCrossOriginString(props.crossOrigin);
+
+    preload(
+      // The preload() API requires a href but if we have an imageSrcSet then that will take precedence.
+      // We already remove the href anyway in both Fizz and Fiber due to a Safari bug so the empty string
+      // will never actually appear in the DOM.
+      src || '',
+      'image',
+      {
+        imageSrcSet: srcSet,
+        imageSizes: sizes,
+        crossOrigin: crossOrigin,
+        integrity: props.integrity,
+        type: props.type,
+        fetchPriority: props.fetchPriority,
+        referrerPolicy: props.referrerPolicy,
+      },
+    );
+  }
+}
 
 function processLink(props: Object, formatContext: FormatContext): void {}
 

From dee5a7d3693d122fa4879e1fcf83c1175280b50b Mon Sep 17 00:00:00 2001
From: Sebastian Markbage <sebastian@calyptus.eu>
Date: Thu, 25 Sep 2025 19:24:42 -0400
Subject: [PATCH 3/5] Preload <link> resources

This includes all resources. Not just hoistable and not just suspensey CSS
since they will all start loading early regardless of where they are
in the viewport anyway.
---
 .../ReactDOMFlightServerHostDispatcher.js     |  5 +-
 .../src/server/ReactFlightServerConfigDOM.js  | 56 ++++++++++++++++++-
 2 files changed, 58 insertions(+), 3 deletions(-)

diff --git a/packages/react-dom-bindings/src/server/ReactDOMFlightServerHostDispatcher.js b/packages/react-dom-bindings/src/server/ReactDOMFlightServerHostDispatcher.js
index b22519c60508c..49c555f43f813 100644
--- a/packages/react-dom-bindings/src/server/ReactDOMFlightServerHostDispatcher.js
+++ b/packages/react-dom-bindings/src/server/ReactDOMFlightServerHostDispatcher.js
@@ -116,7 +116,10 @@ export function preload(
   }
 }
 
-function preloadModule(href: string, options?: ?PreloadModuleImplOptions) {
+export function preloadModule(
+  href: string,
+  options?: ?PreloadModuleImplOptions,
+): void {
   if (typeof href === 'string') {
     const request = resolveRequest();
     if (request) {
diff --git a/packages/react-dom-bindings/src/server/ReactFlightServerConfigDOM.js b/packages/react-dom-bindings/src/server/ReactFlightServerConfigDOM.js
index 8e5df8078d088..8b022476483c1 100644
--- a/packages/react-dom-bindings/src/server/ReactFlightServerConfigDOM.js
+++ b/packages/react-dom-bindings/src/server/ReactFlightServerConfigDOM.js
@@ -18,7 +18,7 @@ import type {
 
 // This module registers the host dispatcher so it needs to be imported
 // even if no exports are used.
-import {preload} from './ReactDOMFlightServerHostDispatcher';
+import {preload, preloadModule} from './ReactDOMFlightServerHostDispatcher';
 
 import {getCrossOriginString} from '../shared/crossOriginStrings';
 
@@ -129,7 +129,59 @@ function processImg(props: Object, formatContext: FormatContext): void {
   }
 }
 
-function processLink(props: Object, formatContext: FormatContext): void {}
+function processLink(props: Object, formatContext: FormatContext): void {
+  const noscriptTagInScope = formatContext & NOSCRIPT_SCOPE;
+  const rel = props.rel;
+  const href = props.href;
+  if (
+    noscriptTagInScope ||
+    props.itemProp != null ||
+    typeof rel !== 'string' ||
+    typeof href !== 'string' ||
+    href === ''
+  ) {
+    // We shouldn't preload resources that are in noscript or have no configuration.
+    return;
+  }
+
+  switch (rel) {
+    case 'preload': {
+      preload(href, props.as, {
+        crossOrigin: props.crossOrigin,
+        integrity: props.integrity,
+        nonce: props.nonce,
+        type: props.type,
+        fetchPriority: props.fetchPriority,
+        referrerPolicy: props.referrerPolicy,
+        imageSrcSet: props.imageSrcSet,
+        imageSizes: props.imageSizes,
+        media: props.media,
+      });
+      return;
+    }
+    case 'modulepreload': {
+      preloadModule(href, {
+        as: props.as,
+        crossOrigin: props.crossOrigin,
+        integrity: props.integrity,
+        nonce: props.nonce,
+      });
+      return;
+    }
+    case 'stylesheet': {
+      preload(href, 'stylesheet', {
+        crossOrigin: props.crossOrigin,
+        integrity: props.integrity,
+        nonce: props.nonce,
+        type: props.type,
+        fetchPriority: props.fetchPriority,
+        referrerPolicy: props.referrerPolicy,
+        media: props.media,
+      });
+      return;
+    }
+  }
+}
 
 export function getChildFormatContext(
   parentContext: FormatContext,

From 05137bbbdbb90b58ad483282552cbbc9469e7d2a Mon Sep 17 00:00:00 2001
From: Sebastian Markbage <sebastian@calyptus.eu>
Date: Thu, 25 Sep 2025 21:04:59 -0400
Subject: [PATCH 4/5] Add test

---
 .../src/__tests__/ReactFlightDOM-test.js      | 102 ++++++++++++++++++
 1 file changed, 102 insertions(+)

diff --git a/packages/react-server-dom-webpack/src/__tests__/ReactFlightDOM-test.js b/packages/react-server-dom-webpack/src/__tests__/ReactFlightDOM-test.js
index 9754a7f51c3b5..97869cf0bea28 100644
--- a/packages/react-server-dom-webpack/src/__tests__/ReactFlightDOM-test.js
+++ b/packages/react-server-dom-webpack/src/__tests__/ReactFlightDOM-test.js
@@ -47,6 +47,9 @@ describe('ReactFlightDOM', () => {
     // condition
     jest.resetModules();
 
+    // Some of the tests pollute the head.
+    document.head.innerHTML = '';
+
     JSDOM = require('jsdom').JSDOM;
 
     patchSetImmediate();
@@ -1998,6 +2001,105 @@ describe('ReactFlightDOM', () => {
     expect(hintRows.length).toEqual(6);
   });
 
+  it('preloads resources without needing to render them', async () => {
+    function NoScriptComponent() {
+      return (
+        <p>
+          <img src="image-do-not-load" />
+          <link rel="stylesheet" href="css-do-not-load" />
+        </p>
+      );
+    }
+
+    function Component() {
+      return (
+        <div>
+          <img src="image-resource" />
+          <img
+            src="image-do-not-load"
+            srcSet="image-preload-src-set"
+            sizes="image-sizes"
+          />
+          <img src="image-do-not-load" loading="lazy" />
+          <link
+            rel="preload"
+            href="video-resource"
+            as="video"
+            media="(orientation: landscape)"
+          />
+          <link rel="modulepreload" href="module-resource" />
+          <picture>
+            <source
+              srcSet="image-not-yet-preloaded"
+              media="(orientation: portrait)"
+            />
+            <img src="image-do-not-load" />
+          </picture>
+          <noscript>
+            <NoScriptComponent />
+          </noscript>
+          <link rel="stylesheet" href="css-resource" />
+        </div>
+      );
+    }
+
+    const {writable, readable} = getTestStream();
+    const {pipe} = await serverAct(() =>
+      ReactServerDOMServer.renderToPipeableStream(<Component />, webpackMap),
+    );
+    pipe(writable);
+
+    let response = null;
+    function getResponse() {
+      if (response === null) {
+        response = ReactServerDOMClient.createFromReadableStream(readable);
+      }
+      return response;
+    }
+
+    function App() {
+      // Not rendered but use for its side-effects.
+      getResponse();
+      return (
+        <html>
+          <body>
+            <p>hello world</p>
+          </body>
+        </html>
+      );
+    }
+
+    const root = ReactDOMClient.createRoot(document);
+    await act(() => {
+      root.render(<App />);
+    });
+
+    expect(getMeaningfulChildren(document)).toEqual(
+      <html>
+        <head>
+          <link rel="preload" as="image" href="image-resource" />
+          <link
+            rel="preload"
+            as="image"
+            imagesrcset="image-preload-src-set"
+            imagesizes="image-sizes"
+          />
+          <link
+            rel="preload"
+            as="video"
+            href="video-resource"
+            media="(orientation: landscape)"
+          />
+          <link rel="modulepreload" href="module-resource" />
+          <link rel="preload" as="stylesheet" href="css-resource" />
+        </head>
+        <body>
+          <p>hello world</p>
+        </body>
+      </html>,
+    );
+  });
+
   it('should be able to include a client reference in printed errors', async () => {
     const reportedErrors = [];
 

From b1636f3beeccacda73d9bd8bf89893ab59eda1d4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebastian=20Markb=C3=A5ge?= <sebastian@calyptus.eu>
Date: Thu, 25 Sep 2025 23:44:04 -0400
Subject: [PATCH 5/5] Comment

Co-authored-by: Josh Story <josh.c.story@gmail.com>
---
 .../react-dom-bindings/src/server/ReactFlightServerConfigDOM.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react-dom-bindings/src/server/ReactFlightServerConfigDOM.js b/packages/react-dom-bindings/src/server/ReactFlightServerConfigDOM.js
index 8b022476483c1..1c9b4763f5201 100644
--- a/packages/react-dom-bindings/src/server/ReactFlightServerConfigDOM.js
+++ b/packages/react-dom-bindings/src/server/ReactFlightServerConfigDOM.js
@@ -75,7 +75,7 @@ export function createRootFormatContext(): FormatContext {
 }
 
 function processImg(props: Object, formatContext: FormatContext): void {
-  // This should mirror the login of pushImg in ReactFizzConfigDOM.
+  // This should mirror the logic of pushImg in ReactFizzConfigDOM.
   const pictureOrNoScriptTagInScope =
     formatContext & (PICTURE_SCOPE | NOSCRIPT_SCOPE);
   const {src, srcSet} = props;