feat: add flag to disable synthetic shadow (#4408)

packages/@lwc/engine-core/src/framework/vm.ts

@@ -511,6 +511,8 @@ function computeShadowMode(
         // on, but components running in actual native shadow mode
         (process.env.NODE_ENV === 'test-karma-lwc' &&
             process.env.FORCE_NATIVE_SHADOW_MODE_FOR_TEST) ||
+        // If synthetic shadow is explicitly disabled, use pure-native
+        lwcRuntimeFlags.DISABLE_SYNTHETIC_SHADOW ||
         // hydration only supports native shadow
         isTrue(hydrated)
     ) {

packages/@lwc/features/src/index.ts

@@ -19,6 +19,7 @@ const features: FeatureFlagMap = {
     ENABLE_LEGACY_SCOPE_TOKENS: null,
     ENABLE_FORCE_SHADOW_MIGRATE_MODE: null,
     ENABLE_EXPERIMENTAL_SIGNALS: null,
+    DISABLE_SYNTHETIC_SHADOW: null,
 };
 
 if (!(globalThis as any).lwcRuntimeFlags) {

packages/@lwc/features/src/types.ts

@@ -69,6 +69,12 @@ export interface FeatureFlagMap {
      * If true, allows the engine to expose reactivity to signals as describe in @lwc/signals.
      */
     ENABLE_EXPERIMENTAL_SIGNALS: FeatureFlagValue;
+
+    /**
+     * If true, ignore `@lwc/synthetic-shadow` even if it's loaded on the page. Instead, run all components in
+     * native shadow mode.
+     */
+    DISABLE_SYNTHETIC_SHADOW: FeatureFlagValue;
 }
 
 export type FeatureFlagName = keyof FeatureFlagMap;

packages/@lwc/integration-karma/test/synthetic-shadow/disable-synthetic-shadow/index.spec.js

@@ -0,0 +1,31 @@
+import { createElement, setFeatureFlagForTest } from 'lwc';
+import { IS_SYNTHETIC_SHADOW_LOADED, isSyntheticShadowRootInstance } from 'test-utils';
+import Component from 'x/component';
+
+if (IS_SYNTHETIC_SHADOW_LOADED && !process.env.FORCE_NATIVE_SHADOW_MODE_FOR_TEST) {
+    describe('DISABLE_SYNTHETIC_SHADOW', () => {
+        describe('flag disabled', () => {
+            it('renders synthetic shadow', () => {
+                const elm = createElement('x-component', { is: Component });
+                document.body.appendChild(elm);
+                expect(isSyntheticShadowRootInstance(elm.shadowRoot)).toBe(true);
+            });
+        });
+
+        describe('flag enabled', () => {
+            beforeEach(() => {
+                setFeatureFlagForTest('DISABLE_SYNTHETIC_SHADOW', true);
+            });
+
+            afterEach(() => {
+                setFeatureFlagForTest('DISABLE_SYNTHETIC_SHADOW', false);
+            });
+
+            it('renders native shadow', () => {
+                const elm = createElement('x-component', { is: Component });
+                document.body.appendChild(elm);
+                expect(isSyntheticShadowRootInstance(elm.shadowRoot)).toBe(false);
+            });
+        });
+    });
+}

packages/@lwc/integration-karma/test/synthetic-shadow/disable-synthetic-shadow/x/component/component.js

@@ -0,0 +1,3 @@
+import { LightningElement } from 'lwc';
+
+export default class extends LightningElement {}

scripts/rollup/rollup.config.js

@@ -27,16 +27,16 @@ const { ROLLUP_WATCH: watchMode } = process.env;
 const formats = ['es', 'cjs'];
 
 if (packageName === '@lwc/synthetic-shadow') {
-    // Here we wrap all of synthetic shadow in a check for lwcRuntimeFlags.ENABLE_FORCE_SHADOW_MIGRATE_MODE, so
-    // that synthetic shadow is not loaded at all if the flag is in effect.
+    // Here we wrap all of synthetic shadow in a check for lwcRuntimeFlags.ENABLE_FORCE_SHADOW_MIGRATE_MODE and
+    // lwcRuntimeFlags.DISABLE_SYNTHETIC_SHADOW, so that synthetic shadow is not loaded if either flag is set.
     // Note that lwcRuntimeFlags must be referenced as a pure global, or else string replacement in ESBuild
     // will not work. But we also have to check to make sure that lwcRuntimeFlags is defined, so this
     // `Object.defineProperty` code is copied from @lwc/features itself.
     banner += `
     if (!globalThis.lwcRuntimeFlags) {
       Object.defineProperty(globalThis, 'lwcRuntimeFlags', { value: Object.create(null) });
     }
-    if (!lwcRuntimeFlags.ENABLE_FORCE_SHADOW_MIGRATE_MODE) {
+    if (!lwcRuntimeFlags.ENABLE_FORCE_SHADOW_MIGRATE_MODE && !lwcRuntimeFlags.DISABLE_SYNTHETIC_SHADOW) {
     `
         .replaceAll(/\n {4}/g, '\n')
         .trimEnd();