fix(react): fix 'ctx not found' when using suspense

[Yradex]

Summary by CodeRabbit

• Bug Fixes

  • Resolved an error that occurred when lazy components resolved after their parent component unmounted.

• New Features

  • lazy and useState are now exported as part of the public API.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Checklist

• Tests updated (or not required).
• Documentation updated (or not required).
• Changeset added, and when a BREAKING CHANGE occurs, it needs to be clearly marked (or not required).

[changeset-bot]

🦋 Changeset detected

Latest commit: cd020e1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@lynx-js/react	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a bug fix for React's lazy bundle resolution after component unmount, introducing a new test case and public API exports for lazy and useState. Implementation updates include detachment-aware logic in BackgroundSnapshotInstance to prevent appendChild operations on removed nodes.

Changes

Cohort / File(s)	Summary
Changeset Documentation .changeset/thirty-buttons-design.md	Documents patch release for @lynx-js/react fixing React CtxNotFound errors when lazy bundles resolve post-unmount.
Suspense Test Updates packages/react/runtime/__test__/lynx/suspense.test.jsx	Adds comprehensive test for late-resolving lazy children after unmount, verifies ctx-not-found reporting and UI consistency; exposes lazy and useState as public exports alongside new test imports.
Background Snapshot Logic packages/react/runtime/src/backgroundSnapshot.ts	Introduces private isDetached getter that walks parent chain for __removed_from_tree markers; guards appendChild to become no-op when node is detached.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

• The detachment-aware guard logic in appendChild requires careful verification of edge cases where nodes are removed during suspension/lazy resolution
• Public API exports (lazy, useState) need validation against existing module structure
• New test scenario exercises a specific timing edge case that warrants thorough walkthrough

Possibly related PRs

• feat(react/runtime): support using a host element as direct child of Suspense #1308: Modifies backgroundSnapshot.ts with similar changes to handle removed/detached nodes in the tree reconstruction flow.
• feat(react/runtime): render Suspense fallback on initial render #1285: Touches React runtime's lazy/Suspense surface including the lazy export and related Suspense tests.
• Revert "feat(react/runtime): support using a host element as direct child of Suspense" #1450: Directly related through opposing changes to detachment logic and __removed_from_tree handling in backgroundSnapshot.ts.

Suggested labels

framework:React

Suggested reviewers

• hzy
• upupming
• colinaaa

Poem

🐰 A lazy bundle arrived too late, the component had gone—
No CtxNotFound errors now, detachment's caught on!
With tests that verify the fix and snapshots held true,
The tree stays intact when patches slip through.
Hip-hop for suspension, hooray for the view! 🌿✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly addresses the main fix: preventing 'ctx not found' errors when using suspense with lazy components that resolve after unmount.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

[codspeed-hq]

CodSpeed Performance Report

Merging #2003 will improve performances by 13.32%

_{Comparing Yradex:fix-suspense (cd020e1) with main (7add9c4)}

Summary

⚡ 1 improvement
✅ 62 untouched
⏩ 3 skipped¹

Benchmarks breakdown

	Benchmark	BASE	HEAD	Change
⚡	002-hello-reactLynx-destroyBackground	702.2 µs	619.7 µs	+13.32%

Footnotes

1. 3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[relativeci]

React Example

#6512 Bundle Size — 237.01KiB (+0.05%).

cd020e1(current) vs 7add9c4 main#6499(baseline)

Bundle metrics   2 changes

	Current #6512	Baseline #6499
Initial JS	0B	0B
Initial CSS	0B	0B
Cache Invalidation	38.47%	0%
Chunks	0	0
Assets	4	4
Modules	162	162
Duplicate Modules	65	65
Duplicate Code	46.75%(+0.02%)	46.74%
Packages	2	2
Duplicate Packages	0	0

Bundle size by type   1 change 1 regression

	Current #6512	Baseline #6499
IMG	145.76KiB	145.76KiB
Other	91.25KiB (+0.12%)	91.14KiB

Bundle analysis report Branch Yradex:fix-suspense Project dashboard

---

^{Generated by RelativeCI Documentation Report issue}

[relativeci]

Web Explorer

#6672 Bundle Size — 372.63KiB (0%).

cd020e1(current) vs 7add9c4 main#6659(baseline)

Bundle metrics   1 change

	Current #6672	Baseline #6659
Initial JS	146.36KiB	146.36KiB
Initial CSS	32.4KiB	32.4KiB
Cache Invalidation	0%	0%
Chunks	8	8
Assets	8	8
Modules	230(-0.43%)	231
Duplicate Modules	16	16
Duplicate Code	2.97%	2.97%
Packages	4	4
Duplicate Packages	0	0

Bundle size by type  no changes

	Current #6672	Baseline #6659
JS	243.25KiB	243.25KiB
Other	96.98KiB	96.98KiB
CSS	32.4KiB	32.4KiB

Bundle analysis report Branch Yradex:fix-suspense Project dashboard

---

^{Generated by RelativeCI Documentation Report issue}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (2)

packages/react/runtime/__test__/lynx/suspense.test.jsx (2)

20-20: Verify if this import is needed.

BackgroundSnapshotInstance is imported but doesn't appear to be used in the test file. Consider removing it if it's not needed.

#!/bin/bash
# Search for usage of BackgroundSnapshotInstance in the test file
rg -n 'BackgroundSnapshotInstance' packages/react/runtime/__test__/lynx/suspense.test.jsx

---

1629-1631: Clarify comment vs. expectation mismatch.

The comment states that a ctx-not-found event "should" be emitted, but the expectation is for an empty array (no events). Given that the PR fixes the CtxNotFound error, the empty array is likely correct—the fix prevents the error from occurring. Consider updating the comment to clarify that the fix ensures no ctx-not-found event is emitted in this scenario.

🔎 Suggested comment update:

-      // snapshotPatchApply should emit a ctx-not-found event back to BG,
-      // which is converted into a lynx.reportError in error.ts.
+      // With the fix, snapshotPatchApply should NOT emit a ctx-not-found event
+      // because appendChild is now a no-op on detached nodes.
       expect(lynx.getJSContext().dispatchEvent.mock.calls).toMatchInlineSnapshot(`[]`);

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3a9a730 and cd020e1.

📒 Files selected for processing (3)

• .changeset/thirty-buttons-design.md (1 hunks)
• packages/react/runtime/__test__/lynx/suspense.test.jsx (3 hunks)
• packages/react/runtime/src/backgroundSnapshot.ts (2 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

.changeset/*.md

📄 CodeRabbit inference engine (AGENTS.md)

For contributions, generate and commit a Changeset describing your changes

Files:

• .changeset/thirty-buttons-design.md

🧠 Learnings (18)

📓 Common learnings

Learnt from: upupming
Repo: lynx-family/lynx-stack PR: 1899
File: packages/react/runtime/__test__/snapshotPatch.test.jsx:725-749
Timestamp: 2025-11-04T10:15:14.965Z
Learning: In packages/react/runtime/src/snapshot.ts, the snapshotCreatorMap type signature uses `Record<string, (uniqId: string) => string>` (returning string) rather than void for backward compatibility. Old lazy bundles still use the pattern `const snapshot_xxx = createSnapshot(...)` directly, which requires createSnapshot to return a value. The snapshotCreatorMap creators that wrap createSnapshot calls must maintain the same return type to support these legacy bundles.

Learnt from: upupming
Repo: lynx-family/lynx-stack PR: 1562
File: packages/react/transform/src/swc_plugin_snapshot/jsx_helpers.rs:261-283
Timestamp: 2025-08-21T07:21:51.621Z
Learning: In packages/react/transform/src/swc_plugin_snapshot/jsx_helpers.rs, the team prefers to keep the original unreachable! logic for JSXSpreadChild in jsx_is_children_full_dynamic function rather than implementing defensive error handling.

📚 Learning: 2025-11-04T10:15:14.965Z

Learnt from: upupming
Repo: lynx-family/lynx-stack PR: 1899
File: packages/react/runtime/__test__/snapshotPatch.test.jsx:725-749
Timestamp: 2025-11-04T10:15:14.965Z
Learning: In packages/react/runtime/src/snapshot.ts, the snapshotCreatorMap type signature uses `Record<string, (uniqId: string) => string>` (returning string) rather than void for backward compatibility. Old lazy bundles still use the pattern `const snapshot_xxx = createSnapshot(...)` directly, which requires createSnapshot to return a value. The snapshotCreatorMap creators that wrap createSnapshot calls must maintain the same return type to support these legacy bundles.

Applied to files:

• packages/react/runtime/src/backgroundSnapshot.ts

📚 Learning: 2025-09-12T09:43:04.847Z

Learnt from: gaoachao
Repo: lynx-family/lynx-stack PR: 1736
File: .changeset/spotty-experts-smoke.md:1-3
Timestamp: 2025-09-12T09:43:04.847Z
Learning: In the lynx-family/lynx-stack repository, private packages (marked with "private": true in package.json) like lynx-js/react-transform don't require meaningful changeset entries even when their public APIs change, since they are not published externally and only affect internal development.

Applied to files:

• .changeset/thirty-buttons-design.md

📚 Learning: 2025-09-12T09:43:04.847Z

Learnt from: gaoachao
Repo: lynx-family/lynx-stack PR: 1736
File: .changeset/spotty-experts-smoke.md:1-3
Timestamp: 2025-09-12T09:43:04.847Z
Learning: In the lynx-family/lynx-stack repository, empty changeset files (containing only `---\n\n---`) are used for internal changes that modify src/** files but don't require meaningful release notes, such as private package changes or testing-only modifications. This satisfies CI requirements without generating user-facing release notes.

Applied to files:

• .changeset/thirty-buttons-design.md

📚 Learning: 2025-07-22T09:23:07.797Z

Learnt from: colinaaa
Repo: lynx-family/lynx-stack PR: 1330
File: .changeset/olive-animals-attend.md:1-3
Timestamp: 2025-07-22T09:23:07.797Z
Learning: In the lynx-family/lynx-stack repository, changesets are only required for meaningful changes to end-users such as bugfixes and features. Internal/development changes like chores, refactoring, or removing debug info do not need changeset entries.

Applied to files:

• .changeset/thirty-buttons-design.md

📚 Learning: 2025-08-19T11:25:36.127Z

Learnt from: colinaaa
Repo: lynx-family/lynx-stack PR: 1558
File: .changeset/solid-squids-fall.md:2-2
Timestamp: 2025-08-19T11:25:36.127Z
Learning: In the lynx-family/lynx-stack repository, changesets should use the exact package name from package.json#name, not generic or unscoped names. Each package has its own specific scoped name (e.g., "lynx-js/react-transform" for packages/react/transform).

Applied to files:

• .changeset/thirty-buttons-design.md

📚 Learning: 2025-07-22T09:26:16.722Z

Learnt from: colinaaa
Repo: lynx-family/lynx-stack PR: 1330
File: .changeset/olive-animals-attend.md:1-3
Timestamp: 2025-07-22T09:26:16.722Z
Learning: In the lynx-family/lynx-stack repository, CI checks require changesets when files matching the pattern "src/**" are modified (as configured in .changeset/config.json). For internal changes that don't need meaningful changesets, an empty changeset file is used to satisfy the CI requirement while not generating any release notes.

Applied to files:

• .changeset/thirty-buttons-design.md

📚 Learning: 2025-08-07T04:00:59.645Z

Learnt from: colinaaa
Repo: lynx-family/lynx-stack PR: 1454
File: pnpm-workspace.yaml:46-46
Timestamp: 2025-08-07T04:00:59.645Z
Learning: In the lynx-family/lynx-stack repository, the webpack patch (patches/webpack5.101.0.patch) was created to fix issues with webpack5.99.9 but only takes effect on webpack5.100.0 and later versions. The patchedDependencies entry should use "webpack@^5.100.0" to ensure the patch applies to the correct version range.

Applied to files:

• .changeset/thirty-buttons-design.md

📚 Learning: 2025-09-18T04:43:54.426Z

Learnt from: gaoachao
Repo: lynx-family/lynx-stack PR: 1771
File: packages/react/transform/tests/__swc_snapshots__/src/swc_plugin_snapshot/mod.rs/basic_component_with_static_sibling.js:2-2
Timestamp: 2025-09-18T04:43:54.426Z
Learning: In the lynx-family/lynx-stack repository, the `add_pure_comment` function in packages/react/transform/src/swc_plugin_compat/mod.rs (around lines 478-482) is specifically for `wrapWithLynxComponent` calls, not `createSnapshot` calls. The PURE comment injection for `createSnapshot` is handled separately in swc_plugin_snapshot/mod.rs.

Applied to files:

• .changeset/thirty-buttons-design.md

📚 Learning: 2025-08-12T16:09:32.413Z

Learnt from: colinaaa
Repo: lynx-family/lynx-stack PR: 1497
File: packages/react/transform/tests/__swc_snapshots__/src/swc_plugin_snapshot/mod.rs/basic_full_static.js:9-10
Timestamp: 2025-08-12T16:09:32.413Z
Learning: In the Lynx stack, functions prefixed with `__` that are called in transformed code may be injected globally by the Lynx Engine at runtime rather than exported from the React runtime package. For example, `__CreateFrame` is injected globally by the Lynx Engine, not exported from lynx-js/react.

Applied to files:

• .changeset/thirty-buttons-design.md

📚 Learning: 2025-09-25T14:03:25.576Z

Learnt from: PupilTong
Repo: lynx-family/lynx-stack PR: 1834
File: packages/web-platform/web-worker-runtime/src/backgroundThread/background-apis/createChunkLoading.ts:162-171
Timestamp: 2025-09-25T14:03:25.576Z
Learning: In the lynx-stack codebase, for loadScriptAsync implementations in createChunkLoading.ts, unhandled promise rejections from readScriptAsync are intentionally not caught - the caller is expected to handle errors rather than the loadScriptAsync method itself invoking the callback with error messages.

Applied to files:

• .changeset/thirty-buttons-design.md

📚 Learning: 2025-08-21T07:21:51.621Z

Learnt from: upupming
Repo: lynx-family/lynx-stack PR: 1562
File: packages/react/transform/src/swc_plugin_snapshot/jsx_helpers.rs:261-283
Timestamp: 2025-08-21T07:21:51.621Z
Learning: In packages/react/transform/src/swc_plugin_snapshot/jsx_helpers.rs, the team prefers to keep the original unreachable! logic for JSXSpreadChild in jsx_is_children_full_dynamic function rather than implementing defensive error handling.

Applied to files:

• .changeset/thirty-buttons-design.md
• packages/react/runtime/__test__/lynx/suspense.test.jsx

📚 Learning: 2025-08-27T12:42:01.095Z

Learnt from: upupming
Repo: lynx-family/lynx-stack PR: 1616
File: packages/webpack/cache-events-webpack-plugin/test/cases/not-cache-events/lazy-bundle/index.js:3-3
Timestamp: 2025-08-27T12:42:01.095Z
Learning: In webpack, properties like __webpack_require__.lynx_ce are injected during compilation/build time when webpack processes modules and generates bundles, not at runtime when dynamic imports execute. Tests for such properties don't need to wait for dynamic imports to complete.

Applied to files:

• .changeset/thirty-buttons-design.md
• packages/react/runtime/__test__/lynx/suspense.test.jsx

📚 Learning: 2025-08-13T09:20:00.936Z

Learnt from: upupming
Repo: lynx-family/lynx-stack PR: 1502
File: packages/react/testing-library/types/entry.d.ts:71-71
Timestamp: 2025-08-13T09:20:00.936Z
Learning: In lynx-js/react testing library, wrapper components must have children as a required prop because they are always called with `h(WrapperComponent, null, innerElement)` where innerElement is passed as children. The type `React.JSXElementConstructor<{ children: React.ReactNode }>` correctly requires children to be mandatory.

Applied to files:

• .changeset/thirty-buttons-design.md

📚 Learning: 2025-08-06T13:28:57.182Z

Learnt from: colinaaa
Repo: lynx-family/lynx-stack PR: 1453
File: vitest.config.ts:49-61
Timestamp: 2025-08-06T13:28:57.182Z
Learning: In the lynx-family/lynx-stack repository, the file `packages/react/testing-library/src/vitest.config.js` is source code for the testing library that gets exported for users, not a test configuration that should be included in the main vitest projects array.

Applied to files:

• packages/react/runtime/__test__/lynx/suspense.test.jsx

📚 Learning: 2025-08-11T05:59:28.530Z

Learnt from: upupming
Repo: lynx-family/lynx-stack PR: 1305
File: packages/react/testing-library/src/plugins/vitest.ts:4-6
Timestamp: 2025-08-11T05:59:28.530Z
Learning: In the lynx-family/lynx-stack repository, the `packages/react/testing-library` package does not have `vite` as a direct dependency. It relies on `vitest` being available from the monorepo root and accesses Vite types through re-exports from `vitest/node`. Direct imports from `vite` should not be suggested for this package.

Applied to files:

• packages/react/runtime/__test__/lynx/suspense.test.jsx

📚 Learning: 2025-10-29T10:28:27.519Z

Learnt from: upupming
Repo: lynx-family/lynx-stack PR: 1899
File: packages/react/transform/crates/swc_plugin_snapshot/tests/__swc_snapshots__/lib.rs/should_static_extract_dynamic_inline_style.js:20-24
Timestamp: 2025-10-29T10:28:27.519Z
Learning: Files inside packages/react/transform/crates/swc_plugin_snapshot/tests/__swc_snapshots__/ are auto-generated test snapshot files and should not be manually updated. Any issues with the generated code should be addressed in the code generator/transform logic, not in the snapshots themselves.

Applied to files:

• packages/react/runtime/__test__/lynx/suspense.test.jsx

📚 Learning: 2025-07-18T04:27:18.291Z

Learnt from: colinaaa
Repo: lynx-family/lynx-stack PR: 1238
File: packages/react/runtime/src/debug/component-stack.ts:70-90
Timestamp: 2025-07-18T04:27:18.291Z
Learning: The component-stack.ts file in packages/react/runtime/src/debug/component-stack.ts is a direct fork from https://github.com/preactjs/preact/blob/main/debug/src/component-stack.js. The team prefers to keep it aligned with the upstream Preact version and may contribute improvements back to Preact in the future.

Applied to files:

• packages/react/runtime/__test__/lynx/suspense.test.jsx

🔇 Additional comments (5)

packages/react/runtime/src/backgroundSnapshot.ts (2)

70-79: LGTM! Clean detachment detection.

The implementation correctly walks the parent chain to detect if any ancestor has been removed from the tree.

---

98-102: LGTM! Prevents operations on detached nodes.

The guard correctly prevents appendChild from operating on detached nodes, which addresses the issue where lazy bundles resolve after component unmount.

.changeset/thirty-buttons-design.md (1)

1-5: LGTM! Clear and appropriate changeset.

The changeset correctly documents this as a patch-level bug fix with a clear description of the issue being resolved.

packages/react/runtime/__test__/lynx/suspense.test.jsx (2)

1506-1633: Well-structured test for late-resolving lazy children.

The test comprehensively covers the scenario described in the PR: mounting a Suspense boundary with a lazy child, unmounting the subtree, then resolving the lazy component after unmount. The three-phase structure clearly exercises the bug fix.

---

1512-1512: Promise.withResolvers() is natively supported in Node.js 22 and later. Since the project requires Node.js ^22 || ^24 (per root package.json), this API is available without requiring polyfills or special configuration in the test environment.

Likely an incorrect or invalid review comment.