salesforce · jmsjtu · Sep 6, 2025 · Sep 6, 2025 · Sep 6, 2025 · Sep 6, 2025
@@ -58,7 +58,9 @@ jobs:
             - run: LEGACY_BROWSERS=1 yarn sauce:ci
             - run: FORCE_NATIVE_SHADOW_MODE_FOR_TEST=1 yarn sauce:ci
             - run: DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE=1 yarn sauce:ci
+            - run: DISABLE_DETACHED_REHYDRATION=1 yarn sauce:ci
             - run: DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE=1 DISABLE_SYNTHETIC=1 yarn sauce:ci
+            - run: DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE=1 DISABLE_DETACHED_REHYDRATION=1 yarn sauce:ci
 
             - name: Upload coverage results
               uses: actions/upload-artifact@v4
@@ -187,6 +189,8 @@ jobs:
             - run: NODE_ENV_FOR_TEST=production yarn hydration:sauce:ci:engine-server
             - run: DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE=1 yarn hydration:sauce:ci:engine-server
             - run: DISABLE_STATIC_CONTENT_OPTIMIZATION=1 yarn hydration:sauce:ci:engine-server
+            - run: DISABLE_DETACHED_REHYDRATION=1 yarn hydration:sauce:ci:engine-server
+            - run: DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE=1 DISABLE_DETACHED_REHYDRATION=1 yarn hydration:sauce:ci:engine-server
             - run: yarn hydration:sauce:ci
             - run: ENABLE_SYNTHETIC_SHADOW_IN_HYDRATION=1 yarn hydration:sauce:ci
             - run: NODE_ENV_FOR_TEST=production yarn hydration:sauce:ci

@@ -673,7 +673,14 @@ function flushRehydrationQueue() {
     for (let i = 0, len = vms.length; i < len; i += 1) {
         const vm = vms[i];
         try {
-            rehydrate(vm);
+            // We want to prevent rehydration from occurring when nodes are detached from the DOM as this can trigger
+            // unintended side effects, like lifecycle methods being called multiple times.
+            // For backwards compatibility, we use a flag to control the check.
+            // 1. When flag is disabled always rehydrate (legacy behavior)
+            // 2. When flag is enabled only rehydrate when the VM state is connected (fixed behavior)
+            if (!lwcRuntimeFlags.DISABLE_DETACHED_REHYDRATION || vm.state === VMState.connected) {
+                rehydrate(vm);
+            }
         } catch (error) {
             if (i + 1 < len) {
                 // pieces of the queue are still pending to be rehydrated, those should have priority

@@ -23,6 +23,7 @@ const features: FeatureFlagMap = {
     DISABLE_SCOPE_TOKEN_VALIDATION: null,
     LEGACY_LOCKER_ENABLED: null,
     DISABLE_LEGACY_VALIDATION: null,
+    DISABLE_DETACHED_REHYDRATION: null,
 };
 
 if (!(globalThis as any).lwcRuntimeFlags) {

@@ -93,6 +93,12 @@ export interface FeatureFlagMap {
      * If false or unset, then the value of the `LEGACY_LOCKER_ENABLED` flag is used.
      */
     DISABLE_LEGACY_VALIDATION: FeatureFlagValue;
+
+    /**
+     * If true, skips rehydration of DOM elements that are not connected.
+     * Applies to rehydration performed while flushing the rehydration queue.
+     */
+    DISABLE_DETACHED_REHYDRATION: FeatureFlagValue;
 }
 
 export type FeatureFlagName = keyof FeatureFlagMap;
@@ -18,6 +18,7 @@ const env = {
         'ENGINE_SERVER',
         'FORCE_NATIVE_SHADOW_MODE_FOR_TEST',
         'NATIVE_SHADOW',
+        'DISABLE_DETACHED_REHYDRATION',
     ]),
     LWC_VERSION,
     NODE_ENV: options.NODE_ENV_FOR_TEST,
@@ -61,7 +62,10 @@ export default {
             <script type="module">
             globalThis.process = ${JSON.stringify({ env })};
             globalThis.lwcRuntimeFlags = ${JSON.stringify(
-                pluck(options, ['DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE'])
+                pluck(options, [
+                    'DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE',
+                    'DISABLE_DETACHED_REHYDRATION',
+                ])
             )};
 
             ${maybeImport('@lwc/synthetic-shadow', !options.DISABLE_SYNTHETIC)}

@@ -34,6 +34,8 @@ export const DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE = Boolean(
     process.env.DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE
 );
 
+export const DISABLE_DETACHED_REHYDRATION = Boolean(process.env.DISABLE_DETACHED_REHYDRATION);
+
 export const ENGINE_SERVER = Boolean(process.env.ENGINE_SERVER);
 
 // --- Test config --- //
@@ -62,6 +64,7 @@ export const COVERAGE_DIR_FOR_OPTIONS =
         NODE_ENV_FOR_TEST,
         DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE,
         ENGINE_SERVER,
+        DISABLE_DETACHED_REHYDRATION,
     })
         .filter(([, val]) => val)
         .map(([key, val]) => `${key}=${val}`)

@@ -11,6 +11,10 @@ import TimingParentLight from 'timing/parentLight';
 import ReorderingList from 'reordering/list';
 import ReorderingListLight from 'reordering/listLight';
 import Details from 'x/details';
+import MutationsParent from 'mutations/parent';
+import MutationsParentLight from 'mutations/parentLight';
+
+import { extractDataIds } from 'test-utils';
 
 function resetTimingBuffer() {
     window.timingBuffer = [];
@@ -319,11 +323,18 @@ describe('connectedCallback/renderedCallback timing when reconnected', () => {
                 resetTimingBuffer();
 
                 document.body.appendChild(elm);
-                expect(window.timingBuffer).toEqual(
-                    !lwcRuntimeFlags.DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE
-                        ? ['parent:connectedCallback', 'child:connectedCallback']
-                        : ['parent:connectedCallback']
-                );
+
+                const expected = ['parent:connectedCallback'];
+
+                if (lwcRuntimeFlags.DISABLE_DETACHED_REHYDRATION) {
+                    expected.push('parent:renderedCallback');
+                }
+
+                if (!lwcRuntimeFlags.DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE) {
+                    expected.push('child:connectedCallback');
+                }
+
+                expect(window.timingBuffer).toEqual(expected);
             });
         });
     });
@@ -436,3 +447,118 @@ describe('attributeChangedCallback', () => {
         expect(details.getAttribute('open')).toBeNull();
     });
 });
+
+describe('child mutations - scheduled rehydration', () => {
+    const scenarios = [
+        {
+            testName: 'shadow',
+            tagName: 'mutations-parent',
+            Ctor: MutationsParent,
+        },
+        {
+            testName: 'light',
+            tagName: 'mutations-parent-light',
+            Ctor: MutationsParentLight,
+        },
+    ];
+
+    scenarios.forEach(({ testName, tagName, Ctor }) => {
+        describe(testName, () => {
+            it('connect', async () => {
+                const elm = createElement(tagName, { is: Ctor });
+                document.body.appendChild(elm);
+
+                expect(window.timingBuffer).toEqual([
+                    'parent:connectedCallback',
+                    'child1:connectedCallback',
+                    'grand:child1:connectedCallback',
+                    'grand:child1:renderedCallback',
+                    'child1:renderedCallback',
+                    'parent:renderedCallback',
+                ]);
+            });
+
+            it('connect/mutate-child', async () => {
+                const elm = createElement(tagName, { is: Ctor });
+                document.body.appendChild(elm);
+                resetTimingBuffer();
+
+                const ids = extractDataIds(elm);
+                ids.child1.addChild();
+
+                await Promise.resolve();
+
+                expect(window.timingBuffer).toEqual([
+                    'grand:child2:connectedCallback',
+                    'grand:child2:renderedCallback',
+                    'child1:renderedCallback',
+                ]);
+            });
+
+            it('connect/mutate-child/disconnect-child', async () => {
+                const elm = createElement(tagName, { is: Ctor });
+                document.body.appendChild(elm);
+                resetTimingBuffer();
+
+                const ids = extractDataIds(elm);
+                // Mutate child - grand child 2
+                ids.child1.addChild();
+                // Disconnect the child that was just mutated
+                elm.disconnectLastChild();
+
+                await Promise.resolve();
+
+                const expected = [
+                    'child1:disconnectedCallback',
+                    'grand:child1:disconnectedCallback',
+                    'parent:renderedCallback',
+                ];
+
+                if (
+                    lwcRuntimeFlags.DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE &&
+                    !lwcRuntimeFlags.DISABLE_DETACHED_REHYDRATION
+                ) {
+                    // These are fired in the children of the disconnected child
+                    expected.push(
+                        'grand:child2:connectedCallback',
+                        'grand:child2:renderedCallback'
+                    );
+                }
+
+                expect(window.timingBuffer).toEqual(expected);
+            });
+
+            it('connect/disconnect-child/mutate-child', async () => {
+                const elm = createElement(tagName, { is: Ctor });
+                document.body.appendChild(elm);
+                resetTimingBuffer();
+
+                const ids = extractDataIds(elm);
+                elm.disconnectLastChild();
+                // Mutate child that was just disconnected
+                ids.child1.addChild();
+
+                await Promise.resolve();
+
+                const expected = [
+                    'child1:disconnectedCallback',
+                    'grand:child1:disconnectedCallback',
+                    'parent:renderedCallback',
+                ];
+
+                if (
+                    lwcRuntimeFlags.DISABLE_NATIVE_CUSTOM_ELEMENT_LIFECYCLE &&
+                    !lwcRuntimeFlags.DISABLE_DETACHED_REHYDRATION
+                ) {
+                    // These are fired in the children of the disconnected child
+                    expected.push(
+                        'grand:child2:connectedCallback',
+                        'grand:child2:renderedCallback'
+                    );
+                }
+
+                expect(window.timingBuffer).toEqual(expected);
+            });
+        });
+    });
+});
@@ -0,0 +1,5 @@
+<template>
+    <template for:each={children} for:item="child">
+        <mutations-grand-child key={child.uid} uid={child.uid}></mutations-grand-child>
+    </template>
+</template>
@@ -0,0 +1,23 @@
+import { LightningElement, api } from 'lwc';
+
+export default class extends LightningElement {
+    @api uid;
+    @api children = [{ uid: '1' }];
+    connectedCallback() {
+        window.timingBuffer.push(`child${this.uid}:connectedCallback`);
+    }
+    renderedCallback() {
+        window.timingBuffer.push(`child${this.uid}:renderedCallback`);
+    }
+    disconnectedCallback() {
+        // This component could get disconnected by our Karma `test-setup.js` after `window.timingBuffer` has
+        // already been cleared; we don't care about the `disconnectedCallback`s in that case.
+        if (window.timingBuffer) {
+            window.timingBuffer.push(`child${this.uid}:disconnectedCallback`);
+        }
+    }
+    @api
+    addChild() {
+        this.children = [...this.children, { uid: `${this.children.length + 1}` }];
+    }
+}
@@ -0,0 +1,5 @@
+<template lwc:render-mode="light">
+    <template for:each={children} for:item="child">
+        <mutations-grand-child key={child.uid} uid={child.uid}></mutations-grand-child>
+    </template>
+</template>
@@ -0,0 +1,24 @@
+import { LightningElement, api } from 'lwc';
+
+export default class extends LightningElement {
+    static renderMode = 'light';
+    @api uid;
+    @api children = [{ uid: '1' }];
+    connectedCallback() {
+        window.timingBuffer.push(`child${this.uid}:connectedCallback`);
+    }
+    renderedCallback() {
+        window.timingBuffer.push(`child${this.uid}:renderedCallback`);
+    }
+    disconnectedCallback() {
+        // This component could get disconnected by our Karma `test-setup.js` after `window.timingBuffer` has
+        // already been cleared; we don't care about the `disconnectedCallback`s in that case.
+        if (window.timingBuffer) {
+            window.timingBuffer.push(`child${this.uid}:disconnectedCallback`);
+        }
+    }
+    @api
+    addChild() {
+        this.children = [...this.children, { uid: `${this.children.length + 1}` }];
+    }
+}
@@ -0,0 +1 @@
+<template></template>
@@ -0,0 +1,18 @@
+import { LightningElement, api } from 'lwc';
+
+export default class extends LightningElement {
+    @api uid;
+    connectedCallback() {
+        window.timingBuffer.push(`grand:child${this.uid}:connectedCallback`);
+    }
+    renderedCallback() {
+        window.timingBuffer.push(`grand:child${this.uid}:renderedCallback`);
+    }
+    disconnectedCallback() {
+        // This component could get disconnected by our Karma `test-setup.js` after `window.timingBuffer` has
+        // already been cleared; we don't care about the `disconnectedCallback`s in that case.
+        if (window.timingBuffer) {
+            window.timingBuffer.push(`grand:child${this.uid}:disconnectedCallback`);
+        }
+    }
+}
@@ -0,0 +1 @@
+<template lwc:render-mode="light"></template>
@@ -0,0 +1,19 @@
+import { LightningElement, api } from 'lwc';
+
+export default class extends LightningElement {
+    static renderMode = 'light';
+    @api uid;
+    connectedCallback() {
+        window.timingBuffer.push(`grand:child${this.uid}:connectedCallback`);
+    }
+    renderedCallback() {
+        window.timingBuffer.push(`grand:child${this.uid}:renderedCallback`);
+    }
+    disconnectedCallback() {
+        // This component could get disconnected by our Karma `test-setup.js` after `window.timingBuffer` has
+        // already been cleared; we don't care about the `disconnectedCallback`s in that case.
+        if (window.timingBuffer) {
+            window.timingBuffer.push(`grand:child${this.uid}:disconnectedCallback`);
+        }
+    }
+}
@@ -0,0 +1,5 @@
+<template>
+    <template for:each={children} for:item="child">
+        <mutations-child key={child.uid} uid={child.uid} data-id={child.name}></mutations-child>
+    </template>
+</template>
@@ -0,0 +1,27 @@
+import { api, LightningElement } from 'lwc';
+
+export default class extends LightningElement {
+    @api children = [{ uid: '1', name: 'child1' }];
+    connectedCallback() {
+        window.timingBuffer.push('parent:connectedCallback');
+    }
+    renderedCallback() {
+        window.timingBuffer.push('parent:renderedCallback');
+    }
+    disconnectedCallback() {
+        // This component could get disconnected by our Karma `test-setup.js` after `window.timingBuffer` has
+        // already been cleared; we don't care about the `disconnectedCallback`s in that case.
+        if (window.timingBuffer) {
+            window.timingBuffer.push('parent:disconnectedCallback');
+        }
+    }
+    @api
+    addChild() {
+        const uid = this.children.length + 1;
+        this.children = [...this.children, { uid, name: `child${uid}` }];
+    }
+    @api
+    disconnectLastChild() {
+        this.children = this.children.slice(0, this.children.length - 1);
+    }
+}
@@ -0,0 +1,5 @@
+<template lwc:render-mode="light">
+    <template for:each={children} for:item="child">
+        <mutations-child key={child.uid} uid={child.uid} data-id={child.name}></mutations-child>
+    </template>
+</template>