react-refresh 0.17.0: default

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.default 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.default

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:aeb39258529f6a0cc8394403698510b3450d964952b3913bc2ad9e661550ff48","contract":["default import provides Fast Refresh runtime functions including isLikelyComponentType, injectIntoGlobalHook, register, setSignature, and performReactRefresh","default export isLikelyComponentType identifies function components, class components, memo components, and forwardRef components while rejecting non-component types","default export injectIntoGlobalHook initializes React DevTools hook and tracks renderer registration and mounted root count","default export register associates component types with unique IDs and preserves family identity across getFamilyByID and getFamilyByType","default export performReactRefresh updates component families when signatures match and marks modified signatures as stale"],"goal":"verify react-refresh.default in pkg:npm/react-refresh@0.17.0","kind":"HOW","packages":["pkg:npm/react-refresh@0.17.0"],"schemaVersion":1,"symbols":["react-refresh.default"]},"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.default"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-react-refresh-default",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-react-refresh-default",
      "version": "1.0.0",
      "license": "MIT-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-default",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "react-refresh": "0.17.0"
  }
}

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

import ReactRefresh from "react-refresh";

export const RefreshRuntime = ReactRefresh;

/**
 * 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 ReactRefresh from "react-refresh";
import {
  RefreshRuntime,
  isComponentType,
  setupDevToolsHook,
  registerComponent,
  setComponentSignature,
  createSignatureTracker,
  triggerRefresh
} from "../src/index.mjs";

// Contract 1: default import provides Fast Refresh runtime functions including isLikelyComponentType, injectIntoGlobalHook, register, setSignature, and performReactRefresh
{
  assert.ok(ReactRefresh, "default export must be present");
  assert.equal(typeof ReactRefresh, "object", "default export must be an object");
  assert.equal(RefreshRuntime, ReactRefresh, "RefreshRuntime should match default import");
  assert.equal(typeof ReactRefresh.isLikelyComponentType, "function");
  assert.equal(typeof ReactRefresh.injectIntoGlobalHook, "function");
  assert.equal(typeof ReactRefresh.register, "function");
  assert.equal(typeof ReactRefresh.setSignature, "function");
  assert.equal(typeof ReactRefresh.performReactRefresh, "function");
  assert.equal(typeof ReactRefresh.createSignatureFunctionForTransform, "function");
  assert.equal(typeof ReactRefresh.getFamilyByID, "function");
  assert.equal(typeof ReactRefresh.getFamilyByType, "function");
  assert.equal(typeof ReactRefresh.hasUnrecoverableErrors, "function");
  assert.equal(ReactRefresh.hasUnrecoverableErrors(), false);
}

// Contract 2: default export isLikelyComponentType identifies function components, class components, memo components, and forwardRef components while rejecting non-component types
{
  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(ReactRefresh.isLikelyComponentType(FunctionalComponent), true);
  assert.equal(isComponentType(ClassComponent), true);
  assert.equal(ReactRefresh.isLikelyComponentType(ClassComponent), true);
  assert.equal(isComponentType(memoComponent), true);
  assert.equal(ReactRefresh.isLikelyComponentType(memoComponent), true);
  assert.equal(isComponentType(forwardRefComponent), true);
  assert.equal(ReactRefresh.isLikelyComponentType(forwardRefComponent), true);

  assert.equal(isComponentType(helperFunction), false);
  assert.equal(ReactRefresh.isLikelyComponentType(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 3: default export injectIntoGlobalHook initializes React DevTools hook and tracks renderer registration and mounted root count
{
  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 4: default export register associates component types with unique IDs and preserves family identity across getFamilyByID and getFamilyByType
{
  function ButtonComponentV1() {
    return "Button V1";
  }

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

// Contract 5: default export performReactRefresh updates component families when signatures match and marks modified signatures as stale
{
  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);

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

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

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

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