react-dom 19.2.8: createRoot

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.createRoot in pkg:npm/react-dom@19.2.8
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/react-dom@19.2.8
Demonstrate these symbols/APIs:
  - react-dom.createRoot
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - 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:d9496e6fcfe5ab3997699bae365d3712325a2191d36d20d7af569784940a3b9d","constraints":{"executionContext":"node"},"contract":["createRoot is exported as a function from react-dom/client","createRoot(null) and createRoot({}) throw Error 'Target container is not a DOM element.'","createRoot(container) returns a root object with render and unmount methods","root.render(element) renders React elements into the target DOM container","root.unmount() unmounts the rendered tree and clears the container contents","createRoot accepts optional configuration including identifierPrefix for React useId hooks"],"goal":"verify react-dom.createRoot in pkg:npm/react-dom@19.2.8","kind":"HOW","packages":["pkg:npm/react-dom@19.2.8"],"schemaVersion":1,"symbols":["react-dom.createRoot"]},"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.2.8"],"schemaVersion":1,"subject":"pkg:npm/react-dom@19.2.8","symbols":["react-dom.createRoot"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-react-dom-createroot",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-react-dom-createroot",
      "version": "1.0.0",
      "dependencies": {
        "react": "19.2.8",
        "react-dom": "19.2.8"
      }
    },
    "node_modules/react": {
      "version": "19.2.8",
      "resolved": "https://registry.npmjs.org/react/-/react-19.2.8.tgz",
      "integrity": "sha512-PWaYA1L/q9u2u7xYQi+Y3L3Yfnie7XyLeaJICV1MGD6LprsBxcAqGjYyr0eY3p+QdsA+x/Irkt4Qif8D63+Sbw==",
      "license": "MIT",
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/react-dom": {
      "version": "19.2.8",
      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.8.tgz",
      "integrity": "sha512-rVprimfGBG3DR+Tq0IQG2DT5PxKth1WIGDmj5yPmlzr4YBe7uyE+Du4oVqTDXZSHGGGXRtTJEGSSePyQCMBglQ==",
      "license": "MIT",
      "dependencies": {
        "scheduler": "^0.27.0"
      },
      "peerDependencies": {
        "react": "^19.2.8"
      }
    },
    "node_modules/scheduler": {
      "version": "0.27.0",
      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.27.0.tgz",
      "integrity": "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-react-dom-createroot",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "react": "19.2.8",
    "react-dom": "19.2.8"
  }
}

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

import { createRoot } from "react-dom/client";

/**
 * Creates and mounts a React root into a DOM container element.
 *
 * @param {Element|Document|DocumentFragment} container
 * @param {import("react").ReactNode} element
 * @param {object} [options]
 * @returns {{ root: object, unmount: () => void }}
 */
export function createAndMountRoot(container, element, options = {}) {
  const root = createRoot(container, options);
  root.render(element);
  return {
    root,
    unmount: () => root.unmount()
  };
}

export { createRoot };

import assert from "node:assert/strict";
import React from "react";
import { createRoot } from "react-dom/client";
import { flushSync } from "react-dom";
import { createAndMountRoot } from "../src/index.mjs";

// Setup minimal offline DOM environment for Node.js
class Node {}
class Element extends Node {}
class HTMLElement extends Element {}
class HTMLIFrameElement extends HTMLElement {}
class Document extends Node {}
class DocumentFragment extends Node {}

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

function createMockDocument() {
  const docListeners = new Map();
  const doc = {
    nodeType: 9,
    nodeName: "#document",
    activeElement: null,
    defaultView: window,
    createElement(tag) {
      const elListeners = new Map();
      const elChildren = [];
      const el = {
        nodeType: 1,
        nodeName: tag.toUpperCase(),
        tagName: tag.toUpperCase(),
        childNodes: elChildren,
        children: elChildren,
        style: {},
        ownerDocument: doc,
        setAttribute(k, v) { this[k] = v; },
        getAttribute(k) { return this[k] || null; },
        appendChild(child) { elChildren.push(child); return child; },
        removeChild(child) {
          const idx = elChildren.indexOf(child);
          if (idx >= 0) elChildren.splice(idx, 1);
          return child;
        },
        insertBefore(newChild, refChild) {
          const idx = elChildren.indexOf(refChild);
          if (idx >= 0) elChildren.splice(idx, 0, newChild);
          else elChildren.push(newChild);
          return newChild;
        },
        addEventListener(event, handler) {
          if (!elListeners.has(event)) elListeners.set(event, []);
          elListeners.get(event).push(handler);
        },
        removeEventListener(event, handler) {
          if (elListeners.has(event)) {
            const arr = elListeners.get(event);
            const idx = arr.indexOf(handler);
            if (idx >= 0) arr.splice(idx, 1);
          }
        }
      };
      return el;
    },
    createTextNode(text) {
      return {
        nodeType: 3,
        nodeName: "#text",
        nodeValue: String(text),
        textContent: String(text),
        ownerDocument: doc
      };
    },
    createComment(data) {
      return {
        nodeType: 8,
        nodeName: "#comment",
        nodeValue: String(data),
        ownerDocument: doc
      };
    },
    addEventListener(event, handler) {
      if (!docListeners.has(event)) docListeners.set(event, []);
      docListeners.get(event).push(handler);
    },
    removeEventListener(event, handler) {
      if (docListeners.has(event)) {
        const arr = docListeners.get(event);
        const idx = arr.indexOf(handler);
        if (idx >= 0) arr.splice(idx, 1);
      }
    }
  };
  window.document = doc;
  return doc;
}

const doc = createMockDocument();
globalThis.document = doc;

// 1. Symbol availability
assert.strictEqual(typeof createRoot, "function", "createRoot must be exported as a function");

// 2. Error handling for invalid containers
assert.throws(
  () => createRoot(null),
  /Target container is not a DOM element/,
  "createRoot(null) must throw Target container is not a DOM element"
);
assert.throws(
  () => createRoot({}),
  /Target container is not a DOM element/,
  "createRoot({}) must throw Target container is not a DOM element"
);

// 3. Create root on valid DOM element
const container = doc.createElement("div");
const root = createRoot(container);
assert.strictEqual(typeof root.render, "function", "root must have a render method");
assert.strictEqual(typeof root.unmount, "function", "root must have an unmount method");

// 4. Render element into container
flushSync(() => {
  root.render(React.createElement("span", { id: "test-node" }, "React 19 createRoot verified"));
});
assert.strictEqual(container.childNodes.length, 1, "Container should have 1 child node after render");
assert.strictEqual(container.childNodes[0].tagName, "SPAN", "Rendered child tag should be SPAN");

// 5. Unmount root
flushSync(() => {
  root.unmount();
});
assert.strictEqual(container.childNodes.length, 0, "Container should have 0 children after unmount");

// 6. Options support (e.g., identifierPrefix)
const optContainer = doc.createElement("div");
const optRoot = createRoot(optContainer, {
  identifierPrefix: "custom-prefix-"
});

function AppWithId() {
  const generatedId = React.useId();
  return React.createElement("div", { id: generatedId }, "Component with ID");
}

flushSync(() => {
  optRoot.render(React.createElement(AppWithId));
});

assert.strictEqual(optContainer.childNodes.length, 1, "Option container should have 1 child");
assert.ok(
  optContainer.childNodes[0].id && optContainer.childNodes[0].id.includes("custom-prefix-"),
  "Generated ID should contain identifierPrefix"
);

flushSync(() => {
  optRoot.unmount();
});
assert.strictEqual(optContainer.childNodes.length, 0, "Option container should be empty after unmount");

// 7. Test helper module
const helperContainer = doc.createElement("div");
let helperHandle;
flushSync(() => {
  helperHandle = createAndMountRoot(
    helperContainer,
    React.createElement("p", null, "Mounted via helper")
  );
});
assert.strictEqual(helperContainer.childNodes.length, 1, "Helper container should have 1 child");
flushSync(() => {
  helperHandle.unmount();
});
assert.strictEqual(helperContainer.childNodes.length, 0, "Helper container should be empty after unmount");

console.log("All contract assertions passed successfully.");