react-dom 19.0.0: preconnect

# React 19 react-dom.preconnect Contract Verification

## Prior CSX search
`search_known_solution` returned `NO_SAFE_MATCH` for explicit verification of `react-dom.preconnect` in `pkg:npm/react-dom@19.0.0`. While existing samples verified other React 19 DOM capabilities (e.g. `createRoot`, `hydrateRoot`, and broad multi-API resource preloading), this sample establishes a minimal, clean contract for `preconnect`.

## The tempting wrong model
1. Assuming `preconnect` requires manual DOM manipulation (e.g. `document.createElement('link')`) or third-party `<head>` management packages like `react-helmet`.
2. Assuming redundant `preconnect` calls across sibling or nested components will emit duplicated `<link rel="preconnect">` elements in SSR markup or `document.head`.
3. Expecting `preconnect(href)` called outside an active React rendering cycle to mutate DOM head elements immediately (it requires an active render context).
4. Forgetting that `crossOrigin: "anonymous"` emits `crossorigin=""` on the `<link>` element in HTML/DOM.

## Observable failure and verified behavior
- Calling `preconnect(href)` or `preconnect(href, { crossOrigin })` during SSR automatically hoists `<link rel="preconnect">` tags to the start of the output HTML markup.
- In client DOM rendering, calling `preconnect` during root rendering dynamically injects the appropriate `<link rel="preconnect">` element into `document.head`.
- Duplicate calls for the exact same destination URL (and options) within the render tree are deduplicated by the React 19 DOM runtime in both SSR and client environments.
- The `crossOrigin` option properly distinguishes between `'anonymous'` (yielding `crossorigin=""`) and `'use-credentials'` (yielding `crossorigin="use-credentials"`).

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify react-dom.preconnect in pkg:npm/react-dom@19.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/react-dom@19.0.0
Demonstrate these symbols/APIs:
  - react-dom.preconnect
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - runtime: node@22.23.2

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:ae70ee3415bfcbdfbae3d50610a1d941f2d610063716fa4a4563439f13f32aa3","constraints":{"executionContext":"node"},"contract":["preconnect is exported as a function from react-dom","preconnect emits hoisted link rel preconnect in ReactDOMServer renderToStaticMarkup","preconnect supports crossOrigin options anonymous and use-credentials during SSR","duplicate preconnect calls across components in the render tree are deduplicated during SSR","preconnect injects link rel preconnect elements into document.head during client root render","duplicate preconnect calls during client root render are deduplicated in document.head"],"goal":"verify react-dom.preconnect in pkg:npm/react-dom@19.0.0","kind":"HOW","packages":["pkg:npm/react-dom@19.0.0"],"schemaVersion":1,"symbols":["react-dom.preconnect"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/react-dom@19.0.0"],"schemaVersion":1,"subject":"pkg:npm/react-dom@19.0.0","symbols":["react-dom.preconnect"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-react-dom-preconnect",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-react-dom-preconnect",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "react": "19.0.0",
        "react-dom": "19.0.0"
      }
    },
    "node_modules/react": {
      "version": "19.0.0",
      "resolved": "https://registry.npmjs.org/react/-/react-19.0.0.tgz",
      "integrity": "sha512-V8AVnmPIICiWpGfm6GLzCR/W5FXLchHop40W4nXBmdlEceh16rCN8O8LNWm5bh5XUX91fh7KpA+W0TgMKmgTpQ==",
      "license": "MIT",
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/react-dom": {
      "version": "19.0.0",
      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.0.0.tgz",
      "integrity": "sha512-4GV5sHFG0e/0AD4X+ySy6UJd3jVl1iNsNHdpad0qhABJ11twS3TTBnseqsKurKcsNqCEFeGL3uLpVChpIO3QfQ==",
      "license": "MIT",
      "dependencies": {
        "scheduler": "^0.25.0"
      },
      "peerDependencies": {
        "react": "^19.0.0"
      }
    },
    "node_modules/scheduler": {
      "version": "0.25.0",
      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.25.0.tgz",
      "integrity": "sha512-xFVuu11jh+xcO7JOAGJNOXld8/TcEHK/4CituBUeUb5hqxJLj9YuemAEuvm9gQ/+pgXYfbQuqAkiYu+u7YEsNA==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-react-dom-preconnect",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "react": "19.0.0",
    "react-dom": "19.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify react-dom.preconnect in pkg:npm/react-dom@19.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/react-dom@19.0.0"
  ],
  "symbols": [
    "react-dom.preconnect"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "runtime": "node@22.23.2"
  }
}

import React from 'react';
import { preconnect } from 'react-dom';

/**
 * Component that registers a preconnect resource hint during rendering.
 *
 * @param {object} props
 * @param {string} props.href - Destination origin URL to establish early connection to.
 * @param {'anonymous' | 'use-credentials'} [props.crossOrigin] - Cross-origin credential policy.
 * @returns {import('react').ReactElement}
 */
export function PreconnectHint({ href, crossOrigin }) {
  if (href) {
    if (crossOrigin) {
      preconnect(href, { crossOrigin });
    } else {
      preconnect(href);
    }
  }
  return React.createElement('meta', { 'data-testid': 'preconnect-hint-marker' });
}

/**
 * Helper to preconnect multiple origins within a React component render tree.
 *
 * @param {object} props
 * @param {Array<{ href: string, crossOrigin?: 'anonymous' | 'use-credentials' }>} props.connections
 * @returns {null}
 */
export function PreconnectList({ connections = [] }) {
  for (const conn of connections) {
    if (conn && conn.href) {
      if (conn.crossOrigin) {
        preconnect(conn.href, { crossOrigin: conn.crossOrigin });
      } else {
        preconnect(conn.href);
      }
    }
  }
  return null;
}

export { preconnect };

import assert from 'node:assert/strict';

// Set up minimal self-contained DOM environment for Node.js offline execution
class Node {}
class Element extends Node {}
class HTMLElement extends Element {}
class HTMLIFrameElement extends HTMLElement {}
class Document extends Node {}
class DocumentFragment extends Node {}

const headElements = [];
const head = {
  nodeType: 1,
  tagName: 'HEAD',
  nodeName: 'HEAD',
  childNodes: headElements,
  children: headElements,
  ownerDocument: null,
  appendChild(child) {
    headElements.push(child);
    child.parentNode = head;
    return child;
  },
  insertBefore(newChild, refChild) {
    const idx = headElements.indexOf(refChild);
    if (idx >= 0) headElements.splice(idx, 0, newChild);
    else headElements.push(newChild);
    newChild.parentNode = head;
    return newChild;
  },
  removeChild(child) {
    const idx = headElements.indexOf(child);
    if (idx >= 0) headElements.splice(idx, 1);
    child.parentNode = null;
    return child;
  }
};

const window = {
  event: undefined,
  Node,
  Element,
  HTMLElement,
  HTMLIFrameElement,
  Document,
  DocumentFragment
};

function createElement(tag) {
  const elChildren = [];
  const attrs = {};
  const el = {
    nodeType: 1,
    nodeName: tag.toUpperCase(),
    tagName: tag.toUpperCase(),
    childNodes: elChildren,
    children: elChildren,
    parentNode: null,
    style: {},
    ownerDocument: doc,
    setAttribute(k, v) {
      attrs[k.toLowerCase()] = String(v);
      this[k] = v;
    },
    getAttribute(k) {
      return attrs[k.toLowerCase()] ?? this[k] ?? null;
    },
    appendChild(child) {
      elChildren.push(child);
      child.parentNode = el;
      return child;
    },
    removeChild(child) {
      const idx = elChildren.indexOf(child);
      if (idx >= 0) elChildren.splice(idx, 1);
      child.parentNode = null;
      return child;
    },
    insertBefore(newChild, refChild) {
      const idx = elChildren.indexOf(refChild);
      if (idx >= 0) elChildren.splice(idx, 0, newChild);
      else elChildren.push(newChild);
      newChild.parentNode = el;
      return newChild;
    },
    addEventListener() {},
    removeEventListener() {}
  };
  return el;
}

const doc = {
  nodeType: 9,
  nodeName: '#document',
  activeElement: null,
  defaultView: window,
  head: head,
  querySelector(sel) {
    return headElements.find(el => {
      if (sel.includes('link') && el.tagName !== 'LINK') return false;
      const relMatch = sel.match(/rel="([^"]+)"/);
      if (relMatch && el.rel !== relMatch[1]) return false;
      const hrefMatch = sel.match(/href="([^"]+)"/);
      if (hrefMatch && el.href !== hrefMatch[1]) return false;
      const crossMatch = sel.match(/crossorigin="([^"]+)"/);
      if (crossMatch && el.getAttribute('crossorigin') !== crossMatch[1]) return false;
      return true;
    }) || null;
  },
  querySelectorAll(sel) {
    return headElements.filter(el => {
      if (sel.includes('link') && el.tagName !== 'LINK') return false;
      const relMatch = sel.match(/rel="([^"]+)"/);
      if (relMatch && el.rel !== relMatch[1]) return false;
      const hrefMatch = sel.match(/href="([^"]+)"/);
      if (hrefMatch && el.href !== hrefMatch[1]) return false;
      return true;
    });
  },
  createElement,
  createTextNode(text) {
    return {
      nodeType: 3,
      nodeName: '#text',
      nodeValue: String(text),
      textContent: String(text),
      parentNode: null,
      ownerDocument: doc
    };
  },
  createComment(data) {
    return {
      nodeType: 8,
      nodeName: '#comment',
      nodeValue: String(data),
      parentNode: null,
      ownerDocument: doc
    };
  },
  addEventListener() {},
  removeEventListener() {}
};

head.ownerDocument = doc;
window.document = doc;
globalThis.window = window;
globalThis.document = doc;
globalThis.Node = Node;
globalThis.Element = Element;
globalThis.HTMLElement = HTMLElement;
globalThis.HTMLIFrameElement = HTMLIFrameElement;
globalThis.Document = Document;
globalThis.DocumentFragment = DocumentFragment;

const React = await import('react');
const ReactDOM = await import('react-dom');
const ReactDOMServer = await import('react-dom/server');
const ReactDOMClient = await import('react-dom/client');
const { PreconnectHint, PreconnectList, preconnect } = await import('../src/index.mjs');
const { flushSync } = ReactDOM;

// Contract Assertion 1: preconnect is exported as a function from react-dom
assert.strictEqual(typeof preconnect, 'function', 'preconnect must be exported as a function from react-dom');
assert.strictEqual(typeof ReactDOM.preconnect, 'function', 'ReactDOM.preconnect must be exported from react-dom');

// Contract Assertion 2 & 3: preconnect emits hoisted link rel preconnect in ReactDOMServer renderToStaticMarkup,
// and supports crossOrigin options anonymous and use-credentials during SSR
function SSRDemo() {
  return React.createElement(
    'div',
    null,
    React.createElement(PreconnectHint, { href: 'https://api.example.com' }),
    React.createElement(PreconnectHint, { href: 'https://cdn.example.com', crossOrigin: 'anonymous' }),
    React.createElement(PreconnectHint, { href: 'https://auth.example.com', crossOrigin: 'use-credentials' }),
    React.createElement('main', null, 'SSR Content')
  );
}

const staticHtml = ReactDOMServer.renderToStaticMarkup(React.createElement(SSRDemo));
assert.ok(
  staticHtml.includes('<link rel="preconnect" href="https://api.example.com"/>'),
  'SSR markup must emit hoisted preconnect link tag without crossorigin attribute'
);
assert.ok(
  staticHtml.includes('<link rel="preconnect" href="https://cdn.example.com" crossorigin=""/>'),
  'SSR markup must emit hoisted preconnect link with crossorigin="" for anonymous mode'
);
assert.ok(
  staticHtml.includes('<link rel="preconnect" href="https://auth.example.com" crossorigin="use-credentials"/>'),
  'SSR markup must emit hoisted preconnect link with crossorigin="use-credentials"'
);

// Contract Assertion 4: duplicate preconnect calls across components in the render tree are deduplicated during SSR
function SSRDuplicateDemo() {
  return React.createElement(
    'section',
    null,
    React.createElement(PreconnectHint, { href: 'https://shared.example.com' }),
    React.createElement(PreconnectHint, { href: 'https://shared.example.com' }),
    React.createElement(PreconnectList, {
      connections: [
        { href: 'https://shared.example.com' },
        { href: 'https://list-item.example.com' },
      ],
    })
  );
}

const dupHtml = ReactDOMServer.renderToStaticMarkup(React.createElement(SSRDuplicateDemo));
const sharedOccurrences = dupHtml.match(/https:\/\/shared\.example\.com/g);
assert.strictEqual(
  sharedOccurrences.length,
  1,
  'Duplicate preconnect calls for identical href must be deduplicated in SSR output'
);
assert.ok(
  dupHtml.includes('<link rel="preconnect" href="https://list-item.example.com"/>'),
  'PreconnectList must emit preconnect hints in SSR'
);

// Contract Assertion 5: preconnect injects link rel preconnect elements into document.head during client root render
function ClientDemo() {
  return React.createElement(
    'div',
    null,
    React.createElement(PreconnectHint, {
      href: 'https://client-api.example.com',
      crossOrigin: 'use-credentials',
    }),
    React.createElement('span', null, 'Mounted Client Component')
  );
}

const container = doc.createElement('div');
const root = ReactDOMClient.createRoot(container);
flushSync(() => {
  root.render(React.createElement(ClientDemo));
});

const clientLinks = headElements.filter(el => el.href === 'https://client-api.example.com');
assert.strictEqual(clientLinks.length, 1, 'Client root render must inject link element into document.head');
assert.strictEqual(clientLinks[0].tagName, 'LINK', 'Injected element must be a LINK tag');
assert.strictEqual(clientLinks[0].rel, 'preconnect', 'Injected element rel attribute must be preconnect');
assert.strictEqual(
  clientLinks[0].getAttribute('crossorigin'),
  'use-credentials',
  'Injected element crossorigin attribute must be use-credentials'
);

// Contract Assertion 6: duplicate preconnect calls during client root render are deduplicated in document.head
function ClientDuplicateDemo() {
  return React.createElement(
    'div',
    null,
    React.createElement(PreconnectHint, {
      href: 'https://client-api.example.com',
      crossOrigin: 'use-credentials',
    }),
    React.createElement(PreconnectHint, {
      href: 'https://client-api.example.com',
      crossOrigin: 'use-credentials',
    }),
    React.createElement('span', null, 'Duplicate Preconnect Mount')
  );
}

flushSync(() => {
  root.render(React.createElement(ClientDuplicateDemo));
});

const dedupClientLinks = headElements.filter(el => el.href === 'https://client-api.example.com');
assert.strictEqual(
  dedupClientLinks.length,
  1,
  'Duplicate preconnect calls across client render tree must be deduplicated in document.head'
);

root.unmount();

console.log('CONTRACT PASS: react-dom.preconnect verified');