fix(native): a stylesheet reload retracts a registered initial value

Deleting an `@property` rule un-registered half of it. `inject` clears
`nonInheritedVariables` before re-adding, so the name stopped being
non-inheriting, but nothing cleared `registeredInitialValues` before the
`options.vi` loop. The initial value outlived the rule that declared it, and the
two halves of one registration disagreed for the rest of the session.

Measured on one sheet, `.probe { width: calc(2px + var(--my-var)) }` against an
`initial-value: 3px` registration:

  cold, no @Property rule          style {}
  @Property present, then deleted  style { width: 5 }

Retracting is not a `clear()`. `family.clear()` is a `Map.clear()` and notifies
nobody: a mounted element keeps painting the deleted value, and the next
registration of that name lands on a fresh observable that element never
subscribed to. Measured — with `clear()` in `inject` the registry reads
`undefined` while the element still paints `width: 5`, so the registry-level
assertion alone would bless it. `set(undefined)` takes the same notification
path a changed value takes and leaves the observable its readers hold in place.

That needs the names the previous sheet registered, so `family` gains `keys()`.
Its Map is already that record; a second registry alongside it would be the same
two-halves-disagreeing shape as the defect. The observable's argument widens to
accept `undefined`, which the read function's first line already implements.

`resetVariableRegistries` keeps clearing, because nothing is mounted across the
test boundary it serves and it has no reader to strand. Its clear of
`registeredInitialValues` was unguarded — removing the line left all 1121 tests
green — and now turns exactly one red.

Correcting the record from 304a506: `root.ts` holds four variable stores and a
second copy of the module cannot reach three of them. That commit pins one,
`registeredInitialValues`. `rootVariables` and `universalVariables` are
pre-existing and are PR 410's subject; `nonInheritedVariables`, the other store
this branch adds, was already pinned.

Five tests. Four are runtime, because only a mounted reader separates a
retraction that notifies from one that does not: the cold-load control, the
registry retraction, the mounted element, and an observable identity that fails
the moment the retraction becomes a `clear()`. The fifth pins the sheet a
deleted rule compiles to, which is what the runtime retracts against.

Author: YevheniiKotyrlo

src/__tests__/compiler/property.test.ts

@@ -359,6 +359,9 @@ test("an unregistered custom property is not recorded", () => {
   const result = compiled.stylesheet();
   expect(result.s).toBeDefined();
   expect(result.vn).toBeUndefined();
+  // Neither half of a registration is emitted. This is the sheet a Fast Refresh produces
+  // when an @property rule is deleted, so it is what the runtime has to retract AGAINST
+  expect(result.vi).toBeUndefined();
 });
 
 test("@property records a name once, however many rules declare it", () => {

src/__tests__/native/non-inheriting-channels.test.tsx

@@ -1,8 +1,12 @@
-import { render, screen } from "@testing-library/react-native";
+import { act, render, screen } from "@testing-library/react-native";
 import { VariableContextProvider } from "react-native-css";
 import { View } from "react-native-css/components/View";
 import { registerCSS, testID } from "react-native-css/jest";
-import { nonInheritedVariables } from "react-native-css/native-internal";
+import {
+  nonInheritedVariables,
+  registeredInitialValues,
+  resetVariableRegistries,
+} from "react-native-css/native-internal";
 
 const parentTestID = "parent";
 
@@ -342,6 +346,102 @@ test("re-registering keeps the registry object identity", () => {
   expect(globalThis.__react_native_css_non_inherited_variables).toBe(before);
 });
 
+/* ------------------------------------------------------------------ *
+ * Lifecycle — a reload retracts a registered initial value
+ * ------------------------------------------------------------------ */
+
+// Composed into arithmetic ON THE DECLARING ELEMENT, which is how Tailwind reads
+// `--tw-ring-offset-width`: `calc(2px + var(--tw-ring-offset-width))`. A registration that
+// outlives the rule declaring it does not hand a descendant something it should not have
+// inherited, it corrupts a length an element computes for itself
+const initialValueRegistration = `
+  @property --my-var {
+    syntax: "<length>";
+    inherits: false;
+    initial-value: 3px;
+  }
+`;
+
+const initialValueConsumer = `
+  .probe { width: calc(2px + var(--my-var)); }
+  .a { --my-var: 10px; }
+  .b { --my-var: 20px; }
+`;
+
+test("a sheet registering nothing leaves the consumer no width", () => {
+  // The control for the two tests below. `.probe` reads a property no rule it matches
+  // declares and no @property registers, so the whole declaration drops
+  registerCSS(initialValueConsumer);
+
+  render(<View testID={testID} className="probe" />);
+
+  expect(screen.getByTestId(testID).props.style).toStrictEqual({});
+});
+
+test("deleting an @property rule retracts its initial value", () => {
+  registerCSS(`
+    ${initialValueRegistration}
+    ${initialValueConsumer}
+  `);
+  expect(registeredInitialValues("my-var").get()).toBe(3);
+
+  registerCSS(initialValueConsumer);
+
+  expect(registeredInitialValues("my-var").get()).toBeUndefined();
+});
+
+test("a mounted element drops a retracted initial value", () => {
+  // Deleting an @property rule un-registered only half of it: the name left
+  // `nonInheritedVariables` and the initial value stayed, so the two halves of one
+  // registration disagreed and the element kept painting a width the sheet no longer
+  // declares anywhere
+  registerCSS(`
+    ${initialValueRegistration}
+    ${initialValueConsumer}
+  `);
+
+  render(<View testID={testID} className="probe" />);
+  expect(screen.getByTestId(testID).props.style).toStrictEqual({ width: 5 });
+
+  act(() => {
+    registerCSS(initialValueConsumer);
+  });
+
+  // Exactly what the same sheet paints when it is the first one loaded, two tests above
+  expect(screen.getByTestId(testID).props.style).toStrictEqual({});
+});
+
+test("retracting an initial value keeps the observable its readers hold", () => {
+  // This is why the retraction is `.set(undefined)` and not `.clear()`. Clearing the family
+  // drops the map entry without notifying anyone, so a mounted reader keeps the deleted
+  // value AND the next registration of the same name lands on an observable it never
+  // subscribed to — the reader is then stranded for the rest of the session
+  registerCSS(`
+    ${initialValueRegistration}
+    ${initialValueConsumer}
+  `);
+  const before = registeredInitialValues("my-var");
+
+  registerCSS(initialValueConsumer);
+
+  expect(registeredInitialValues("my-var")).toBe(before);
+});
+
+test("resetVariableRegistries retracts a registered initial value", () => {
+  // The jest preset's beforeEach is all that stands between one test's @property
+  // registration and the next test's. A plain clear() is right HERE and wrong in inject():
+  // testing-library unmounts between tests, so this retraction has no reader to strand
+  registerCSS(`
+    ${initialValueRegistration}
+    ${initialValueConsumer}
+  `);
+  expect(registeredInitialValues("my-var").get()).toBe(3);
+
+  resetVariableRegistries();
+
+  expect(registeredInitialValues("my-var").get()).toBeUndefined();
+});
+
 /* ------------------------------------------------------------------ *
  * Tailwind v4 ring composition, end to end
  * ------------------------------------------------------------------ */

src/native-internal/root.ts

@@ -1,13 +1,21 @@
 import { Platform, PlatformColor } from "react-native";
 
-import type { StyleDescriptor, VariableValue } from "react-native-css/compiler";
+import type {
+  RootVariables,
+  StyleDescriptor,
+  VariableValue,
+} from "react-native-css/compiler";
 
 import { testMediaQuery } from "../native/conditions/media-query";
 import { family, observable, type Observable } from "../native/reactivity";
 
+// The argument is nullable because a reload has to be able to RETRACT a name, and the read
+// below already answers `undefined` for one — see replaceRegisteredInitialValues
+type VariableArg = VariableValue[] | undefined;
+
 const rootVariableFamily = () => {
-  return family<string, Observable<StyleDescriptor, VariableValue[]>>(() => {
-    const obs = observable<StyleDescriptor, VariableValue[]>(
+  return family<string, Observable<StyleDescriptor, VariableArg>>(() => {
+    const obs = observable<StyleDescriptor, VariableArg>(
       (read, variableValue) => {
         if (!variableValue) return undefined;
 
@@ -89,6 +97,37 @@ export function assignInheritedVariables<TValue>(
   }
 }
 
+/**
+ * Replace every registered initial value with the ones a stylesheet carries.
+ *
+ * A reload has to be able to DELETE an `@property` rule, and this registry is observable,
+ * so dropping the entry is not enough. `family.clear()` is a `Map.clear()`, which notifies
+ * nobody: a mounted element keeps painting the deleted registration's value, and the next
+ * registration of that name lands on a fresh observable that element never subscribed to.
+ * Retracting through `set(undefined)` takes the same notification path a changed value
+ * takes, and leaves the observable its readers already hold in place.
+ *
+ * `resetVariableRegistries` below still clears, because nothing is mounted across the test
+ * boundary it serves — the mechanism differs where the readers do.
+ */
+export function replaceRegisteredInitialValues(entries: RootVariables = []) {
+  const registered = new Set(entries.map(([name]) => name));
+
+  // Snapshotted because the family creates an entry for every name the resolver LOOKS UP,
+  // so a retraction outside a batch can notify a reader that resolves a new one mid-walk.
+  // Retracting a name that carries no registration is already a no-op: the observable
+  // recomputes to the `undefined` it holds, compares equal, and notifies nobody
+  for (const name of Array.from(registeredInitialValues.keys())) {
+    if (!registered.has(name)) {
+      registeredInitialValues(name).set(undefined);
+    }
+  }
+
+  for (const [name, value] of entries) {
+    registeredInitialValues(name).set(value);
+  }
+}
+
 function seedRootVariables() {
   rootVariables("__rn-css-rem").set([[14]]);
   // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
@@ -107,9 +146,14 @@ seedRootVariables();
 /**
  * Return every variable registry to its boot state, seeds included.
  *
- * A stylesheet reload only overwrites the names the new sheet mentions, so a name it
- * drops keeps the value the previous one gave it. That is what a reload should do to a
- * running app and the opposite of what one test should do to the next.
+ * A reload replaces the two registries an `@property` rule writes, but `:root` and `*`
+ * declarations are overwrite-only — a name the new sheet drops keeps the value the previous
+ * one gave it. That is what a reload should do to a running app and the opposite of what one
+ * test should do to the next, and a test that injects no stylesheet at all needs the reset
+ * either way.
+ *
+ * Clearing is enough here, where `inject` has to retract through `set(undefined)`: nothing
+ * is mounted across the boundary this serves, so there is no reader to strand.
  */
 export function resetVariableRegistries() {
   rootVariables.clear();

src/native-internal/style-collection.ts

@@ -17,6 +17,7 @@ import {
 import {
   nonInheritedVariables,
   registeredInitialValues,
+  replaceRegisteredInitialValues,
   rootVariables,
   universalVariables,
 } from "./root";
@@ -107,16 +108,16 @@ globalThis.__react_native_css_style_collection ??= {
       }
     }
 
-    if (options.vi) {
-      for (const entry of options.vi) {
-        registeredInitialValues(entry[0]).set(entry[1]);
-      }
-    }
-
     // A stylesheet reload REPLACES the registrations it carries — editing an @property
-    // rule to `inherits: true`, or deleting it, has to take effect. The container itself
-    // is kept, because the globalThis pin exists so a second copy of root.ts shares this
-    // exact Set; swapping it would leave that copy reading one nothing writes to
+    // rule to `inherits: true`, or deleting it, has to take effect. Both halves of a
+    // registration are replaced, or the two disagree: the name leaves the Set below while
+    // its initial value stays behind, and an element goes on painting a length no rule in
+    // the sheet declares. Retracting an observed value is not a clear() — see root.ts
+    replaceRegisteredInitialValues(options.vi);
+
+    // The container itself is kept, because the globalThis pin exists so a second copy of
+    // root.ts shares this exact Set; swapping it would leave that copy reading one nothing
+    // writes to
     nonInheritedVariables.clear();
 
     if (options.vn) {

src/native/reactivity.ts

@@ -140,6 +140,9 @@ export function family<Key, Result = Key, Args extends any = void>(
       delete(key: Key) {
         return map.delete(key);
       },
+      keys() {
+        return map.keys();
+      },
       clear() {
         return map.clear();
       },