From 864267b269c27901fb288f9e1c19c4a4431c287e Mon Sep 17 00:00:00 2001
From: Kealan Clarke <59548500+KealanAU@users.noreply.github.com>
Date: Sun, 29 Mar 2026 18:37:09 +1100
Subject: [PATCH 01/16] [fix]: add explicit type annotations, build internal
 package before starting dev watch

---
 packages/vue-lynx/main-thread/src/element-registry.ts | 2 +-
 packages/vue-lynx/runtime/src/TransitionGroup.ts      | 8 +++++---
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/packages/vue-lynx/main-thread/src/element-registry.ts b/packages/vue-lynx/main-thread/src/element-registry.ts
index d2b88d532..b5a5af01b 100644
--- a/packages/vue-lynx/main-thread/src/element-registry.ts
+++ b/packages/vue-lynx/main-thread/src/element-registry.ts
@@ -3,7 +3,7 @@
 // LICENSE file in the root directory of this source tree.
 
 /** Map from BG-thread ShadowElement id to Lynx Main Thread element handle */
-export const elements = new Map<number, LynxElement>();
+export const elements: Map<number, LynxElement> = new Map();
 
 /**
  * PAPI unique ID of the root PageElement.
diff --git a/packages/vue-lynx/runtime/src/TransitionGroup.ts b/packages/vue-lynx/runtime/src/TransitionGroup.ts
index 67f734f19..1dfbc5aff 100644
--- a/packages/vue-lynx/runtime/src/TransitionGroup.ts
+++ b/packages/vue-lynx/runtime/src/TransitionGroup.ts
@@ -13,6 +13,8 @@
 
 import {
   type SetupContext,
+  type VNode,
+  type Component,
   defineComponent,
   getCurrentInstance,
   h,
@@ -126,7 +128,7 @@ export interface TransitionGroupProps extends TransitionProps {
 // <TransitionGroup>
 // ---------------------------------------------------------------------------
 
-export const TransitionGroup = defineComponent({
+export const TransitionGroup: Component = defineComponent({
   name: 'TransitionGroup',
 
   props: {
@@ -152,11 +154,11 @@ export const TransitionGroup = defineComponent({
     moveClass: String,
   },
 
-  setup(props: TransitionGroupProps, { slots }: SetupContext) {
+  setup(props: TransitionGroupProps, { slots }: SetupContext): () => VNode {
     const instance = getCurrentInstance()!;
     const state = useTransitionState();
 
-    return () => {
+    return (): VNode => {
       const rawChildren = slots.default ? slots.default() : [];
       const children = getTransitionRawChildren(rawChildren);
 

From 26308af95aa2b87b28afa94a3b6ddcb72f8a33cf Mon Sep 17 00:00:00 2001
From: Kealan Clarke <59548500+KealanAU@users.noreply.github.com>
Date: Wed, 1 Apr 2026 16:58:35 +1100
Subject: [PATCH 02/16] [feat] updates to have the scoped-css work

---
 examples/css-features/src/App.vue             |   8 +-
 .../css-features/src/ScopedStyleWorking.vue   |  59 +++
 examples/css-features/src/VBindCSS.vue        | 103 +++--
 package.json                                  |   2 +-
 .../template-vue-js/lynx.config.js            |   2 +
 .../template-vue-ts/lynx.config.ts            |   2 +
 packages/upstream-tests/package.json          |   2 +
 .../upstream-tests/src/local-test-setup.ts    |  71 ++++
 .../upstream-tests/src/use-css-vars.spec.ts   | 365 ++++++++++++++++++
 packages/upstream-tests/tsconfig.json         |   5 +
 .../upstream-tests/vitest.local.config.ts     |  82 ++++
 packages/vue-lynx/runtime/src/LYNX-ISSUES.md  |  84 ++++
 packages/vue-lynx/runtime/src/index.ts        |   7 +
 packages/vue-lynx/runtime/src/node-ops.ts     |  14 +
 packages/vue-lynx/runtime/src/use-css-vars.md | 137 +++++++
 packages/vue-lynx/runtime/src/use-css-vars.ts |  86 +++++
 16 files changed, 998 insertions(+), 31 deletions(-)
 create mode 100644 examples/css-features/src/ScopedStyleWorking.vue
 create mode 100644 packages/upstream-tests/src/local-test-setup.ts
 create mode 100644 packages/upstream-tests/src/use-css-vars.spec.ts
 create mode 100644 packages/upstream-tests/vitest.local.config.ts
 create mode 100644 packages/vue-lynx/runtime/src/LYNX-ISSUES.md
 create mode 100644 packages/vue-lynx/runtime/src/use-css-vars.md
 create mode 100644 packages/vue-lynx/runtime/src/use-css-vars.ts

diff --git a/examples/css-features/src/App.vue b/examples/css-features/src/App.vue
index 7a9be7e81..6edf33b29 100644
--- a/examples/css-features/src/App.vue
+++ b/examples/css-features/src/App.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import PlainStyle from './PlainStyle.vue'
 import ScopedStyle from './ScopedStyle.vue'
+import ScopedStyleWorking from './ScopedStyleWorking.vue'
 import CSSModules from './CSSModules.vue'
 import VBindCSS from './VBindCSS.vue'
 import CSSVarsWorkaround from './CSSVarsWorkaround.vue'
@@ -19,13 +20,16 @@ import ImportedCSS from './ImportedCSS.vue'
     <!-- 1. Plain <style> — WORKS -->
     <PlainStyle />
 
-    <!-- 2. <style scoped> — DOES NOT WORK -->
+    <!-- 2a. <style scoped> — DOES NOT WORK -->
     <ScopedStyle />
 
+    <!-- 2b. <style module> as scoped alternative — WORKS -->
+    <ScopedStyleWorking />
+
     <!-- 3. <style module> — SHOULD WORK -->
     <CSSModules />
 
-    <!-- 4. v-bind() in CSS — DOES NOT WORK -->
+    <!-- 4. v-bind() in CSS — WORKS (useCssVars implemented in vue-lynx) -->
     <VBindCSS />
 
     <!-- 5. Workaround: Reactive inline :style -->
diff --git a/examples/css-features/src/ScopedStyleWorking.vue b/examples/css-features/src/ScopedStyleWorking.vue
new file mode 100644
index 000000000..40928e4e9
--- /dev/null
+++ b/examples/css-features/src/ScopedStyleWorking.vue
@@ -0,0 +1,59 @@
+<script setup lang="ts">
+// Working alternative to <style scoped> using <style module>
+//
+// <style scoped> fails in Lynx because:
+//   1. vue-lynx's renderer does not implement setScopeId() in nodeOps,
+//      so data-v-{hash} attributes are never added to elements.
+//   2. Even if they were, Lynx's CSS engine does not support attribute
+//      selectors like [data-v-xxx], so the rules would still not match.
+//
+// <style module> achieves the same scoping goal differently:
+//   1. css-loader renames each class to a unique hash (e.g. .demoText → .demoText_abc123)
+//   2. The mapping is exported as $style — a plain JS object
+//   3. You apply classes with :class="$style.demoText" instead of class="demoText"
+//   4. The CSS rules use the hashed names — plain class selectors, fully supported by Lynx
+</script>
+
+<template>
+  <view :class="$style.card">
+    <text :class="$style.title">&lt;style module&gt; — scoped alternative</text>
+    <text :class="$style.desc">
+      Uses hashed class names instead of [data-v-xxx] attribute selectors.
+      Plain class selectors are fully supported in Lynx.
+    </text>
+    <view :class="$style.demoBox">
+      <text :class="$style.demoText">This text is blue — CSS Modules scoping works</text>
+    </view>
+  </view>
+</template>
+
+<style module>
+.card {
+  display: flex;
+  flex-direction: column;
+  background-color: #e3f2fd;
+  padding: 12px;
+  border-radius: 8px;
+  margin-bottom: 12px;
+}
+.title {
+  font-size: 15px;
+  font-weight: bold;
+  color: #1565c0;
+  margin-bottom: 4px;
+}
+.desc {
+  font-size: 12px;
+  color: #555;
+  margin-bottom: 8px;
+}
+.demoBox {
+  background-color: #fff;
+  padding: 8px;
+  border-radius: 4px;
+}
+.demoText {
+  font-size: 13px;
+  color: blue;
+}
+</style>
diff --git a/examples/css-features/src/VBindCSS.vue b/examples/css-features/src/VBindCSS.vue
index 4b703613f..a1661e2a0 100644
--- a/examples/css-features/src/VBindCSS.vue
+++ b/examples/css-features/src/VBindCSS.vue
@@ -1,44 +1,91 @@
 <script setup lang="ts">
-// Test: v-bind() in <style>
-//
-// RESULT: BUILD ERROR — confirmed.
-//
-// Vue's v-bind() in CSS compiles to a `useCssVars()` call, which is a
-// @vue/runtime-dom API (not runtime-core). vue-lynx only re-exports from
-// @vue/runtime-core, so this API is unavailable.
-//
-// Error message:
-//   ESModulesLinkingError: export 'useCssVars' (imported as '_useCssVars')
-//   was not found in 'vue'
-//
-// Even if useCssVars were exported, it would not work because:
-//   1. useCssVars internally calls `document.getElementById()` — no document in Lynx
-//   2. It sets CSS vars via `el.style.setProperty()` — DOM API, not available
-//   3. The Background Thread cannot directly access native element styles
-//
-// WORKAROUND: Use computed() + reactive :style bindings instead.
-// See CSSVarsWorkaround.vue for the recommended pattern.
+import { ref } from 'vue'
+
+const textColor = ref('#1565c0')
+const bgColor = ref('#e3f2fd')
+const fontSize = ref('14px')
+
+function cycleColor() {
+  const colors = ['#1565c0', '#c62828', '#2e7d32', '#f57f17']
+  const idx = colors.indexOf(textColor.value)
+  textColor.value = colors[(idx + 1) % colors.length]
+  const bgs = ['#e3f2fd', '#ffebee', '#e8f5e9', '#fffde7']
+  bgColor.value = bgs[(idx + 1) % bgs.length]
+}
+
+function cycleFontSize() {
+  const sizes = ['12px', '14px', '16px', '20px']
+  const idx = sizes.indexOf(fontSize.value)
+  fontSize.value = sizes[(idx + 1) % sizes.length]
+}
 </script>
 
 <template>
   <view :style="{
     display: 'flex',
     flexDirection: 'column',
-    backgroundColor: '#ffebee',
+    backgroundColor: bgColor,
     padding: '12px',
     borderRadius: '8px',
     marginBottom: '12px',
   }">
-    <text :style="{ fontSize: '15px', fontWeight: 'bold', color: '#c62828', marginBottom: '4px' }">
-      v-bind() in &lt;style&gt; — BUILD ERROR
+    <text :style="{ fontSize: '15px', fontWeight: 'bold', marginBottom: '4px' }" class="title">
+      v-bind() in &lt;style&gt; — WORKS
     </text>
-    <text :style="{ fontSize: '12px', color: '#555', marginBottom: '8px' }">
-      Vue's v-bind() in CSS compiles to useCssVars() which is a
-      @vue/runtime-dom API. vue-lynx only uses @vue/runtime-core,
-      so this causes an ESModulesLinkingError at build time.
+    <text class="description">
+      textColor: {{ textColor }} | fontSize: {{ fontSize }}
     </text>
-    <text :style="{ fontSize: '11px', color: '#888', fontStyle: 'italic' }">
-      Workaround: use computed() + :style bindings (see below)
+    <text class="sample-text" :style="{ fontSize }">
+      This text uses v-bind() in CSS
     </text>
+    <view :style="{ display: 'flex', flexDirection: 'row', gap: '8px', marginTop: '8px' }">
+      <text
+        :style="{
+          backgroundColor: '#1565c0',
+          color: '#fff',
+          padding: '6px 12px',
+          borderRadius: '4px',
+          fontSize: '12px',
+        }"
+        :bindtap="cycleColor"
+      >
+        Cycle Color
+      </text>
+      <text
+        :style="{
+          backgroundColor: '#2e7d32',
+          color: '#fff',
+          padding: '6px 12px',
+          borderRadius: '4px',
+          fontSize: '12px',
+        }"
+        :bindtap="cycleFontSize"
+      >
+        Cycle Size
+      </text>
+    </view>
   </view>
 </template>
+
+<style>
+.title {
+  color: v-bind(textColor);
+}
+
+.description {
+  font-size: 11px;
+  color: #555;
+  margin-bottom: 8px;
+}
+
+.sample-text {
+  color: v-bind(textColor);
+  /* font-size: v-bind(fontSize) is omitted here.
+     font-size IS in Lynx's default CSS inheritance list and var() in CSS
+     class rules is supported, but dynamic CSS var updates on inline styles
+     do not appear to trigger a layout re-pass for font-size (unlike color,
+     which is paint-only). This gap is undocumented in Lynx and no roadmap
+     item exists for it. font-size is driven via :style binding instead. */
+  font-weight: bold;
+}
+</style>
diff --git a/package.json b/package.json
index a6851e14c..2e4b351ae 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "vue-lynx-monorepo",
-  "private": true,
+  "private": false,
   "scripts": {
     "build": "pnpm --filter vue-lynx run build",
     "build:examples": "pnpm --filter './examples/*' --parallel run build",
diff --git a/packages/create-vue-lynx/template-vue-js/lynx.config.js b/packages/create-vue-lynx/template-vue-js/lynx.config.js
index 7f6efc11f..8cafb6d27 100644
--- a/packages/create-vue-lynx/template-vue-js/lynx.config.js
+++ b/packages/create-vue-lynx/template-vue-js/lynx.config.js
@@ -20,6 +20,8 @@ export default defineConfig({
     }),
     pluginVueLynx({
       optionsApi: false,
+      enableCSSInlineVariables: true,
+      enableCSSInheritance: true,
     }),
   ],
 })
diff --git a/packages/create-vue-lynx/template-vue-ts/lynx.config.ts b/packages/create-vue-lynx/template-vue-ts/lynx.config.ts
index bc9c89d54..625fec73e 100644
--- a/packages/create-vue-lynx/template-vue-ts/lynx.config.ts
+++ b/packages/create-vue-lynx/template-vue-ts/lynx.config.ts
@@ -17,6 +17,8 @@ export default defineConfig({
     }),
     pluginVueLynx({
       optionsApi: false,
+      enableCSSInlineVariables: true,
+      enableCSSInheritance: true,
     }),
   ],
 })
diff --git a/packages/upstream-tests/package.json b/packages/upstream-tests/package.json
index c5ac62288..540e4b198 100644
--- a/packages/upstream-tests/package.json
+++ b/packages/upstream-tests/package.json
@@ -8,6 +8,8 @@
     "test": "vitest run",
     "test:dom": "vitest run --config vitest.dom.config.ts",
     "test:dom:watch": "vitest --config vitest.dom.config.ts",
+    "test:local": "vitest run --config vitest.local.config.ts",
+    "test:local:watch": "vitest --config vitest.local.config.ts",
     "test:watch": "vitest",
     "vuejs:init": "git submodule update --init --depth 1 core",
     "vuejs:status": "cd core && git log --oneline -1"
diff --git a/packages/upstream-tests/src/local-test-setup.ts b/packages/upstream-tests/src/local-test-setup.ts
new file mode 100644
index 000000000..381d68819
--- /dev/null
+++ b/packages/upstream-tests/src/local-test-setup.ts
@@ -0,0 +1,71 @@
+/**
+ * Minimal setup for local (non-upstream) tests that exercise the vue-lynx
+ * BG-thread renderer directly, without the full DOM bridge pipeline.
+ *
+ * The vue-lynx flush module sends ops to the main thread via
+ * `lynx.getNativeApp().callLepusMethod('vuePatchUpdate', ...)`.  In the test
+ * environment `lynx` is not defined, so we stub it here.
+ *
+ * We also capture the JSON-serialised ops that `doFlush` passes to
+ * `callLepusMethod` and re-push them into a test-accessible buffer so that
+ * tests can inspect them via `collectFlushedOps()` after awaiting `nextTick`.
+ */
+
+import { OP } from 'vue-lynx/internal/ops';
+
+// ---------------------------------------------------------------------------
+// Captured ops buffer
+// ---------------------------------------------------------------------------
+
+// Ops that doFlush() sent to callLepusMethod (after JSON round-trip).
+let _capturedOps: unknown[] = [];
+
+/**
+ * Return and clear all ops that have been flushed to the "main thread" since
+ * the last call.  Call this after `await nextTick()` instead of `takeOps()`.
+ */
+export function collectFlushedOps(): unknown[] {
+  const ops = _capturedOps;
+  _capturedOps = [];
+  return ops;
+}
+
+export function resetCapturedOps(): void {
+  _capturedOps = [];
+}
+
+// ---------------------------------------------------------------------------
+// lynx stub
+// ---------------------------------------------------------------------------
+
+const lynxStub = {
+  getNativeApp() {
+    return {
+      callLepusMethod(
+        _method: string,
+        params: { data: string },
+        callback: () => void,
+      ) {
+        // Deserialise and capture the ops for test assertions.
+        const ops: unknown[] = JSON.parse(params.data);
+        _capturedOps.push(...ops);
+        // Simulate synchronous MT acknowledgement.
+        callback();
+      },
+    };
+  },
+};
+
+// Install as a global so flush.ts's `declare var lynx` reference resolves.
+(globalThis as Record<string, unknown>)['lynx'] = lynxStub;
+
+// ---------------------------------------------------------------------------
+// Per-test reset
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  resetCapturedOps();
+});
+
+// Re-export OP for convenience in tests that import from this file.
+export { OP };
diff --git a/packages/upstream-tests/src/use-css-vars.spec.ts b/packages/upstream-tests/src/use-css-vars.spec.ts
new file mode 100644
index 000000000..86f696a6e
--- /dev/null
+++ b/packages/upstream-tests/src/use-css-vars.spec.ts
@@ -0,0 +1,365 @@
+/**
+ * Tests for useCssVars — the Lynx BG-thread implementation of Vue's
+ * CSS v-bind() support.
+ *
+ * useCssVars is called by the SFC compiler when a <style> block uses v-bind().
+ * These tests exercise the function directly (passing the getter manually in
+ * setup()) to verify:
+ *
+ *   1. Basic element — SET_STYLE op emitted on mount and on reactive update.
+ *   2. Fragment root — SET_STYLE emitted for every sibling root element.
+ *   3. Nested component root — CSS vars propagate through SF_COMPONENT paths.
+ *   4. vShow interaction — SET_STYLE preserves `display: none` when v-show is active.
+ *   5. Reactivity — changing the reactive source triggers a new SET_STYLE op
+ *      via watchPostEffect without a manual flush.
+ *
+ * NOTE on ops capture:
+ *   useCssVars calls scheduleFlush() which queues doFlush via queuePostFlushCb.
+ *   doFlush drains the ops buffer (takeOps()) and sends the result to the MT
+ *   via lynx.getNativeApp().callLepusMethod().  The local-test-setup.ts stub
+ *   intercepts callLepusMethod and re-exposes the ops via collectFlushedOps().
+ *   Tests must therefore use collectFlushedOps() (not takeOps()) after awaiting
+ *   nextTick(), since the ops buffer is already empty by that point.
+ */
+
+import {
+  createApp,
+  defineComponent,
+  Fragment,
+  h,
+  nextTick,
+  ref,
+  resetForTesting,
+  useCssVars,
+  vShow,
+  withDirectives,
+} from 'vue-lynx';
+import { OP } from 'vue-lynx/internal/ops';
+import { collectFlushedOps, resetCapturedOps } from './local-test-setup.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Find all SET_STYLE ops in the flat ops buffer.
+ * The buffer format is: [..., OP.SET_STYLE, id, styleObject, ...]
+ * Returns an array of { id, style } tuples for each SET_STYLE op found.
+ */
+function parseSetStyleOps(ops: unknown[]): Array<{ id: unknown; style: unknown }> {
+  const results: Array<{ id: unknown; style: unknown }> = [];
+  for (let i = 0; i < ops.length; i++) {
+    if (ops[i] === OP.SET_STYLE) {
+      results.push({ id: ops[i + 1], style: ops[i + 2] });
+      i += 2; // skip id and style
+    }
+  }
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Test setup
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  resetForTesting();
+  resetCapturedOps();
+});
+
+// ---------------------------------------------------------------------------
+// 1. Basic element
+// ---------------------------------------------------------------------------
+
+describe('useCssVars — basic element', () => {
+  it('emits SET_STYLE with CSS var on mount', async () => {
+    const color = ref('red');
+
+    const App = defineComponent({
+      setup() {
+        useCssVars((_ctx: unknown) => ({ 'abc123': color.value }));
+        return () => h('view', { style: { fontSize: '14px' } });
+      },
+    });
+
+    createApp(App).mount();
+    await nextTick();
+
+    const ops = collectFlushedOps();
+    const styleOps = parseSetStyleOps(ops);
+
+    // There should be at least one SET_STYLE op for the root element
+    expect(styleOps.length).toBeGreaterThanOrEqual(1);
+
+    // The last SET_STYLE for the root element (from useCssVars) should include
+    // the CSS var with the leading '--' added by the implementation.
+    const lastStyleOp = styleOps[styleOps.length - 1];
+    expect(lastStyleOp.style).toMatchObject({
+      '--abc123': 'red',
+    });
+  });
+
+  it('emits a new SET_STYLE op when reactive source updates', async () => {
+    const color = ref('red');
+
+    const App = defineComponent({
+      setup() {
+        useCssVars((_ctx: unknown) => ({ 'abc123': color.value }));
+        return () => h('view');
+      },
+    });
+
+    createApp(App).mount();
+    await nextTick();
+
+    // Drain the mount-time ops
+    collectFlushedOps();
+
+    // Update the reactive source
+    color.value = 'blue';
+    await nextTick();
+
+    const ops = collectFlushedOps();
+    const styleOps = parseSetStyleOps(ops);
+
+    expect(styleOps.length).toBeGreaterThanOrEqual(1);
+    const lastStyleOp = styleOps[styleOps.length - 1];
+    expect(lastStyleOp.style).toMatchObject({
+      '--abc123': 'blue',
+    });
+  });
+
+  it('merges CSS var on top of existing element styles', async () => {
+    const color = ref('green');
+
+    const App = defineComponent({
+      setup() {
+        useCssVars((_ctx: unknown) => ({ 'v1a2b3': color.value }));
+        return () => h('view', { style: { backgroundColor: 'white' } });
+      },
+    });
+
+    createApp(App).mount();
+    await nextTick();
+
+    const ops = collectFlushedOps();
+    const styleOps = parseSetStyleOps(ops);
+
+    // The SET_STYLE from useCssVars must include BOTH the original style AND
+    // the CSS var (useCssVars spreads el._style then adds the vars).
+    const cssVarOp = styleOps.find(
+      (op) => (op.style as Record<string, unknown>)['--v1a2b3'] !== undefined,
+    );
+    expect(cssVarOp).toBeDefined();
+    expect(cssVarOp!.style).toMatchObject({
+      backgroundColor: 'white',
+      '--v1a2b3': 'green',
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. Fragment root
+// ---------------------------------------------------------------------------
+
+describe('useCssVars — fragment root', () => {
+  it('emits SET_STYLE for every sibling root element in a Fragment', async () => {
+    const color = ref('purple');
+
+    const App = defineComponent({
+      setup() {
+        useCssVars((_ctx: unknown) => ({ 'frag1': color.value }));
+        return () =>
+          h(Fragment, null, [
+            h('view', { key: 'a' }),
+            h('text', { key: 'b' }),
+            h('image', { key: 'c' }),
+          ]);
+      },
+    });
+
+    createApp(App).mount();
+    await nextTick();
+
+    const ops = collectFlushedOps();
+    const styleOps = parseSetStyleOps(ops);
+
+    // Each of the three root fragment children should have received a SET_STYLE
+    // with the CSS var injected.
+    const cssVarOps = styleOps.filter(
+      (op) => (op.style as Record<string, unknown>)['--frag1'] !== undefined,
+    );
+
+    expect(cssVarOps.length).toBe(3);
+
+    for (const op of cssVarOps) {
+      expect((op.style as Record<string, unknown>)['--frag1']).toBe('purple');
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3. Nested component root
+// ---------------------------------------------------------------------------
+
+describe('useCssVars — nested component root', () => {
+  it('propagates CSS vars through SF_COMPONENT path to child element', async () => {
+    const color = ref('orange');
+
+    // Inner child component — single root element
+    const Child = defineComponent({
+      setup() {
+        return () => h('view');
+      },
+    });
+
+    // Parent applies useCssVars; its subtree is a component (Child)
+    const Parent = defineComponent({
+      setup() {
+        useCssVars((_ctx: unknown) => ({ 'nested1': color.value }));
+        return () => h(Child);
+      },
+    });
+
+    createApp(Parent).mount();
+    await nextTick();
+
+    const ops = collectFlushedOps();
+    const styleOps = parseSetStyleOps(ops);
+
+    // The CSS var must reach the actual DOM element inside Child
+    const cssVarOp = styleOps.find(
+      (op) => (op.style as Record<string, unknown>)['--nested1'] !== undefined,
+    );
+    expect(cssVarOp).toBeDefined();
+    expect((cssVarOp!.style as Record<string, unknown>)['--nested1']).toBe('orange');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 4. vShow interaction
+// ---------------------------------------------------------------------------
+
+describe('useCssVars — vShow interaction', () => {
+  it('preserves display:none when v-show is false alongside CSS vars', async () => {
+    const color = ref('teal');
+    const visible = ref(false);
+
+    const App = defineComponent({
+      setup() {
+        useCssVars((_ctx: unknown) => ({ 'show1': color.value }));
+        return () =>
+          withDirectives(h('view'), [[vShow, visible.value]]);
+      },
+    });
+
+    createApp(App).mount();
+    await nextTick();
+
+    const ops = collectFlushedOps();
+    const styleOps = parseSetStyleOps(ops);
+
+    // The SET_STYLE emitted by useCssVars must include display:none because
+    // applyVarsToEl reads el._vShowHidden and merges it in.
+    const cssVarOp = styleOps.find(
+      (op) => (op.style as Record<string, unknown>)['--show1'] !== undefined,
+    );
+
+    expect(cssVarOp).toBeDefined();
+    expect((cssVarOp!.style as Record<string, unknown>)['display']).toBe('none');
+    expect((cssVarOp!.style as Record<string, unknown>)['--show1']).toBe('teal');
+  });
+
+  it('does not add display:none when v-show is true', async () => {
+    const color = ref('teal');
+    const visible = ref(true);
+
+    const App = defineComponent({
+      setup() {
+        useCssVars((_ctx: unknown) => ({ 'show2': color.value }));
+        return () =>
+          withDirectives(h('view'), [[vShow, visible.value]]);
+      },
+    });
+
+    createApp(App).mount();
+    await nextTick();
+
+    const ops = collectFlushedOps();
+    const styleOps = parseSetStyleOps(ops);
+
+    const cssVarOp = styleOps.find(
+      (op) => (op.style as Record<string, unknown>)['--show2'] !== undefined,
+    );
+
+    expect(cssVarOp).toBeDefined();
+    expect((cssVarOp!.style as Record<string, unknown>)['display']).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 5. Reactivity — watchPostEffect triggers automatically
+// ---------------------------------------------------------------------------
+
+describe('useCssVars — reactivity', () => {
+  it('triggers SET_STYLE via watchPostEffect without manual flush', async () => {
+    const color = ref('black');
+
+    const App = defineComponent({
+      setup() {
+        useCssVars((_ctx: unknown) => ({ 'react1': color.value }));
+        return () => h('view');
+      },
+    });
+
+    createApp(App).mount();
+    await nextTick();
+    collectFlushedOps(); // drain mount ops
+
+    // Change the reactive source — the watchPostEffect inside useCssVars
+    // should automatically schedule and emit a new SET_STYLE op.
+    color.value = 'white';
+
+    // nextTick() waits for the Vue scheduler to flush the post-effect queue,
+    // which is exactly when watchPostEffect fires — no manual flush needed.
+    await nextTick();
+
+    const ops = collectFlushedOps();
+    const styleOps = parseSetStyleOps(ops);
+
+    expect(styleOps.length).toBeGreaterThanOrEqual(1);
+
+    const cssVarOp = styleOps.find(
+      (op) => (op.style as Record<string, unknown>)['--react1'] !== undefined,
+    );
+    expect(cssVarOp).toBeDefined();
+    expect((cssVarOp!.style as Record<string, unknown>)['--react1']).toBe('white');
+  });
+
+  it('does not emit SET_STYLE when reactive source does not change', async () => {
+    const color = ref('gray');
+
+    const App = defineComponent({
+      setup() {
+        useCssVars((_ctx: unknown) => ({ 'react2': color.value }));
+        return () => h('view');
+      },
+    });
+
+    createApp(App).mount();
+    await nextTick();
+    collectFlushedOps(); // drain mount ops
+
+    // Setting the same value should not trigger a new effect run
+    color.value = 'gray';
+    await nextTick();
+
+    const ops = collectFlushedOps();
+    const styleOps = parseSetStyleOps(ops);
+
+    // No SET_STYLE from useCssVars — the reactive dependency didn't change
+    const cssVarOp = styleOps.find(
+      (op) => (op.style as Record<string, unknown>)['--react2'] !== undefined,
+    );
+    expect(cssVarOp).toBeUndefined();
+  });
+});
diff --git a/packages/upstream-tests/tsconfig.json b/packages/upstream-tests/tsconfig.json
index 01004aa56..792c9bae5 100644
--- a/packages/upstream-tests/tsconfig.json
+++ b/packages/upstream-tests/tsconfig.json
@@ -7,6 +7,11 @@
     "esModuleInterop": true,
     "skipLibCheck": true,
     "types": ["vitest/globals"],
+    "baseUrl": ".",
+    "paths": {
+      "vue-lynx": ["../vue-lynx/runtime/src/index.ts"],
+      "vue-lynx/internal/ops": ["../vue-lynx/internal/src/ops.ts"]
+    },
   },
   "include": ["src"],
   "references": [
diff --git a/packages/upstream-tests/vitest.local.config.ts b/packages/upstream-tests/vitest.local.config.ts
new file mode 100644
index 000000000..beba4a8c9
--- /dev/null
+++ b/packages/upstream-tests/vitest.local.config.ts
@@ -0,0 +1,82 @@
+/**
+ * Vitest configuration for vue-lynx-specific (non-upstream) tests.
+ *
+ * These tests exercise vue-lynx runtime internals directly — they do NOT
+ * require the upstream Vue core submodule or the full DOM bridge pipeline.
+ * They only need the BG-thread renderer (ShadowElement + ops buffer).
+ */
+
+import { defineConfig } from 'vitest/config';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export default defineConfig({
+  define: {
+    __DEV__: 'true',
+    __TEST__: 'true',
+    __BROWSER__: 'false',
+    __GLOBAL__: 'false',
+    __ESM_BUNDLER__: 'true',
+    __ESM_BROWSER__: 'false',
+    __CJS__: 'false',
+    __SSR__: 'false',
+    __FEATURE_OPTIONS_API__: 'true',
+    __VUE_OPTIONS_API__: 'true',
+    __VUE_PROD_DEVTOOLS__: 'false',
+    __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: 'false',
+    __VUE_LYNX_AUTO_PIXEL_UNIT__: 'true',
+    __FEATURE_SUSPENSE__: 'true',
+    __FEATURE_PROD_DEVTOOLS__: 'false',
+    __FEATURE_PROD_HYDRATION_MISMATCH_DETAILS__: 'false',
+    __COMPAT__: 'false',
+    __VERSION__: '"3.5.12"',
+  },
+  test: {
+    globals: true,
+    include: [
+      path.resolve(__dirname, 'src/**/*.spec.ts'),
+    ],
+    alias: [
+      // vue-lynx/internal/ops → source
+      {
+        find: 'vue-lynx/internal/ops',
+        replacement: path.resolve(__dirname, '../vue-lynx/internal/src/ops.ts'),
+      },
+      // vue-lynx → runtime source
+      {
+        find: /^vue-lynx$/,
+        replacement: path.resolve(__dirname, '../vue-lynx/runtime/src/index.ts'),
+      },
+      // Ensure all @vue/* resolve to the same ESM bundle instance so
+      // module-level state (currentRenderingInstance, scheduler, etc.) is
+      // shared between vue-lynx and the test file.
+      {
+        find: '@vue/runtime-core',
+        replacement: path.join(
+          path.dirname(require.resolve('@vue/runtime-core/package.json')),
+          'dist/runtime-core.esm-bundler.js',
+        ),
+      },
+      {
+        find: '@vue/reactivity',
+        replacement: path.join(
+          path.dirname(require.resolve('@vue/reactivity/package.json')),
+          'dist/reactivity.esm-bundler.js',
+        ),
+      },
+      {
+        find: '@vue/shared',
+        replacement: path.join(
+          path.dirname(require.resolve('@vue/shared/package.json')),
+          'dist/shared.esm-bundler.js',
+        ),
+      },
+    ],
+    setupFiles: [
+      path.resolve(__dirname, 'src/local-test-setup.ts'),
+    ],
+    testTimeout: 10000,
+  },
+});
diff --git a/packages/vue-lynx/runtime/src/LYNX-ISSUES.md b/packages/vue-lynx/runtime/src/LYNX-ISSUES.md
new file mode 100644
index 000000000..a034ced02
--- /dev/null
+++ b/packages/vue-lynx/runtime/src/LYNX-ISSUES.md
@@ -0,0 +1,84 @@
+# Lynx Engine Issues to File
+
+Issues discovered while implementing `v-bind()` in `<style>` blocks for vue-lynx.
+File these at https://github.com/lynx-family/lynx/issues.
+
+---
+
+## 1. `font-size: var(--*)` does not trigger relayout on dynamic inline CSS var update
+
+**Repo:** `lynx-family/lynx`
+**Suggested label:** `bug`, `css`
+
+### Description
+
+When a CSS custom property is set as an inline style and a CSS class rule references it via `var()`, paint-only properties (e.g. `color`) update correctly on dynamic change. Layout-affecting properties (e.g. `font-size`) do not — the initial render value is applied, but subsequent reactive updates have no visual effect.
+
+### Reproduction
+
+Enable `enableCSSInlineVariables: true` and `enableCSSInheritance: true`. Mount a component where:
+
+1. A CSS custom property `--font-size` is set on the root element's inline style
+2. A descendant element has a CSS class rule `font-size: var(--font-size)`
+3. The inline style is updated (e.g. from `14px` to `20px`)
+
+**Expected:** the descendant element re-renders at the new font size.
+**Actual:** the font size does not change. The CSS var value is updated in the inline style, but no layout re-pass is triggered.
+
+### Contrast
+
+`color: var(--color)` in the same setup updates correctly, suggesting the engine re-evaluates paint properties on CSS var change but does not re-trigger layout measurement.
+
+### Context
+
+- `font-size` is in the default `enableCSSInheritance` property list
+- `font-size: var(--x)` in static CSS class rules works on initial render
+- Inline CSS variable support shipped in Lynx 3.6.0 ([#3136](https://github.com/lynx-family/lynx/pull/3136), [#3518](https://github.com/lynx-family/lynx/pull/3518))
+- No prior issue filed for this specific case
+
+### Workaround
+
+Drive `font-size` via an inline `:style` binding directly on the element instead of through a CSS class rule with `var()`.
+
+---
+
+## 2. Attribute selectors (`[data-v-xxx]`) not supported — `<style scoped>` silently broken
+
+**Repo:** `lynx-family/lynx`
+**Suggested label:** `enhancement`, `css`
+
+### Description
+
+Vue's `<style scoped>` compiles CSS rules to use attribute selectors (e.g. `.title[data-v-abc123]`) and adds the matching attribute to every element at render time. Lynx's CSS engine does not support attribute selectors, so scoped CSS rules are silently ignored — no error, no warning, styles simply don't apply.
+
+### Impact
+
+Any Vue component that uses `<style scoped>` (the default in most Vue tooling and tutorials) will appear unstyled. Because there is no error, this is a silent failure that is difficult to diagnose.
+
+### Behaviour observed
+
+- Elements have the correct class names in the rendered tree
+- The `data-v-xxx` scope attributes are never present on elements (vue-lynx's renderer does not implement `setScopeId` since the attributes serve no purpose without engine support)
+- CSS rules with attribute selectors produce no match
+
+### Request
+
+Support attribute selectors in the CSS engine, or document the limitation explicitly in the Lynx CSS reference with a recommended alternative.
+
+### Workaround
+
+Use `<style module>` with `:class="$style.className"` bindings. CSS Modules achieve the same component-scoping goal using hashed class names (plain class selectors), which Lynx fully supports.
+
+---
+
+## 3. (Known, open) Chained CSS variable references not evaluated
+
+**Repo:** `lynx-family/lynx`
+**Existing issue:** [#816](https://github.com/lynx-family/lynx/issues/816)
+**Status:** Open, assigned, as of April 2026
+
+### Description
+
+A CSS variable that references another variable (`--color-critical: var(--color-red)`) is not evaluated correctly and can cause elements to disappear from rendering.
+
+This is already tracked. No action needed unless you have additional reproduction context to add to the existing issue.
diff --git a/packages/vue-lynx/runtime/src/index.ts b/packages/vue-lynx/runtime/src/index.ts
index 8fb594cb0..c931f4519 100644
--- a/packages/vue-lynx/runtime/src/index.ts
+++ b/packages/vue-lynx/runtime/src/index.ts
@@ -740,6 +740,13 @@ export { version } from '@vue/runtime-core';
  */
 export { mergeProps } from '@vue/runtime-core';
 
+// ===========================================================================
+// @internal — CSS v-bind() support
+// ===========================================================================
+
+/** @hidden */
+export { useCssVars } from './use-css-vars.js';
+
 // ===========================================================================
 // @internal — Template compiler runtime helpers
 // ===========================================================================
diff --git a/packages/vue-lynx/runtime/src/node-ops.ts b/packages/vue-lynx/runtime/src/node-ops.ts
index 1ef478bee..5a3ffd813 100644
--- a/packages/vue-lynx/runtime/src/node-ops.ts
+++ b/packages/vue-lynx/runtime/src/node-ops.ts
@@ -309,6 +309,20 @@ export const nodeOps: RendererOptions<ShadowElement, ShadowElement> = {
   nextSibling(node: ShadowElement): ShadowElement | null {
     return node.next;
   },
+
+  // Vue calls setScopeId when mounting a component that uses <style scoped>.
+  // Lynx's CSS engine does not support the attribute selectors ([data-v-xxx])
+  // that scoped CSS generates, so scoped styles will never match any element.
+  // We emit a dev warning pointing to the supported alternative.
+  setScopeId(_el: ShadowElement, id: string): void {
+    if (__DEV__) {
+      console.warn(
+        `[vue-lynx] <style scoped> is not supported (scope id: ${id}). `
+        + `Lynx's CSS engine does not support attribute selectors ([data-v-xxx]). `
+        + `Use <style module> with :class="$style.className" for component-scoped styles instead.`,
+      );
+    }
+  },
 };
 
 /** Reset module state – for testing only. */
diff --git a/packages/vue-lynx/runtime/src/use-css-vars.md b/packages/vue-lynx/runtime/src/use-css-vars.md
new file mode 100644
index 000000000..8d8657220
--- /dev/null
+++ b/packages/vue-lynx/runtime/src/use-css-vars.md
@@ -0,0 +1,137 @@
+# `v-bind()` in `<style>` blocks
+
+## Overview
+
+Vue's SFC compiler lets you reference reactive JavaScript values directly inside CSS:
+
+```vue
+<script setup>
+import { ref } from 'vue'
+const textColor = ref('#1565c0')
+</script>
+
+<style>
+.title {
+  color: v-bind(textColor);
+}
+</style>
+```
+
+The compiler transforms this at build time:
+
+- **CSS** — `color: v-bind(textColor)` becomes `color: var(--v33993c7f)`
+- **JS** — a `useCssVars` call is injected into `setup()`: `useCssVars(_ctx => ({ "v33993c7f": _ctx.textColor }))`
+
+The hash (`v33993c7f`) is deterministic and scoped per component.
+
+---
+
+## Setup
+
+Two flags must be set in `lynx.config.ts`:
+
+```ts
+pluginVueLynx({
+  enableCSSInlineVariables: true, // allows --* properties in inline styles
+  enableCSSInheritance: true,     // allows CSS vars to cascade to child elements
+})
+```
+
+Without `enableCSSInlineVariables` the engine ignores `--*` on inline styles. Without `enableCSSInheritance` the variable is set on the component root but never reaches descendant elements.
+
+---
+
+## What works
+
+```vue
+<style>
+.title {
+  color: v-bind(textColor);         /* ✓ paint property — updates reactively */
+}
+.card {
+  background-color: v-bind(bgColor); /* ✓ paint property — updates reactively */
+}
+</style>
+```
+
+Paint-only properties (`color`, `background-color`, `opacity`, `border-color`) update correctly when the reactive value changes.
+
+---
+
+## Known limitation — layout properties
+
+```vue
+<style>
+.text {
+  font-size: v-bind(fontSize); /* ✗ does not update reactively */
+}
+</style>
+```
+
+`font-size` and other layout-affecting properties do not update visually when the reactive value changes. The CSS var is set correctly on the root element, but the Lynx engine does not appear to trigger a layout re-pass when an inherited inline CSS var changes. This is specific to dynamic updates — the initial render value is applied correctly.
+
+**Workaround:** drive layout properties via `:style` binding directly on the element.
+
+```vue
+<text :style="{ fontSize }">...</text>
+```
+
+This is undocumented behaviour in the Lynx engine. See [`LYNX-ISSUES.md`](./LYNX-ISSUES.md) for the issue to file upstream.
+
+---
+
+## Use `<style>` not `<style scoped>`
+
+`<style scoped>` does not work in Lynx — the engine does not support the `[data-v-xxx]` attribute selectors Vue generates for scoped styles. Use plain `<style>` for global rules, or `<style module>` for component-scoped styles.
+
+```vue
+<!-- ✗ scoped — rules are silently ignored in Lynx -->
+<style scoped>
+.title { color: v-bind(textColor); }
+</style>
+
+<!-- ✓ plain — works -->
+<style>
+.title { color: v-bind(textColor); }
+</style>
+```
+
+A DEV-mode console warning is emitted when a scoped component mounts, pointing to `<style module>` as the alternative.
+
+---
+
+## How it works internally
+
+`use-css-vars.ts` provides a Lynx-native `useCssVars` that replaces the `@vue/runtime-dom` version (which uses DOM APIs unavailable in Lynx's Background Thread). It is re-exported from `index.ts` so the compiler-generated `import { useCssVars } from 'vue'` resolves correctly.
+
+```
+useCssVars(getter)
+  └── watchPostEffect(() => {
+        vars = getter(instance.proxy)
+        applyVarsToVNode(instance.subTree, vars)
+      })
+
+applyVarsToVNode(vnode, vars)
+  ├── SF_ELEMENT       → applyVarsToEl(el, vars)
+  ├── SF_COMPONENT     → recurse into vnode.component.subTree
+  └── SF_ARRAY_CHILDREN → walk each child (Fragment support)
+
+applyVarsToEl(el: ShadowElement, vars)
+  ├── merge vars into el._style as '--key': value
+  ├── preserve vShow hidden state
+  └── pushOp(OP.SET_STYLE, el.id, style) + scheduleFlush()
+```
+
+The SFC compiler passes keys without a leading `--` (e.g. `"v33993c7f"`). The implementation adds `--` here, matching `@vue/runtime-dom`'s `el.style.setProperty('--v33993c7f', value)`.
+
+---
+
+## File map
+
+| File | Role |
+|---|---|
+| `runtime/src/use-css-vars.ts` | Lynx-specific `useCssVars` implementation |
+| `runtime/src/index.ts` | Re-exports `useCssVars` so the compiler alias resolves |
+| `runtime/src/node-ops.ts` | `setScopeId` — emits DEV warning for `<style scoped>` |
+| `examples/css-features/src/VBindCSS.vue` | Live example |
+| `examples/css-features/lynx.config.ts` | Config with required flags |
diff --git a/packages/vue-lynx/runtime/src/use-css-vars.ts b/packages/vue-lynx/runtime/src/use-css-vars.ts
new file mode 100644
index 000000000..d51a30d24
--- /dev/null
+++ b/packages/vue-lynx/runtime/src/use-css-vars.ts
@@ -0,0 +1,86 @@
+// Copyright 2026 Xuan Huang (huxpro). All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+import { getCurrentInstance, watchPostEffect } from '@vue/runtime-core';
+import type { VNode } from '@vue/runtime-core';
+
+import { OP, pushOp } from './ops.js';
+import { scheduleFlush } from './flush.js';
+import { ShadowElement } from './shadow-element.js';
+
+// ShapeFlags from @vue/shared (not publicly exported from runtime-core).
+// Kept as plain constants to avoid a hard dep on @vue/shared internals.
+const SF_ELEMENT = 1;
+const SF_COMPONENT = 6; // STATEFUL_COMPONENT (4) | FUNCTIONAL_COMPONENT (2)
+const SF_ARRAY_CHILDREN = 16;
+
+function applyVarsToEl(el: ShadowElement, vars: Record<string, string>): void {
+  const style: Record<string, unknown> = { ...el._style };
+  for (const key in vars) {
+    // The SFC compiler passes keys WITHOUT the leading '--' (e.g. "v33993c7f").
+    // We add '--' here, matching what @vue/runtime-dom does with el.style.setProperty().
+    style[`--${key}`] = vars[key];
+  }
+  // Preserve vShow hidden state
+  const effective = el._vShowHidden ? { ...style, display: 'none' } : style;
+  pushOp(OP.SET_STYLE, el.id, effective);
+  scheduleFlush();
+}
+
+function applyVarsToVNode(
+  vnode: VNode | null | undefined,
+  vars: Record<string, string>,
+): void {
+  if (!vnode) return;
+  const { shapeFlag, el } = vnode;
+
+  if (shapeFlag & SF_ELEMENT) {
+    if (el instanceof ShadowElement) {
+      applyVarsToEl(el, vars);
+    }
+  } else if (shapeFlag & SF_COMPONENT) {
+    // Recurse into the component's rendered subtree
+    if (vnode.component) {
+      applyVarsToVNode(vnode.component.subTree, vars);
+    }
+  }
+
+  // Fragment / array children — walk every child
+  if (shapeFlag & SF_ARRAY_CHILDREN) {
+    const children = vnode.children as VNode[];
+    for (const child of children) {
+      applyVarsToVNode(child, vars);
+    }
+  }
+}
+
+/**
+ * Lynx-specific implementation of Vue's `useCssVars`.
+ *
+ * Vue's SFC compiler transforms `v-bind(expr)` inside a `<style>` block into:
+ * - CSS:  `color: var(--v33993c7f)`
+ * - JS:   `useCssVars(_ctx => ({ "v33993c7f": _ctx.textColor }))`
+ *
+ * The standard `@vue/runtime-dom` version uses DOM APIs (`el.style.setProperty`)
+ * which are unavailable in Lynx's Background Thread.  This implementation
+ * instead merges the CSS variables into the element's inline style and sends
+ * them to the Main Thread via the ops pipeline.
+ *
+ * Requires `enableCSSInlineVariables: true` and `enableCSSInheritance: true`
+ * in `lynx.config.ts` so the Lynx engine propagates `--*` inline-style vars
+ * to descendant elements.
+ *
+ * @hidden
+ */
+export function useCssVars(
+  getter: (ctx: unknown) => Record<string, string>,
+): void {
+  const instance = getCurrentInstance();
+  if (!instance) return;
+
+  watchPostEffect(() => {
+    const vars = getter(instance.proxy);
+    applyVarsToVNode(instance.subTree, vars);
+  });
+}

From 2ecaeaa37d61110ab004fca74b6838fc43261739 Mon Sep 17 00:00:00 2001
From: Kealan Clarke <59548500+KealanAU@users.noreply.github.com>
Date: Wed, 1 Apr 2026 21:46:56 +1100
Subject: [PATCH 03/16] =?UTF-8?q?chore:=20fix=20build=20=E2=80=94=20move?=
 =?UTF-8?q?=20docs=20out=20of=20runtime/src,=20restore=20private=20flag?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Move use-css-vars.md and LYNX-ISSUES.md from runtime/src/ to
  packages/vue-lynx/docs/ so rslib does not try to bundle them
- Restore root package.json private: true (was accidentally set to false)
---
 package.json                                            | 2 +-
 packages/vue-lynx/{runtime/src => docs}/LYNX-ISSUES.md  | 0
 packages/vue-lynx/{runtime/src => docs}/use-css-vars.md | 0
 3 files changed, 1 insertion(+), 1 deletion(-)
 rename packages/vue-lynx/{runtime/src => docs}/LYNX-ISSUES.md (100%)
 rename packages/vue-lynx/{runtime/src => docs}/use-css-vars.md (100%)

diff --git a/package.json b/package.json
index 2e4b351ae..a6851e14c 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "vue-lynx-monorepo",
-  "private": false,
+  "private": true,
   "scripts": {
     "build": "pnpm --filter vue-lynx run build",
     "build:examples": "pnpm --filter './examples/*' --parallel run build",
diff --git a/packages/vue-lynx/runtime/src/LYNX-ISSUES.md b/packages/vue-lynx/docs/LYNX-ISSUES.md
similarity index 100%
rename from packages/vue-lynx/runtime/src/LYNX-ISSUES.md
rename to packages/vue-lynx/docs/LYNX-ISSUES.md
diff --git a/packages/vue-lynx/runtime/src/use-css-vars.md b/packages/vue-lynx/docs/use-css-vars.md
similarity index 100%
rename from packages/vue-lynx/runtime/src/use-css-vars.md
rename to packages/vue-lynx/docs/use-css-vars.md

From 3c30c1835b58102a2aa7cba666275bfad1fe0f96 Mon Sep 17 00:00:00 2001
From: Kealan Clarke <59548500+KealanAU@users.noreply.github.com>
Date: Sat, 4 Apr 2026 01:54:12 +1100
Subject: [PATCH 04/16] chore: remove internal docs from PR

---
 packages/vue-lynx/docs/LYNX-ISSUES.md  |  84 ---------------
 packages/vue-lynx/docs/use-css-vars.md | 137 -------------------------
 2 files changed, 221 deletions(-)
 delete mode 100644 packages/vue-lynx/docs/LYNX-ISSUES.md
 delete mode 100644 packages/vue-lynx/docs/use-css-vars.md

diff --git a/packages/vue-lynx/docs/LYNX-ISSUES.md b/packages/vue-lynx/docs/LYNX-ISSUES.md
deleted file mode 100644
index a034ced02..000000000
--- a/packages/vue-lynx/docs/LYNX-ISSUES.md
+++ /dev/null
@@ -1,84 +0,0 @@
-# Lynx Engine Issues to File
-
-Issues discovered while implementing `v-bind()` in `<style>` blocks for vue-lynx.
-File these at https://github.com/lynx-family/lynx/issues.
-
----
-
-## 1. `font-size: var(--*)` does not trigger relayout on dynamic inline CSS var update
-
-**Repo:** `lynx-family/lynx`
-**Suggested label:** `bug`, `css`
-
-### Description
-
-When a CSS custom property is set as an inline style and a CSS class rule references it via `var()`, paint-only properties (e.g. `color`) update correctly on dynamic change. Layout-affecting properties (e.g. `font-size`) do not — the initial render value is applied, but subsequent reactive updates have no visual effect.
-
-### Reproduction
-
-Enable `enableCSSInlineVariables: true` and `enableCSSInheritance: true`. Mount a component where:
-
-1. A CSS custom property `--font-size` is set on the root element's inline style
-2. A descendant element has a CSS class rule `font-size: var(--font-size)`
-3. The inline style is updated (e.g. from `14px` to `20px`)
-
-**Expected:** the descendant element re-renders at the new font size.
-**Actual:** the font size does not change. The CSS var value is updated in the inline style, but no layout re-pass is triggered.
-
-### Contrast
-
-`color: var(--color)` in the same setup updates correctly, suggesting the engine re-evaluates paint properties on CSS var change but does not re-trigger layout measurement.
-
-### Context
-
-- `font-size` is in the default `enableCSSInheritance` property list
-- `font-size: var(--x)` in static CSS class rules works on initial render
-- Inline CSS variable support shipped in Lynx 3.6.0 ([#3136](https://github.com/lynx-family/lynx/pull/3136), [#3518](https://github.com/lynx-family/lynx/pull/3518))
-- No prior issue filed for this specific case
-
-### Workaround
-
-Drive `font-size` via an inline `:style` binding directly on the element instead of through a CSS class rule with `var()`.
-
----
-
-## 2. Attribute selectors (`[data-v-xxx]`) not supported — `<style scoped>` silently broken
-
-**Repo:** `lynx-family/lynx`
-**Suggested label:** `enhancement`, `css`
-
-### Description
-
-Vue's `<style scoped>` compiles CSS rules to use attribute selectors (e.g. `.title[data-v-abc123]`) and adds the matching attribute to every element at render time. Lynx's CSS engine does not support attribute selectors, so scoped CSS rules are silently ignored — no error, no warning, styles simply don't apply.
-
-### Impact
-
-Any Vue component that uses `<style scoped>` (the default in most Vue tooling and tutorials) will appear unstyled. Because there is no error, this is a silent failure that is difficult to diagnose.
-
-### Behaviour observed
-
-- Elements have the correct class names in the rendered tree
-- The `data-v-xxx` scope attributes are never present on elements (vue-lynx's renderer does not implement `setScopeId` since the attributes serve no purpose without engine support)
-- CSS rules with attribute selectors produce no match
-
-### Request
-
-Support attribute selectors in the CSS engine, or document the limitation explicitly in the Lynx CSS reference with a recommended alternative.
-
-### Workaround
-
-Use `<style module>` with `:class="$style.className"` bindings. CSS Modules achieve the same component-scoping goal using hashed class names (plain class selectors), which Lynx fully supports.
-
----
-
-## 3. (Known, open) Chained CSS variable references not evaluated
-
-**Repo:** `lynx-family/lynx`
-**Existing issue:** [#816](https://github.com/lynx-family/lynx/issues/816)
-**Status:** Open, assigned, as of April 2026
-
-### Description
-
-A CSS variable that references another variable (`--color-critical: var(--color-red)`) is not evaluated correctly and can cause elements to disappear from rendering.
-
-This is already tracked. No action needed unless you have additional reproduction context to add to the existing issue.
diff --git a/packages/vue-lynx/docs/use-css-vars.md b/packages/vue-lynx/docs/use-css-vars.md
deleted file mode 100644
index 8d8657220..000000000
--- a/packages/vue-lynx/docs/use-css-vars.md
+++ /dev/null
@@ -1,137 +0,0 @@
-# `v-bind()` in `<style>` blocks
-
-## Overview
-
-Vue's SFC compiler lets you reference reactive JavaScript values directly inside CSS:
-
-```vue
-<script setup>
-import { ref } from 'vue'
-const textColor = ref('#1565c0')
-</script>
-
-<style>
-.title {
-  color: v-bind(textColor);
-}
-</style>
-```
-
-The compiler transforms this at build time:
-
-- **CSS** — `color: v-bind(textColor)` becomes `color: var(--v33993c7f)`
-- **JS** — a `useCssVars` call is injected into `setup()`: `useCssVars(_ctx => ({ "v33993c7f": _ctx.textColor }))`
-
-The hash (`v33993c7f`) is deterministic and scoped per component.
-
----
-
-## Setup
-
-Two flags must be set in `lynx.config.ts`:
-
-```ts
-pluginVueLynx({
-  enableCSSInlineVariables: true, // allows --* properties in inline styles
-  enableCSSInheritance: true,     // allows CSS vars to cascade to child elements
-})
-```
-
-Without `enableCSSInlineVariables` the engine ignores `--*` on inline styles. Without `enableCSSInheritance` the variable is set on the component root but never reaches descendant elements.
-
----
-
-## What works
-
-```vue
-<style>
-.title {
-  color: v-bind(textColor);         /* ✓ paint property — updates reactively */
-}
-.card {
-  background-color: v-bind(bgColor); /* ✓ paint property — updates reactively */
-}
-</style>
-```
-
-Paint-only properties (`color`, `background-color`, `opacity`, `border-color`) update correctly when the reactive value changes.
-
----
-
-## Known limitation — layout properties
-
-```vue
-<style>
-.text {
-  font-size: v-bind(fontSize); /* ✗ does not update reactively */
-}
-</style>
-```
-
-`font-size` and other layout-affecting properties do not update visually when the reactive value changes. The CSS var is set correctly on the root element, but the Lynx engine does not appear to trigger a layout re-pass when an inherited inline CSS var changes. This is specific to dynamic updates — the initial render value is applied correctly.
-
-**Workaround:** drive layout properties via `:style` binding directly on the element.
-
-```vue
-<text :style="{ fontSize }">...</text>
-```
-
-This is undocumented behaviour in the Lynx engine. See [`LYNX-ISSUES.md`](./LYNX-ISSUES.md) for the issue to file upstream.
-
----
-
-## Use `<style>` not `<style scoped>`
-
-`<style scoped>` does not work in Lynx — the engine does not support the `[data-v-xxx]` attribute selectors Vue generates for scoped styles. Use plain `<style>` for global rules, or `<style module>` for component-scoped styles.
-
-```vue
-<!-- ✗ scoped — rules are silently ignored in Lynx -->
-<style scoped>
-.title { color: v-bind(textColor); }
-</style>
-
-<!-- ✓ plain — works -->
-<style>
-.title { color: v-bind(textColor); }
-</style>
-```
-
-A DEV-mode console warning is emitted when a scoped component mounts, pointing to `<style module>` as the alternative.
-
----
-
-## How it works internally
-
-`use-css-vars.ts` provides a Lynx-native `useCssVars` that replaces the `@vue/runtime-dom` version (which uses DOM APIs unavailable in Lynx's Background Thread). It is re-exported from `index.ts` so the compiler-generated `import { useCssVars } from 'vue'` resolves correctly.
-
-```
-useCssVars(getter)
-  └── watchPostEffect(() => {
-        vars = getter(instance.proxy)
-        applyVarsToVNode(instance.subTree, vars)
-      })
-
-applyVarsToVNode(vnode, vars)
-  ├── SF_ELEMENT       → applyVarsToEl(el, vars)
-  ├── SF_COMPONENT     → recurse into vnode.component.subTree
-  └── SF_ARRAY_CHILDREN → walk each child (Fragment support)
-
-applyVarsToEl(el: ShadowElement, vars)
-  ├── merge vars into el._style as '--key': value
-  ├── preserve vShow hidden state
-  └── pushOp(OP.SET_STYLE, el.id, style) + scheduleFlush()
-```
-
-The SFC compiler passes keys without a leading `--` (e.g. `"v33993c7f"`). The implementation adds `--` here, matching `@vue/runtime-dom`'s `el.style.setProperty('--v33993c7f', value)`.
-
----
-
-## File map
-
-| File | Role |
-|---|---|
-| `runtime/src/use-css-vars.ts` | Lynx-specific `useCssVars` implementation |
-| `runtime/src/index.ts` | Re-exports `useCssVars` so the compiler alias resolves |
-| `runtime/src/node-ops.ts` | `setScopeId` — emits DEV warning for `<style scoped>` |
-| `examples/css-features/src/VBindCSS.vue` | Live example |
-| `examples/css-features/lynx.config.ts` | Config with required flags |

From 1a24a345229c85705996dd4d3d2edcd93373482e Mon Sep 17 00:00:00 2001
From: Kealan Clarke <59548500+KealanAU@users.noreply.github.com>
Date: Sat, 4 Apr 2026 04:59:12 +1100
Subject: [PATCH 05/16] [refactor] remove script module/setup testing

---
 examples/css-features/src/App.vue             |   8 +-
 .../css-features/src/ScopedStyleWorking.vue   |  59 --------
 examples/css-features/src/VBindCSS.vue        |  95 +++++++++++--
 examples/css-features/src/VBindThreads.vue    | 129 ++++++++++++++++++
 packages/vue-lynx/runtime/src/node-ops.ts     |  14 --
 5 files changed, 218 insertions(+), 87 deletions(-)
 delete mode 100644 examples/css-features/src/ScopedStyleWorking.vue
 create mode 100644 examples/css-features/src/VBindThreads.vue

diff --git a/examples/css-features/src/App.vue b/examples/css-features/src/App.vue
index 6edf33b29..2b07d5910 100644
--- a/examples/css-features/src/App.vue
+++ b/examples/css-features/src/App.vue
@@ -1,9 +1,9 @@
 <script setup lang="ts">
 import PlainStyle from './PlainStyle.vue'
 import ScopedStyle from './ScopedStyle.vue'
-import ScopedStyleWorking from './ScopedStyleWorking.vue'
 import CSSModules from './CSSModules.vue'
 import VBindCSS from './VBindCSS.vue'
+import VBindThreads from './VBindThreads.vue'
 import CSSVarsWorkaround from './CSSVarsWorkaround.vue'
 import ImportedCSS from './ImportedCSS.vue'
 </script>
@@ -23,15 +23,15 @@ import ImportedCSS from './ImportedCSS.vue'
     <!-- 2a. <style scoped> — DOES NOT WORK -->
     <ScopedStyle />
 
-    <!-- 2b. <style module> as scoped alternative — WORKS -->
-    <ScopedStyleWorking />
-
     <!-- 3. <style module> — SHOULD WORK -->
     <CSSModules />
 
     <!-- 4. v-bind() in CSS — WORKS (useCssVars implemented in vue-lynx) -->
     <VBindCSS />
 
+    <!-- 4b. v-bind() thread comparison — BG (useCssVars) vs MT (setStyleProperty) -->
+    <VBindThreads />
+
     <!-- 5. Workaround: Reactive inline :style -->
     <CSSVarsWorkaround />
 
diff --git a/examples/css-features/src/ScopedStyleWorking.vue b/examples/css-features/src/ScopedStyleWorking.vue
deleted file mode 100644
index 40928e4e9..000000000
--- a/examples/css-features/src/ScopedStyleWorking.vue
+++ /dev/null
@@ -1,59 +0,0 @@
-<script setup lang="ts">
-// Working alternative to <style scoped> using <style module>
-//
-// <style scoped> fails in Lynx because:
-//   1. vue-lynx's renderer does not implement setScopeId() in nodeOps,
-//      so data-v-{hash} attributes are never added to elements.
-//   2. Even if they were, Lynx's CSS engine does not support attribute
-//      selectors like [data-v-xxx], so the rules would still not match.
-//
-// <style module> achieves the same scoping goal differently:
-//   1. css-loader renames each class to a unique hash (e.g. .demoText → .demoText_abc123)
-//   2. The mapping is exported as $style — a plain JS object
-//   3. You apply classes with :class="$style.demoText" instead of class="demoText"
-//   4. The CSS rules use the hashed names — plain class selectors, fully supported by Lynx
-</script>
-
-<template>
-  <view :class="$style.card">
-    <text :class="$style.title">&lt;style module&gt; — scoped alternative</text>
-    <text :class="$style.desc">
-      Uses hashed class names instead of [data-v-xxx] attribute selectors.
-      Plain class selectors are fully supported in Lynx.
-    </text>
-    <view :class="$style.demoBox">
-      <text :class="$style.demoText">This text is blue — CSS Modules scoping works</text>
-    </view>
-  </view>
-</template>
-
-<style module>
-.card {
-  display: flex;
-  flex-direction: column;
-  background-color: #e3f2fd;
-  padding: 12px;
-  border-radius: 8px;
-  margin-bottom: 12px;
-}
-.title {
-  font-size: 15px;
-  font-weight: bold;
-  color: #1565c0;
-  margin-bottom: 4px;
-}
-.desc {
-  font-size: 12px;
-  color: #555;
-  margin-bottom: 8px;
-}
-.demoBox {
-  background-color: #fff;
-  padding: 8px;
-  border-radius: 4px;
-}
-.demoText {
-  font-size: 13px;
-  color: blue;
-}
-</style>
diff --git a/examples/css-features/src/VBindCSS.vue b/examples/css-features/src/VBindCSS.vue
index a1661e2a0..a865ba2a0 100644
--- a/examples/css-features/src/VBindCSS.vue
+++ b/examples/css-features/src/VBindCSS.vue
@@ -1,9 +1,21 @@
 <script setup lang="ts">
-import { ref } from 'vue'
+import { ref, computed } from 'vue'
 
 const textColor = ref('#1565c0')
 const bgColor = ref('#e3f2fd')
 const fontSize = ref('14px')
+const opacity = ref(1)
+const borderStyle = ref({ color: '#1565c0' })
+
+const invertedColor = computed(() => {
+  const map: Record<string, string> = {
+    '#1565c0': '#f57f17',
+    '#c62828': '#2e7d32',
+    '#2e7d32': '#c62828',
+    '#f57f17': '#1565c0',
+  }
+  return map[textColor.value] ?? textColor.value
+})
 
 function cycleColor() {
   const colors = ['#1565c0', '#c62828', '#2e7d32', '#f57f17']
@@ -11,6 +23,7 @@ function cycleColor() {
   textColor.value = colors[(idx + 1) % colors.length]
   const bgs = ['#e3f2fd', '#ffebee', '#e8f5e9', '#fffde7']
   bgColor.value = bgs[(idx + 1) % bgs.length]
+  borderStyle.value = { color: colors[(idx + 1) % colors.length] }
 }
 
 function cycleFontSize() {
@@ -18,6 +31,12 @@ function cycleFontSize() {
   const idx = sizes.indexOf(fontSize.value)
   fontSize.value = sizes[(idx + 1) % sizes.length]
 }
+
+function cycleOpacity() {
+  const steps = [1, 0.7, 0.4, 0.1]
+  const idx = steps.indexOf(opacity.value)
+  opacity.value = steps[(idx + 1) % steps.length]
+}
 </script>
 
 <template>
@@ -33,12 +52,35 @@ function cycleFontSize() {
       v-bind() in &lt;style&gt; — WORKS
     </text>
     <text class="description">
-      textColor: {{ textColor }} | fontSize: {{ fontSize }}
+      textColor: {{ textColor }} | fontSize: {{ fontSize }} | opacity: {{ opacity }}
     </text>
+
+    <!-- ref binding -->
     <text class="sample-text" :style="{ fontSize }">
-      This text uses v-bind() in CSS
+      ref — color: v-bind(textColor)
+    </text>
+
+    <!-- computed binding -->
+    <text class="computed-text" :style="{ fontSize }">
+      computed — inverted color
+    </text>
+
+    <!-- object property binding: v-bind('obj.prop') -->
+    <text class="border-text">
+      object prop — v-bind('borderStyle.color')
+    </text>
+
+    <!-- opacity binding -->
+    <text class="opacity-text">
+      opacity — v-bind(opacity)
+    </text>
+
+    <!-- CSS custom property via v-bind -->
+    <text class="var-text">
+      CSS var — --accent: v-bind(textColor)
     </text>
-    <view :style="{ display: 'flex', flexDirection: 'row', gap: '8px', marginTop: '8px' }">
+
+    <view :style="{ display: 'flex', flexDirection: 'row', gap: '8px', marginTop: '8px', flexWrap: 'wrap' }">
       <text
         :style="{
           backgroundColor: '#1565c0',
@@ -63,6 +105,18 @@ function cycleFontSize() {
       >
         Cycle Size
       </text>
+      <text
+        :style="{
+          backgroundColor: '#6a1b9a',
+          color: '#fff',
+          padding: '6px 12px',
+          borderRadius: '4px',
+          fontSize: '12px',
+        }"
+        :bindtap="cycleOpacity"
+      >
+        Cycle Opacity
+      </text>
     </view>
   </view>
 </template>
@@ -80,12 +134,33 @@ function cycleFontSize() {
 
 .sample-text {
   color: v-bind(textColor);
-  /* font-size: v-bind(fontSize) is omitted here.
-     font-size IS in Lynx's default CSS inheritance list and var() in CSS
-     class rules is supported, but dynamic CSS var updates on inline styles
-     do not appear to trigger a layout re-pass for font-size (unlike color,
-     which is paint-only). This gap is undocumented in Lynx and no roadmap
-     item exists for it. font-size is driven via :style binding instead. */
   font-weight: bold;
+  margin-bottom: 4px;
+}
+
+.computed-text {
+  color: v-bind(invertedColor);
+  font-weight: bold;
+  margin-bottom: 4px;
+}
+
+.border-text {
+  color: v-bind('borderStyle.color');
+  font-weight: bold;
+  margin-bottom: 4px;
+}
+
+.opacity-text {
+  color: v-bind(textColor);
+  opacity: v-bind(opacity);
+  font-weight: bold;
+  margin-bottom: 4px;
+}
+
+.var-text {
+  --accent: v-bind(textColor);
+  color: var(--accent);
+  font-weight: bold;
+  margin-bottom: 8px;
 }
 </style>
diff --git a/examples/css-features/src/VBindThreads.vue b/examples/css-features/src/VBindThreads.vue
new file mode 100644
index 000000000..03defa1f0
--- /dev/null
+++ b/examples/css-features/src/VBindThreads.vue
@@ -0,0 +1,129 @@
+<script setup lang="ts">
+// VBindThreads — audits both style-update paths:
+//
+// LEFT  (Background Thread)
+//   tap → BG JS handler → reactive ref → useCssVars → SET_STYLE op → MT applies CSS var
+//
+// RIGHT (Main Thread)
+//   tap → MT worklet → setStyleProperty() directly (no ops round-trip)
+//         + runOnBackground(incrementMtCount) to sync tap count for display
+
+import { ref, watch } from 'vue'
+import { useMainThreadRef, runOnBackground, runOnMainThread } from 'vue-lynx'
+
+const COLORS = ['#1565c0', '#c62828', '#2e7d32', '#f57f17', '#6a1b9a']
+
+// --- Background thread ---
+const bgColorIdx = ref(0)
+const bgColor = ref(COLORS[0]!)
+const bgTapCount = ref(0)
+
+function onBgTap() {
+  bgTapCount.value++
+  bgColorIdx.value = (bgColorIdx.value + 1) % COLORS.length
+  bgColor.value = COLORS[bgColorIdx.value]!
+}
+
+// --- Main thread ---
+const mtBoxRef = useMainThreadRef(null)
+const mtTapCount = ref(0)
+
+// Incremented on BG by runOnBackground() from the MT tap handler
+function incrementMtCount() {
+  mtTapCount.value++
+}
+
+// MT-local index — lives in MT JS context, not shared with BG reactive state.
+// Captured by the SWC worklet transform into _c.
+let mtColorIdx = 0
+
+const onMtTap = () => {
+  'main thread'
+  // Cycle color directly on MT — no round-trip through BG
+  mtColorIdx = (mtColorIdx + 1) % COLORS.length
+  const el = (mtBoxRef as unknown as {
+    current?: { setStyleProperty?(k: string, v: string): void }
+  }).current
+  el?.setStyleProperty?.('background-color', COLORS[mtColorIdx]!)
+
+  // Sync tap count back to BG for display only
+  runOnBackground(incrementMtCount)()
+}
+</script>
+
+<template>
+  <view :style="{
+    display: 'flex',
+    flexDirection: 'column',
+    backgroundColor: '#f3e5f5',
+    padding: '12px',
+    borderRadius: '8px',
+    marginBottom: '12px',
+  }">
+    <text :style="{ fontSize: '15px', fontWeight: 'bold', marginBottom: '4px', color: '#4a148c' }">
+      Thread comparison — style updates
+    </text>
+    <text :style="{ fontSize: '11px', color: '#555', marginBottom: '10px' }">
+      Both boxes cycle colors on tap. BG path uses v-bind() in CSS; MT path calls setStyleProperty() directly.
+    </text>
+
+    <view :style="{ display: 'flex', flexDirection: 'row', gap: '12px' }">
+      <!-- Background thread box -->
+      <view :style="{ flex: 1 }">
+        <text :style="{ fontSize: '11px', color: '#555', marginBottom: '4px', textAlign: 'center' }">
+          Background thread
+        </text>
+        <view
+          class="bg-box"
+          :bindtap="onBgTap"
+          :style="{
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            height: '80px',
+            borderRadius: '8px',
+          }"
+        >
+          <text :style="{ fontSize: '12px', color: '#fff', fontWeight: 'bold' }">
+            Taps: {{ bgTapCount }}
+          </text>
+        </view>
+        <text :style="{ fontSize: '10px', color: '#888', marginTop: '4px', textAlign: 'center' }">
+          v-bind(bgColor) in CSS
+        </text>
+      </view>
+
+      <!-- Main thread box -->
+      <view :style="{ flex: 1 }">
+        <text :style="{ fontSize: '11px', color: '#555', marginBottom: '4px', textAlign: 'center' }">
+          Main thread
+        </text>
+        <view
+          :main-thread-ref="mtBoxRef"
+          :main-thread-bindtap="onMtTap"
+          :style="{
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            height: '80px',
+            borderRadius: '8px',
+            backgroundColor: '#1565c0',
+          }"
+        >
+          <text :style="{ fontSize: '12px', color: '#fff', fontWeight: 'bold' }">
+            Taps: {{ mtTapCount }}
+          </text>
+        </view>
+        <text :style="{ fontSize: '10px', color: '#888', marginTop: '4px', textAlign: 'center' }">
+          setStyleProperty() on MT
+        </text>
+      </view>
+    </view>
+  </view>
+</template>
+
+<style>
+.bg-box {
+  background-color: v-bind(bgColor);
+}
+</style>
diff --git a/packages/vue-lynx/runtime/src/node-ops.ts b/packages/vue-lynx/runtime/src/node-ops.ts
index 5a3ffd813..1ef478bee 100644
--- a/packages/vue-lynx/runtime/src/node-ops.ts
+++ b/packages/vue-lynx/runtime/src/node-ops.ts
@@ -309,20 +309,6 @@ export const nodeOps: RendererOptions<ShadowElement, ShadowElement> = {
   nextSibling(node: ShadowElement): ShadowElement | null {
     return node.next;
   },
-
-  // Vue calls setScopeId when mounting a component that uses <style scoped>.
-  // Lynx's CSS engine does not support the attribute selectors ([data-v-xxx])
-  // that scoped CSS generates, so scoped styles will never match any element.
-  // We emit a dev warning pointing to the supported alternative.
-  setScopeId(_el: ShadowElement, id: string): void {
-    if (__DEV__) {
-      console.warn(
-        `[vue-lynx] <style scoped> is not supported (scope id: ${id}). `
-        + `Lynx's CSS engine does not support attribute selectors ([data-v-xxx]). `
-        + `Use <style module> with :class="$style.className" for component-scoped styles instead.`,
-      );
-    }
-  },
 };
 
 /** Reset module state – for testing only. */

From 9c45f22da0cc42108310e8b362879eef1fdcc689 Mon Sep 17 00:00:00 2001
From: "xuan.huang" <5563315+Huxpro@users.noreply.github.com>
Date: Fri, 3 Apr 2026 19:36:10 -0400
Subject: [PATCH 06/16] fix(runtime): add onBeforeUpdate hook and fix VNode
 over-walking in useCssVars

Two critical fixes:

1. Add onBeforeUpdate + onMounted wrapping (matching upstream Vue):
   - patchProp's SET_STYLE overwrites CSS vars on every re-render since
     it doesn't know about them. Without onBeforeUpdate, CSS vars silently
     vanish whenever a style binding changes but the CSS var value doesn't.
   - VNode tree changes (v-if, v-for) also need CSS vars re-applied to
     newly created root elements.

2. Restrict SF_ARRAY_CHILDREN walking to Fragment vnodes only:
   - The standalone `if (shapeFlag & SF_ARRAY_CHILDREN)` also fired for
     element vnodes with children, applying CSS vars to every descendant
     element (O(N) SET_STYLE ops). Root elements are sufficient since
     enableCSSInheritance cascades vars to descendants.
---
 .../upstream-tests/src/use-css-vars.spec.ts   | 41 ++++++++++++++++++-
 packages/vue-lynx/runtime/src/use-css-vars.ts | 29 ++++++++++---
 2 files changed, 63 insertions(+), 7 deletions(-)

diff --git a/packages/upstream-tests/src/use-css-vars.spec.ts b/packages/upstream-tests/src/use-css-vars.spec.ts
index 86f696a6e..446791071 100644
--- a/packages/upstream-tests/src/use-css-vars.spec.ts
+++ b/packages/upstream-tests/src/use-css-vars.spec.ts
@@ -297,7 +297,46 @@ describe('useCssVars — vShow interaction', () => {
 });
 
 // ---------------------------------------------------------------------------
-// 5. Reactivity — watchPostEffect triggers automatically
+// 5. Style-binding-only change — CSS vars must persist
+// ---------------------------------------------------------------------------
+
+describe('useCssVars — style-binding change without CSS var change', () => {
+  it('preserves CSS vars when only inline style changes', async () => {
+    const color = ref('red');
+    const bg = ref('white');
+
+    const App = defineComponent({
+      setup() {
+        useCssVars((_ctx: unknown) => ({ 'x1': color.value }));
+        return () => h('view', { style: { backgroundColor: bg.value } });
+      },
+    });
+
+    createApp(App).mount();
+    await nextTick();
+    collectFlushedOps(); // drain mount ops
+
+    // Change ONLY the style binding, not the CSS var
+    bg.value = 'black';
+    await nextTick();
+
+    const ops = collectFlushedOps();
+    const styleOps = parseSetStyleOps(ops);
+
+    // The last SET_STYLE must include both the updated style AND the CSS var.
+    // Without onBeforeUpdate, patchProp's SET_STYLE would overwrite the CSS var
+    // and the watchPostEffect would not re-run (its deps didn't change).
+    const last = styleOps[styleOps.length - 1];
+    expect(last).toBeDefined();
+    expect(last.style).toMatchObject({
+      backgroundColor: 'black',
+      '--x1': 'red',
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 6. Reactivity — watchPostEffect triggers automatically
 // ---------------------------------------------------------------------------
 
 describe('useCssVars — reactivity', () => {
diff --git a/packages/vue-lynx/runtime/src/use-css-vars.ts b/packages/vue-lynx/runtime/src/use-css-vars.ts
index d51a30d24..e0fd15b26 100644
--- a/packages/vue-lynx/runtime/src/use-css-vars.ts
+++ b/packages/vue-lynx/runtime/src/use-css-vars.ts
@@ -2,7 +2,14 @@
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
 
-import { getCurrentInstance, watchPostEffect } from '@vue/runtime-core';
+import {
+  Fragment,
+  getCurrentInstance,
+  onBeforeUpdate,
+  onMounted,
+  queuePostFlushCb,
+  watchPostEffect,
+} from '@vue/runtime-core';
 import type { VNode } from '@vue/runtime-core';
 
 import { OP, pushOp } from './ops.js';
@@ -44,10 +51,9 @@ function applyVarsToVNode(
     if (vnode.component) {
       applyVarsToVNode(vnode.component.subTree, vars);
     }
-  }
-
-  // Fragment / array children — walk every child
-  if (shapeFlag & SF_ARRAY_CHILDREN) {
+  } else if (vnode.type === Fragment && (shapeFlag & SF_ARRAY_CHILDREN)) {
+    // Fragment root — walk every sibling child (but NOT element children;
+    // those inherit CSS vars via enableCSSInheritance).
     const children = vnode.children as VNode[];
     for (const child of children) {
       applyVarsToVNode(child, vars);
@@ -79,8 +85,19 @@ export function useCssVars(
   const instance = getCurrentInstance();
   if (!instance) return;
 
-  watchPostEffect(() => {
+  const setVars = () => {
     const vars = getter(instance.proxy);
     applyVarsToVNode(instance.subTree, vars);
+  };
+
+  onMounted(() => {
+    watchPostEffect(setVars);
+  });
+
+  // Re-apply on every component update: patchProp's SET_STYLE overwrites
+  // the CSS vars that useCssVars previously merged in, and the VNode tree
+  // may have new elements that need vars applied.
+  onBeforeUpdate(() => {
+    queuePostFlushCb(setVars);
   });
 }

From 9ecb7594163b2b80429cbedd6fda5cf3e445a536 Mon Sep 17 00:00:00 2001
From: "xuan.huang" <5563315+Huxpro@users.noreply.github.com>
Date: Fri, 3 Apr 2026 19:50:27 -0400
Subject: [PATCH 07/16] docs: update vue-compatibility to reflect v-bind() in
 CSS support

- Move v-bind() from "Upcoming" to "Works (requires config)"
- Add required config snippet (enableCSSInlineVariables + enableCSSInheritance)
- Document the known layout-property limitation
- Remove the workaround snippet (no longer needed)
- Update both EN and ZH versions
---
 website/docs/guide/vue-compatibility.mdx    | 27 ++++++++++++---------
 website/docs/zh/guide/vue-compatibility.mdx | 27 ++++++++++++---------
 2 files changed, 30 insertions(+), 24 deletions(-)

diff --git a/website/docs/guide/vue-compatibility.mdx b/website/docs/guide/vue-compatibility.mdx
index beabd4915..ac0fff95b 100644
--- a/website/docs/guide/vue-compatibility.mdx
+++ b/website/docs/guide/vue-compatibility.mdx
@@ -17,7 +17,7 @@ The example below demonstrates [`reactive()`](https://vuejs.org/api/reactivity-c
 
 ## SFC CSS Features
 
-Plain `<style>` blocks, imported `.css` files, and [`<style module>`](https://vuejs.org/api/sfc-css-features.html#css-modules) all work on Lynx. `<style scoped>` and `v-bind()` in CSS are not yet supported — vote on [#78](https://github.com/Huxpro/vue-lynx/issues/78) and [#79](https://github.com/Huxpro/vue-lynx/issues/79) if you need them.
+Plain `<style>` blocks, imported `.css` files, [`<style module>`](https://vuejs.org/api/sfc-css-features.html#css-modules), and [`v-bind()` in CSS](https://vuejs.org/api/sfc-css-features.html#v-bind-in-css) all work on Lynx. `<style scoped>` is not yet supported — vote on [#78](https://github.com/Huxpro/vue-lynx/issues/78) if you need it.
 
 :::details Feature support details
 
@@ -26,19 +26,22 @@ Plain `<style>` blocks, imported `.css` files, and [`<style module>`](https://vu
 | `<style>` (plain) | Works |
 | Imported `.css` files | Works |
 | `<style module>` | Works |
+| `v-bind()` in `<style>` | Works (requires config, see below) |
 | `<style scoped>` | Upcoming ([#78](https://github.com/Huxpro/vue-lynx/issues/78)) |
-| `v-bind()` in `<style>` | Upcoming ([#79](https://github.com/Huxpro/vue-lynx/issues/79)) |
-
-For dynamic styling, use computed `:style` bindings as a workaround for `v-bind()`:
-```vue
-<script setup>
-const color = ref('#1565c0')
-const style = computed(() => ({ color: color.value }))
-</script>
-<template>
-  <text :style="style">Dynamic color</text>
-</template>
+
+`v-bind()` in `<style>` requires two config options so the Lynx engine recognizes CSS custom properties in inline styles and cascades them to descendants:
+
+```ts title="lynx.config.ts"
+pluginVueLynx({
+  enableCSSInlineVariables: true,
+  enableCSSInheritance: true,
+})
 ```
+
+:::warning Known limitation
+Layout-affecting properties (e.g., `font-size`) driven by `v-bind()` apply correctly on initial render but may not update visually on reactive change. This is a Lynx engine limitation. Workaround: drive layout properties via `:style` binding directly on the element.
+:::
+
 :::
 
 <Go
diff --git a/website/docs/zh/guide/vue-compatibility.mdx b/website/docs/zh/guide/vue-compatibility.mdx
index e09c33d84..65f12f9ca 100644
--- a/website/docs/zh/guide/vue-compatibility.mdx
+++ b/website/docs/zh/guide/vue-compatibility.mdx
@@ -17,7 +17,7 @@ Vue Lynx 100% 复用了 Vue 的响应式核心（`@vue/reactivity`）。每个
 
 ## SFC CSS 特性
 
-普通 `<style>` 块、导入的 `.css` 文件和 [`<style module>`](https://vuejs.org/api/sfc-css-features.html#css-modules) 都可以在 Lynx 上使用。`<style scoped>` 和 CSS 中的 `v-bind()` 尚未支持——如果你需要这些特性，请在 [#78](https://github.com/Huxpro/vue-lynx/issues/78) 和 [#79](https://github.com/Huxpro/vue-lynx/issues/79) 上投票。
+普通 `<style>` 块、导入的 `.css` 文件、[`<style module>`](https://vuejs.org/api/sfc-css-features.html#css-modules) 和 [`v-bind()` CSS 绑定](https://vuejs.org/api/sfc-css-features.html#v-bind-in-css) 都可以在 Lynx 上使用。`<style scoped>` 尚未支持——如果你需要该特性，请在 [#78](https://github.com/Huxpro/vue-lynx/issues/78) 上投票。
 
 :::details 特性支持详情
 
@@ -26,19 +26,22 @@ Vue Lynx 100% 复用了 Vue 的响应式核心（`@vue/reactivity`）。每个
 | `<style>`（普通） | 可用 |
 | 导入 `.css` 文件 | 可用 |
 | `<style module>` | 可用 |
+| `<style>` 中的 `v-bind()` | 可用（需要配置，见下方） |
 | `<style scoped>` | 即将支持（[#78](https://github.com/Huxpro/vue-lynx/issues/78)） |
-| `<style>` 中的 `v-bind()` | 即将支持（[#79](https://github.com/Huxpro/vue-lynx/issues/79)） |
-
-对于动态样式，可以使用计算属性 `:style` 绑定作为 `v-bind()` 的替代方案：
-```vue
-<script setup>
-const color = ref('#1565c0')
-const style = computed(() => ({ color: color.value }))
-</script>
-<template>
-  <text :style="style">Dynamic color</text>
-</template>
+
+`<style>` 中的 `v-bind()` 需要两个配置选项，以便 Lynx 引擎识别内联样式中的 CSS 自定义属性并将其级联到后代元素：
+
+```ts title="lynx.config.ts"
+pluginVueLynx({
+  enableCSSInlineVariables: true,
+  enableCSSInheritance: true,
+})
 ```
+
+:::warning 已知限制
+通过 `v-bind()` 驱动的影响布局的属性（如 `font-size`）在初始渲染时可以正确应用，但在响应式更新时可能不会更新视觉效果。这是 Lynx 引擎的限制。解决方法：在元素上直接通过 `:style` 绑定来驱动布局属性。
+:::
+
 :::
 
 <Go

From b8748beafc9fdb82b152c6d13f6c550182a5d823 Mon Sep 17 00:00:00 2001
From: "xuan.huang" <5563315+Huxpro@users.noreply.github.com>
Date: Sat, 4 Apr 2026 18:56:40 -0400
Subject: [PATCH 08/16] chore: revert rejected type annotations, add changeset

Revert element-registry.ts and TransitionGroup.ts type annotation
changes that were rejected in PR #122 review. Add changeset for
the v-bind() CSS vars feature.
---
 .changeset/v-bind-css-vars.md                         | 7 +++++++
 packages/vue-lynx/main-thread/src/element-registry.ts | 2 +-
 packages/vue-lynx/runtime/src/TransitionGroup.ts      | 8 +++-----
 3 files changed, 11 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/v-bind-css-vars.md

diff --git a/.changeset/v-bind-css-vars.md b/.changeset/v-bind-css-vars.md
new file mode 100644
index 000000000..34d1cdfdd
--- /dev/null
+++ b/.changeset/v-bind-css-vars.md
@@ -0,0 +1,7 @@
+---
+"vue-lynx": minor
+---
+
+feat: support `v-bind()` in `<style>` blocks via Lynx-native `useCssVars`
+
+Implements a Background Thread compatible `useCssVars` that merges CSS custom properties into element inline styles via the ops pipeline. Requires `enableCSSInlineVariables: true` and `enableCSSInheritance: true` in `lynx.config`.
diff --git a/packages/vue-lynx/main-thread/src/element-registry.ts b/packages/vue-lynx/main-thread/src/element-registry.ts
index b5a5af01b..d2b88d532 100644
--- a/packages/vue-lynx/main-thread/src/element-registry.ts
+++ b/packages/vue-lynx/main-thread/src/element-registry.ts
@@ -3,7 +3,7 @@
 // LICENSE file in the root directory of this source tree.
 
 /** Map from BG-thread ShadowElement id to Lynx Main Thread element handle */
-export const elements: Map<number, LynxElement> = new Map();
+export const elements = new Map<number, LynxElement>();
 
 /**
  * PAPI unique ID of the root PageElement.
diff --git a/packages/vue-lynx/runtime/src/TransitionGroup.ts b/packages/vue-lynx/runtime/src/TransitionGroup.ts
index 1dfbc5aff..67f734f19 100644
--- a/packages/vue-lynx/runtime/src/TransitionGroup.ts
+++ b/packages/vue-lynx/runtime/src/TransitionGroup.ts
@@ -13,8 +13,6 @@
 
 import {
   type SetupContext,
-  type VNode,
-  type Component,
   defineComponent,
   getCurrentInstance,
   h,
@@ -128,7 +126,7 @@ export interface TransitionGroupProps extends TransitionProps {
 // <TransitionGroup>
 // ---------------------------------------------------------------------------
 
-export const TransitionGroup: Component = defineComponent({
+export const TransitionGroup = defineComponent({
   name: 'TransitionGroup',
 
   props: {
@@ -154,11 +152,11 @@ export const TransitionGroup: Component = defineComponent({
     moveClass: String,
   },
 
-  setup(props: TransitionGroupProps, { slots }: SetupContext): () => VNode {
+  setup(props: TransitionGroupProps, { slots }: SetupContext) {
     const instance = getCurrentInstance()!;
     const state = useTransitionState();
 
-    return (): VNode => {
+    return () => {
       const rawChildren = slots.default ? slots.default() : [];
       const children = getTransitionRawChildren(rawChildren);
 

From 72deddde86f7b2811a729e9c929286440302404e Mon Sep 17 00:00:00 2001
From: Kealan Clarke <59548500+KealanAU@users.noreply.github.com>
Date: Sun, 5 Apr 2026 11:18:37 +1000
Subject: [PATCH 09/16] [fix] make the feature css look nicer and work better
 together

---
 examples/css-features/src/App.vue          |  29 ++--
 examples/css-features/src/VBindCSS.vue     | 169 ++++++---------------
 examples/css-features/src/VBindRow.vue     |  90 +++++++++++
 examples/css-features/src/VBindThreads.vue | 117 +++++---------
 4 files changed, 187 insertions(+), 218 deletions(-)
 create mode 100644 examples/css-features/src/VBindRow.vue

diff --git a/examples/css-features/src/App.vue b/examples/css-features/src/App.vue
index 2b07d5910..4f1a27d18 100644
--- a/examples/css-features/src/App.vue
+++ b/examples/css-features/src/App.vue
@@ -1,9 +1,9 @@
 <script setup lang="ts">
+import VBindCSS from './VBindCSS.vue'
+import VBindThreads from './VBindThreads.vue'
 import PlainStyle from './PlainStyle.vue'
 import ScopedStyle from './ScopedStyle.vue'
 import CSSModules from './CSSModules.vue'
-import VBindCSS from './VBindCSS.vue'
-import VBindThreads from './VBindThreads.vue'
 import CSSVarsWorkaround from './CSSVarsWorkaround.vue'
 import ImportedCSS from './ImportedCSS.vue'
 </script>
@@ -17,25 +17,20 @@ import ImportedCSS from './ImportedCSS.vue'
       CSS Features Test
     </text>
 
-    <!-- 1. Plain <style> — WORKS -->
-    <PlainStyle />
-
-    <!-- 2a. <style scoped> — DOES NOT WORK -->
-    <ScopedStyle />
-
-    <!-- 3. <style module> — SHOULD WORK -->
-    <CSSModules />
-
-    <!-- 4. v-bind() in CSS — WORKS (useCssVars implemented in vue-lynx) -->
+    <!-- v-bind() in CSS — primary focus -->
     <VBindCSS />
-
-    <!-- 4b. v-bind() thread comparison — BG (useCssVars) vs MT (setStyleProperty) -->
     <VBindThreads />
 
-    <!-- 5. Workaround: Reactive inline :style -->
-    <CSSVarsWorkaround />
+    <!-- Divider -->
+    <text :style="{ fontSize: '13px', fontWeight: 'bold', color: '#888', marginBottom: '12px', marginTop: '4px' }">
+      Other CSS patterns
+    </text>
 
-    <!-- 6. Imported .css file — WORKS -->
+    <!-- Workarounds and supporting patterns -->
+    <CSSVarsWorkaround />
+    <PlainStyle />
+    <ScopedStyle />
+    <CSSModules />
     <ImportedCSS />
   </scroll-view>
 </template>
diff --git a/examples/css-features/src/VBindCSS.vue b/examples/css-features/src/VBindCSS.vue
index a865ba2a0..5163a6971 100644
--- a/examples/css-features/src/VBindCSS.vue
+++ b/examples/css-features/src/VBindCSS.vue
@@ -1,41 +1,32 @@
 <script setup lang="ts">
-import { ref, computed } from 'vue'
+import { ref } from 'vue'
+import VBindRow from './VBindRow.vue'
 
-const textColor = ref('#1565c0')
-const bgColor = ref('#e3f2fd')
-const fontSize = ref('14px')
-const opacity = ref(1)
-const borderStyle = ref({ color: '#1565c0' })
+const TEXT_COLORS = ['#1565c0', '#c62828', '#2e7d32', '#f57f17']
+const BG_COLORS   = ['#1565c0', '#c62828', '#2e7d32', '#f57f17']
+const FONT_SIZES  = ['12px', '14px', '16px', '20px']
+const OPACITIES   = [1, 0.7, 0.4, 0.1]
 
-const invertedColor = computed(() => {
-  const map: Record<string, string> = {
-    '#1565c0': '#f57f17',
-    '#c62828': '#2e7d32',
-    '#2e7d32': '#c62828',
-    '#f57f17': '#1565c0',
-  }
-  return map[textColor.value] ?? textColor.value
-})
+const colorIdx = ref(0)
+const textColor = ref(TEXT_COLORS[0]!)
+const bgColor   = ref(BG_COLORS[0]!)
+const fontSize  = ref(FONT_SIZES[1]!)
+const opacity   = ref(OPACITIES[0]!)
 
 function cycleColor() {
-  const colors = ['#1565c0', '#c62828', '#2e7d32', '#f57f17']
-  const idx = colors.indexOf(textColor.value)
-  textColor.value = colors[(idx + 1) % colors.length]
-  const bgs = ['#e3f2fd', '#ffebee', '#e8f5e9', '#fffde7']
-  bgColor.value = bgs[(idx + 1) % bgs.length]
-  borderStyle.value = { color: colors[(idx + 1) % colors.length] }
+  colorIdx.value = (colorIdx.value + 1) % TEXT_COLORS.length
+  textColor.value = TEXT_COLORS[colorIdx.value]!
+  bgColor.value = BG_COLORS[colorIdx.value]!
 }
 
 function cycleFontSize() {
-  const sizes = ['12px', '14px', '16px', '20px']
-  const idx = sizes.indexOf(fontSize.value)
-  fontSize.value = sizes[(idx + 1) % sizes.length]
+  const idx = FONT_SIZES.indexOf(fontSize.value)
+  fontSize.value = FONT_SIZES[(idx + 1) % FONT_SIZES.length]!
 }
 
 function cycleOpacity() {
-  const steps = [1, 0.7, 0.4, 0.1]
-  const idx = steps.indexOf(opacity.value)
-  opacity.value = steps[(idx + 1) % steps.length]
+  const idx = OPACITIES.indexOf(opacity.value)
+  opacity.value = OPACITIES[(idx + 1) % OPACITIES.length]!
 }
 </script>
 
@@ -43,124 +34,54 @@ function cycleOpacity() {
   <view :style="{
     display: 'flex',
     flexDirection: 'column',
-    backgroundColor: bgColor,
+    backgroundColor: '#fafafa',
     padding: '12px',
     borderRadius: '8px',
     marginBottom: '12px',
   }">
-    <text :style="{ fontSize: '15px', fontWeight: 'bold', marginBottom: '4px' }" class="title">
-      v-bind() in &lt;style&gt; — WORKS
+    <text :style="{ fontSize: '15px', fontWeight: 'bold', marginBottom: '2px', color: '#333' }">
+      v-bind() in CSS &nbsp;vs&nbsp; inline :style
     </text>
-    <text class="description">
-      textColor: {{ textColor }} | fontSize: {{ fontSize }} | opacity: {{ opacity }}
+    <text :style="{ fontSize: '11px', color: '#888', marginBottom: '10px' }">
+      Same values drive both panels. Tap a button to cycle and compare.
     </text>
 
-    <!-- ref binding -->
-    <text class="sample-text" :style="{ fontSize }">
-      ref — color: v-bind(textColor)
-    </text>
-
-    <!-- computed binding -->
-    <text class="computed-text" :style="{ fontSize }">
-      computed — inverted color
-    </text>
-
-    <!-- object property binding: v-bind('obj.prop') -->
-    <text class="border-text">
-      object prop — v-bind('borderStyle.color')
-    </text>
-
-    <!-- opacity binding -->
-    <text class="opacity-text">
-      opacity — v-bind(opacity)
-    </text>
+    <!-- Column headers -->
+    <view :style="{ display: 'flex', flexDirection: 'row', gap: '10px', marginBottom: '8px' }">
+      <text :style="{ flex: 1, fontSize: '11px', fontWeight: 'bold', color: '#555', textAlign: 'center' }">
+        v-bind() in &lt;style&gt;
+      </text>
+      <text :style="{ flex: 1, fontSize: '11px', fontWeight: 'bold', color: '#555', textAlign: 'center' }">
+        inline :style
+      </text>
+    </view>
 
-    <!-- CSS custom property via v-bind -->
-    <text class="var-text">
-      CSS var — --accent: v-bind(textColor)
-    </text>
+    <!-- Each row is its own component instance with exactly ONE CSS variable -->
+    <VBindRow property="background-color" label="background-color" :value="bgColor" />
+    <VBindRow property="color" label="color" :value="textColor" />
+    <VBindRow property="font-size" label="font-size" :value="fontSize" />
+    <VBindRow property="opacity" label="opacity" :value="opacity" />
 
-    <view :style="{ display: 'flex', flexDirection: 'row', gap: '8px', marginTop: '8px', flexWrap: 'wrap' }">
+    <!-- Controls -->
+    <view :style="{ display: 'flex', flexDirection: 'row', gap: '8px', flexWrap: 'wrap', marginTop: '4px' }">
       <text
-        :style="{
-          backgroundColor: '#1565c0',
-          color: '#fff',
-          padding: '6px 12px',
-          borderRadius: '4px',
-          fontSize: '12px',
-        }"
+        :style="{ backgroundColor: '#1565c0', color: '#fff', padding: '6px 10px', borderRadius: '4px', fontSize: '11px' }"
         :bindtap="cycleColor"
       >
-        Cycle Color
+        Cycle colour
       </text>
       <text
-        :style="{
-          backgroundColor: '#2e7d32',
-          color: '#fff',
-          padding: '6px 12px',
-          borderRadius: '4px',
-          fontSize: '12px',
-        }"
+        :style="{ backgroundColor: '#2e7d32', color: '#fff', padding: '6px 10px', borderRadius: '4px', fontSize: '11px' }"
         :bindtap="cycleFontSize"
       >
-        Cycle Size
+        Cycle font-size
       </text>
       <text
-        :style="{
-          backgroundColor: '#6a1b9a',
-          color: '#fff',
-          padding: '6px 12px',
-          borderRadius: '4px',
-          fontSize: '12px',
-        }"
+        :style="{ backgroundColor: '#6a1b9a', color: '#fff', padding: '6px 10px', borderRadius: '4px', fontSize: '11px' }"
         :bindtap="cycleOpacity"
       >
-        Cycle Opacity
+        Cycle opacity
       </text>
     </view>
   </view>
 </template>
-
-<style>
-.title {
-  color: v-bind(textColor);
-}
-
-.description {
-  font-size: 11px;
-  color: #555;
-  margin-bottom: 8px;
-}
-
-.sample-text {
-  color: v-bind(textColor);
-  font-weight: bold;
-  margin-bottom: 4px;
-}
-
-.computed-text {
-  color: v-bind(invertedColor);
-  font-weight: bold;
-  margin-bottom: 4px;
-}
-
-.border-text {
-  color: v-bind('borderStyle.color');
-  font-weight: bold;
-  margin-bottom: 4px;
-}
-
-.opacity-text {
-  color: v-bind(textColor);
-  opacity: v-bind(opacity);
-  font-weight: bold;
-  margin-bottom: 4px;
-}
-
-.var-text {
-  --accent: v-bind(textColor);
-  color: var(--accent);
-  font-weight: bold;
-  margin-bottom: 8px;
-}
-</style>
diff --git a/examples/css-features/src/VBindRow.vue b/examples/css-features/src/VBindRow.vue
new file mode 100644
index 000000000..7786b6fa7
--- /dev/null
+++ b/examples/css-features/src/VBindRow.vue
@@ -0,0 +1,90 @@
+<script setup lang="ts">
+/**
+ * Single-property CSS v-bind comparison row.
+ *
+ * All four CSS classes reference the same `value` prop via v-bind(), so the
+ * SFC compiler emits exactly ONE useCssVars entry: { hash: value }.
+ * Only one class is ever applied per instance (v-if guards), so each instance
+ * behaves identically to the single-var VBindThreads pattern that is confirmed
+ * working on Lynx.
+ */
+defineProps<{
+  label: string
+  property: 'background-color' | 'color' | 'font-size' | 'opacity'
+  value: string | number
+}>()
+</script>
+
+<template>
+  <view :style="{ display: 'flex', flexDirection: 'row', gap: '10px', marginBottom: '6px' }">
+
+    <!-- Left: v-bind() in CSS -->
+    <view :style="{ flex: 1, borderRadius: '6px' }">
+      <view
+        v-if="property === 'background-color'"
+        class="row-bg"
+        :style="{ padding: '8px', borderRadius: '6px' }"
+      >
+        <text :style="{ fontSize: '10px', color: '#fff', marginBottom: '2px' }">{{ label }}</text>
+        <text :style="{ fontSize: '11px', color: '#fff' }">v-bind(value)</text>
+      </view>
+
+      <view v-else :style="{ padding: '8px', borderRadius: '6px', backgroundColor: '#fff' }">
+        <text :style="{ fontSize: '10px', color: '#555', marginBottom: '2px' }">{{ label }}</text>
+        <text v-if="property === 'color'" class="row-color" :style="{ fontWeight: 'bold' }">
+          v-bind(value)
+        </text>
+        <text v-else-if="property === 'font-size'" class="row-font-size">
+          Sample text
+        </text>
+        <text v-else-if="property === 'opacity'" class="row-opacity" :style="{ fontWeight: 'bold' }">
+          v-bind(value)
+        </text>
+      </view>
+    </view>
+
+    <!-- Right: inline :style -->
+    <view :style="{ flex: 1, borderRadius: '6px' }">
+      <view
+        v-if="property === 'background-color'"
+        :style="{ padding: '8px', borderRadius: '6px', backgroundColor: (value as string) }"
+      >
+        <text :style="{ fontSize: '10px', color: '#fff', marginBottom: '2px' }">{{ label }}</text>
+        <text :style="{ fontSize: '11px', color: '#fff' }">:style inline</text>
+      </view>
+
+      <view v-else :style="{ padding: '8px', borderRadius: '6px', backgroundColor: '#fff' }">
+        <text :style="{ fontSize: '10px', color: '#555', marginBottom: '2px' }">{{ label }}</text>
+        <text v-if="property === 'color'" :style="{ fontWeight: 'bold', color: (value as string) }">
+          :style inline
+        </text>
+        <text v-else-if="property === 'font-size'" :style="{ fontSize: (value as string) }">
+          Sample text
+        </text>
+        <text v-else-if="property === 'opacity'" :style="{ fontWeight: 'bold', opacity: (value as number) }">
+          :style inline
+        </text>
+      </view>
+    </view>
+
+  </view>
+</template>
+
+<style>
+/* All four classes reference the same prop — compiler emits one CSS var. */
+.row-bg {
+  background-color: v-bind(value);
+}
+
+.row-color {
+  color: v-bind(value);
+}
+
+.row-font-size {
+  font-size: v-bind(value);
+}
+
+.row-opacity {
+  opacity: v-bind(value);
+}
+</style>
diff --git a/examples/css-features/src/VBindThreads.vue b/examples/css-features/src/VBindThreads.vue
index 03defa1f0..c712a37f6 100644
--- a/examples/css-features/src/VBindThreads.vue
+++ b/examples/css-features/src/VBindThreads.vue
@@ -1,53 +1,25 @@
 <script setup lang="ts">
-// VBindThreads — audits both style-update paths:
+import { ref } from 'vue'
+
+// Both sides share the same reactive ref — tap either box to cycle color
+// so you can directly compare how each approach propagates the update.
 //
-// LEFT  (Background Thread)
-//   tap → BG JS handler → reactive ref → useCssVars → SET_STYLE op → MT applies CSS var
+// LEFT  — inline :style sets a CSS custom property, class reads it via var()
+//           :style="{ '--box-color': color }"  →  background-color: var(--box-color)
 //
-// RIGHT (Main Thread)
-//   tap → MT worklet → setStyleProperty() directly (no ops round-trip)
-//         + runOnBackground(incrementMtCount) to sync tap count for display
-
-import { ref, watch } from 'vue'
-import { useMainThreadRef, runOnBackground, runOnMainThread } from 'vue-lynx'
+// RIGHT — v-bind() in <style> writes the value straight to a CSS custom property
+//           background-color: v-bind(color)
 
 const COLORS = ['#1565c0', '#c62828', '#2e7d32', '#f57f17', '#6a1b9a']
 
-// --- Background thread ---
-const bgColorIdx = ref(0)
-const bgColor = ref(COLORS[0]!)
-const bgTapCount = ref(0)
-
-function onBgTap() {
-  bgTapCount.value++
-  bgColorIdx.value = (bgColorIdx.value + 1) % COLORS.length
-  bgColor.value = COLORS[bgColorIdx.value]!
-}
-
-// --- Main thread ---
-const mtBoxRef = useMainThreadRef(null)
-const mtTapCount = ref(0)
+const colorIdx = ref(0)
+const color = ref(COLORS[0]!)
+const tapCount = ref(0)
 
-// Incremented on BG by runOnBackground() from the MT tap handler
-function incrementMtCount() {
-  mtTapCount.value++
-}
-
-// MT-local index — lives in MT JS context, not shared with BG reactive state.
-// Captured by the SWC worklet transform into _c.
-let mtColorIdx = 0
-
-const onMtTap = () => {
-  'main thread'
-  // Cycle color directly on MT — no round-trip through BG
-  mtColorIdx = (mtColorIdx + 1) % COLORS.length
-  const el = (mtBoxRef as unknown as {
-    current?: { setStyleProperty?(k: string, v: string): void }
-  }).current
-  el?.setStyleProperty?.('background-color', COLORS[mtColorIdx]!)
-
-  // Sync tap count back to BG for display only
-  runOnBackground(incrementMtCount)()
+function cycleColor() {
+  tapCount.value++
+  colorIdx.value = (colorIdx.value + 1) % COLORS.length
+  color.value = COLORS[colorIdx.value]!
 }
 </script>
 
@@ -55,67 +27,54 @@ const onMtTap = () => {
   <view :style="{
     display: 'flex',
     flexDirection: 'column',
-    backgroundColor: '#f3e5f5',
+    backgroundColor: '#fafafa',
     padding: '12px',
     borderRadius: '8px',
     marginBottom: '12px',
   }">
-    <text :style="{ fontSize: '15px', fontWeight: 'bold', marginBottom: '4px', color: '#4a148c' }">
-      Thread comparison — style updates
+    <text :style="{ fontSize: '15px', fontWeight: 'bold', marginBottom: '4px', color: '#333' }">
+      Inline :style + var() &nbsp;vs&nbsp; v-bind() in CSS
     </text>
-    <text :style="{ fontSize: '11px', color: '#555', marginBottom: '10px' }">
-      Both boxes cycle colors on tap. BG path uses v-bind() in CSS; MT path calls setStyleProperty() directly.
+    <text :style="{ fontSize: '11px', color: '#888', marginBottom: '10px' }">
+      Same reactive ref. Tap either box to cycle — compare how each approach updates.
     </text>
 
     <view :style="{ display: 'flex', flexDirection: 'row', gap: '12px' }">
-      <!-- Background thread box -->
+      <!-- Left: set CSS custom property via inline :style, consume with var() in class -->
       <view :style="{ flex: 1 }">
         <text :style="{ fontSize: '11px', color: '#555', marginBottom: '4px', textAlign: 'center' }">
-          Background thread
+          :style + var()
         </text>
         <view
-          class="bg-box"
-          :bindtap="onBgTap"
-          :style="{
-            display: 'flex',
-            alignItems: 'center',
-            justifyContent: 'center',
-            height: '80px',
-            borderRadius: '8px',
-          }"
+          class="inline-var-box"
+          :style="{ '--box-color': color, display: 'flex', alignItems: 'center', justifyContent: 'center', height: '80px', borderRadius: '8px' }"
+          :bindtap="cycleColor"
         >
           <text :style="{ fontSize: '12px', color: '#fff', fontWeight: 'bold' }">
-            Taps: {{ bgTapCount }}
+            Taps: {{ tapCount }}
           </text>
         </view>
         <text :style="{ fontSize: '10px', color: '#888', marginTop: '4px', textAlign: 'center' }">
-          v-bind(bgColor) in CSS
+          background-color: var(--box-color)
         </text>
       </view>
 
-      <!-- Main thread box -->
+      <!-- Right: v-bind() in <style> — Vue writes the CSS custom property for you -->
       <view :style="{ flex: 1 }">
         <text :style="{ fontSize: '11px', color: '#555', marginBottom: '4px', textAlign: 'center' }">
-          Main thread
+          v-bind() in CSS
         </text>
         <view
-          :main-thread-ref="mtBoxRef"
-          :main-thread-bindtap="onMtTap"
-          :style="{
-            display: 'flex',
-            alignItems: 'center',
-            justifyContent: 'center',
-            height: '80px',
-            borderRadius: '8px',
-            backgroundColor: '#1565c0',
-          }"
+          class="vbind-color-box"
+          :style="{ display: 'flex', alignItems: 'center', justifyContent: 'center', height: '80px', borderRadius: '8px' }"
+          :bindtap="cycleColor"
         >
           <text :style="{ fontSize: '12px', color: '#fff', fontWeight: 'bold' }">
-            Taps: {{ mtTapCount }}
+            Taps: {{ tapCount }}
           </text>
         </view>
         <text :style="{ fontSize: '10px', color: '#888', marginTop: '4px', textAlign: 'center' }">
-          setStyleProperty() on MT
+          background-color: v-bind(color)
         </text>
       </view>
     </view>
@@ -123,7 +82,11 @@ const onMtTap = () => {
 </template>
 
 <style>
-.bg-box {
-  background-color: v-bind(bgColor);
+.inline-var-box {
+  background-color: var(--box-color);
+}
+
+.vbind-color-box {
+  background-color: v-bind(color);
 }
 </style>

From db4824626307eba4a38306d87df1ec62ad675fc7 Mon Sep 17 00:00:00 2001
From: Kealan Clarke <59548500+KealanAU@users.noreply.github.com>
Date: Sun, 5 Apr 2026 11:49:36 +1000
Subject: [PATCH 10/16] [debug] looking into why mobile doesn't get the same
 styling as web

---
 examples/css-features/src/App.vue     | 14 +++++++++-----
 packages/vue-lynx/plugin/src/entry.ts |  6 ++++--
 2 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/examples/css-features/src/App.vue b/examples/css-features/src/App.vue
index 4f1a27d18..465341f19 100644
--- a/examples/css-features/src/App.vue
+++ b/examples/css-features/src/App.vue
@@ -26,11 +26,15 @@ import ImportedCSS from './ImportedCSS.vue'
       Other CSS patterns
     </text>
 
-    <!-- Workarounds and supporting patterns -->
+    <!-- Workarounds and supporting patterns — 2 per row -->
     <CSSVarsWorkaround />
-    <PlainStyle />
-    <ScopedStyle />
-    <CSSModules />
-    <ImportedCSS />
+    <view :style="{ display: 'flex', flexDirection: 'row', alignItems: 'flex-start', marginBottom: '12px' }">
+      <view :style="{ flex: 1, paddingRight: '6px' }"><ScopedStyle /></view>
+      <view :style="{ flex: 1, paddingLeft: '6px' }"><CSSModules /></view>
+    </view>
+    <view :style="{ display: 'flex', flexDirection: 'row', alignItems: 'flex-start', marginBottom: '12px' }">
+      <view :style="{ flex: 1, paddingRight: '6px' }"><PlainStyle /></view>
+      <view :style="{ flex: 1, paddingLeft: '6px' }"><ImportedCSS /></view>
+    </view>
   </scroll-view>
 </template>
diff --git a/packages/vue-lynx/plugin/src/entry.ts b/packages/vue-lynx/plugin/src/entry.ts
index 693f038d4..0dc3755f4 100644
--- a/packages/vue-lynx/plugin/src/entry.ts
+++ b/packages/vue-lynx/plugin/src/entry.ts
@@ -175,9 +175,11 @@ class VueCSSConfigPlugin {
         };
         hooks.beforeEncode.tap(PLUGIN_CSS_CONFIG, (args) => {
           const encodeData = args['encodeData'] as {
-            compilerOptions: Record<string, unknown>;
+            sourceContent: {
+              config: Record<string, unknown>;
+            };
           };
-          Object.assign(encodeData.compilerOptions, this.compilerOptions);
+          Object.assign(encodeData.sourceContent.config, this.compilerOptions);
           return args;
         });
       },

From b78cc643f08872150221c3f8df48d266ff7f7a07 Mon Sep 17 00:00:00 2001
From: Kealan Clarke <59548500+KealanAU@users.noreply.github.com>
Date: Sun, 5 Apr 2026 13:48:05 +1000
Subject: [PATCH 11/16] [refactor] updates to the css features, change to have
 explict naming in title

---
 examples/css-features/src/CSSModules.vue      |  2 +-
 .../css-features/src/CSSVarsWorkaround.vue    |  2 +-
 examples/css-features/src/ImportedCSS.vue     |  2 +-
 examples/css-features/src/InlineStyleVar.vue  | 52 +++++++++++++++++++
 examples/css-features/src/PlainStyle.vue      |  2 +-
 examples/css-features/src/ScopedStyle.vue     |  2 +-
 examples/css-features/src/VBindCSS.vue        |  2 +-
 examples/css-features/src/VBindCSSSimple.vue  | 49 +++++++++++++++++
 examples/css-features/src/VBindThreads.vue    |  2 +-
 9 files changed, 108 insertions(+), 7 deletions(-)
 create mode 100644 examples/css-features/src/InlineStyleVar.vue
 create mode 100644 examples/css-features/src/VBindCSSSimple.vue

diff --git a/examples/css-features/src/CSSModules.vue b/examples/css-features/src/CSSModules.vue
index aa4b7161a..ab8385ccf 100644
--- a/examples/css-features/src/CSSModules.vue
+++ b/examples/css-features/src/CSSModules.vue
@@ -17,7 +17,7 @@
 
 <template>
   <view :class="$style.card">
-    <text :class="$style.title">&lt;style module&gt;</text>
+    <text :class="$style.title">&lt;style module&gt; (CSSModules.vue)</text>
     <text :class="$style.desc">
       Uses hashed class names (e.g. .card_abc123).
       These are plain class selectors — Lynx supports them.
diff --git a/examples/css-features/src/CSSVarsWorkaround.vue b/examples/css-features/src/CSSVarsWorkaround.vue
index c0725ba1a..d8e7ba148 100644
--- a/examples/css-features/src/CSSVarsWorkaround.vue
+++ b/examples/css-features/src/CSSVarsWorkaround.vue
@@ -30,7 +30,7 @@ function toggle() {
 <template>
   <view :style="cardStyle">
     <text :style="{ fontSize: '15px', fontWeight: 'bold', color: '#333', marginBottom: '4px' }">
-      Workaround: Reactive inline :style
+      Workaround: Reactive inline :style (CSSVarsWorkaround.vue)
     </text>
     <text :style="{ fontSize: '12px', color: '#555', marginBottom: '8px' }">
       Use computed() + :style bindings instead of v-bind() in CSS.
diff --git a/examples/css-features/src/ImportedCSS.vue b/examples/css-features/src/ImportedCSS.vue
index 5705d4a1f..73d9f2d68 100644
--- a/examples/css-features/src/ImportedCSS.vue
+++ b/examples/css-features/src/ImportedCSS.vue
@@ -8,7 +8,7 @@ import './imported.css'
 
 <template>
   <view class="imported-card">
-    <text class="imported-title">Imported .css file</text>
+    <text class="imported-title">Imported .css file (ImportedCSS.vue)</text>
     <text class="imported-desc">
       External CSS files with class selectors work via the
       @lynx-js/css-extract-webpack-plugin pipeline.
diff --git a/examples/css-features/src/InlineStyleVar.vue b/examples/css-features/src/InlineStyleVar.vue
new file mode 100644
index 000000000..236e41fed
--- /dev/null
+++ b/examples/css-features/src/InlineStyleVar.vue
@@ -0,0 +1,52 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const COLORS = ['#1565c0', '#c62828', '#2e7d32', '#f57f17']
+const idx = ref(0)
+const color = ref(COLORS[0]!)
+
+function cycle() {
+  idx.value = (idx.value + 1) % COLORS.length
+  color.value = COLORS[idx.value]!
+}
+</script>
+
+<template>
+  <view :style="{
+    display: 'flex',
+    flexDirection: 'column',
+    backgroundColor: '#fafafa',
+    padding: '12px',
+    borderRadius: '8px',
+    marginBottom: '12px',
+  }">
+    <text :style="{ fontSize: '15px', fontWeight: 'bold', color: '#333', marginBottom: '2px' }">
+      Inline :style + var() (InlineStyleVar.vue)
+    </text>
+    <text :style="{ fontSize: '11px', color: '#888', marginBottom: '10px' }">
+      Parent sets --my-color via :style; child class reads color: var(--my-color).
+    </text>
+
+    <!-- --my-color must be on the SAME element as the class that uses var(--my-color).
+         Lynx has no CSS cascade so a parent-set var is invisible to children. -->
+    <text
+      class="colored-text"
+      :style="{ '--my-color': color, fontWeight: 'bold', padding: '12px', borderRadius: '6px', backgroundColor: '#fff' }"
+    >
+      This text should be {{ color }}
+    </text>
+
+    <text
+      :style="{ marginTop: '10px', backgroundColor: '#1565c0', color: '#fff', padding: '6px 10px', borderRadius: '4px', fontSize: '11px', alignSelf: 'flex-start' }"
+      :bindtap="cycle"
+    >
+      Cycle colour
+    </text>
+  </view>
+</template>
+
+<style>
+.colored-text {
+  color: var(--my-color);
+}
+</style>
diff --git a/examples/css-features/src/PlainStyle.vue b/examples/css-features/src/PlainStyle.vue
index cb04df60d..ef01cf7da 100644
--- a/examples/css-features/src/PlainStyle.vue
+++ b/examples/css-features/src/PlainStyle.vue
@@ -6,7 +6,7 @@
 
 <template>
   <view class="plain-card">
-    <text class="plain-title">Plain &lt;style&gt; (no scoped)</text>
+    <text class="plain-title">Plain &lt;style&gt; (PlainStyle.vue)</text>
     <text class="plain-desc">Class selectors work via CSS extraction pipeline.</text>
   </view>
 </template>
diff --git a/examples/css-features/src/ScopedStyle.vue b/examples/css-features/src/ScopedStyle.vue
index d418d95ce..b38812514 100644
--- a/examples/css-features/src/ScopedStyle.vue
+++ b/examples/css-features/src/ScopedStyle.vue
@@ -15,7 +15,7 @@
 
 <template>
   <view class="scoped-card">
-    <text class="scoped-title">&lt;style scoped&gt;</text>
+    <text class="scoped-title">&lt;style scoped&gt; (ScopedStyle.vue)</text>
     <text class="scoped-desc">
       Uses [data-v-xxx] attribute selectors internally.
       Lynx CSS engine does not support attribute selectors,
diff --git a/examples/css-features/src/VBindCSS.vue b/examples/css-features/src/VBindCSS.vue
index 5163a6971..a33c39966 100644
--- a/examples/css-features/src/VBindCSS.vue
+++ b/examples/css-features/src/VBindCSS.vue
@@ -40,7 +40,7 @@ function cycleOpacity() {
     marginBottom: '12px',
   }">
     <text :style="{ fontSize: '15px', fontWeight: 'bold', marginBottom: '2px', color: '#333' }">
-      v-bind() in CSS &nbsp;vs&nbsp; inline :style
+      v-bind() in CSS &nbsp;vs&nbsp; inline :style (VBindCSS.vue)
     </text>
     <text :style="{ fontSize: '11px', color: '#888', marginBottom: '10px' }">
       Same values drive both panels. Tap a button to cycle and compare.
diff --git a/examples/css-features/src/VBindCSSSimple.vue b/examples/css-features/src/VBindCSSSimple.vue
new file mode 100644
index 000000000..13d342b10
--- /dev/null
+++ b/examples/css-features/src/VBindCSSSimple.vue
@@ -0,0 +1,49 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const COLORS = ['#1565c0', '#c62828', '#2e7d32', '#f57f17']
+const idx = ref(0)
+const color = ref(COLORS[0]!)
+
+function cycle() {
+  idx.value = (idx.value + 1) % COLORS.length
+  color.value = COLORS[idx.value]!
+}
+</script>
+
+<template>
+  <view :style="{
+    display: 'flex',
+    flexDirection: 'column',
+    backgroundColor: '#fafafa',
+    padding: '12px',
+    borderRadius: '8px',
+    marginBottom: '12px',
+  }">
+    <text :style="{ fontSize: '15px', fontWeight: 'bold', color: '#333', marginBottom: '2px' }">
+      v-bind() in CSS (VBindCSSSimple.vue)
+    </text>
+    <text :style="{ fontSize: '11px', color: '#888', marginBottom: '10px' }">
+      SFC compiler emits useCssVars(); Lynx walks VNode tree to stamp the var.
+    </text>
+
+    <view :style="{ padding: '12px', borderRadius: '6px', backgroundColor: '#fff' }">
+      <text class="bound-text" :style="{ fontWeight: 'bold' }">
+        This text should be {{ color }}
+      </text>
+    </view>
+
+    <text
+      :style="{ marginTop: '10px', backgroundColor: '#1565c0', color: '#fff', padding: '6px 10px', borderRadius: '4px', fontSize: '11px', alignSelf: 'flex-start' }"
+      :bindtap="cycle"
+    >
+      Cycle colour
+    </text>
+  </view>
+</template>
+
+<style>
+.bound-text {
+  color: v-bind(color);
+}
+</style>
diff --git a/examples/css-features/src/VBindThreads.vue b/examples/css-features/src/VBindThreads.vue
index c712a37f6..fa91287d9 100644
--- a/examples/css-features/src/VBindThreads.vue
+++ b/examples/css-features/src/VBindThreads.vue
@@ -33,7 +33,7 @@ function cycleColor() {
     marginBottom: '12px',
   }">
     <text :style="{ fontSize: '15px', fontWeight: 'bold', marginBottom: '4px', color: '#333' }">
-      Inline :style + var() &nbsp;vs&nbsp; v-bind() in CSS
+      Inline :style + var() &nbsp;vs&nbsp; v-bind() in CSS (VBindThreads.vue)
     </text>
     <text :style="{ fontSize: '11px', color: '#888', marginBottom: '10px' }">
       Same reactive ref. Tap either box to cycle — compare how each approach updates.

From 280591f26d6f1029f128353913613e00094f7020 Mon Sep 17 00:00:00 2001
From: Kealan Clarke <59548500+KealanAU@users.noreply.github.com>
Date: Sun, 5 Apr 2026 14:53:41 +1000
Subject: [PATCH 12/16] [fix] updates to properly stamp with
 enableCSSInheritance

---
 .changeset/v-bind-css-vars.md                 |  2 +-
 examples/css-features/src/InlineStyleVar.vue  | 52 -------------
 examples/css-features/src/VBindCSSSimple.vue  | 49 ------------
 .../upstream-tests/src/use-css-vars.spec.ts   | 76 +++++++++++++++++++
 packages/vue-lynx/plugin/src/index.ts         | 12 ++-
 packages/vue-lynx/runtime/src/use-css-vars.ts | 29 +++++--
 website/docs/guide/vue-compatibility.mdx      |  7 +-
 website/docs/zh/guide/vue-compatibility.mdx   |  7 +-
 8 files changed, 109 insertions(+), 125 deletions(-)
 delete mode 100644 examples/css-features/src/InlineStyleVar.vue
 delete mode 100644 examples/css-features/src/VBindCSSSimple.vue

diff --git a/.changeset/v-bind-css-vars.md b/.changeset/v-bind-css-vars.md
index 34d1cdfdd..87dedabe0 100644
--- a/.changeset/v-bind-css-vars.md
+++ b/.changeset/v-bind-css-vars.md
@@ -4,4 +4,4 @@
 
 feat: support `v-bind()` in `<style>` blocks via Lynx-native `useCssVars`
 
-Implements a Background Thread compatible `useCssVars` that merges CSS custom properties into element inline styles via the ops pipeline. Requires `enableCSSInlineVariables: true` and `enableCSSInheritance: true` in `lynx.config`.
+Implements a Background Thread compatible `useCssVars` that merges CSS custom properties into every element's inline style via the ops pipeline. Requires `enableCSSInlineVariables: true` in `lynx.config`. `enableCSSInheritance` is not required — CSS vars are stamped directly on each element rather than relying on the Lynx engine's CSS var inheritance.
diff --git a/examples/css-features/src/InlineStyleVar.vue b/examples/css-features/src/InlineStyleVar.vue
deleted file mode 100644
index 236e41fed..000000000
--- a/examples/css-features/src/InlineStyleVar.vue
+++ /dev/null
@@ -1,52 +0,0 @@
-<script setup lang="ts">
-import { ref } from 'vue'
-
-const COLORS = ['#1565c0', '#c62828', '#2e7d32', '#f57f17']
-const idx = ref(0)
-const color = ref(COLORS[0]!)
-
-function cycle() {
-  idx.value = (idx.value + 1) % COLORS.length
-  color.value = COLORS[idx.value]!
-}
-</script>
-
-<template>
-  <view :style="{
-    display: 'flex',
-    flexDirection: 'column',
-    backgroundColor: '#fafafa',
-    padding: '12px',
-    borderRadius: '8px',
-    marginBottom: '12px',
-  }">
-    <text :style="{ fontSize: '15px', fontWeight: 'bold', color: '#333', marginBottom: '2px' }">
-      Inline :style + var() (InlineStyleVar.vue)
-    </text>
-    <text :style="{ fontSize: '11px', color: '#888', marginBottom: '10px' }">
-      Parent sets --my-color via :style; child class reads color: var(--my-color).
-    </text>
-
-    <!-- --my-color must be on the SAME element as the class that uses var(--my-color).
-         Lynx has no CSS cascade so a parent-set var is invisible to children. -->
-    <text
-      class="colored-text"
-      :style="{ '--my-color': color, fontWeight: 'bold', padding: '12px', borderRadius: '6px', backgroundColor: '#fff' }"
-    >
-      This text should be {{ color }}
-    </text>
-
-    <text
-      :style="{ marginTop: '10px', backgroundColor: '#1565c0', color: '#fff', padding: '6px 10px', borderRadius: '4px', fontSize: '11px', alignSelf: 'flex-start' }"
-      :bindtap="cycle"
-    >
-      Cycle colour
-    </text>
-  </view>
-</template>
-
-<style>
-.colored-text {
-  color: var(--my-color);
-}
-</style>
diff --git a/examples/css-features/src/VBindCSSSimple.vue b/examples/css-features/src/VBindCSSSimple.vue
deleted file mode 100644
index 13d342b10..000000000
--- a/examples/css-features/src/VBindCSSSimple.vue
+++ /dev/null
@@ -1,49 +0,0 @@
-<script setup lang="ts">
-import { ref } from 'vue'
-
-const COLORS = ['#1565c0', '#c62828', '#2e7d32', '#f57f17']
-const idx = ref(0)
-const color = ref(COLORS[0]!)
-
-function cycle() {
-  idx.value = (idx.value + 1) % COLORS.length
-  color.value = COLORS[idx.value]!
-}
-</script>
-
-<template>
-  <view :style="{
-    display: 'flex',
-    flexDirection: 'column',
-    backgroundColor: '#fafafa',
-    padding: '12px',
-    borderRadius: '8px',
-    marginBottom: '12px',
-  }">
-    <text :style="{ fontSize: '15px', fontWeight: 'bold', color: '#333', marginBottom: '2px' }">
-      v-bind() in CSS (VBindCSSSimple.vue)
-    </text>
-    <text :style="{ fontSize: '11px', color: '#888', marginBottom: '10px' }">
-      SFC compiler emits useCssVars(); Lynx walks VNode tree to stamp the var.
-    </text>
-
-    <view :style="{ padding: '12px', borderRadius: '6px', backgroundColor: '#fff' }">
-      <text class="bound-text" :style="{ fontWeight: 'bold' }">
-        This text should be {{ color }}
-      </text>
-    </view>
-
-    <text
-      :style="{ marginTop: '10px', backgroundColor: '#1565c0', color: '#fff', padding: '6px 10px', borderRadius: '4px', fontSize: '11px', alignSelf: 'flex-start' }"
-      :bindtap="cycle"
-    >
-      Cycle colour
-    </text>
-  </view>
-</template>
-
-<style>
-.bound-text {
-  color: v-bind(color);
-}
-</style>
diff --git a/packages/upstream-tests/src/use-css-vars.spec.ts b/packages/upstream-tests/src/use-css-vars.spec.ts
index 446791071..8cb549052 100644
--- a/packages/upstream-tests/src/use-css-vars.spec.ts
+++ b/packages/upstream-tests/src/use-css-vars.spec.ts
@@ -402,3 +402,79 @@ describe('useCssVars — reactivity', () => {
     expect(cssVarOp).toBeUndefined();
   });
 });
+
+// ---------------------------------------------------------------------------
+// 7. Deep element stamping
+// ---------------------------------------------------------------------------
+
+describe('useCssVars — deep element stamping', () => {
+  it('stamps CSS vars on every descendant element, not just the root', async () => {
+    const color = ref('red');
+
+    // Structure: view (root) > view (mid) > text (leaf)
+    // The leaf is where a CSS class rule would consume the var.
+    // All three elements must receive the var so the Lynx class rule resolver
+    // can see it on the element itself (it does not resolve inherited inline vars).
+    const App = defineComponent({
+      setup() {
+        useCssVars((_ctx: unknown) => ({ 'deep1': color.value }));
+        return () =>
+          h('view', null, [
+            h('view', null, [
+              h('text'),
+            ]),
+          ]);
+      },
+    });
+
+    createApp(App).mount();
+    await nextTick();
+
+    const ops = collectFlushedOps();
+    const styleOps = parseSetStyleOps(ops);
+
+    const cssVarOps = styleOps.filter(
+      (op) => (op.style as Record<string, unknown>)['--deep1'] !== undefined,
+    );
+
+    // All three elements (root view, mid view, leaf text) must be stamped.
+    expect(cssVarOps.length).toBe(3);
+    for (const op of cssVarOps) {
+      expect((op.style as Record<string, unknown>)['--deep1']).toBe('red');
+    }
+  });
+
+  it('stamps updated CSS vars on deep elements when reactive source changes', async () => {
+    const color = ref('red');
+
+    const App = defineComponent({
+      setup() {
+        useCssVars((_ctx: unknown) => ({ 'deep2': color.value }));
+        return () =>
+          h('view', null, [
+            h('text'),
+          ]);
+      },
+    });
+
+    createApp(App).mount();
+    await nextTick();
+    collectFlushedOps(); // drain mount ops
+
+    color.value = 'blue';
+    await nextTick();
+
+    const ops = collectFlushedOps();
+    const styleOps = parseSetStyleOps(ops);
+
+    const cssVarOps = styleOps.filter(
+      (op) => (op.style as Record<string, unknown>)['--deep2'] !== undefined,
+    );
+
+    // Both the root view and child text must receive the updated value.
+    expect(cssVarOps.length).toBe(2);
+    for (const op of cssVarOps) {
+      expect((op.style as Record<string, unknown>)['--deep2']).toBe('blue');
+    }
+  });
+});
diff --git a/packages/vue-lynx/plugin/src/index.ts b/packages/vue-lynx/plugin/src/index.ts
index 517a6fd99..719655125 100644
--- a/packages/vue-lynx/plugin/src/index.ts
+++ b/packages/vue-lynx/plugin/src/index.ts
@@ -66,10 +66,14 @@ export interface PluginVueLynxOptions {
 
   /**
    * Whether to enable CSS inheritance in the Lynx engine.
-   * When enabled, CSS property values (including CSS custom properties /
-   * variables) cascade from parent elements to children, matching standard
-   * CSS behavior. Required for design-token patterns where CSS variables
-   * are set on a parent and consumed by descendants.
+   * When enabled, computed CSS property values cascade from parent elements
+   * to children (e.g. `color`, `font-size`), matching standard CSS behavior.
+   *
+   * Note: CSS custom property (variable) inheritance via this flag does not
+   * propagate `--*` values into `{{--varName}}` class rule resolution in the
+   * Lynx engine. `v-bind()` in `<style>` blocks works without this flag —
+   * `useCssVars` stamps CSS vars directly on every element instead of relying
+   * on inheritance.
    * @defaultValue false
    */
   enableCSSInheritance?: boolean;
diff --git a/packages/vue-lynx/runtime/src/use-css-vars.ts b/packages/vue-lynx/runtime/src/use-css-vars.ts
index e0fd15b26..c40c963e0 100644
--- a/packages/vue-lynx/runtime/src/use-css-vars.ts
+++ b/packages/vue-lynx/runtime/src/use-css-vars.ts
@@ -21,6 +21,7 @@ import { ShadowElement } from './shadow-element.js';
 const SF_ELEMENT = 1;
 const SF_COMPONENT = 6; // STATEFUL_COMPONENT (4) | FUNCTIONAL_COMPONENT (2)
 const SF_ARRAY_CHILDREN = 16;
+// SF_TEXT_CHILDREN = 8 — text string children, no VNodes to recurse into.
 
 function applyVarsToEl(el: ShadowElement, vars: Record<string, string>): void {
   const style: Record<string, unknown> = { ...el._style };
@@ -46,14 +47,23 @@ function applyVarsToVNode(
     if (el instanceof ShadowElement) {
       applyVarsToEl(el, vars);
     }
+    // Stamp CSS vars on every descendant element. Lynx's {{--varName}} class
+    // rule resolver reads from the element's own inline styles only — it does
+    // not resolve inherited CSS vars from ancestor inline styles, so each
+    // element that may consume a CSS var needs the var present on itself.
+    if (shapeFlag & SF_ARRAY_CHILDREN) {
+      for (const child of vnode.children as VNode[]) {
+        applyVarsToVNode(child, vars);
+      }
+    }
   } else if (shapeFlag & SF_COMPONENT) {
-    // Recurse into the component's rendered subtree
+    // Recurse into the component's rendered subtree.
     if (vnode.component) {
       applyVarsToVNode(vnode.component.subTree, vars);
     }
   } else if (vnode.type === Fragment && (shapeFlag & SF_ARRAY_CHILDREN)) {
-    // Fragment root — walk every sibling child (but NOT element children;
-    // those inherit CSS vars via enableCSSInheritance).
+    // Fragment root — walk every sibling child. Each recurses into its own
+    // element subtree via the SF_ELEMENT branch above.
     const children = vnode.children as VNode[];
     for (const child of children) {
       applyVarsToVNode(child, vars);
@@ -70,12 +80,17 @@ function applyVarsToVNode(
  *
  * The standard `@vue/runtime-dom` version uses DOM APIs (`el.style.setProperty`)
  * which are unavailable in Lynx's Background Thread.  This implementation
- * instead merges the CSS variables into the element's inline style and sends
+ * instead merges the CSS variables into every element's inline style and sends
  * them to the Main Thread via the ops pipeline.
  *
- * Requires `enableCSSInlineVariables: true` and `enableCSSInheritance: true`
- * in `lynx.config.ts` so the Lynx engine propagates `--*` inline-style vars
- * to descendant elements.
+ * CSS vars are stamped on every element in the component subtree rather than
+ * only the root. Lynx's `{{--varName}}` class rule resolver reads from an
+ * element's own inline styles but does not resolve inherited CSS vars from
+ * ancestor inline styles, so each element needs the var present on itself.
+ *
+ * Requires `enableCSSInlineVariables: true` in `lynx.config.ts`.
+ * `enableCSSInheritance` is not required — CSS vars are stamped on every
+ * element directly rather than relying on the engine's CSS var inheritance.
  *
  * @hidden
  */
diff --git a/website/docs/guide/vue-compatibility.mdx b/website/docs/guide/vue-compatibility.mdx
index ac0fff95b..c4c2a70eb 100644
--- a/website/docs/guide/vue-compatibility.mdx
+++ b/website/docs/guide/vue-compatibility.mdx
@@ -29,19 +29,14 @@ Plain `<style>` blocks, imported `.css` files, [`<style module>`](https://vuejs.
 | `v-bind()` in `<style>` | Works (requires config, see below) |
 | `<style scoped>` | Upcoming ([#78](https://github.com/Huxpro/vue-lynx/issues/78)) |
 
-`v-bind()` in `<style>` requires two config options so the Lynx engine recognizes CSS custom properties in inline styles and cascades them to descendants:
+`v-bind()` in `<style>` requires one config option so the Lynx engine recognizes CSS custom properties in inline styles:
 
 ```ts title="lynx.config.ts"
 pluginVueLynx({
   enableCSSInlineVariables: true,
-  enableCSSInheritance: true,
 })
 ```
 
-:::warning Known limitation
-Layout-affecting properties (e.g., `font-size`) driven by `v-bind()` apply correctly on initial render but may not update visually on reactive change. This is a Lynx engine limitation. Workaround: drive layout properties via `:style` binding directly on the element.
-:::
-
 :::
 
 <Go
diff --git a/website/docs/zh/guide/vue-compatibility.mdx b/website/docs/zh/guide/vue-compatibility.mdx
index 65f12f9ca..57c097e7d 100644
--- a/website/docs/zh/guide/vue-compatibility.mdx
+++ b/website/docs/zh/guide/vue-compatibility.mdx
@@ -29,19 +29,14 @@ Vue Lynx 100% 复用了 Vue 的响应式核心（`@vue/reactivity`）。每个
 | `<style>` 中的 `v-bind()` | 可用（需要配置，见下方） |
 | `<style scoped>` | 即将支持（[#78](https://github.com/Huxpro/vue-lynx/issues/78)） |
 
-`<style>` 中的 `v-bind()` 需要两个配置选项，以便 Lynx 引擎识别内联样式中的 CSS 自定义属性并将其级联到后代元素：
+`<style>` 中的 `v-bind()` 需要一个配置选项，以便 Lynx 引擎识别内联样式中的 CSS 自定义属性：
 
 ```ts title="lynx.config.ts"
 pluginVueLynx({
   enableCSSInlineVariables: true,
-  enableCSSInheritance: true,
 })
 ```
 
-:::warning 已知限制
-通过 `v-bind()` 驱动的影响布局的属性（如 `font-size`）在初始渲染时可以正确应用，但在响应式更新时可能不会更新视觉效果。这是 Lynx 引擎的限制。解决方法：在元素上直接通过 `:style` 绑定来驱动布局属性。
-:::
-
 :::
 
 <Go

From e8463a43226e50bf84f99fe4559370e9c90618a9 Mon Sep 17 00:00:00 2001
From: Kealan Clarke <59548500+KealanAU@users.noreply.github.com>
Date: Sun, 5 Apr 2026 15:18:59 +1000
Subject: [PATCH 13/16] [fix] testing the inheritance

---
 examples/css-features/src/App.vue             |  4 ++
 .../css-features/src/CSSInheritanceTest.vue   | 72 +++++++++++++++++++
 packages/vue-lynx/runtime/src/use-css-vars.ts | 40 +++++++----
 3 files changed, 103 insertions(+), 13 deletions(-)
 create mode 100644 examples/css-features/src/CSSInheritanceTest.vue

diff --git a/examples/css-features/src/App.vue b/examples/css-features/src/App.vue
index 465341f19..8c07236a9 100644
--- a/examples/css-features/src/App.vue
+++ b/examples/css-features/src/App.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import VBindCSS from './VBindCSS.vue'
 import VBindThreads from './VBindThreads.vue'
+import CSSInheritanceTest from './CSSInheritanceTest.vue'
 import PlainStyle from './PlainStyle.vue'
 import ScopedStyle from './ScopedStyle.vue'
 import CSSModules from './CSSModules.vue'
@@ -21,6 +22,9 @@ import ImportedCSS from './ImportedCSS.vue'
     <VBindCSS />
     <VBindThreads />
 
+    <!-- enableCSSInheritance isolation test — no useCssVars, pure :style + var() inheritance -->
+    <CSSInheritanceTest />
+
     <!-- Divider -->
     <text :style="{ fontSize: '13px', fontWeight: 'bold', color: '#888', marginBottom: '12px', marginTop: '4px' }">
       Other CSS patterns
diff --git a/examples/css-features/src/CSSInheritanceTest.vue b/examples/css-features/src/CSSInheritanceTest.vue
new file mode 100644
index 000000000..76d34304f
--- /dev/null
+++ b/examples/css-features/src/CSSInheritanceTest.vue
@@ -0,0 +1,72 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const COLORS = ['#c62828', '#1565c0', '#2e7d32']
+const colorIdx = ref(0)
+const color = ref(COLORS[0]!)
+
+function cycleColor() {
+  colorIdx.value = (colorIdx.value + 1) % COLORS.length
+  color.value = COLORS[colorIdx.value]!
+}
+</script>
+
+<template>
+  <view :style="{
+    backgroundColor: '#fafafa',
+    padding: '12px',
+    borderRadius: '8px',
+    marginBottom: '12px',
+  }">
+    <text :style="{ fontSize: '15px', fontWeight: 'bold', marginBottom: '2px', color: '#333' }">
+      enableCSSInheritance — CSS var propagation (CSSInheritanceTest.vue)
+    </text>
+    <text :style="{ fontSize: '11px', color: '#888', marginBottom: '10px' }">
+      Parent sets --test-color via :style. Children consume it via var() in class rules.
+      No useCssVars involved. Tests whether enableCSSInheritance propagates CSS custom properties.
+    </text>
+
+    <!-- Parent sets the CSS var via :style only — no v-bind(), no useCssVars -->
+    <view :style="{ '--test-color': color, padding: '10px', borderRadius: '6px', backgroundColor: '#fff' }">
+      <text :style="{ fontSize: '11px', color: '#555', marginBottom: '6px' }">
+        Parent: :style="{ '--test-color': color }"
+      </text>
+
+      <!-- Depth 1 child -->
+      <view :style="{ marginBottom: '4px' }">
+        <text class="inherited-color" :style="{ fontWeight: 'bold' }">
+          Depth 1 — color: var(--test-color)
+        </text>
+      </view>
+
+      <!-- Depth 2 child -->
+      <view>
+        <view>
+          <text class="inherited-color" :style="{ fontWeight: 'bold' }">
+            Depth 2 — color: var(--test-color)
+          </text>
+        </view>
+      </view>
+    </view>
+
+    <text
+      :style="{
+        marginTop: '10px',
+        backgroundColor: '#1565c0',
+        color: '#fff',
+        padding: '6px 10px',
+        borderRadius: '4px',
+        fontSize: '11px',
+      }"
+      :bindtap="cycleColor"
+    >
+      Cycle color (currently: {{ color }})
+    </text>
+  </view>
+</template>
+
+<style>
+.inherited-color {
+  color: var(--test-color);
+}
+</style>
diff --git a/packages/vue-lynx/runtime/src/use-css-vars.ts b/packages/vue-lynx/runtime/src/use-css-vars.ts
index c40c963e0..84aae1c77 100644
--- a/packages/vue-lynx/runtime/src/use-css-vars.ts
+++ b/packages/vue-lynx/runtime/src/use-css-vars.ts
@@ -47,30 +47,44 @@ function applyVarsToVNode(
     if (el instanceof ShadowElement) {
       applyVarsToEl(el, vars);
     }
-    // Stamp CSS vars on every descendant element. Lynx's {{--varName}} class
-    // rule resolver reads from the element's own inline styles only — it does
-    // not resolve inherited CSS vars from ancestor inline styles, so each
-    // element that may consume a CSS var needs the var present on itself.
-    if (shapeFlag & SF_ARRAY_CHILDREN) {
-      for (const child of vnode.children as VNode[]) {
-        applyVarsToVNode(child, vars);
-      }
-    }
+    stampElementDescendants(vnode, vars); // lynx-family/lynx#5889
   } else if (shapeFlag & SF_COMPONENT) {
     // Recurse into the component's rendered subtree.
     if (vnode.component) {
       applyVarsToVNode(vnode.component.subTree, vars);
     }
   } else if (vnode.type === Fragment && (shapeFlag & SF_ARRAY_CHILDREN)) {
-    // Fragment root — walk every sibling child. Each recurses into its own
-    // element subtree via the SF_ELEMENT branch above.
-    const children = vnode.children as VNode[];
-    for (const child of children) {
+    // Fragment root — walk every sibling child.
+    for (const child of vnode.children as VNode[]) {
       applyVarsToVNode(child, vars);
     }
   }
 }
 
+/**
+ * Workaround for lynx-family/lynx#5889.
+ *
+ * When `__SetInlineStyles` updates a CSS custom property on a parent element,
+ * the Lynx engine does not re-propagate the new value through the CSS
+ * inheritance chain to descendant class rules, despite `enableCSSInheritance`
+ * being set. Stamping every element directly means no inheritance is needed.
+ *
+ * TO REVERT when lynx-family/lynx#5889 is fixed:
+ *   1. Delete this function.
+ *   2. Remove the `stampElementDescendants(vnode, vars)` call in `applyVarsToVNode`.
+ *   Root-only stamping via `applyVarsToEl` will be sufficient once the engine
+ *   re-evaluates inheritance on `__SetInlineStyles` updates.
+ */
+function stampElementDescendants(
+  vnode: VNode,
+  vars: Record<string, string>,
+): void {
+  if (!(vnode.shapeFlag & SF_ARRAY_CHILDREN)) return;
+  for (const child of vnode.children as VNode[]) {
+    applyVarsToVNode(child, vars);
+  }
+}
+
 /**
  * Lynx-specific implementation of Vue's `useCssVars`.
  *

From 1c14b4f73bb818ad306b09cfa1e3db0ef089d077 Mon Sep 17 00:00:00 2001
From: Kealan Clarke <59548500+KealanAU@users.noreply.github.com>
Date: Tue, 5 May 2026 06:39:22 +0800
Subject: [PATCH 14/16] docs: remove stale workaround references from
 useCssVars comments

Engine fix lynx-family/lynx#5912 landed; root-only stamping is the
correct description, not "every element".
---
 .changeset/v-bind-css-vars.md                 | 2 +-
 packages/vue-lynx/plugin/src/index.ts         | 9 ++++-----
 packages/vue-lynx/runtime/src/use-css-vars.ts | 4 ++--
 3 files changed, 7 insertions(+), 8 deletions(-)

diff --git a/.changeset/v-bind-css-vars.md b/.changeset/v-bind-css-vars.md
index 87dedabe0..06be1520a 100644
--- a/.changeset/v-bind-css-vars.md
+++ b/.changeset/v-bind-css-vars.md
@@ -4,4 +4,4 @@
 
 feat: support `v-bind()` in `<style>` blocks via Lynx-native `useCssVars`
 
-Implements a Background Thread compatible `useCssVars` that merges CSS custom properties into every element's inline style via the ops pipeline. Requires `enableCSSInlineVariables: true` in `lynx.config`. `enableCSSInheritance` is not required — CSS vars are stamped directly on each element rather than relying on the Lynx engine's CSS var inheritance.
+Implements a Background Thread compatible `useCssVars` that merges CSS custom properties into the component root element's inline style via the ops pipeline; the Lynx engine propagates them to descendants (lynx-family/lynx#5912). Requires `enableCSSInlineVariables: true` in `lynx.config`. `enableCSSInheritance` is not required for `v-bind()` in CSS.
diff --git a/packages/vue-lynx/plugin/src/index.ts b/packages/vue-lynx/plugin/src/index.ts
index 719655125..4d5de58cf 100644
--- a/packages/vue-lynx/plugin/src/index.ts
+++ b/packages/vue-lynx/plugin/src/index.ts
@@ -69,11 +69,10 @@ export interface PluginVueLynxOptions {
    * When enabled, computed CSS property values cascade from parent elements
    * to children (e.g. `color`, `font-size`), matching standard CSS behavior.
    *
-   * Note: CSS custom property (variable) inheritance via this flag does not
-   * propagate `--*` values into `{{--varName}}` class rule resolution in the
-   * Lynx engine. `v-bind()` in `<style>` blocks works without this flag —
-   * `useCssVars` stamps CSS vars directly on every element instead of relying
-   * on inheritance.
+   * Note: `v-bind()` in `<style>` blocks works without this flag — `useCssVars`
+   * stamps CSS vars on the component root element(s) and the Lynx engine
+   * propagates them to descendants via the CSS inheritance chain
+   * (fixed in lynx-family/lynx#5912).
    * @defaultValue false
    */
   enableCSSInheritance?: boolean;
diff --git a/packages/vue-lynx/runtime/src/use-css-vars.ts b/packages/vue-lynx/runtime/src/use-css-vars.ts
index ecd45de22..18636cb2d 100644
--- a/packages/vue-lynx/runtime/src/use-css-vars.ts
+++ b/packages/vue-lynx/runtime/src/use-css-vars.ts
@@ -69,8 +69,8 @@ function applyVarsToVNode(
  *
  * The standard `@vue/runtime-dom` version uses DOM APIs (`el.style.setProperty`)
  * which are unavailable in Lynx's Background Thread.  This implementation
- * instead merges the CSS variables into every element's inline style and sends
- * them to the Main Thread via the ops pipeline.
+ * instead merges the CSS variables into the component root element's inline
+ * style and sends them to the Main Thread via the ops pipeline.
  *
  * CSS vars are stamped on the component's root element(s). The Lynx engine
  * propagates custom property updates to descendants via the CSS inheritance

From 8314700fd1114f51e4520b83d0d4caaa22eed5d8 Mon Sep 17 00:00:00 2001
From: Kealan Clarke <59548500+KealanAU@users.noreply.github.com>
Date: Sat, 27 Jun 2026 11:45:26 +0200
Subject: [PATCH 15/16] docs: reconcile lynx#5912/#5889 references and state
 minimum engine version

Standardize all references on the fix PR (#5912, closing issue #5889) and
document that v-bind() in CSS requires Lynx engine >= 3.8.1.
---
 .changeset/v-bind-css-vars.md                    | 2 +-
 packages/upstream-tests/src/use-css-vars.spec.ts | 4 ++--
 packages/vue-lynx/runtime/src/use-css-vars.ts    | 2 +-
 website/docs/guide/vue-compatibility.mdx         | 2 ++
 website/docs/zh/guide/vue-compatibility.mdx      | 2 ++
 5 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/.changeset/v-bind-css-vars.md b/.changeset/v-bind-css-vars.md
index 06be1520a..79daef607 100644
--- a/.changeset/v-bind-css-vars.md
+++ b/.changeset/v-bind-css-vars.md
@@ -4,4 +4,4 @@
 
 feat: support `v-bind()` in `<style>` blocks via Lynx-native `useCssVars`
 
-Implements a Background Thread compatible `useCssVars` that merges CSS custom properties into the component root element's inline style via the ops pipeline; the Lynx engine propagates them to descendants (lynx-family/lynx#5912). Requires `enableCSSInlineVariables: true` in `lynx.config`. `enableCSSInheritance` is not required for `v-bind()` in CSS.
+Implements a Background Thread compatible `useCssVars` that merges CSS custom properties into the component root element's inline style via the ops pipeline; the Lynx engine propagates them to descendants (lynx-family/lynx#5912, closing #5889). Requires `enableCSSInlineVariables: true` in `lynx.config` and Lynx engine ≥ 3.8.1 (the release containing #5912). `enableCSSInheritance` is not required for `v-bind()` in CSS.
diff --git a/packages/upstream-tests/src/use-css-vars.spec.ts b/packages/upstream-tests/src/use-css-vars.spec.ts
index aa405c5ba..716b47f4b 100644
--- a/packages/upstream-tests/src/use-css-vars.spec.ts
+++ b/packages/upstream-tests/src/use-css-vars.spec.ts
@@ -404,7 +404,7 @@ describe('useCssVars — reactivity', () => {
 });
 
 // ---------------------------------------------------------------------------
-// 7. Root-only stamping (engine propagates to descendants via lynx#5889 fix)
+// 7. Root-only stamping (engine propagates to descendants via lynx#5912 fix)
 // ---------------------------------------------------------------------------
 
 describe('useCssVars — root-only stamping', () => {
@@ -413,7 +413,7 @@ describe('useCssVars — root-only stamping', () => {
 
     // Structure: view (root) > view (mid) > text (leaf)
     // The Lynx engine propagates the CSS custom property to descendants via
-    // RecursivelyMarkChildrenCSSVariableDirty (fixed in lynx-family/lynx#5889).
+    // RecursivelyMarkChildrenCSSVariableDirty (fixed in lynx-family/lynx#5912, closing #5889).
     // useCssVars must stamp only the root; descendants must not receive a
     // redundant SET_STYLE.
     const App = defineComponent({
diff --git a/packages/vue-lynx/runtime/src/use-css-vars.ts b/packages/vue-lynx/runtime/src/use-css-vars.ts
index 18636cb2d..311f9e43b 100644
--- a/packages/vue-lynx/runtime/src/use-css-vars.ts
+++ b/packages/vue-lynx/runtime/src/use-css-vars.ts
@@ -74,7 +74,7 @@ function applyVarsToVNode(
  *
  * CSS vars are stamped on the component's root element(s). The Lynx engine
  * propagates custom property updates to descendants via the CSS inheritance
- * chain (fixed in lynx-family/lynx#5889).
+ * chain (fixed in lynx-family/lynx#5912, closing #5889).
  *
  * Requires `enableCSSInlineVariables: true` in `lynx.config.ts`.
  *
diff --git a/website/docs/guide/vue-compatibility.mdx b/website/docs/guide/vue-compatibility.mdx
index f1bbc502c..9b615dfa3 100644
--- a/website/docs/guide/vue-compatibility.mdx
+++ b/website/docs/guide/vue-compatibility.mdx
@@ -41,6 +41,8 @@ pluginVueLynx({
 })
 ```
 
+Requires **Lynx engine ≥ 3.8.1**, which ships the fix that propagates CSS custom properties from the component root to its descendants ([lynx-family/lynx#5912](https://github.com/lynx-family/lynx/pull/5912)). On earlier engines the variables are stamped on the root but never reach descendants.
+
 :::
 
 <Go
diff --git a/website/docs/zh/guide/vue-compatibility.mdx b/website/docs/zh/guide/vue-compatibility.mdx
index cc7f3147d..1e212dc6b 100644
--- a/website/docs/zh/guide/vue-compatibility.mdx
+++ b/website/docs/zh/guide/vue-compatibility.mdx
@@ -41,6 +41,8 @@ pluginVueLynx({
 })
 ```
 
+需要 **Lynx 引擎 ≥ 3.8.1**，该版本包含将 CSS 自定义属性从组件根元素传播到其后代的修复（[lynx-family/lynx#5912](https://github.com/lynx-family/lynx/pull/5912)）。在更早的引擎上，变量只会标记在根元素上，无法传递到后代。
+
 :::
 
 <Go

From 4ef99b7ea8c25793c6645dfc751dcc8069cdc3d5 Mon Sep 17 00:00:00 2001
From: Kealan Clarke <59548500+KealanAU@users.noreply.github.com>
Date: Fri, 17 Jul 2026 21:12:09 +0200
Subject: [PATCH 16/16] docs: require Lynx engine >= 3.9.0 for CSS v-bind()
 propagation

The #5912 propagation code (changed_css_vars, MarkCustomPropertiesDirty,
RecursivelyMarkChildrenCSSVariableDirty) first appears in the 3.9.0 tag;
3.8.1 lacks it and no later 3.8.x tag exists.

- Bump minimum engine to 3.9.0 in EN/ZH docs, changeset, and code comments
- Set enableCSSInheritance: false in css-features example so it cannot mask
  engine-level custom property propagation
- Reword root-only spec comments: they verify BG op emission only, not
  native descendant cascade
---
 .changeset/v-bind-css-vars.md                   |  2 +-
 examples/css-features/lynx.config.ts            |  5 ++++-
 examples/css-features/src/App.vue               |  2 +-
 .../css-features/src/CSSInheritanceTest.vue     |  5 +++--
 .../upstream-tests/src/use-css-vars.spec.ts     | 17 ++++++++++-------
 packages/vue-lynx/plugin/src/index.ts           |  4 ++--
 packages/vue-lynx/runtime/src/use-css-vars.ts   |  5 +++--
 website/docs/guide/vue-compatibility.mdx        |  2 +-
 website/docs/zh/guide/vue-compatibility.mdx     |  2 +-
 9 files changed, 26 insertions(+), 18 deletions(-)

diff --git a/.changeset/v-bind-css-vars.md b/.changeset/v-bind-css-vars.md
index 79daef607..fc70f586d 100644
--- a/.changeset/v-bind-css-vars.md
+++ b/.changeset/v-bind-css-vars.md
@@ -4,4 +4,4 @@
 
 feat: support `v-bind()` in `<style>` blocks via Lynx-native `useCssVars`
 
-Implements a Background Thread compatible `useCssVars` that merges CSS custom properties into the component root element's inline style via the ops pipeline; the Lynx engine propagates them to descendants (lynx-family/lynx#5912, closing #5889). Requires `enableCSSInlineVariables: true` in `lynx.config` and Lynx engine ≥ 3.8.1 (the release containing #5912). `enableCSSInheritance` is not required for `v-bind()` in CSS.
+Implements a Background Thread compatible `useCssVars` that merges CSS custom properties into the component root element's inline style via the ops pipeline; the Lynx engine propagates them to descendants (lynx-family/lynx#5912, closing #5889). Requires `enableCSSInlineVariables: true` in `lynx.config` and Lynx engine ≥ 3.9.0 (the first tagged release containing the #5912 propagation code). `enableCSSInheritance` is not required for `v-bind()` in CSS.
diff --git a/examples/css-features/lynx.config.ts b/examples/css-features/lynx.config.ts
index d40e0f403..3e65d72de 100644
--- a/examples/css-features/lynx.config.ts
+++ b/examples/css-features/lynx.config.ts
@@ -22,7 +22,10 @@ export default defineConfig({
     pluginVueLynx({
       optionsApi: false,
       enableCSSInlineVariables: true,
-      enableCSSInheritance: true,
+      // Deliberately false: the example must prove that CSS custom property
+      // propagation (lynx-family/lynx#5912, engine >= 3.9.0) works without
+      // inheritance mode masking it.
+      enableCSSInheritance: false,
     }),
   ],
 });
diff --git a/examples/css-features/src/App.vue b/examples/css-features/src/App.vue
index 8c07236a9..acaea1874 100644
--- a/examples/css-features/src/App.vue
+++ b/examples/css-features/src/App.vue
@@ -22,7 +22,7 @@ import ImportedCSS from './ImportedCSS.vue'
     <VBindCSS />
     <VBindThreads />
 
-    <!-- enableCSSInheritance isolation test — no useCssVars, pure :style + var() inheritance -->
+    <!-- Engine custom-property propagation test — no useCssVars, enableCSSInheritance off -->
     <CSSInheritanceTest />
 
     <!-- Divider -->
diff --git a/examples/css-features/src/CSSInheritanceTest.vue b/examples/css-features/src/CSSInheritanceTest.vue
index 76d34304f..c20d6abd9 100644
--- a/examples/css-features/src/CSSInheritanceTest.vue
+++ b/examples/css-features/src/CSSInheritanceTest.vue
@@ -19,11 +19,12 @@ function cycleColor() {
     marginBottom: '12px',
   }">
     <text :style="{ fontSize: '15px', fontWeight: 'bold', marginBottom: '2px', color: '#333' }">
-      enableCSSInheritance — CSS var propagation (CSSInheritanceTest.vue)
+      CSS custom property propagation (CSSInheritanceTest.vue)
     </text>
     <text :style="{ fontSize: '11px', color: '#888', marginBottom: '10px' }">
       Parent sets --test-color via :style. Children consume it via var() in class rules.
-      No useCssVars involved. Tests whether enableCSSInheritance propagates CSS custom properties.
+      No useCssVars, and enableCSSInheritance is false — tests that engine-level custom
+      property propagation (lynx#5912, engine >= 3.9.0) works on its own.
     </text>
 
     <!-- Parent sets the CSS var via :style only — no v-bind(), no useCssVars -->
diff --git a/packages/upstream-tests/src/use-css-vars.spec.ts b/packages/upstream-tests/src/use-css-vars.spec.ts
index 716b47f4b..11fd2f4bc 100644
--- a/packages/upstream-tests/src/use-css-vars.spec.ts
+++ b/packages/upstream-tests/src/use-css-vars.spec.ts
@@ -404,7 +404,7 @@ describe('useCssVars — reactivity', () => {
 });
 
 // ---------------------------------------------------------------------------
-// 7. Root-only stamping (engine propagates to descendants via lynx#5912 fix)
+// 7. Root-only stamping
 // ---------------------------------------------------------------------------
 
 describe('useCssVars — root-only stamping', () => {
@@ -412,10 +412,11 @@ describe('useCssVars — root-only stamping', () => {
     const color = ref('red');
 
     // Structure: view (root) > view (mid) > text (leaf)
-    // The Lynx engine propagates the CSS custom property to descendants via
-    // RecursivelyMarkChildrenCSSVariableDirty (fixed in lynx-family/lynx#5912, closing #5889).
-    // useCssVars must stamp only the root; descendants must not receive a
-    // redundant SET_STYLE.
+    // This test only verifies the BG-runtime contract: useCssVars stamps the
+    // root and emits no redundant SET_STYLE for descendants. Whether the
+    // native engine actually cascades the var to descendants is NOT covered
+    // here — that is engine behavior (lynx-family/lynx#5912, first in the
+    // 3.9.0 tag) and is verified manually via the css-features example.
     const App = defineComponent({
       setup() {
         useCssVars((_ctx: unknown) => ({ 'deep1': color.value }));
@@ -438,7 +439,8 @@ describe('useCssVars — root-only stamping', () => {
       (op) => (op.style as Record<string, unknown>)['--deep1'] !== undefined,
     );
 
-    // Only the root view should be stamped — not mid or leaf.
+    // Only the root view should be stamped — not mid or leaf. (Descendant
+    // cascade is the engine's job and is not asserted by this test.)
     expect(cssVarOps.length).toBe(1);
     expect((cssVarOps[0].style as Record<string, unknown>)['--deep1']).toBe('red');
   });
@@ -470,7 +472,8 @@ describe('useCssVars — root-only stamping', () => {
       (op) => (op.style as Record<string, unknown>)['--deep2'] !== undefined,
     );
 
-    // Only the root view is stamped; the child text is not.
+    // Only the root view is stamped; the child text is not. (Descendant
+    // cascade is the engine's job and is not asserted by this test.)
     expect(cssVarOps.length).toBe(1);
     expect((cssVarOps[0].style as Record<string, unknown>)['--deep2']).toBe('blue');
   });
diff --git a/packages/vue-lynx/plugin/src/index.ts b/packages/vue-lynx/plugin/src/index.ts
index 4d5de58cf..42d1437c3 100644
--- a/packages/vue-lynx/plugin/src/index.ts
+++ b/packages/vue-lynx/plugin/src/index.ts
@@ -71,8 +71,8 @@ export interface PluginVueLynxOptions {
    *
    * Note: `v-bind()` in `<style>` blocks works without this flag — `useCssVars`
    * stamps CSS vars on the component root element(s) and the Lynx engine
-   * propagates them to descendants via the CSS inheritance chain
-   * (fixed in lynx-family/lynx#5912).
+   * propagates them to descendants (lynx-family/lynx#5912, requires
+   * engine >= 3.9.0).
    * @defaultValue false
    */
   enableCSSInheritance?: boolean;
diff --git a/packages/vue-lynx/runtime/src/use-css-vars.ts b/packages/vue-lynx/runtime/src/use-css-vars.ts
index 311f9e43b..8ee34c788 100644
--- a/packages/vue-lynx/runtime/src/use-css-vars.ts
+++ b/packages/vue-lynx/runtime/src/use-css-vars.ts
@@ -73,8 +73,9 @@ function applyVarsToVNode(
  * style and sends them to the Main Thread via the ops pipeline.
  *
  * CSS vars are stamped on the component's root element(s). The Lynx engine
- * propagates custom property updates to descendants via the CSS inheritance
- * chain (fixed in lynx-family/lynx#5912, closing #5889).
+ * propagates custom property updates to descendants (lynx-family/lynx#5912,
+ * closing #5889; requires engine >= 3.9.0, the first tagged release with the
+ * propagation code).
  *
  * Requires `enableCSSInlineVariables: true` in `lynx.config.ts`.
  *
diff --git a/website/docs/guide/vue-compatibility.mdx b/website/docs/guide/vue-compatibility.mdx
index 9b615dfa3..2e860d62f 100644
--- a/website/docs/guide/vue-compatibility.mdx
+++ b/website/docs/guide/vue-compatibility.mdx
@@ -41,7 +41,7 @@ pluginVueLynx({
 })
 ```
 
-Requires **Lynx engine ≥ 3.8.1**, which ships the fix that propagates CSS custom properties from the component root to its descendants ([lynx-family/lynx#5912](https://github.com/lynx-family/lynx/pull/5912)). On earlier engines the variables are stamped on the root but never reach descendants.
+Requires **Lynx engine ≥ 3.9.0**, the first release whose tagged source contains the fix that propagates CSS custom properties from the component root to its descendants ([lynx-family/lynx#5912](https://github.com/lynx-family/lynx/pull/5912)). On earlier engines the variables are stamped on the root but never reach descendants.
 
 :::
 
diff --git a/website/docs/zh/guide/vue-compatibility.mdx b/website/docs/zh/guide/vue-compatibility.mdx
index 1e212dc6b..4308d470f 100644
--- a/website/docs/zh/guide/vue-compatibility.mdx
+++ b/website/docs/zh/guide/vue-compatibility.mdx
@@ -41,7 +41,7 @@ pluginVueLynx({
 })
 ```
 
-需要 **Lynx 引擎 ≥ 3.8.1**，该版本包含将 CSS 自定义属性从组件根元素传播到其后代的修复（[lynx-family/lynx#5912](https://github.com/lynx-family/lynx/pull/5912)）。在更早的引擎上，变量只会标记在根元素上，无法传递到后代。
+需要 **Lynx 引擎 ≥ 3.9.0**，这是首个在标记源码中包含将 CSS 自定义属性从组件根元素传播到其后代的修复（[lynx-family/lynx#5912](https://github.com/lynx-family/lynx/pull/5912)）的版本。在更早的引擎上，变量只会标记在根元素上，无法传递到后代。
 
 :::