feat: add flag to disable synthetic shadow

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();