@lynx-js/react 0.121.0 → 0.121.1

package/runtime/lib/element-template/background/attr-slots.js

@@ -1,7 +1,8 @@
 // Copyright 2026 The Lynx Authors. 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 { __etAttrPlanMap } from '../runtime/template/attr-slot-plan.js';
+import { getSpreadRefFromValue, queueRefAttrUpdate } from '../prop-adapters/ref.js';
+import { __etAttrPlanMap, adaptRefAttrSlot, adaptSpreadAttrSlot } from '../runtime/template/attr-slot-plan.js';
 function normalizeAttributeSlots(rawSlots) {
     let normalizedSlots;
     for (let slotIndex = 0; slotIndex < rawSlots.length; slotIndex += 1) {
@@ -14,7 +15,25 @@ function normalizeAttributeSlots(rawSlots) {
     }
     return normalizedSlots ?? rawSlots;
 }
-export function prepareAttributeSlots(templateKey, handleId, rawSlots) {
+function queuePlannedRefAttributeSlotUpdates(handleId, attrPlan, previousRawSlots, nextRawSlots) {
+    for (let planIndex = 0; planIndex < attrPlan.length; planIndex += 2) {
+        const attrSlotIndex = attrPlan[planIndex];
+        const adapter = attrPlan[planIndex + 1];
+        if (adapter === adaptRefAttrSlot) {
+            queueRefAttrUpdate(previousRawSlots?.[attrSlotIndex], nextRawSlots?.[attrSlotIndex], handleId, attrSlotIndex);
+            continue;
+        }
+        if (adapter === adaptSpreadAttrSlot) {
+            const previousSpreadRef = getSpreadRefFromValue(previousRawSlots?.[attrSlotIndex]);
+            const nextSpreadRef = getSpreadRefFromValue(nextRawSlots?.[attrSlotIndex]);
+            if (previousSpreadRef === undefined && nextSpreadRef === undefined) {
+                continue;
+            }
+            queueRefAttrUpdate(previousSpreadRef, nextSpreadRef ?? null, handleId, attrSlotIndex);
+        }
+    }
+}
+export function prepareAttributeSlots(templateKey, handleId, rawSlots, options) {
     const attrPlan = __etAttrPlanMap[templateKey];
     if (!attrPlan || attrPlan.length === 0) {
         return normalizeAttributeSlots(rawSlots);
@@ -23,12 +42,26 @@ export function prepareAttributeSlots(templateKey, handleId, rawSlots) {
     const preparedSlots = normalizedSlots === rawSlots
         ? rawSlots.slice()
         : normalizedSlots;
+    const shouldQueueRefEffects = options?.queueRefEffects === true;
+    const previousRawSlots = options?.previousRawSlots;
     for (let planIndex = 0; planIndex < attrPlan.length; planIndex += 2) {
         const attrSlotIndex = attrPlan[planIndex];
         const adapter = attrPlan[planIndex + 1];
         const rawValue = rawSlots[attrSlotIndex];
         preparedSlots[attrSlotIndex] = adapter(handleId, attrSlotIndex, rawValue);
     }
+    if (shouldQueueRefEffects) {
+        // Ref effects compare raw user refs, not prepared marker strings or the
+        // spread wrapper object.
+        queuePlannedRefAttributeSlotUpdates(handleId, attrPlan, previousRawSlots, rawSlots);
+    }
     return preparedSlots;
 }
+export function queueRefAttributeSlotUpdates(templateKey, handleId, previousRawSlots, nextRawSlots) {
+    const attrPlan = __etAttrPlanMap[templateKey];
+    if (!attrPlan || attrPlan.length === 0) {
+        return;
+    }
+    queuePlannedRefAttributeSlotUpdates(handleId, attrPlan, previousRawSlots, nextRawSlots);
+}
 //# sourceMappingURL=attr-slots.js.map

package/runtime/lib/element-template/background/attr-slots.js.map

@@ -1 +1 @@
-{"version":3,"file":"attr-slots.js","sourceRoot":"","sources":["../../../src/element-template/background/attr-slots.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,yEAAyE;AACzE,0DAA0D;AAG1D,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAGxE,SAAS,uBAAuB,CAAC,QAA4B;IAC3D,IAAI,eAAgD,CAAC;IACrD,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC,MAAM,EAAE,SAAS,IAAI,CAAC,EAAE,CAAC;QACpE,MAAM,OAAO,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;QACpC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,SAAS;QACX,CAAC;QACD,eAAe,KAAK,QAAQ,CAAC,KAAK,EAAyB,CAAC;QAC5D,eAAe,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;IACpC,CAAC;IACD,OAAO,eAAe,IAAI,QAA+B,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,WAAmB,EACnB,QAAgB,EAChB,QAA4B;IAE5B,MAAM,QAAQ,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;IAC9C,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvC,OAAO,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED,MAAM,eAAe,GAAG,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAC1D,MAAM,aAAa,GAAG,eAAe,KAAK,QAAQ;QAChD,CAAC,CAAC,QAAQ,CAAC,KAAK,EAAyB;QACzC,CAAC,CAAC,eAAe,CAAC;IACpB,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC,MAAM,EAAE,SAAS,IAAI,CAAC,EAAE,CAAC;QACpE,MAAM,aAAa,GAAG,QAAQ,CAAC,SAAS,CAAW,CAAC;QACpD,MAAM,OAAO,GAAG,QAAQ,CAAC,SAAS,GAAG,CAAC,CAAkB,CAAC;QACzD,MAAM,QAAQ,GAAG,QAAQ,CAAC,aAAa,CAAC,CAAC;QACzC,aAAa,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO,aAAa,CAAC;AACvB,CAAC"}
+{"version":3,"file":"attr-slots.js","sourceRoot":"","sources":["../../../src/element-template/background/attr-slots.ts"],"names":[],"mappings":"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"}

package/runtime/lib/element-template/background/commit-context.d.ts

@@ -1,13 +1,13 @@
 import type { BackgroundElementTemplateInstance } from './instance.js';
 import type { ElementTemplateUpdateCommitContext } from '../protocol/types.js';
 interface ElementTemplateCommitNonPayloadState {
-    removedSubtrees: BackgroundElementTemplateInstance[];
+    removedSubtreesAwaitingTeardown: BackgroundElementTemplateInstance[];
 }
 type ElementTemplateGlobalCommitContext = ElementTemplateUpdateCommitContext & {
     nonPayload: ElementTemplateCommitNonPayloadState;
 };
 export declare const globalCommitContext: ElementTemplateGlobalCommitContext;
 export declare function resetGlobalCommitContext(): void;
-export declare function markRemovedSubtreeForCurrentCommit(root: BackgroundElementTemplateInstance): void;
-export declare function takeRemovedSubtreesForCurrentCommit(): BackgroundElementTemplateInstance[];
+export declare function markRemovedSubtreeForPostDispatchTeardown(root: BackgroundElementTemplateInstance): void;
+export declare function takeRemovedSubtreesForPostDispatchTeardown(): BackgroundElementTemplateInstance[];
 export {};

package/runtime/lib/element-template/background/commit-context.js

@@ -1,25 +1,22 @@
-export const globalCommitContext = {
-    ops: [],
-    flushOptions: {},
-    nonPayload: {
-        removedSubtrees: [],
-    },
+import { globalCommitContext as coreGlobalCommitContext, resetGlobalCommitContext as resetCoreGlobalCommitContext, } from '../../core/commit-context.js';
+const nonPayload = {
+    removedSubtreesAwaitingTeardown: [],
 };
+export const globalCommitContext = coreGlobalCommitContext;
+globalCommitContext.nonPayload = nonPayload;
 export function resetGlobalCommitContext() {
-    globalCommitContext.ops = [];
-    globalCommitContext.flushOptions = {};
-    delete globalCommitContext.flowIds;
-    globalCommitContext.nonPayload.removedSubtrees = [];
+    resetCoreGlobalCommitContext();
+    nonPayload.removedSubtreesAwaitingTeardown = [];
 }
-export function markRemovedSubtreeForCurrentCommit(root) {
-    const { removedSubtrees } = globalCommitContext.nonPayload;
-    if (!removedSubtrees.includes(root)) {
-        removedSubtrees.push(root);
+export function markRemovedSubtreeForPostDispatchTeardown(root) {
+    const { removedSubtreesAwaitingTeardown } = globalCommitContext.nonPayload;
+    if (!removedSubtreesAwaitingTeardown.includes(root)) {
+        removedSubtreesAwaitingTeardown.push(root);
     }
 }
-export function takeRemovedSubtreesForCurrentCommit() {
-    const removedSubtrees = globalCommitContext.nonPayload.removedSubtrees;
-    globalCommitContext.nonPayload.removedSubtrees = [];
-    return removedSubtrees;
+export function takeRemovedSubtreesForPostDispatchTeardown() {
+    const removedSubtreesAwaitingTeardown = globalCommitContext.nonPayload.removedSubtreesAwaitingTeardown;
+    globalCommitContext.nonPayload.removedSubtreesAwaitingTeardown = [];
+    return removedSubtreesAwaitingTeardown;
 }
 //# sourceMappingURL=commit-context.js.map

package/runtime/lib/element-template/background/commit-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"commit-context.js","sourceRoot":"","sources":["../../../src/element-template/background/commit-context.ts"],"names":[],"mappings":"AAgBA,MAAM,CAAC,MAAM,mBAAmB,GAAuC;IACrE,GAAG,EAAE,EAAE;IACP,YAAY,EAAE,EAAE;IAChB,UAAU,EAAE;QACV,eAAe,EAAE,EAAE;KACpB;CACF,CAAC;AAEF,MAAM,UAAU,wBAAwB;IACtC,mBAAmB,CAAC,GAAG,GAAG,EAAE,CAAC;IAC7B,mBAAmB,CAAC,YAAY,GAAG,EAAE,CAAC;IACtC,OAAO,mBAAmB,CAAC,OAAO,CAAC;IACnC,mBAAmB,CAAC,UAAU,CAAC,eAAe,GAAG,EAAE,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,kCAAkC,CAChD,IAAuC;IAEvC,MAAM,EAAE,eAAe,EAAE,GAAG,mBAAmB,CAAC,UAAU,CAAC;IAC3D,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,mCAAmC;IACjD,MAAM,eAAe,GAAG,mBAAmB,CAAC,UAAU,CAAC,eAAe,CAAC;IACvE,mBAAmB,CAAC,UAAU,CAAC,eAAe,GAAG,EAAE,CAAC;IACpD,OAAO,eAAe,CAAC;AACzB,CAAC"}
+{"version":3,"file":"commit-context.js","sourceRoot":"","sources":["../../../src/element-template/background/commit-context.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,mBAAmB,IAAI,uBAAuB,EAC9C,wBAAwB,IAAI,4BAA4B,GACzD,MAAM,8BAA8B,CAAC;AActC,MAAM,UAAU,GAAyC;IACvD,+BAA+B,EAAE,EAAE;CACpC,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,uBAAwE,CAAC;AAE5G,mBAAmB,CAAC,UAAU,GAAG,UAAU,CAAC;AAE5C,MAAM,UAAU,wBAAwB;IACtC,4BAA4B,EAAE,CAAC;IAC/B,UAAU,CAAC,+BAA+B,GAAG,EAAE,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,yCAAyC,CACvD,IAAuC;IAEvC,MAAM,EAAE,+BAA+B,EAAE,GAAG,mBAAmB,CAAC,UAAU,CAAC;IAC3E,IAAI,CAAC,+BAA+B,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACpD,+BAA+B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC;AAED,MAAM,UAAU,0CAA0C;IACxD,MAAM,+BAA+B,GAAG,mBAAmB,CAAC,UAAU,CAAC,+BAA+B,CAAC;IACvG,mBAAmB,CAAC,UAAU,CAAC,+BAA+B,GAAG,EAAE,CAAC;IACpE,OAAO,+BAA+B,CAAC;AACzC,CAAC"}

package/runtime/lib/element-template/background/commit-hook.d.ts

@@ -2,6 +2,6 @@ import type { BackgroundElementTemplateInstance } from './instance.js';
 export declare function markElementTemplateHydrated(): void;
 export declare function isElementTemplateHydrated(): boolean;
 export declare function resetElementTemplateCommitState(): void;
-export declare function scheduleElementTemplateRemovedSubtreeCleanup(removedSubtrees: BackgroundElementTemplateInstance[]): void;
+export declare function scheduleElementTemplateRemovedSubtreeCleanup(removedSubtreesAwaitingTeardown: BackgroundElementTemplateInstance[]): void;
 export declare function cancelElementTemplateRemovedSubtreeCleanup(): void;
 export declare function installElementTemplateCommitHook(): void;

package/runtime/lib/element-template/background/commit-hook.js

@@ -2,16 +2,18 @@
 // 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 { options } from 'preact';
-import { globalCommitContext, resetGlobalCommitContext, takeRemovedSubtreesForCurrentCommit, } from './commit-context.js';
+import { globalCommitContext, resetGlobalCommitContext, takeRemovedSubtreesForPostDispatchTeardown, } from './commit-context.js';
+import { getReloadVersion } from '../../core/reload-version.js';
 import { COMMIT } from '../../shared/render-constants.js';
-import { hook } from '../../utils.js';
+import { hook, isEmptyObject } from '../../utils.js';
 import { formatElementTemplateUpdateCommands } from '../debug/alog.js';
 import { profileEnd, profileStart } from '../debug/profile.js';
 import { globalPipelineOptions, markTiming, markTimingLegacy, setPipeline } from '../lynx/performance.js';
+import { clearPendingRefs, flushPendingRefs, hasPendingRefs } from '../prop-adapters/ref.js';
 import { ElementTemplateLifecycleConstant } from '../protocol/lifecycle-constant.js';
 let installed = false;
 let hasHydrated = false;
-const scheduledRemovedSubtreeCleanupTimers = new Set();
+const scheduledRemovedSubtreeCleanupTimers = /*#__PURE__*/ new Set();
 export function markElementTemplateHydrated() {
     hasHydrated = true;
 }
@@ -22,13 +24,13 @@ export function resetElementTemplateCommitState() {
     hasHydrated = false;
     resetGlobalCommitContext();
 }
-export function scheduleElementTemplateRemovedSubtreeCleanup(removedSubtrees) {
-    if (removedSubtrees.length === 0) {
+export function scheduleElementTemplateRemovedSubtreeCleanup(removedSubtreesAwaitingTeardown) {
+    if (removedSubtreesAwaitingTeardown.length === 0) {
         return;
     }
     const timer = setTimeout(() => {
         scheduledRemovedSubtreeCleanupTimers.delete(timer);
-        for (const root of removedSubtrees) {
+        for (const root of removedSubtreesAwaitingTeardown) {
             root.tearDown();
         }
     }, 10000);
@@ -46,48 +48,71 @@ export function installElementTemplateCommitHook() {
     }
     installed = true;
     hook(options, COMMIT, (originalCommit, vnode, commitQueue) => {
-        if (__BACKGROUND__ && hasHydrated && globalCommitContext.ops.length > 0) {
-            markTimingLegacy('updateDiffVdomEnd');
-            markTiming('diffVdomEnd');
-            if (__PROFILE__) {
-                profileStart('ReactLynx::commitChanges');
-            }
-            markTiming('packChangesStart');
-            if (globalPipelineOptions) {
-                globalCommitContext.flushOptions.pipelineOptions = globalPipelineOptions;
-            }
-            markTiming('packChangesEnd');
-            if (globalPipelineOptions) {
-                setPipeline(undefined);
-            }
-            if (__PROFILE__) {
-                profileEnd();
-            }
-            if (typeof __ALOG__ !== 'undefined' && __ALOG__) {
-                console.alog?.('[ReactLynxDebug] ElementTemplate BTS -> MTS update:\n'
-                    + JSON.stringify({
-                        ops: formatElementTemplateUpdateCommands(globalCommitContext.ops),
-                        flushOptions: globalCommitContext.flushOptions,
-                        flowIds: globalCommitContext.flowIds,
-                    }, null, 2));
-            }
-            const removedSubtrees = takeRemovedSubtreesForCurrentCommit();
+        if (__BACKGROUND__ && !hasHydrated && hasPendingRefs()) {
+            // User effects can run before ET hydrate arrives, so ordinary refs must be
+            // attached on the background commit even though native UI ops are delayed.
+            flushPendingRefs();
+        }
+        else if (__BACKGROUND__ && hasHydrated
+            && (globalCommitContext.ops.length > 0
+                || !isEmptyObject(globalCommitContext.flushOptions)
+                || hasPendingRefs())) {
+            const hasNativeOps = globalCommitContext.ops.length > 0;
+            const hasUpdatePayload = hasNativeOps || !isEmptyObject(globalCommitContext.flushOptions);
+            const removedSubtreesAwaitingTeardown = hasNativeOps ? takeRemovedSubtreesForPostDispatchTeardown() : [];
+            let didFlushRefs = false;
             try {
-                lynx.getCoreContext().dispatchEvent({
-                    type: ElementTemplateLifecycleConstant.update,
-                    data: {
-                        ops: globalCommitContext.ops,
-                        flushOptions: globalCommitContext.flushOptions,
-                        flowIds: globalCommitContext.flowIds,
-                    },
-                });
+                if (hasUpdatePayload) {
+                    markTimingLegacy('updateDiffVdomEnd');
+                    markTiming('diffVdomEnd');
+                    if (__PROFILE__) {
+                        profileStart('ReactLynx::commitChanges');
+                    }
+                    markTiming('packChangesStart');
+                    if (globalPipelineOptions) {
+                        globalCommitContext.flushOptions.pipelineOptions = globalPipelineOptions;
+                    }
+                    markTiming('packChangesEnd');
+                    if (globalPipelineOptions) {
+                        setPipeline(undefined);
+                    }
+                    if (__PROFILE__) {
+                        profileEnd();
+                    }
+                    if (typeof __ALOG__ !== 'undefined' && __ALOG__) {
+                        console.alog?.('[ReactLynxDebug] ElementTemplate BTS -> MTS update:\n'
+                            + JSON.stringify({
+                                ops: formatElementTemplateUpdateCommands(globalCommitContext.ops),
+                                flushOptions: globalCommitContext.flushOptions,
+                                flowIds: globalCommitContext.flowIds,
+                            }, null, 2));
+                    }
+                }
+                if (hasUpdatePayload) {
+                    lynx.getCoreContext().dispatchEvent({
+                        type: ElementTemplateLifecycleConstant.update,
+                        data: {
+                            ops: globalCommitContext.ops,
+                            flushOptions: globalCommitContext.flushOptions,
+                            flowIds: globalCommitContext.flowIds,
+                            reloadVersion: getReloadVersion(),
+                        },
+                    });
+                }
+                // When native ops exist, patch first so a newly attached ref observes the
+                // committed native state. Ref-only commits still flush through this path.
+                flushPendingRefs();
+                didFlushRefs = true;
             }
             finally {
+                if (!didFlushRefs) {
+                    clearPendingRefs();
+                }
                 resetGlobalCommitContext();
                 // Match Snapshot's cleanup boundary: start the delayed teardown only
                 // after the bridge dispatch attempt, so background JS objects are not
                 // torn down before main-thread detach observes the same commit.
-                scheduleElementTemplateRemovedSubtreeCleanup(removedSubtrees);
+                scheduleElementTemplateRemovedSubtreeCleanup(removedSubtreesAwaitingTeardown);
             }
         }
         originalCommit?.(vnode, commitQueue);

package/runtime/lib/element-template/background/commit-hook.js.map

@@ -1 +1 @@
-{"version":3,"file":"commit-hook.js","sourceRoot":"","sources":["../../../src/element-template/background/commit-hook.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"commit-hook.js","sourceRoot":"","sources":["../../../src/element-template/background/commit-hook.ts"],"names":[],"mappings":"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"}

package/runtime/lib/element-template/background/destroy.js

@@ -1,17 +1,20 @@
-// Copyright 2026 The Lynx Authors. 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 { render } from 'preact';
 import { cancelElementTemplateRemovedSubtreeCleanup, resetElementTemplateCommitState } from './commit-hook.js';
 import { resetElementTemplateHydrationListener } from './hydration-listener.js';
 import { backgroundElementTemplateInstanceManager } from './manager.js';
 import { clearEventState } from '../prop-adapters/event.js';
+import { clearRefState, flushPendingRefs } from '../prop-adapters/ref.js';
+import { __root } from '../runtime/page/root-instance.js';
 export function destroyElementTemplateBackgroundRuntime() {
     resetElementTemplateHydrationListener();
-    resetElementTemplateCommitState();
-    // Destroy is the only place that may discard delayed removed subtrees instead
-    // of letting the Snapshot-aligned timer tear them down later.
     cancelElementTemplateRemovedSubtreeCleanup();
+    render(null, __root);
+    // Run user cleanup before dropping the backend side tables; after clearRefState
+    // the raw ref ownership needed to detach callbacks is gone.
+    flushPendingRefs();
+    resetElementTemplateCommitState();
     clearEventState();
+    clearRefState();
     backgroundElementTemplateInstanceManager.clear();
 }
 //# sourceMappingURL=destroy.js.map

package/runtime/lib/element-template/background/destroy.js.map

@@ -1 +1 @@
-{"version":3,"file":"destroy.js","sourceRoot":"","sources":["../../../src/element-template/background/destroy.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,yEAAyE;AACzE,0DAA0D;AAE1D,OAAO,EAAE,0CAA0C,EAAE,+BAA+B,EAAE,MAAM,kBAAkB,CAAC;AAC/G,OAAO,EAAE,qCAAqC,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,EAAE,wCAAwC,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D,MAAM,UAAU,uCAAuC;IACrD,qCAAqC,EAAE,CAAC;IACxC,+BAA+B,EAAE,CAAC;IAClC,8EAA8E;IAC9E,8DAA8D;IAC9D,0CAA0C,EAAE,CAAC;IAC7C,eAAe,EAAE,CAAC;IAClB,wCAAwC,CAAC,KAAK,EAAE,CAAC;AACnD,CAAC"}
+{"version":3,"file":"destroy.js","sourceRoot":"","sources":["../../../src/element-template/background/destroy.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EAAE,0CAA0C,EAAE,+BAA+B,EAAE,MAAM,kBAAkB,CAAC;AAC/G,OAAO,EAAE,qCAAqC,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,EAAE,wCAAwC,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAE1D,MAAM,UAAU,uCAAuC;IACrD,qCAAqC,EAAE,CAAC;IACxC,0CAA0C,EAAE,CAAC;IAE7C,MAAM,CAAC,IAAI,EAAE,MAAkC,CAAC,CAAC;IACjD,gFAAgF;IAChF,4DAA4D;IAC5D,gBAAgB,EAAE,CAAC;IAEnB,+BAA+B,EAAE,CAAC;IAClC,eAAe,EAAE,CAAC;IAClB,aAAa,EAAE,CAAC;IAChB,wCAAwC,CAAC,KAAK,EAAE,CAAC;AACnD,CAAC"}

package/runtime/lib/element-template/background/document.js

@@ -2,19 +2,13 @@
 // 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 { options } from 'preact';
-import { BUILTIN_RAW_TEXT_TEMPLATE_KEY, BackgroundElementTemplateInstance, BackgroundElementTemplateSlot, } from './instance.js';
+import { BUILTIN_RAW_TEXT_TEMPLATE_KEY, BackgroundElementTemplateInstance } from './instance.js';
 export function setupBackgroundElementTemplateDocument() {
     const doc = {
         createElement(type) {
-            if (type === 'slot') {
-                return new BackgroundElementTemplateSlot();
-            }
             return new BackgroundElementTemplateInstance(type);
         },
         createElementNS(_ns, type) {
-            if (type === 'slot') {
-                return new BackgroundElementTemplateSlot();
-            }
             return new BackgroundElementTemplateInstance(type);
         },
         createTextNode(text) {

package/runtime/lib/element-template/background/document.js.map

@@ -1 +1 @@
-{"version":3,"file":"document.js","sourceRoot":"","sources":["../../../src/element-template/background/document.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,yEAAyE;AACzE,0DAA0D;AAE1D,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEjC,OAAO,EACL,6BAA6B,EAC7B,iCAAiC,EACjC,6BAA6B,GAC9B,MAAM,eAAe,CAAC;AAQvB,MAAM,UAAU,sCAAsC;IACpD,MAAM,GAAG,GAAG;QACV,aAAa,CAAC,IAAY;YACxB,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;gBACpB,OAAO,IAAI,6BAA6B,EAAE,CAAC;YAC7C,CAAC;YACD,OAAO,IAAI,iCAAiC,CAAC,IAAI,CAAC,CAAC;QACrD,CAAC;QACD,eAAe,CAAC,GAAW,EAAE,IAAY;YACvC,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;gBACpB,OAAO,IAAI,6BAA6B,EAAE,CAAC;YAC7C,CAAC;YACD,OAAO,IAAI,iCAAiC,CAAC,IAAI,CAAC,CAAC;QACrD,CAAC;QACD,cAAc,CAAC,IAAY;YACzB,OAAO,IAAI,iCAAiC,CAAC,6BAA6B,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;QACtF,CAAC;KACF,CAAC;IAEF,OAAO,CAAC,QAAQ,GAAG,GAA0B,CAAC;IAE9C,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../../../src/element-template/background/document.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,yEAAyE;AACzE,0DAA0D;AAE1D,OAAO,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEjC,OAAO,EAAE,6BAA6B,EAAE,iCAAiC,EAAE,MAAM,eAAe,CAAC;AAQjG,MAAM,UAAU,sCAAsC;IACpD,MAAM,GAAG,GAAG;QACV,aAAa,CAAC,IAAY;YACxB,OAAO,IAAI,iCAAiC,CAAC,IAAI,CAAC,CAAC;QACrD,CAAC;QACD,eAAe,CAAC,GAAW,EAAE,IAAY;YACvC,OAAO,IAAI,iCAAiC,CAAC,IAAI,CAAC,CAAC;QACrD,CAAC;QACD,cAAc,CAAC,IAAY;YACzB,OAAO,IAAI,iCAAiC,CAAC,6BAA6B,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;QACtF,CAAC;KACF,CAAC;IAEF,OAAO,CAAC,QAAQ,GAAG,GAA0B,CAAC;IAE9C,OAAO,GAAG,CAAC;AACb,CAAC"}

package/runtime/lib/element-template/background/hydrate.d.ts

@@ -1,4 +1,4 @@
 import type { BackgroundElementTemplateInstance } from './instance.js';
 import type { ElementTemplateUpdateCommandStream, SerializedElementTemplate } from '../protocol/types.js';
 export declare function hydrate(serialized: SerializedElementTemplate, instance: BackgroundElementTemplateInstance): ElementTemplateUpdateCommandStream;
-export declare function hydrateIntoContext(serialized: SerializedElementTemplate, instance: BackgroundElementTemplateInstance): void;
+export declare function hydrateIntoContext(serialized: SerializedElementTemplate, instance: BackgroundElementTemplateInstance): boolean;

package/runtime/lib/element-template/background/hydrate.js

@@ -1,18 +1,24 @@
 // Copyright 2025 The Lynx Authors. 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 { globalCommitContext, markRemovedSubtreeForCurrentCommit, resetGlobalCommitContext } from './commit-context.js';
+import { globalCommitContext, markRemovedSubtreeForPostDispatchTeardown, resetGlobalCommitContext, } from './commit-context.js';
 import { BUILTIN_RAW_TEXT_TEMPLATE_KEY } from './instance.js';
 import { backgroundElementTemplateInstanceManager } from './manager.js';
 import { isDirectOrDeepEqual } from '../../utils.js';
+import { hydrationMap } from '../hydration-map.js';
 import { ElementTemplateUpdateOps } from '../protocol/opcodes.js';
 export function hydrate(serialized, instance) {
     resetGlobalCommitContext();
-    hydrateIntoContext(serialized, instance);
+    if (!hydrateIntoContext(serialized, instance)) {
+        // Hydration protocol errors are not transactional: earlier matched nodes
+        // may already be rebound while discovering a later mismatch. Discard the
+        // native output for this failed pass and let the listener keep refs/events gated.
+        resetGlobalCommitContext();
+    }
     return globalCommitContext.ops;
 }
 export function hydrateIntoContext(serialized, instance) {
-    hydrateInstance(serialized, instance);
+    return hydrateInstance(serialized, instance);
 }
 function hydrateMatchingChildrenAndDiffSlot(serializedChildren, backgroundChildren) {
     let lastPlacedIndex = 0;
@@ -37,7 +43,9 @@ function hydrateMatchingChildrenAndDiffSlot(serializedChildren, backgroundChildr
         if (matchedSerialized) {
             serializedCursorByTemplateKey[backgroundChild.type] = candidateCursor + 1;
             const oldIndex = matchedSerialized[1];
-            hydrateInstance(matchedSerialized[0], backgroundChild);
+            if (!hydrateInstance(matchedSerialized[0], backgroundChild)) {
+                return null;
+            }
             if (oldIndex < lastPlacedIndex) {
                 result.moves[oldIndex] = { toIndex: i, instance: backgroundChild };
                 result.hasChanges = true;
@@ -67,48 +75,54 @@ function hydrateInstance(serialized, instance) {
         if (__DEV__) {
             lynx.reportError(new Error(`ElementTemplate hydrate key mismatch: main='${serialized.templateKey}' background='${instance.type}'.`));
         }
-        return;
+        return false;
     }
     const handleId = serialized.uid;
     if (!bindHydrationHandleId(instance, handleId, serialized.templateKey)) {
-        return;
+        return false;
     }
-    instance.prepareAttributeSlotsForNative();
+    instance.prepareAttributeSlotsForHydration();
     hydrateAttributeSlots(handleId, serialized.attributeSlots ?? [], instance.attributeSlots);
     if (serialized.templateKey === BUILTIN_RAW_TEXT_TEMPLATE_KEY) {
-        return;
+        return true;
     }
     const serializedElementSlots = serialized.elementSlots ?? [];
+    const backgroundElementSlots = instance.elementSlots;
     // Snapshot hydrates dynamic children through slot-filtered lists. Keeping ET
     // scoped the same way means a cross-slot candidate is a source remove plus a
     // target create/insert, while same-slot reorder can still stay move-like.
-    const slotCount = Math.max(serializedElementSlots.length, instance.elementSlots.length);
+    const slotCount = Math.max(serializedElementSlots.length, backgroundElementSlots.length);
     for (let slotId = 0; slotId < slotCount; slotId += 1) {
         const serializedSlot = serializedElementSlots[slotId];
-        const backgroundSlot = instance.elementSlots[slotId];
+        const backgroundSlot = backgroundElementSlots[slotId];
         if (!serializedSlot && !backgroundSlot) {
             continue;
         }
-        hydrateElementSlot(instance, slotId, serializedSlot ?? []);
+        if (!hydrateElementSlot(instance, slotId, serializedSlot ?? [], backgroundSlot ?? [])) {
+            return false;
+        }
     }
+    return true;
 }
-function hydrateElementSlot(parent, slotId, serializedChildren) {
-    const backgroundChildren = parent.elementSlots[slotId] ?? [];
+function hydrateElementSlot(parent, slotId, serializedChildren, backgroundChildren) {
     if (backgroundChildren.length === 0) {
         for (const serialized of serializedChildren) {
             emitSerializedSubtreeRemove(parent, slotId, serialized);
         }
-        return;
+        return true;
     }
     const listDiff = hydrateMatchingChildrenAndDiffSlot(serializedChildren, backgroundChildren);
+    if (listDiff === null) {
+        return false;
+    }
     if (!listDiff.hasChanges) {
-        return;
+        return true;
     }
     // Hydrate emits patches directly here. Replaying against serialized order
     // keeps insert targets in the main-thread slot without reshaping background.
     const removalIndexes = new Set(listDiff.removals);
     const { insertions, moves } = listDiff;
-    const pendingMoves = new Map();
+    const movesWaitingForInsertionPoint = new Map();
     let serializedCursor = 0;
     let currentSerializedChild = serializedChildren[serializedCursor];
     let newIndex = 0;
@@ -116,31 +130,31 @@ function hydrateElementSlot(parent, slotId, serializedChildren) {
     // Insertions are known before replay starts. Moves are counted only when their
     // old serialized position is reached, so the cursor can keep emitting patches
     // even after all serialized children have been consumed.
-    let pendingInsertOrMovePatchCount = listDiff.insertionCount;
-    while (currentSerializedChild || pendingInsertOrMovePatchCount > 0) {
+    let insertOrMovePatchesWaitingForInsertionPoint = listDiff.insertionCount;
+    while (currentSerializedChild || insertOrMovePatchesWaitingForInsertionPoint > 0) {
         let keepCurrentSerializedChild = false;
         if (currentSerializedChild && removalIndexes.has(oldIndex)) {
             emitSerializedSubtreeRemove(parent, slotId, currentSerializedChild);
         }
         else if (currentSerializedChild && moves[oldIndex] !== undefined) {
             const move = moves[oldIndex];
-            pendingMoves.set(move.toIndex, move.instance);
-            pendingInsertOrMovePatchCount += 1;
+            movesWaitingForInsertionPoint.set(move.toIndex, move.instance);
+            insertOrMovePatchesWaitingForInsertionPoint += 1;
         }
         else {
             const beforeChildId = currentSerializedChild ? currentSerializedChild.uid : 0;
-            const movedChild = pendingMoves.get(newIndex);
+            const movedChild = movesWaitingForInsertionPoint.get(newIndex);
             if (movedChild) {
                 keepCurrentSerializedChild = true;
                 globalCommitContext.ops.push(ElementTemplateUpdateOps.insertNode, parent.instanceId, slotId, movedChild.instanceId, beforeChildId);
-                pendingInsertOrMovePatchCount -= 1;
+                insertOrMovePatchesWaitingForInsertionPoint -= 1;
             }
             else if (insertions[newIndex] !== undefined) {
                 const insertedChild = insertions[newIndex];
                 keepCurrentSerializedChild = true;
                 emitCreateSubtree(insertedChild);
                 globalCommitContext.ops.push(ElementTemplateUpdateOps.insertNode, parent.instanceId, slotId, insertedChild.instanceId, beforeChildId);
-                pendingInsertOrMovePatchCount -= 1;
+                insertOrMovePatchesWaitingForInsertionPoint -= 1;
             }
             newIndex += 1;
         }
@@ -149,6 +163,7 @@ function hydrateElementSlot(parent, slotId, serializedChildren) {
             oldIndex += 1;
         }
     }
+    return true;
 }
 function emitSerializedSubtreeRemove(parent, slotId, serialized) {
     const childId = serialized.uid;
@@ -159,7 +174,7 @@ function emitSerializedSubtreeRemove(parent, slotId, serialized) {
     collectSerializedSubtreeHandleIdsInto(serialized, removedSubtreeHandleIds);
     globalCommitContext.ops.push(ElementTemplateUpdateOps.removeNode, parent.instanceId, slotId, childId, removedSubtreeHandleIds);
     if (existing && !existing.parent) {
-        markRemovedSubtreeForCurrentCommit(existing);
+        markRemovedSubtreeForPostDispatchTeardown(existing);
     }
 }
 function collectSerializedSubtreeHandleIdsInto(serialized, handles) {
@@ -174,23 +189,25 @@ function collectSerializedSubtreeHandleIdsInto(serialized, handles) {
     }
 }
 function emitCreateSubtree(node) {
-    for (const slotChildren of node.elementSlots) {
-        /* v8 ignore start */
-        if (!slotChildren) {
-            continue;
-        }
-        /* v8 ignore stop */
-        for (const child of slotChildren) {
-            emitCreateSubtree(child);
-        }
-    }
-    node.prepareAttributeSlotsForNative();
+    // Linked-list walk: slot grouping would be discarded since we recurse into
+    // every child regardless of slot. `emitCreate` does its own single-walk
+    // serialization of `instanceId`s grouped by slot.
+    let child = node.firstChild;
+    while (child) {
+        emitCreateSubtree(child);
+        child = child.nextSibling;
+    }
+    node.prepareAttributeSlotsForHydration();
     node.emitCreate();
 }
 function bindHydrationHandleId(instance, handleId, templateKey) {
+    const oldHandleId = instance.instanceId;
     try {
         backgroundElementTemplateInstanceManager.updateId(instance.instanceId, handleId);
-        instance.markCreateEmittedForHydration();
+        // Ref proxies created before hydrate keep the old background id; resolve it
+        // lazily so user-held proxies continue selecting the hydrated native node.
+        hydrationMap.set(oldHandleId, handleId);
+        instance.markMaterializedByHydration();
         return true;
     }
     catch (error) {