react-refresh 0.18.0: setSignature

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

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

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:87c8384a1ef67ad8811681507f4e56db09b3168e04682e6048aa8fbf531c60d0","constraints":{"executionContext":"node"},"contract":["setSignature registers a hook signature for a component and is idempotent preventing duplicate key overwrites","performReactRefresh includes family in updatedFamilies when re-registered component retains identical signature key","performReactRefresh marks family in staleFamilies when signature key changes between component versions","setSignature with forceReset flag set to true marks component family in staleFamilies even with matching signature keys","setSignature propagates recursively to inner render functions of React forwardRef and memo component wrappers","setSignature with custom hook getter incorporates nested hook signatures causing remount when nested hook signature changes"],"goal":"verify react-refresh.setSignature in pkg:npm/react-refresh@0.18.0","kind":"HOW","packages":["pkg:npm/react-refresh@0.18.0"],"schemaVersion":1,"symbols":["react-refresh.setSignature"]},"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.setSignature"],"verifierAdapter":"node-typescript@1"}

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

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

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);
}

/**
 * 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 or hook.
 *
 * @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);
}

/**
 * Collects and computes the full signature key including custom hook dependencies.
 *
 * @param {function|object} type
 */
export function collectCustomHooks(type) {
  RefreshRuntime.collectCustomHooksForSignature(type);
}

/**
 * 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();
}

/**
 * Retrieves a component family by its registered identifier.
 *
 * @param {string} id
 * @returns {{ current: any } | undefined}
 */
export function getFamilyByID(id) {
  return RefreshRuntime.getFamilyByID(id);
}

/**
 * Retrieves a component family by its current type reference.
 *
 * @param {function|object} type
 * @returns {{ current: any } | undefined}
 */
export function getFamilyByType(type) {
  return RefreshRuntime.getFamilyByType(type);
}

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

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

// Contract 1: setSignature registers a hook signature for a component and is idempotent preventing duplicate key overwrites
{
  function CounterV1() {
    return 1;
  }
  setComponentSignature(CounterV1, "useState{[count, setCount]}");
  // Calling setSignature again on the same type reference must be ignored (idempotent)
  setComponentSignature(CounterV1, "overwrittenSignatureKey");

  const familyV1 = registerComponent(CounterV1, "CounterComponentId");
  assert.ok(familyV1);
  assert.equal(familyV1.current, CounterV1);

  function CounterV2() {
    return 2;
  }
  // Matches original signature
  setComponentSignature(CounterV2, "useState{[count, setCount]}");
  registerComponent(CounterV2, "CounterComponentId");

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

// Contract 2: performReactRefresh includes family in updatedFamilies when re-registered component retains identical signature key
{
  function HeaderV1() {
    return "Header 1";
  }
  setComponentSignature(HeaderV1, "header-sig-key");
  const family = registerComponent(HeaderV1, "HeaderComponentId");
  triggerRefresh();

  function HeaderV2() {
    return "Header 2";
  }
  setComponentSignature(HeaderV2, "header-sig-key");
  registerComponent(HeaderV2, "HeaderComponentId");

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

// Contract 3: performReactRefresh marks family in staleFamilies when signature key changes between component versions
{
  function SidebarV1() {
    return "Sidebar 1";
  }
  setComponentSignature(SidebarV1, "useState{[open, setOpen]}");
  const family = registerComponent(SidebarV1, "SidebarComponentId");
  triggerRefresh();

  function SidebarV2() {
    return "Sidebar 2";
  }
  setComponentSignature(SidebarV2, "useState{[open, setOpen]}\nuseEffect{}");
  registerComponent(SidebarV2, "SidebarComponentId");

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

// Contract 4: setSignature with forceReset flag set to true marks component family in staleFamilies even with matching signature keys
{
  function ModalV1() {
    return "Modal 1";
  }
  setComponentSignature(ModalV1, "modal-sig-key");
  const family = registerComponent(ModalV1, "ModalComponentId");
  triggerRefresh();

  function ModalV2() {
    return "Modal 2";
  }
  setComponentSignature(ModalV2, "modal-sig-key", true);
  registerComponent(ModalV2, "ModalComponentId");

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

// Contract 5: setSignature propagates recursively to inner render functions of React forwardRef and memo component wrappers
{
  function InnerInput(props, ref) {
    return null;
  }
  const ForwardRefInputV1 = {
    $$typeof: Symbol.for("react.forward_ref"),
    render: InnerInput
  };
  setComponentSignature(ForwardRefInputV1, "input-sig-v1");
  registerComponent(ForwardRefInputV1, "InputWrapperId");
  triggerRefresh();

  function InnerInputV2(props, ref) {
    return null;
  }
  const ForwardRefInputV2 = {
    $$typeof: Symbol.for("react.forward_ref"),
    render: InnerInputV2
  };
  setComponentSignature(ForwardRefInputV2, "input-sig-v2");
  registerComponent(ForwardRefInputV2, "InputWrapperId");

  const refreshResult = triggerRefresh();
  assert.ok(refreshResult);

  const renderFamily = getFamilyByID("InputWrapperId$render");
  assert.ok(renderFamily);
  assert.equal(refreshResult.staleFamilies.has(renderFamily), true);

  function InnerButton() {
    return null;
  }
  const MemoButton = {
    $$typeof: Symbol.for("react.memo"),
    type: InnerButton
  };
  setComponentSignature(MemoButton, "memo-button-sig");
  registerComponent(MemoButton, "MemoButtonId");
  const memoInnerFamily = getFamilyByID("MemoButtonId$type");
  assert.ok(memoInnerFamily);
}

// Contract 6: setSignature with custom hook getter incorporates nested hook signatures causing remount when nested hook signature changes
{
  function useDataFetcherV1() {
    return "data1";
  }
  setComponentSignature(useDataFetcherV1, "fetch-cache-key-1");

  function DataWidgetV1() {
    return "Widget 1";
  }
  setComponentSignature(DataWidgetV1, "widget-key", false, () => [useDataFetcherV1]);
  const family = registerComponent(DataWidgetV1, "DataWidgetId");
  triggerRefresh();

  function useDataFetcherV2() {
    return "data2";
  }
  setComponentSignature(useDataFetcherV2, "fetch-cache-key-2");

  function DataWidgetV2() {
    return "Widget 2";
  }
  setComponentSignature(DataWidgetV2, "widget-key", false, () => [useDataFetcherV2]);
  collectCustomHooks(DataWidgetV2);
  registerComponent(DataWidgetV2, "DataWidgetId");

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

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