react-refresh 0.17.0: createSignatureFunctionForTransform

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

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:26a66c16e665ceeadfbf6577a285f401d9a867cdcc52895d065b1029222b27ea","contract":["createSignatureFunctionForTransform returns a signature transform function","signature function called with string key associates signature with component and returns the component","signature function handles null and primitive values safely without error","signature function called without arguments executes getCustomHooks callback to collect nested hook signatures","performReactRefresh updates component family without remounting when signature key is unchanged","performReactRefresh marks component family as stale when signature key changes or forceReset is true","signature registration propagates to wrapped components for memo and forwardRef"],"goal":"verify react-refresh.createSignatureFunctionForTransform in pkg:npm/react-refresh@0.17.0","kind":"HOW","packages":["pkg:npm/react-refresh@0.17.0"],"schemaVersion":1,"symbols":["react-refresh.createSignatureFunctionForTransform"]},"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.createSignatureFunctionForTransform"],"verifierAdapter":"node-typescript@1"}

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

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

import refreshRuntimeModule from "react-refresh/runtime";

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

/**
 * Creates a signature function used by compiler transforms to record hook signatures.
 *
 * @returns {Function}
 */
export function createSignatureFunctionForTransform() {
  return RefreshRuntime.createSignatureFunctionForTransform();
}

/**
 * Registers a component type with a stable identifier in the Fast Refresh runtime.
 *
 * @param {Function|object} type
 * @param {string} id
 */
export function register(type, id) {
  RefreshRuntime.register(type, id);
}

/**
 * Triggers a React Refresh update pass, resolving pending registrations
 * and returning sets of updated and stale families.
 *
 * @returns {object|null}
 */
export function performReactRefresh() {
  return RefreshRuntime.performReactRefresh();
}

/**
 * Returns the family object associated with a given component family identifier.
 *
 * @param {string} id
 * @returns {object|undefined}
 */
export function getFamilyByID(id) {
  return RefreshRuntime.getFamilyByID(id);
}

/**
 * Returns the family object associated with a given component type.
 *
 * @param {Function|object} type
 * @returns {object|undefined}
 */
export function getFamilyByType(type) {
  return RefreshRuntime.getFamilyByType(type);
}

import assert from "node:assert/strict";
import refreshRuntimeModule from "react-refresh/runtime";
import {
  RefreshRuntime,
  createSignatureFunctionForTransform,
  register,
  performReactRefresh,
  getFamilyByID,
  getFamilyByType
} from "../src/index.mjs";

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

// Contract 1: createSignatureFunctionForTransform returns a signature transform function
{
  const sig = createSignatureFunctionForTransform();
  assert.equal(typeof sig, "function", "createSignatureFunctionForTransform must return a function");
  assert.equal(typeof rawRuntime.createSignatureFunctionForTransform(), "function");
}

// Contract 2: signature function called with string key associates signature with component and returns the component
{
  const sig = createSignatureFunctionForTransform();
  function ButtonV1() {
    sig();
    return "button v1";
  }
  const result = sig(ButtonV1, "useState{[count, setCount]}");
  assert.strictEqual(result, ButtonV1, "signature call with key must return the passed component");
  ButtonV1();
}

// Contract 3: signature function handles null and primitive values safely without error
{
  const sig = createSignatureFunctionForTransform();
  assert.strictEqual(sig(null, "key"), null, "handles null component gracefully");
  assert.strictEqual(sig(undefined, "key"), undefined, "handles undefined component gracefully");
  assert.strictEqual(sig(12345, "key"), 12345, "handles number gracefully");
  assert.strictEqual(sig("not-a-component", "key"), "not-a-component", "handles string gracefully");
}

// Contract 4: signature function called without arguments executes getCustomHooks callback to collect nested hook signatures
{
  let customHooksCalled = false;
  function useCustomCounter() {
    return 0;
  }
  const hookSig = createSignatureFunctionForTransform();
  hookSig(useCustomCounter, "useState{[count]}");

  const compSig = createSignatureFunctionForTransform();
  function CounterConsumer() {
    compSig();
    return null;
  }
  compSig(CounterConsumer, "useCustomCounter{}", false, () => {
    customHooksCalled = true;
    return [useCustomCounter];
  });

  assert.equal(customHooksCalled, false, "getCustomHooks should not be called until component executes");
  CounterConsumer();
  assert.equal(customHooksCalled, true, "executing component must invoke getCustomHooks to collect hook signature");
}

// Contract 5: performReactRefresh updates component family without remounting when signature key is unchanged
{
  const sigA1 = createSignatureFunctionForTransform();
  function CardV1() {
    sigA1();
    return "card v1";
  }
  sigA1(CardV1, "useState{[state]}");
  register(CardV1, "CardComponent");

  const sigA2 = createSignatureFunctionForTransform();
  function CardV2() {
    sigA2();
    return "card v2";
  }
  sigA2(CardV2, "useState{[state]}"); // Identical signature key
  register(CardV2, "CardComponent");

  const updateResult = performReactRefresh();
  assert.notEqual(updateResult, null, "performReactRefresh returns update object");
  const family = getFamilyByID("CardComponent");
  assert.notEqual(family, undefined);
  assert.strictEqual(family.current, CardV2, "family current should be updated to CardV2");
  assert.ok(updateResult.updatedFamilies.has(family), "family must be in updatedFamilies when signature matches");
  assert.ok(!updateResult.staleFamilies.has(family), "family must not be in staleFamilies when signature matches");
}

// Contract 6: performReactRefresh marks component family as stale when signature key changes or forceReset is true
{
  // 6a: Changed signature key
  const sigB1 = createSignatureFunctionForTransform();
  function PanelV1() {
    sigB1();
    return "panel v1";
  }
  sigB1(PanelV1, "useState{[open]}");
  register(PanelV1, "PanelComponent");

  const sigB2 = createSignatureFunctionForTransform();
  function PanelV2() {
    sigB2();
    return "panel v2";
  }
  sigB2(PanelV2, "useState{[open, extra]}"); // Different hook signature
  register(PanelV2, "PanelComponent");

  const updateResultB = performReactRefresh();
  const familyB = getFamilyByID("PanelComponent");
  assert.ok(updateResultB.staleFamilies.has(familyB), "family must be in staleFamilies when signature changes");
  assert.ok(!updateResultB.updatedFamilies.has(familyB), "family must not be in updatedFamilies when signature changes");

  // 6b: forceReset is true
  const sigC1 = createSignatureFunctionForTransform();
  function ModalV1() {
    sigC1();
    return "modal v1";
  }
  sigC1(ModalV1, "useState{[isOpen]}");
  register(ModalV1, "ModalComponent");

  const sigC2 = createSignatureFunctionForTransform();
  function ModalV2() {
    sigC2();
    return "modal v2";
  }
  sigC2(ModalV2, "useState{[isOpen]}", true); // forceReset = true
  register(ModalV2, "ModalComponent");

  const updateResultC = performReactRefresh();
  const familyC = getFamilyByID("ModalComponent");
  assert.ok(updateResultC.staleFamilies.has(familyC), "family must be in staleFamilies when forceReset is true");
  assert.ok(!updateResultC.updatedFamilies.has(familyC), "family must not be in updatedFamilies when forceReset is true");
}

// Contract 7: signature registration propagates to wrapped components for memo and forwardRef
{
  const REACT_MEMO_TYPE = Symbol.for("react.memo");
  const REACT_FORWARD_REF_TYPE = Symbol.for("react.forward_ref");

  function MemoInner() {
    return "memo inner";
  }
  const MemoWrapper = {
    $$typeof: REACT_MEMO_TYPE,
    type: MemoInner
  };

  const memoSig = createSignatureFunctionForTransform();
  const memoResult = memoSig(MemoWrapper, "useState{[memoState]}");
  assert.strictEqual(memoResult, MemoWrapper, "signature function returns memo wrapper");

  register(MemoWrapper, "WrappedMemo");
  const outerFamily = getFamilyByID("WrappedMemo");
  const innerFamily = getFamilyByID("WrappedMemo$type");
  assert.notEqual(outerFamily, undefined);
  assert.notEqual(innerFamily, undefined);

  function RenderInner(props, ref) {
    return "forward ref inner";
  }
  const ForwardRefWrapper = {
    $$typeof: REACT_FORWARD_REF_TYPE,
    render: RenderInner
  };

  const refSig = createSignatureFunctionForTransform();
  const refResult = refSig(ForwardRefWrapper, "useImperativeHandle{}");
  assert.strictEqual(refResult, ForwardRefWrapper, "signature function returns forwardRef wrapper");

  register(ForwardRefWrapper, "WrappedForwardRef");
  const refOuterFamily = getFamilyByID("WrappedForwardRef");
  const refInnerFamily = getFamilyByID("WrappedForwardRef$render");
  assert.notEqual(refOuterFamily, undefined);
  assert.notEqual(refInnerFamily, undefined);
}

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