fix(runtime): support CSS v-bind() on Lynx native

[KealanAU]

Summary

Adds Background-Thread-safe support for v-bind() in Vue <style> blocks on Lynx native.

• Writes CSS custom properties onto component root element(s) through the ops pipeline.
• Relies on the Lynx engine inheritance fix from [BugFix] Fix CSS custom property propagation in FiberSetInlineStyles lynx-family/lynx#5912; no descendant-stamping workaround remains.
• Updates docs/examples and removes stale enableCSSInheritance guidance.
• Adds upstream runtime coverage for mount + reactive updates.

Compatibility

• Requires Lynx engine ≥ 3.8.1 — the release line containing the CSS custom property propagation fix (lynx-family/lynx#5912, which closes issue lynx#5889). On earlier engines the vars are stamped on the root but never reach descendants. This is stated in the EN + ZH compatibility docs and the changeset.
• Depends on chore: update Lynx toolchain to 3.8.1 release line #192 (toolchain bump to the 3.8.1 line). Please merge after chore: update Lynx toolchain to 3.8.1 release line #192 so the examples/toolchain run the engine this feature requires. (Cross-fork PRs can't retarget the base branch, so this is tracked as an explicit dependency rather than a GitHub stack.)

Verification

• pnpm test:local in packages/upstream-tests
• Verified in the Lynx native simulator: background-color, color, font-size, and opacity all update via CSS v-bind().

Before	After
CleanShot.2026-04-05.at.15.29.59.mp4	CleanShot.2026-04-05.at.15.07.14.mp4

[vercel]

@KealanAU is attempting to deploy a commit to the huxpro's projects Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
vue-lynx	Ready	Preview, Comment	Apr 5, 2026 0:03am

[Huxpro]

@KealanAU Thanks for the thorough investigation and the detailed PR description -- the root cause analysis of the Lynx engine's CSS var inheritance gap is spot on, and the isolation test (CSSInheritanceTest.vue) is a great addition.

I've been digging into this and wanted to share where I've landed.

What we've verified

I traced through the Lynx engine source and confirmed the bug. The root cause is that FiberSetInlineStyles calls UpdateCSSInlineVariables to store --* properties, but never calls RecursivelyMarkChildrenCSSVariableDirty afterward -- so descendants never see the change. The working path (FiberElement::UpdateCSSVariable, used by setProperty) does all three steps: MarkCustomPropertiesDirty, MarkStyleDirty, and RecursivelyMarkChildrenCSSVariableDirty. I've updated the upstream issue with the full analysis and suggested fix: lynx-family/lynx#5889

I also verified on Lynx Explorer 3.8 that same-element CSS vars (set and consumed on the same element via inline :style) work, but parent-to-child inheritance does not. This confirms the workaround is necessary on current engine versions.

Separate fix for entry.ts

The entry.ts change (from encodeData.compilerOptions to encodeData.sourceContent.config) is actually a pre-existing bug from #127 -- the CSS config options were being injected into the wrong section and never reaching the engine. I've split this out into a standalone fix: #145.

Performance concerns with stampElementDescendants

The workaround stamps CSS vars on every element in the component subtree, which means:

• O(N) SET_STYLE ops per CSS var change, where N = total elements in the subtree (instead of O(1) for root-only stamping)
• O(N) on every component re-render (not just when CSS vars change), because onBeforeUpdate re-stamps the full subtree to compensate for patchProp overwriting the merged styles
• Cross-component double-stamping: if a parent and child component both use v-bind() in CSS, the parent's walk stamps into the child's subtree, then the child's own useCssVars stamps them again

For small components this is fine, but for components with 100+ elements or frequent updates, this could become a bottleneck.

Questions

Before merging this, I'd like to understand:

1. How urgent is this for you? If it's not blocking, I'd prefer to first see how hard the upstream fix is (the suggested change in lynx#5889 is fairly contained -- adding ~5 lines after the ForEachLepusValue loop). With the engine fix, we'd get O(1) root-only stamping with no workaround needed.

2. If we do merge the workaround, I think we should document the performance characteristics so users know to prefer inline :style for performance-critical reactive values in large components.

Thanks again for all the work here -- the examples, tests, and the debugging that led to finding the entry.ts config bug are all valuable.

[KealanAU]

@Huxpro I totally agree that O(N) is terrible to pay on every change. I'm happy to wait for
the upstream engine fix instead, then update or close this PR. Since you've narrowed it
down to the lines and functions in lynx#5889, the O(1) solution is definitely the long-term
solution — we don't want a short-term fix that ends up sticking around long-term.

I did think it was still an upstream issue that would need to be resolved, and had made the
PR since it would be easy to pull out, but this isn't urgent — just wanting to help get
Vue working well on Lynx and learn.

Thanks for splitting it off into its own PR for the other fix and the deeper dive. I was
going to try to find the function and line in Lynx causing the problem today!

[Huxpro]

@KealanAU I just confirmed that we can make it work by fixing lynx#5889! I'll see what the nearest release I can land it in is. Thanks for the detailed issue analysis and the comprehensive CSS feature tests! I'll get back to you when it's landed.

[Huxpro]

The engine fix is merged lynx-family/lynx#5912 and will be released in 3.8 (May)

[KealanAU]

@Huxpro , Perfect, I'll remove the work around then and we can merge in May

[Huxpro]

Blocking from my side: this adds user-facing v-bind() support/docs that appear to depend on the newer Lynx engine/toolchain surface, but the compatibility baseline is still ambiguous here.

If this lands before #192, readers can reasonably take the docs as applying to the default current toolchain, while the required support may only exist on the newer release line. I think this either needs to be explicitly stacked after #192 or the docs need to state the minimum required Lynx engine/toolchain version very clearly.

Also, the linked Lynx issue references should be reconciled. I saw both lynx#5912 and lynx#5889 in the surrounding discussion/context, and that kind of mismatch makes the support story harder to trust.

[KealanAU]

Thanks — both addressed.

Issue references: the two numbers are an issue↔fix pair, not a mismatch. lynx-family/lynx#5912 is the fix PR; it closes issue #5889. Every mention in the code comments, the spec, the changeset, and the docs now reads "#5912 (closing #5889)" consistently.

Compatibility baseline: you're right that this depends on the engine fix in #5912, which ships in the 3.8.1 line. I've made the requirement explicit:

• The EN + ZH compatibility docs and the changeset now state "requires Lynx engine ≥ 3.8.1", noting that on earlier engines the vars are stamped on the root but never propagate to descendants.
• Added a "depends on chore: update Lynx toolchain to 3.8.1 release line #192 (3.8.1 toolchain), merge after" note to the PR description. These are cross-fork PRs, so the base branch can't be retargeted into a GitHub stack — and merging chore: update Lynx toolchain to 3.8.1 release line #192 into this branch instead would've pulled its full ~100-file diff into this review, so an explicit dependency note is the cleaner option. We'll follow up once chore: update Lynx toolchain to 3.8.1 release line #192 lands.