react-refresh 0.17.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.17.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/react-refresh@0.17.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:52e9c4970eee91e7d9193e4ff567976787017df34095255d4bcc4f3a3f86e6cd","contract":["setSignature associates signature key with component type and returns nothing","setSignature ignores subsequent calls for already registered types preserving initial signature","setSignature throws a TypeError when called with null or primitive values because target must be an object or function","setSignature recursively assigns signature to wrapped forwardRef and memo component descriptors","performReactRefresh classifies families as updated when setSignature keys match across revisions","performReactRefresh classifies families as stale when setSignature key changes or forceReset is true","setSignature with getCustomHooks incorporates nested custom hook signatures and propagates forceReset"],"goal":"verify react-refresh.setSignature in pkg:npm/react-refresh@0.17.0","kind":"HOW","packages":["pkg:npm/react-refresh@0.17.0"],"schemaVersion":1,"symbols":["react-refresh.setSignature"]},"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.setSignature"],"verifierAdapter":"node-typescript@1"}

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

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

import refreshRuntimeModule from "react-refresh/runtime";

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

/**
 * Associates a signature with a component type or hook for React Fast Refresh tracking.
 *
 * @param {Function|object} type - Component or hook to attach signature to
 * @param {string} key - Unique signature key representing hook calls/state shape
 * @param {boolean} [forceReset=false] - Whether changes should force a full remount
 * @param {Function} [getCustomHooks] - Callback returning array of custom hook functions
 */
export function setSignature(type, key, forceReset = false, getCustomHooks) {
  RefreshRuntime.setSignature(type, key, forceReset, getCustomHooks);
}

/**
 * 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,
  setSignature,
  register,
  performReactRefresh,
  getFamilyByID,
  getFamilyByType
} from "../src/index.mjs";

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

// Contract 1: setSignature associates signature key with component type and returns nothing
{
  assert.equal(typeof setSignature, "function", "setSignature must be a function");
  assert.equal(typeof rawRuntime.setSignature, "function", "runtime must export setSignature");

  function ButtonV1() {
    return "button v1";
  }
  const ret = setSignature(ButtonV1, "useState{[count, setCount]}");
  assert.strictEqual(ret, undefined, "setSignature should return undefined");
  register(ButtonV1, "Button");

  const family = getFamilyByID("Button");
  assert.notEqual(family, undefined);
  assert.strictEqual(family.current, ButtonV1);
}

// Contract 2: setSignature ignores subsequent calls for already registered types preserving initial signature
{
  function FirstWins() {
    return "v1";
  }
  setSignature(FirstWins, "initialKey");
  setSignature(FirstWins, "overwrittenKey"); // Redundant call must be ignored

  register(FirstWins, "FirstWinsId");

  function FirstWinsV2() {
    return "v2";
  }
  setSignature(FirstWinsV2, "initialKey"); // Matches initialKey, not overwrittenKey
  register(FirstWinsV2, "FirstWinsId");

  const update = performReactRefresh();
  const family = getFamilyByID("FirstWinsId");
  assert.ok(update.updatedFamilies.has(family), "family must be in updatedFamilies since initialKey was preserved");
  assert.ok(!update.staleFamilies.has(family));
}

// Contract 3: setSignature throws a TypeError when called with null or primitive values because target must be an object or function
{
  assert.throws(() => setSignature(null, "key"), /Invalid value used as weak map key|must be an object/i);
  assert.throws(() => setSignature(undefined, "key"), /Invalid value used as weak map key|must be an object/i);
  assert.throws(() => setSignature(12345, "key"), /Invalid value used as weak map key|must be an object/i);
  assert.throws(() => setSignature("not-a-component", "key"), /Invalid value used as weak map key|must be an object/i);
  assert.throws(() => setSignature(true, "key"), /Invalid value used as weak map key|must be an object/i);
}

// Contract 4: setSignature recursively assigns signature to wrapped forwardRef and memo component descriptors
{
  const REACT_FORWARD_REF_TYPE = Symbol.for("react.forward_ref");
  const REACT_MEMO_TYPE = Symbol.for("react.memo");

  function InnerInput(props, ref) {
    return "input";
  }
  const ForwardRefComponent = {
    $$typeof: REACT_FORWARD_REF_TYPE,
    render: InnerInput
  };

  setSignature(ForwardRefComponent, "useImperativeHandle{}");
  register(ForwardRefComponent, "ForwardRefInput");

  const outerFamilyRef = getFamilyByID("ForwardRefInput");
  const innerFamilyRef = getFamilyByID("ForwardRefInput$render");
  assert.notEqual(outerFamilyRef, undefined);
  assert.notEqual(innerFamilyRef, undefined);

  function InnerCard() {
    return "card";
  }
  const MemoComponent = {
    $$typeof: REACT_MEMO_TYPE,
    type: InnerCard
  };

  setSignature(MemoComponent, "useMemo{[data]}");
  register(MemoComponent, "MemoCard");

  const outerFamilyMemo = getFamilyByID("MemoCard");
  const innerFamilyMemo = getFamilyByID("MemoCard$type");
  assert.notEqual(outerFamilyMemo, undefined);
  assert.notEqual(innerFamilyMemo, undefined);
}

// Contract 5: performReactRefresh classifies families as updated when setSignature keys match across revisions
{
  function TabV1() {
    return "tab 1";
  }
  setSignature(TabV1, "useState{[active]}");
  register(TabV1, "TabComponent");

  function TabV2() {
    return "tab 2";
  }
  setSignature(TabV2, "useState{[active]}"); // Matching signature key
  register(TabV2, "TabComponent");

  const update = performReactRefresh();
  const family = getFamilyByID("TabComponent");
  assert.notEqual(family, undefined);
  assert.strictEqual(family.current, TabV2);
  assert.ok(update.updatedFamilies.has(family), "matching signatures must update cleanly");
  assert.ok(!update.staleFamilies.has(family));
}

// Contract 6: performReactRefresh classifies families as stale when setSignature key changes or forceReset is true
{
  // 6a: Key changed
  function NavV1() {
    return "nav 1";
  }
  setSignature(NavV1, "useState{[route]}");
  register(NavV1, "NavComponent");

  function NavV2() {
    return "nav 2";
  }
  setSignature(NavV2, "useState{[route, params]}"); // Changed signature
  register(NavV2, "NavComponent");

  const updateA = performReactRefresh();
  const familyA = getFamilyByID("NavComponent");
  assert.ok(updateA.staleFamilies.has(familyA), "changed key must mark family as stale");
  assert.ok(!updateA.updatedFamilies.has(familyA));

  // 6b: forceReset is true
  function HeaderV1() {
    return "header 1";
  }
  setSignature(HeaderV1, "useState{[title]}", false);
  register(HeaderV1, "HeaderComponent");

  function HeaderV2() {
    return "header 2";
  }
  setSignature(HeaderV2, "useState{[title]}", true); // forceReset = true
  register(HeaderV2, "HeaderComponent");

  const updateB = performReactRefresh();
  const familyB = getFamilyByID("HeaderComponent");
  assert.ok(updateB.staleFamilies.has(familyB), "forceReset must mark family as stale");
  assert.ok(!updateB.updatedFamilies.has(familyB));
}

// Contract 7: setSignature with getCustomHooks incorporates nested custom hook signatures and propagates forceReset
{
  function useCustomThemeV1() {
    return "dark";
  }
  setSignature(useCustomThemeV1, "theme-v1");

  function ThemedBoxV1() {
    return "themed box 1";
  }
  setSignature(ThemedBoxV1, "box", false, () => [useCustomThemeV1]);
  register(ThemedBoxV1, "ThemedBox");

  function useCustomThemeV2() {
    return "dark-updated";
  }
  setSignature(useCustomThemeV2, "theme-v2"); // Nested hook signature changed

  function ThemedBoxV2() {
    return "themed box 2";
  }
  setSignature(ThemedBoxV2, "box", false, () => [useCustomThemeV2]);
  register(ThemedBoxV2, "ThemedBox");

  const updateResult = performReactRefresh();
  const boxFamily = getFamilyByID("ThemedBox");
  assert.ok(updateResult.staleFamilies.has(boxFamily), "nested hook signature change must mark parent component as stale");
  assert.ok(!updateResult.updatedFamilies.has(boxFamily));
}

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