Skip to content

iOS new architecture: migrate away from ref rewriting - #72

Merged
RyanCommits merged 5 commits into
masterfrom
ryanwang/ios-fabric-prop-refactor
Jul 2, 2026
Merged

RyanCommits merged 5 commits into
masterfrom
ryanwang/ios-fabric-prop-refactor

Conversation

@RyanCommits

@RyanCommits RyanCommits commented Jun 26, 2026 •

Copy link
Copy Markdown
Contributor

Stacked with fullstorydev/fullstory-react-native#151

The previous approach to delivering FS attributes (fsClass, fsAttribute, fsTagName, dataElement, dataComponent, dataSourceFile) on the New Architecture worked by intercepting React element creation and replacing every element's ref with a wrapper function (applyFSPropertiesWithRef) that dispatched a setBatchProperties native command when React attached the ref during the layout phase.

This PR replaces that mechanism entirely with a Fabric renderer commit-phase hook.

Changes

  • Instead of rewriting refs, the plugin injects a block of code at the end of commitMutationEffectsOnFiber inside the three shipped Fabric renderer files (ReactFabric-dev.js, ReactFabric-prod.js, ReactFabric-profiling.js). The injected code runs a two-pass collect/drain:
    • Collect (finishedWork.tag === 5, HostComponent): during React's walk of the fiber tree, any host fiber whose memoizedProps carry an FS attribute is pushed onto a global pending list.
    • Drain (finishedWork.tag === 3, HostRoot): once replaceContainerChildren has committed the shadow tree to native (meaning the native views exists), the pending list is drained. Each fiber's public instance is passed to applyFSPropertiesToInstance from fullstory-react-native, which dispatches a single batched setBatchProperties native command, identical to what we did before with Refs.

    Why is this a good change?

    • No more ref manipulation. The old approach turned every object ref (useRef, createRef) into a callback ref, which has a rare, but non-zero chance of causing hard to debug UI bugs in customer code. See fix: make synthetic refs non-enumerable to prevent leaking through rest spreads #64
    • Earlier dispatch. The hook fires at the end of flushMutationEffects, before flushLayoutEffects runs. The old ref callback fired during flushLayoutEffects. The new approach dispatches the setBatchProperties command sooner, shrinking the window between a view appearing on screen and its FS class being applied.
    • Improved performance. We are no longer adding a ref callback function to every annotated component, which can have a non-trivial effect when the annotate plugin is active. Also, FS properties are now dispatched in a single synchronous drain during the commit phase rather than as N separate ref callbacks interleaved with layout effects.
Screenshot 2026-06-26 at 1 53 55 PM
  • Deleted __tests__/fixtures/react-native/fabricRefRewrites/** - We are no longer hooking React refs, so these can be deleted
  • added __tests__/fixtures/react-native/fabricCommitHook/** - make sure that we're hooking the right function and ignore unrelated files. Metro minifier runs after babel transforms, so we can assume variable names will stay constant during our hook (unless React Native changes its internal implementation)
  • added test realRendererInjection.test.js. This will rewrite the actual react-native code in devDependencies and assert for correct code insertion. When new react-native versions release, we can update the devDependencies and make sure the tests still pass.

See test sessions, full selectors are identical for the same screens:
Old:
https://app.staging.fullstory.com/ui/3RWN/session/6931349912851457513:4631609143069378314

New:
https://app.staging.fullstory.com/ui/3RWN/session/6931349912851457513:5869121012440433111


Note

High Risk
Touches React Native renderer internals and privacy-attribute forwarding; incorrect hook timing or RN API drift could break masking or crash at startup on iOS New Architecture.

Overview
Replaces iOS New Architecture FS attribute delivery from intercepting element refs with code injected at the end of commitMutationEffectsOnFiber in shipped ReactFabric-*.js renderers.

On bridgeless iOS (non-TV), the hook collects HostComponent fibers (tag 5) whose memoizedProps include FS fields, then drains on HostRoot (tag 3) by calling applyFSPropertiesToInstance with getPublicInstance(stateNode). It fails loudly if getPublicInstance is missing or returns null for a host stateNode, so privacy attrs are not silently dropped.

Tests: snapshot fixtures under fabricCommitHook/ (inject vs skip non-Fabric / renamed params), VM behavioral tests for collect/drain ordering, and realRendererInjection.test.js against the installed react-native Fabric files. Removes the old fabricRefRewrites fixture (large react.development.js). README updates “FullStory” → “Fullstory” copy.

Reviewed by Cursor Bugbot for commit e06b21a. Bugbot is set up for automated code reviews on this repo. Configure here.

@RyanCommits RyanCommits changed the title replace ref hook with commitLayoutEffectOnFiber hook iOS new architecture: migrate away from ref rewriting Jun 26, 2026
@RyanCommits
RyanCommits marked this pull request as ready for review June 26, 2026 20:29

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 1755c89. Configure here.

@RyanCommits
RyanCommits requested a review from JoshMiers-FS June 30, 2026 14:55

@martin-fs martin-fs left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm glad it works! I'd like as many asserts as possible to make sure that the architectural details we rely upon continue to hold.

Comment on lines +15 to +18
if (finishedWork.tag === 5) {
// Collect host fibers with FS attributes.
// ReactWorkTags.HostComponent === 5 — the only fiber tag in React Native
// whose stateNode is a Fabric ShadowNode resolvable via getPublicInstance.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd like a little more documentation here. This 5 is a magic number. It seems that this is based on observation of RN code. Can we add some kind of check to make sure that the assumptions continue to hold for future versions of Fabric? For example, the command count, the assertion that the "stateNode is a Fabric ShadowNode resolvable via getPublicInstance". Is it important that 5 is the only such tag, or it just the fact that it is resolvable that is important and we're lucky that there is such a tag?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The magic numbers 5 and 3 are defined here. https://github.com/react/react/blob/bf76955e/packages/react-reconciler/src/ReactWorkTags.js

What does 3 mean? What properties should we assert 3 has? Why do 3 and 5 suffice?
Tag 3 is ReactWorkTags.HostRoot, the single fiber at the root of every React tree. We rely on tag 3 because its case arm calls replaceContainerChildren, which ships the Fabric shadow tree to native. We call applyFSPropertiesToInstance after this happens.

Tag 5 is the only tag that createFiberFromTypeAndProps in Fabric that is associated with a native element. createFiberFromTypeAndProps is the function in React that creates a new Fiber node when React processes a JSX element. We're only concerned with reading Fullstory props off of native elements, so tag 5 suffices for observing Fullstory props.

As discussed, I'll make some asserts during runtime that throw if they fail.

@RyanCommits RyanCommits Jul 1, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this commit, I've added a runtime assertion that getPublicInstance is both defined and available.

I've also added tests ReactFabric renderer structural assumptions that pulls in react-native code from node_modules and asserts that our assumptions hold true. We test each react native minor version manually so if we ever update react-native in devDependencies, they would fail if anything changes.

Also added fabricCommitHookBehavior.test.js to test the actual injected code with command count assertions.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The magic numbers 5 and 3 are defined here. https://github.com/react/react/blob/bf76955e/packages/react-reconciler/src/ReactWorkTags.js

Okay, at least the past 7+ years have maintained these low numbered definitions. The definitions were not stable before react/react@95a313e (October 19 2018) but they have been since then. There have been a few alterations to some of the higher numbered definitions in more recent years such as export const HostResource = 26; in react/react@7b25b96 (September 30 2022) and export const HostHoistable = 26; in react/react@6396b66 (February 9 2023).

@RyanCommits
RyanCommits requested a review from martin-fs July 1, 2026 15:20

@JoshMiers-FS JoshMiers-FS left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@martin-fs martin-fs left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the additional checks! Great improvement, thanks for this work!

@RyanCommits
RyanCommits merged commit e12a5f5 into master Jul 2, 2026
3 checks passed
@RyanCommits
RyanCommits deleted the ryanwang/ios-fabric-prop-refactor branch July 2, 2026 14:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants