fix: Prevent partial bundle loading and double fetching in `TemplateM…

[PupilTong]

…anager.fetchBundle` by handling concurrent requests and renaming template-related methods to bundle.

Summary by CodeRabbit

• Bug Fixes
  • Fixed a race condition where concurrently requesting the same bundle could produce partial loads, duplicate network fetches, or missed callbacks. Concurrent requests now share a single load operation, ensure complete bundle content is stored, cleanup is handled correctly on errors, and all awaiting callbacks are invoked.

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: 9dca8a0

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

This PR includes changesets to release 9 packages

Name	Type
@lynx-js/web-core	Patch
upgrade-rspeedy	Patch
@lynx-js/web-rsbuild-server-middleware	Patch
@lynx-js/template-webpack-plugin	Patch
@lynx-js/react-rsbuild-plugin	Patch
create-rspeedy	Patch
@lynx-js/web-worker-rpc	Patch
@lynx-js/react-alias-rsbuild-plugin	Patch
@lynx-js/rspeedy	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

Refactors TemplateManager to split storage into completed (#bundles) and in-flight (#loadingBundles) entries, adds #loadingPromises to deduplicate concurrent fetchBundle calls, renames template-centric APIs to bundle-centric names, and updates call sites and tests to use the new bundle model. (50 words)

Changes

Cohort / File(s)	Summary
Changeset Entry .changeset/fix-bundle-race-condition.md	Added patch changeset describing fix for partial bundle loading and duplicate network fetches when fetchBundle is called concurrently.
TemplateManager core packages/web-platform/web-core/ts/client/mainthread/TemplateManager.ts	Replaced single #templates map with #bundles and #loadingBundles; introduced #loadingPromises to reuse in-flight loads; renamed lifecycle helpers (createTemplate→createBundle, getTemplate→getBundle, removeTemplate→removeBundle); promote/cleanup logic adjusted and blob URL/style revocation expanded.
Call-site updates packages/web-platform/web-core/ts/client/mainthread/LynxViewInstance.ts, packages/web-platform/web-core/ts/client/mainthread/createMainThreadGlobalAPIs.ts	Replaced getTemplate(...) usages with getBundle(...) and adjusted locations where lepusCode, backgroundCode, config, and customSections are read.
Tests packages/web-platform/web-core/tests/template-manager.spec.ts	Updated assertions to use getBundle(...), switched commented helpers toward createBundle/removeBundle, and added a concurrency test that calls fetchBundle twice for the same URL and verifies no partial bundle state and both callbacks fire.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• perf(externals-loading): merge multiple fetchBundle calls for the same URL #2307: Implements merging/deduplication for concurrent fetchBundle calls; strongly related to TemplateManager concurrency changes.

Suggested reviewers

• Sherry-hue
• colinaaa

Poem

🐰 I hopped through code where bundles collide,
I stitched their paths so races subside.
Promises pooled, no duplicate streams,
Complete bundles now fulfill our dreams. ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ 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%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: preventing partial bundle loading and double fetching in TemplateManager, which is the core purpose across all modified files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

❌ Patch coverage is 67.41573% with 29 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
...m/web-core/ts/client/mainthread/TemplateManager.ts	71.42%	24 Missing ⚠️
.../web-core/ts/client/mainthread/LynxViewInstance.ts	0.00%	4 Missing ⚠️
...ts/client/mainthread/createMainThreadGlobalAPIs.ts	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will degrade performance by 21.15%

❌ 1 regressed benchmark
✅ 62 untouched benchmarks
⏩ 21 skipped benchmarks¹

⚠️ Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	002-hello-reactLynx-destroyBackground	678.9 µs	861 µs	-21.15%

---

_{Comparing PupilTong:p/hw/fetchBundle-race (9dca8a0) with main (a32bc28)}

Footnotes

1. 21 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. ↩

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

packages/web-platform/web-core/tests/template-manager.spec.ts (1)

398-455: Cover the mixed overrideConfig race in this regression test.

The bug report path is fetchBundle(url) racing with fetchBundle(url, ..., { enableCSSSelector: ... }) from queryComponent(). This test only covers two identical requests, so it won't catch URL-only dedupe dropping the second caller's override. I'd extend it with one overridden caller and assert both the override and single-fetch behavior.

✅ Suggested test extension

     await Promise.all([
       templateManager.fetchBundle(
         'http://example.com/template_concurrent',
         Promise.resolve(instance1 as unknown as LynxViewInstance),
         false,
         false,
       ),
       templateManager.fetchBundle(
         'http://example.com/template_concurrent',
         Promise.resolve(instance2 as unknown as LynxViewInstance),
         false,
         false,
+        { enableCSSSelector: 'true' } as any,
       ),
     ]);
@@
     expect(decodedCustomSections).toEqual(sampleTasm.customSections);
     expect(instance1.onPageConfigReady).toHaveBeenCalled();
-    expect(instance2.onPageConfigReady).toHaveBeenCalled();
+    expect(instance2.onPageConfigReady).toHaveBeenCalledWith(
+      expect.objectContaining({ enableCSSSelector: 'true' }),
+    );
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
   });

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/web-platform/web-core/tests/template-manager.spec.ts` around lines
398 - 455, Extend the concurrent-fetch test to also exercise the mixed-override
race: call templateManager.fetchBundle twice concurrently where one call passes
an overrideConfig (e.g., { enableCSSSelector: true } or the real override shape
used by queryComponent) and the other call uses the default override (no
overrideConfig), then assert both callers complete and that (1) the stored
bundle from templateManager.getBundle(url) remains correct for the fetched
bundle, and (2) the caller that supplied overrideConfig received the overridden
behavior (verify via the instance's onPageConfigReady / pageConfig or other
public observable produced by fetchBundle) while the other caller still receives
normal behavior; reference templateManager.fetchBundle, getBundle,
queryComponent, overrideConfig and the instances' onPageConfigReady to locate
and implement the assertions.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/web-platform/web-core/ts/client/mainthread/TemplateManager.ts`:
- Around line 65-75: The dedupe branch is collapsing concurrent requests by URL
only, which loses per-call overrideConfig from queryComponent; update the logic
around `#loadingPromises` (the dedupe path that returns
this.#loadingPromises.get(url)) so it preserves per-caller overrideConfig:
either include overrideConfig in the dedupe key (e.g., use a composite key of
url + serialized overrideConfig when storing/checking `#loadingPromises` for
fetchBundle) or, if overrideConfig exists on the waiting caller, skip the
URL-only dedupe and start a new fetch; then ensure the waiting caller uses its
overrideConfig when calling lynxViewInstance.onPageConfigReady and related
methods (references: `#loadingPromises`, fetchBundle, queryComponent,
lynxViewInstancePromise, onPageConfigReady).
- Around line 198-213: When handling the 'done' case, ensure the in-flight entry
is settled and removed even if lynxViewInstancePromise rejects: move the calls
to this.#resolvePromise(url) and this.#loadingPromises.delete(url) out of the
.then handler and into a .finally (or mirror them in both .then and .catch), and
in the .catch propagate or log the error so callers don't hang; keep the
existing backgroundThread markTiming calls inside the successful path
(lynxViewInstancePromise.then) and ensure bundle promotion (this.#bundles/set
and this.#loadingBundles.delete) remains unchanged.

---

Nitpick comments:
In `@packages/web-platform/web-core/tests/template-manager.spec.ts`:
- Around line 398-455: Extend the concurrent-fetch test to also exercise the
mixed-override race: call templateManager.fetchBundle twice concurrently where
one call passes an overrideConfig (e.g., { enableCSSSelector: true } or the real
override shape used by queryComponent) and the other call uses the default
override (no overrideConfig), then assert both callers complete and that (1) the
stored bundle from templateManager.getBundle(url) remains correct for the
fetched bundle, and (2) the caller that supplied overrideConfig received the
overridden behavior (verify via the instance's onPageConfigReady / pageConfig or
other public observable produced by fetchBundle) while the other caller still
receives normal behavior; reference templateManager.fetchBundle, getBundle,
queryComponent, overrideConfig and the instances' onPageConfigReady to locate
and implement the assertions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e032d625-beda-403b-ad39-d5fccb8df10a

📥 Commits

Reviewing files that changed from the base of the PR and between dae9fed and dfae1be.

📒 Files selected for processing (5)

• .changeset/fix-bundle-race-condition.md
• packages/web-platform/web-core/tests/template-manager.spec.ts
• packages/web-platform/web-core/ts/client/mainthread/LynxViewInstance.ts
• packages/web-platform/web-core/ts/client/mainthread/TemplateManager.ts
• packages/web-platform/web-core/ts/client/mainthread/createMainThreadGlobalAPIs.ts

[relativeci]

Web Explorer

#8469 Bundle Size — 728.55KiB (+0.09%).

9dca8a0(current) vs a32bc28 main#8457(baseline)

Bundle metrics   4 changes 1 regression

	Current #8469	Baseline #8457
Initial JS	43.29KiB(+1.57%)	42.62KiB
Initial CSS	2.16KiB	2.16KiB
Cache Invalidation	15.49%	0%
Chunks	8	8
Assets	10	10
Modules	150(+0.67%)	149
Duplicate Modules	11	11
Duplicate Code	34.68%(-0.14%)	34.73%
Packages	3	3
Duplicate Packages	0	0

Bundle size by type   1 change 1 regression

	Current #8469	Baseline #8457
Other	384.4KiB	384.4KiB
JS	342KiB (+0.19%)	341.33KiB
CSS	2.16KiB	2.16KiB

Bundle analysis report Branch PupilTong:p/hw/fetchBundle-race Project dashboard

---

^{Generated by RelativeCI Documentation Report issue}

[relativeci]

React MTF Example

#25 Bundle Size — 207.47KiB (0%).

9dca8a0(current) vs a32bc28 main#13(baseline)

Bundle metrics  no changes

	Current #25	Baseline #13
Initial JS	0B	0B
Initial CSS	0B	0B
Cache Invalidation	0%	0%
Chunks	0	0
Assets	3	3
Modules	168	168
Duplicate Modules	66	66
Duplicate Code	46.13%	46.13%
Packages	2	2
Duplicate Packages	0	0

Bundle size by type  no changes

	Current #25	Baseline #13
IMG	111.23KiB	111.23KiB
Other	96.24KiB	96.24KiB

Bundle analysis report Branch PupilTong:p/hw/fetchBundle-race Project dashboard

---

^{Generated by RelativeCI Documentation Report issue}

[relativeci]

React Example

#6891 Bundle Size — 237.89KiB (0%).

9dca8a0(current) vs a32bc28 main#6879(baseline)

Bundle metrics  no changes

	Current #6891	Baseline #6879
Initial JS	0B	0B
Initial CSS	0B	0B
Cache Invalidation	0%	0%
Chunks	0	0
Assets	4	4
Modules	174	174
Duplicate Modules	69	69
Duplicate Code	46.44%	46.44%
Packages	2	2
Duplicate Packages	0	0

Bundle size by type  no changes

	Current #6891	Baseline #6879
IMG	145.76KiB	145.76KiB
Other	92.13KiB	92.13KiB

Bundle analysis report Branch PupilTong:p/hw/fetchBundle-race Project dashboard

---

^{Generated by RelativeCI Documentation Report issue}

[coderabbitai]

Actionable comments posted: 2

♻️ Duplicate comments (1)

packages/web-platform/web-core/ts/client/mainthread/TemplateManager.ts (1)

54-85: ⚠️ Potential issue | 🟠 Major

overrideConfig is still missing from the cache/dedupe key.

This state is still keyed by bare url, so a load started with one override can be replayed for concurrent callers with a different override, and the completed #bundles entry can later serve that overridden config back to a no-override caller on the fast path. Please key shared entries by (url, overrideConfig) or avoid sharing/caching overridden loads.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/web-platform/web-core/ts/client/mainthread/TemplateManager.ts`
around lines 54 - 85, The cache/dedupe keys for bundle loading are currently
only using url, so entries in this.#bundles and this.#loadingPromises can be
reused across different overrideConfig values causing incorrect config replay;
change the keying to include overrideConfig (for example, combine url and a
stable serialization of overrideConfig) wherever entries are set and looked up
(references: this.#bundles, this.#loadingPromises, createBundle, and the call
site of this.#load) or alternatively avoid caching when overrideConfig is
present by branching to always call this.#load for overrideConfig !== undefined;
ensure lookups, set calls, and the fast path that reads bundle?.config all use
the same (url, overrideConfig) composite key so no cross-contamination occurs.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/web-platform/web-core/ts/client/mainthread/TemplateManager.ts`:
- Around line 275-319: createBundle currently destroys the existing entry in
`#bundles` immediately, exposing a missing/partial bundle during reloads; change
the flow so createBundle only creates an empty in-flight record in
`#loadingBundles` (do not revoke or delete from `#bundles` there), perform
fetch/build into that loading entry, and on the successful completion event
('done') swap the completed bundle into `#bundles` while then revoking/cleaning
the previous `#bundles` entry; update getBundle usage so it falls back to `#bundles`
as before; also modify `#removeBundle` to only clear the in-flight state in
`#loadingBundles` (do not call createBundle to perform the clear), and ensure
cleanup/revocation logic references bundle.lepusCode, bundle.backgroundCode, and
bundle.styleSheet when swapping/removing the old bundle.
- Around line 198-206: The 'done' branch in TemplateManager (within
`#handleSection` and similar branches) promotes the bundle from `#loadingBundles` to
`#bundles` and deletes the `#loadingBundles` entry immediately, which lets async
section writers resume later and silently lose updates; change the logic so you
either (a) wait until the per-URL section queue/section writers have drained
before deleting the `#loadingBundles` entry (i.e., keep the loading entry until
all pending section promises for that URL have completed), or (b) update the
section-writer paths to detect a promoted bundle and apply their
config/style/code writes to the already-promoted bundle (fall back to `#bundles`
when `#loadingBundles.get`(url) is missing). Apply the same fix to other similar
blocks that call `#cleanup`, move entries between `#loadingBundles` and `#bundles`,
call `#resolvePromise`, and delete `#loadingPromises` (the other occurrences noted
in the review).

---

Duplicate comments:
In `@packages/web-platform/web-core/ts/client/mainthread/TemplateManager.ts`:
- Around line 54-85: The cache/dedupe keys for bundle loading are currently only
using url, so entries in this.#bundles and this.#loadingPromises can be reused
across different overrideConfig values causing incorrect config replay; change
the keying to include overrideConfig (for example, combine url and a stable
serialization of overrideConfig) wherever entries are set and looked up
(references: this.#bundles, this.#loadingPromises, createBundle, and the call
site of this.#load) or alternatively avoid caching when overrideConfig is
present by branching to always call this.#load for overrideConfig !== undefined;
ensure lookups, set calls, and the fast path that reads bundle?.config all use
the same (url, overrideConfig) composite key so no cross-contamination occurs.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d5d139b4-3a6b-4924-9e8f-08eee14b0ac5

📥 Commits

Reviewing files that changed from the base of the PR and between dfae1be and 9dca8a0.

📒 Files selected for processing (1)

• packages/web-platform/web-core/ts/client/mainthread/TemplateManager.ts