react-refresh 0.18.0: runtime

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 pkg:npm/react-refresh@0.18.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/react-refresh@0.18.0
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:81c3a8ad759fd45ff1a7a38907fa57250054a4ef3c5daac55a1bcff89fdf49de","constraints":{"executionContext":"node"},"contract":["isLikelyComponentType identifies valid React component functions, class components, and memo/forwardRef objects while rejecting primitives and helper functions","injectIntoGlobalHook initializes React DevTools hook and tracks renderer injection and mounted fiber roots","register establishes component family association accessible via getFamilyByID and getFamilyByType","performReactRefresh updates component family to new implementation and returns updatedFamilies when hook signatures match","performReactRefresh marks family as stale in staleFamilies when hook signature changes or forceReset is set"],"goal":"verify pkg:npm/react-refresh@0.18.0","kind":"HOW","packages":["pkg:npm/react-refresh@0.18.0"],"schemaVersion":1,"symbols":["react-refresh/runtime"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","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-refresh@0.18.0"],"schemaVersion":1,"subject":"pkg:npm/react-refresh@0.18.0","symbols":["react-refresh/runtime"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-react-refresh",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-react-refresh",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "react-refresh": "0.18.0"
      }
    },
    "node_modules/react-refresh": {
      "version": "0.18.0",
      "resolved": "https://registry.npmjs.org/react-refresh/-/react-refresh-0.18.0.tgz",
      "integrity": "sha512-QgT5//D3jfjJb6Gsjxv0Slpj23ip+HtOpnNgnb2S5zU3CB26G/IDPGoy4RJB42wzFE46DRsstbW6tKHoKbhAxw==",
      "license": "MIT",
      "engines": {
        "node": ">=0.10.0"
      }
    }
  }
}

{
  "name": "sample-react-refresh",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "react-refresh": "0.18.0"
  }
}

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

import refreshRuntimeModule from "react-refresh/runtime";

export const RefreshRuntime =
  refreshRuntimeModule && typeof refreshRuntimeModule === "object" && "default" in refreshRuntimeModule
    ? refreshRuntimeModule.default
    : refreshRuntimeModule;

/**
 * Checks whether a given type is recognized by React Refresh as a component.
 *
 * @param {any} type
 * @returns {boolean}
 */
export function isComponentType(type) {
  return RefreshRuntime.isLikelyComponentType(type);
}

/**
 * Injects React Refresh runtime into a global hook container, establishing
 * devtools hooks for renderer registration and root commit tracking.
 *
 * @param {object} [globalScope={}]
 * @returns {{ hook: object, getMountedRootCount: () => number }}
 */
export function setupDevToolsHook(globalScope = {}) {
  RefreshRuntime.injectIntoGlobalHook(globalScope);
  return {
    hook: globalScope.__REACT_DEVTOOLS_GLOBAL_HOOK__,
    getMountedRootCount: () => RefreshRuntime._getMountedRootCount()
  };
}

/**
 * Registers a component type with a persistent identifier and retrieves its family.
 *
 * @param {function|object} type
 * @param {string} id
 * @returns {{ current: any }}
 */
export function registerComponent(type, id) {
  RefreshRuntime.register(type, id);
  return RefreshRuntime.getFamilyByID(id);
}

/**
 * Sets up signature tracking for a component type.
 *
 * @param {function|object} type
 * @param {string} key
 * @param {boolean} [forceReset=false]
 * @param {function} [getCustomHooks]
 */
export function setComponentSignature(type, key, forceReset = false, getCustomHooks) {
  RefreshRuntime.setSignature(type, key, forceReset, getCustomHooks);
}

/**
 * Creates a signature function as generated by Babel transforms.
 *
 * @returns {function}
 */
export function createSignatureTracker() {
  return RefreshRuntime.createSignatureFunctionForTransform();
}

/**
 * Triggers a Fast Refresh reconciliation cycle across registered components and renderers.
 *
 * @returns {{ updatedFamilies: Set<object>, staleFamilies: Set<object> } | null}
 */
export function triggerRefresh() {
  return RefreshRuntime.performReactRefresh();
}

import assert from "node:assert/strict";
import refreshRuntimeModule from "react-refresh/runtime";
import {
  RefreshRuntime,
  isComponentType,
  setupDevToolsHook,
  registerComponent,
  setComponentSignature,
  createSignatureTracker,
  triggerRefresh
} from "../src/index.mjs";

const rawRuntime =
  refreshRuntimeModule && typeof refreshRuntimeModule === "object" && "default" in refreshRuntimeModule
    ? refreshRuntimeModule.default
    : refreshRuntimeModule;

// Contract 1: isLikelyComponentType identifies valid React component functions, class components, and memo/forwardRef objects while rejecting primitives and helper functions
{
  function FunctionalComponent() {
    return null;
  }
  function helperFunction() {
    return false;
  }
  class ClassComponent {
    render() {
      return null;
    }
  }
  ClassComponent.prototype.isReactComponent = {};

  const memoComponent = {
    $$typeof: Symbol.for("react.memo"),
    type: FunctionalComponent
  };
  const forwardRefComponent = {
    $$typeof: Symbol.for("react.forward_ref"),
    render: (props, ref) => null
  };

  assert.equal(isComponentType(FunctionalComponent), true);
  assert.equal(rawRuntime.isLikelyComponentType(FunctionalComponent), true);
  assert.equal(isComponentType(ClassComponent), true);
  assert.equal(isComponentType(memoComponent), true);
  assert.equal(isComponentType(forwardRefComponent), true);

  assert.equal(isComponentType(helperFunction), false);
  assert.equal(isComponentType(null), false);
  assert.equal(isComponentType(undefined), false);
  assert.equal(isComponentType(42), false);
  assert.equal(isComponentType("ComponentName"), false);
  assert.equal(isComponentType({}), false);
}

// Contract 2: injectIntoGlobalHook initializes React DevTools hook and tracks renderer injection and mounted fiber roots
{
  const mockGlobal = {};
  const { hook, getMountedRootCount } = setupDevToolsHook(mockGlobal);

  assert.ok(hook);
  assert.equal(typeof hook.inject, "function");
  assert.equal(typeof hook.onCommitFiberRoot, "function");
  assert.equal(typeof hook.onScheduleFiberRoot, "function");

  let scheduledRefreshCalls = 0;
  let refreshHandlerFn = null;
  const rendererId = hook.inject({
    scheduleRefresh: () => {
      scheduledRefreshCalls++;
    },
    setRefreshHandler: (fn) => {
      refreshHandlerFn = fn;
    }
  });
  assert.equal(typeof rendererId, "number");

  const initialRoots = getMountedRootCount();
  const mockFiberRoot = {
    current: {
      alternate: null,
      memoizedState: { element: true }
    }
  };
  hook.onCommitFiberRoot(rendererId, mockFiberRoot, null, false);
  assert.equal(getMountedRootCount(), initialRoots + 1);
}

// Contract 3: register establishes component family association accessible via getFamilyByID and getFamilyByType
{
  function ButtonComponentV1() {
    return "Button V1";
  }

  const family = registerComponent(ButtonComponentV1, "ButtonComponentID");
  assert.ok(family);
  assert.equal(family.current, ButtonComponentV1);
  assert.equal(RefreshRuntime.getFamilyByID("ButtonComponentID"), family);
  assert.equal(RefreshRuntime.getFamilyByType(ButtonComponentV1), family);
}

// Contract 4: performReactRefresh updates component family to new implementation and returns updatedFamilies when hook signatures match
{
  const tracker = createSignatureTracker();

  function ProfileCardV1() {
    tracker();
    return "Profile V1";
  }
  tracker(ProfileCardV1, "useState{[name, setName]('user')}");
  const family = registerComponent(ProfileCardV1, "ProfileCardID");

  function ProfileCardV2() {
    tracker();
    return "Profile V2";
  }
  tracker(ProfileCardV2, "useState{[name, setName]('user')}");
  registerComponent(ProfileCardV2, "ProfileCardID");

  const refreshResult = triggerRefresh();
  assert.ok(refreshResult);
  assert.equal(refreshResult.updatedFamilies.has(family), true);
  assert.equal(refreshResult.staleFamilies.has(family), false);
  assert.equal(family.current, ProfileCardV2);
}

// Contract 5: performReactRefresh marks family as stale in staleFamilies when hook signature changes or forceReset is set
{
  const tracker = createSignatureTracker();

  function NavigationBarV1() {
    tracker();
    return "Nav V1";
  }
  tracker(NavigationBarV1, "useState{[theme, setTheme]('light')}");
  const family = registerComponent(NavigationBarV1, "NavigationBarID");
  triggerRefresh();

  function NavigationBarV2() {
    tracker();
    return "Nav V2";
  }
  // Signature changed to useEffect
  tracker(NavigationBarV2, "useEffect{}");
  registerComponent(NavigationBarV2, "NavigationBarID");

  const refreshResult = triggerRefresh();
  assert.ok(refreshResult);
  assert.equal(refreshResult.staleFamilies.has(family), true);
  assert.equal(refreshResult.updatedFamilies.has(family), false);
  assert.equal(family.current, NavigationBarV2);
}

console.log("All react-refresh/runtime contract tests passed successfully.");