fix(runtime,main-thread): backport branch-independent fixes from vapor

[Huxpro]

Follow-up to #358. Ports the parts of the vapor line that aren't vapor-specific — each is a fix main wants on its own terms, and porting them shrinks the eventual vapor → main merge surface in shared files.

Ported

worklet-apply.ts — the background thread's MainThreadRef init value was being dropped. INIT_MT_REF is an 'always' op during hydration precisely because the background value is authoritative, but applyInitMtRef skipped whenever the main-thread first-screen render had already registered the same _wvid. Now it mutates the existing cell (worklet-runtime hands these out by reference) instead of skipping. resetWorkletState() was an empty stub; it now clears the external ref registry, and IFR teardown calls it for the same reason it clears list state — the replay re-applies SET_MT_REF/INIT_MT_REF.

ifr.ts — list platform metadata and the no-throw boundary. A diverging item-key / estimated-main-axis-size-px / … reaches native through update-list-info at insert time, so patching our JS map cannot repair the row native was already told about; that now forces a rebuild rather than an in-place patch (this was the open question I flagged in #357). A throwing hydration patch falls back to the background replay instead of escaping vuePatchUpdate into Lepus.

flush.ts — main-thread ops could be posted as background ops. On the IFR main thread with no ops sink installed, doFlush fell through to callLepusMethod('vuePatchUpdate'), re-entering the executor as if the batch had come from the background thread and desyncing the hydration stream. It now drops the batch with a dev warning. Also: typeof lynx guard before use (bare AMD identifier throws ReferenceError in plain node realms), and the ack fallback is only armed where setTimeout exists.

cross-thread.ts — runOnMainThread no longer stamps _execId into the background exec map when the module evaluates in the IFR main-thread realm; that map is meaningless there and the entry is retained for the life of the page.

worklet-loader.ts — use the shared hasMainThreadDirective rather than an inline substring check, so the two thread bundles cannot disagree about which files carry worklets. No behavior change on main today (the helper is the same substring check); it removes a call-site divergence and picks up vapor's AST-based version for free when that lands.

Deliberately not ported

• Page.ts scope handling and transition-shared.ts — composable scope classes and the ShadowElement.id → uid rename, both vapor infrastructure.
• The vueIfrHydrationComplete handshake, completeIfrInitialRender, ifrInert / isIfrEnabled — need the vapor background entry and plugin pipeline.
• __VUE_LYNX_FLUSH_HOOK__ observability — benchmark tooling, not a fix.
• entry-main.ts's SystemInfo init — vapor flips the precedence between an engine-provided global and lynx.SystemInfo; the two behaviors differ and neither is obviously right, so I left main's alone.

Testing

• pnpm --filter vue-lynx-testing-library test — 238 passed (4 new).
• New mt-worklet-refs.test.ts (2 of 3 fail without the worklet-apply change) and a list platform-metadata rebuild case in ifr-list.test.ts (fails without the ifr.ts change).
• pnpm --filter vue-lynx build clean; biome clean over the touched sources.
• The flush.ts and cross-thread.ts guards are not covered by new tests — both are small guards on paths that need a real IFR bundle to exercise.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
vue-lynx	Ready	Preview	Aug 6, 2026 5:16pm