react-refresh 0.17.0: performReactRefresh

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-refresh.performReactRefresh in pkg:npm/react-refresh@0.17.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/react-refresh@0.17.0
Demonstrate these symbols/APIs:
  - react-refresh.performReactRefresh

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:6848f78713956fb384b4862a1be7c99b21daf3de7750b9fd1ff0610a721f5e37","contract":["performReactRefresh returns null when no pending component updates exist","register queues pending updates when registering a new component type with an existing ID","performReactRefresh applies pending updates to component families and returns an update object with updatedFamilies","performReactRefresh clears pending updates so subsequent calls return null","performReactRefresh notifies injected DevTools renderer refresh handlers of updated family resolutions"],"goal":"verify react-refresh.performReactRefresh in pkg:npm/react-refresh@0.17.0","kind":"HOW","packages":["pkg:npm/react-refresh@0.17.0"],"schemaVersion":1,"symbols":["react-refresh.performReactRefresh"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/react-refresh@0.17.0"],"schemaVersion":1,"subject":"pkg:npm/react-refresh@0.17.0","symbols":["react-refresh.performReactRefresh"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-react-refresh-perform-react-refresh",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-react-refresh-perform-react-refresh",
      "version": "1.0.0",
      "dependencies": {
        "react-refresh": "0.17.0"
      }
    },
    "node_modules/react-refresh": {
      "version": "0.17.0",
      "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.17.0.tgz",
      "integrity": "sha512-z6F7K9bV85EfseRCp2bzrpyQ0Gkw1uLoCel9XBVWPg/TjRj94SkJzUTGfOa4bs7iJvBWtQG0Wq7wnI0syw3EBQ==",
      "license": "MIT",
      "engines": {
        "node": ">=0.10.0"
      }
    }
  }
}

{
  "name": "sample-react-refresh-perform-react-refresh",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of react-refresh.performReactRefresh in react-refresh",
  "type": "module",
  "main": "src/index.js",
  "dependencies": {
    "react-refresh": "0.17.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify react-refresh.performReactRefresh in pkg:npm/react-refresh@0.17.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/react-refresh@0.17.0"
  ],
  "symbols": [
    "react-refresh.performReactRefresh"
  ]
}

import RefreshRuntime from 'react-refresh/runtime';

const {
  performReactRefresh,
  register,
  setSignature,
  injectIntoGlobalHook,
  getFamilyByID,
  getFamilyByType,
  isLikelyComponentType,
} = RefreshRuntime;

/**
 * Executes a pending React Refresh pass.
 *
 * @returns {object|null} The refresh update object containing updatedFamilies and staleFamilies, or null if no updates.
 */
export function executeReactRefresh() {
  return performReactRefresh();
}

/**
 * Registers a component type with an identifier for hot reloading.
 *
 * @param {Function|object} type - Component type.
 * @param {string} id - Component identifier.
 */
export function registerComponent(type, id) {
  register(type, id);
}

/**
 * Inspects the registered family for a component identifier.
 *
 * @param {string} id - Component identifier.
 * @returns {object|undefined} Component family object.
 */
export function getComponentFamily(id) {
  return getFamilyByID(id);
}

/**
 * Injects React DevTools hook helpers for refresh testing.
 *
 * @param {object} globalObject - Target global object.
 */
export function setupRefreshHook(globalObject) {
  injectIntoGlobalHook(globalObject);
}

export {
  performReactRefresh,
  register,
  setSignature,
  injectIntoGlobalHook,
  getFamilyByID,
  getFamilyByType,
  isLikelyComponentType,
};

import assert from 'node:assert/strict';
import {
  executeReactRefresh,
  registerComponent,
  getComponentFamily,
  setupRefreshHook,
  performReactRefresh,
  register,
  getFamilyByID,
  getFamilyByType,
} from '../src/index.js';

// 1. Symbol and function export verification
assert.equal(typeof performReactRefresh, 'function', 'performReactRefresh must be exported as a function');
assert.equal(typeof register, 'function', 'register must be exported as a function');
assert.equal(typeof executeReactRefresh, 'function', 'executeReactRefresh wrapper must be a function');
assert.equal(typeof registerComponent, 'function', 'registerComponent wrapper must be a function');

// 2. Initial state returns null when no updates are queued
const initialResult = performReactRefresh();
assert.equal(initialResult, null, 'performReactRefresh returns null when no pending component updates exist');

const wrapperNoopResult = executeReactRefresh();
assert.equal(wrapperNoopResult, null, 'executeReactRefresh returns null when no pending component updates exist');

// 3. Register first version of a component family
function HeaderV1() {
  return 'Header version 1';
}
registerComponent(HeaderV1, 'HeaderComponent');

const headerFamily = getComponentFamily('HeaderComponent');
assert.ok(headerFamily, 'Component family should be created for HeaderComponent');
assert.equal(headerFamily.current, HeaderV1, 'Family current pointer should initially reference HeaderV1');
assert.equal(getFamilyByType(HeaderV1), headerFamily, 'getFamilyByType should map HeaderV1 to the created family');

// Registering initial version does not queue a pending update
assert.equal(performReactRefresh(), null, 'performReactRefresh returns null when only initial registration occurred');

// 4. Register updated version with the same ID - queues pending update
function HeaderV2() {
  return 'Header version 2';
}
registerComponent(HeaderV2, 'HeaderComponent');

// 5. performReactRefresh applies update and returns update object
const updateResult = performReactRefresh();
assert.ok(updateResult, 'performReactRefresh must return an update object when updates are pending');
assert.ok(updateResult.updatedFamilies instanceof Set, 'updatedFamilies must be an instance of Set');
assert.ok(updateResult.staleFamilies instanceof Set, 'staleFamilies must be an instance of Set');
assert.equal(updateResult.updatedFamilies.has(headerFamily), true, 'updatedFamilies must contain the modified HeaderComponent family');
assert.equal(headerFamily.current, HeaderV2, 'Component family current pointer must update to HeaderV2');
assert.equal(getFamilyByType(HeaderV2), headerFamily, 'getFamilyByType should resolve HeaderV2 to the updated family');

// 6. performReactRefresh clears pending updates
assert.equal(performReactRefresh(), null, 'performReactRefresh clears pending updates so subsequent calls return null');

// 7. DevTools global hook integration and renderer refresh handler notification
const mockRenderer = {
  scheduleRefresh: (root, update) => {},
  setRefreshHandler: (handler) => {
    mockRenderer.refreshHandler = handler;
  },
};

const fakeGlobal = {};
setupRefreshHook(fakeGlobal);
assert.ok(fakeGlobal.__REACT_DEVTOOLS_GLOBAL_HOOK__, 'DevTools global hook should be created');
assert.equal(typeof fakeGlobal.__REACT_DEVTOOLS_GLOBAL_HOOK__.inject, 'function', 'Global hook inject must be a function');

fakeGlobal.__REACT_DEVTOOLS_GLOBAL_HOOK__.inject(mockRenderer);

function HeaderV3() {
  return 'Header version 3';
}
register(HeaderV3, 'HeaderComponent');

const rendererUpdate = executeReactRefresh();
assert.ok(rendererUpdate, 'executeReactRefresh should return update object');
assert.equal(typeof mockRenderer.refreshHandler, 'function', 'setRefreshHandler must be called on registered renderer');
assert.equal(mockRenderer.refreshHandler(HeaderV1), headerFamily, 'refreshHandler must resolve original HeaderV1 to family');
assert.equal(mockRenderer.refreshHandler(HeaderV2), headerFamily, 'refreshHandler must resolve intermediate HeaderV2 to family');
assert.equal(mockRenderer.refreshHandler(HeaderV3), headerFamily, 'refreshHandler must resolve current HeaderV3 to family');
assert.equal(headerFamily.current, HeaderV3, 'Family current pointer must point to HeaderV3');

console.log('Contract tests passed successfully.');