@adobe/data-lit 0.10.14 → 0.10.15

package/dist/hooks/component/hooks-lifecycle.integration.test.js

@@ -0,0 +1,244 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, it, expect } from "vitest";
+import { LitElement, html } from "lit";
+import { attachDecorator } from "../attach-decorator.js";
+import { withHooks } from "../with-hooks.js";
+import { useObservable } from "../use-observable.js";
+import { useState } from "../use-state.js";
+import { useConnected } from "../use-connected.js";
+import { useEffect } from "../use-effect.js";
+/**
+ * Real-DOM regression tests for the two-slot hook lifecycle:
+ *
+ *  - Value/subscription slots (useState, useObservable) SURVIVE a DOM move and
+ *    are finalized only on a genuine unmount (deferred `isConnected` re-check).
+ *  - Connectedness edges (useConnected) fire SYNCHRONOUSLY on every raw
+ *    connect/disconnect edge — including a move — so listener/portal/drag setup
+ *    tears down and re-attaches deterministically, with no deferral.
+ *
+ * These pin the contract that neither the 0.10.11 nuke-on-disconnect nor the
+ * 0.10.14 defer-everything controller could satisfy simultaneously.
+ */
+const flushMicrotasks = () => new Promise(resolve => queueMicrotask(resolve));
+/** An Observe whose subscribe/unsubscribe churn the test can inspect. */
+function createTrackedObservable(initial = 0) {
+    const subscribers = new Set();
+    let subscribes = 0;
+    let unsubscribes = 0;
+    const observable = observer => {
+        subscribes++;
+        subscribers.add(observer);
+        observer(initial);
+        return () => {
+            unsubscribes++;
+            subscribers.delete(observer);
+        };
+    };
+    return {
+        observable,
+        subscriberCount: () => subscribers.size,
+        totalSubscribes: () => subscribes,
+        totalUnsubscribes: () => unsubscribes,
+    };
+}
+// Module-scoped probes the element writes into, so a test can read edge/render
+// history without reaching into the element instance.
+let connectEdges = [];
+let disconnectEdges = [];
+let openResources = 0;
+let effectSetups = 0;
+let effectCleanups = 0;
+let renderCount = 0;
+let observableUnderTest;
+class LifecycleProbeElement extends LitElement {
+    constructor() {
+        super();
+        attachDecorator(this, "render", withHooks);
+    }
+    render() {
+        renderCount++;
+        // Edge primitive: must fire synchronously on every connect/disconnect edge,
+        // and open exactly one resource per connect (balanced by its teardown).
+        useConnected(() => {
+            connectEdges.push("connect");
+            openResources++;
+            return () => {
+                disconnectEdges.push("disconnect");
+                openResources--;
+            };
+        });
+        // Plain effect slot: React-parity — cleanup on finalization/dep-change,
+        // never on a bare disconnect (so it survives a move too).
+        useEffect(() => {
+            effectSetups++;
+            return () => {
+                effectCleanups++;
+            };
+        }, []);
+        // Value slot: must survive a move (retain its number across re-parenting).
+        const [n] = useState(() => 41);
+        // Subscription slot: must survive a move (no unsubscribe/re-subscribe).
+        const value = useObservable(observableUnderTest);
+        return html `<span>${n}:${value ?? ""}</span>`;
+    }
+}
+customElements.define("lifecycle-probe-element", LifecycleProbeElement);
+function resetProbes(obs) {
+    connectEdges = [];
+    disconnectEdges = [];
+    openResources = 0;
+    effectSetups = 0;
+    effectCleanups = 0;
+    renderCount = 0;
+    observableUnderTest = obs;
+}
+describe("two-slot hook lifecycle — real DOM", () => {
+    it("useConnected fires its disconnect edge SYNCHRONOUSLY on a genuine unmount", async () => {
+        const { observable } = createTrackedObservable();
+        resetProbes(observable);
+        const el = document.createElement("lifecycle-probe-element");
+        document.body.appendChild(el);
+        await el.updateComplete;
+        expect(connectEdges).toEqual(["connect"]);
+        expect(disconnectEdges).toEqual([]);
+        el.remove();
+        // The edge is synchronous: no microtask flush before this assertion.
+        expect(disconnectEdges).toEqual(["disconnect"]);
+    });
+    it("useConnected runs setup ONCE across ordinary re-renders — no per-render leak", async () => {
+        const { observable } = createTrackedObservable();
+        resetProbes(observable);
+        const el = document.createElement("lifecycle-probe-element");
+        document.body.appendChild(el);
+        await el.updateComplete;
+        expect(connectEdges).toEqual(["connect"]);
+        expect(openResources).toBe(1);
+        // Ordinary re-renders (no connect/disconnect edge) re-run the hook body but
+        // must NOT re-invoke setup — the teardown handle persists across renders.
+        el.requestUpdate();
+        await el.updateComplete;
+        el.requestUpdate();
+        await el.updateComplete;
+        expect(connectEdges).toEqual(["connect"]);
+        expect(openResources).toBe(1);
+        // Unmount tears down exactly the one open resource — nothing leaked.
+        el.remove();
+        expect(disconnectEdges).toEqual(["disconnect"]);
+        expect(openResources).toBe(0);
+    });
+    it("useConnected churns disconnect→connect SYNCHRONOUSLY on a MOVE (re-parent)", async () => {
+        const { observable } = createTrackedObservable();
+        resetProbes(observable);
+        const parentA = document.createElement("div");
+        const parentB = document.createElement("div");
+        document.body.append(parentA, parentB);
+        const el = document.createElement("lifecycle-probe-element");
+        parentA.appendChild(el);
+        await el.updateComplete;
+        expect(connectEdges).toEqual(["connect"]);
+        // MOVE: disconnectedCallback then connectedCallback fire synchronously.
+        parentB.appendChild(el);
+        expect(el.isConnected).toBe(true);
+        // The edge primitive tore down and re-attached, synchronously and in order.
+        expect(disconnectEdges).toEqual(["disconnect"]);
+        expect(connectEdges).toEqual(["connect", "connect"]);
+    });
+    it("value + subscription slots SURVIVE a MOVE (state kept, no re-subscribe, no forced render)", async () => {
+        const { observable, subscriberCount, totalSubscribes, totalUnsubscribes } = createTrackedObservable();
+        resetProbes(observable);
+        const parentA = document.createElement("div");
+        const parentB = document.createElement("div");
+        document.body.append(parentA, parentB);
+        const el = document.createElement("lifecycle-probe-element");
+        parentA.appendChild(el);
+        await el.updateComplete;
+        expect(totalSubscribes()).toBe(1);
+        const rendersBeforeMove = renderCount;
+        parentB.appendChild(el);
+        await flushMicrotasks();
+        await el.updateComplete;
+        // Subscription untouched; useState value preserved; no re-render forced.
+        expect(subscriberCount()).toBe(1);
+        expect(totalSubscribes()).toBe(1);
+        expect(totalUnsubscribes()).toBe(0);
+        expect(renderCount).toBe(rendersBeforeMove);
+    });
+    it("finalizes on a genuine unmount — subscription disposed, no leak", async () => {
+        const { observable, subscriberCount, totalUnsubscribes } = createTrackedObservable();
+        resetProbes(observable);
+        const el = document.createElement("lifecycle-probe-element");
+        document.body.appendChild(el);
+        await el.updateComplete;
+        expect(subscriberCount()).toBe(1);
+        el.remove();
+        await flushMicrotasks();
+        expect(subscriberCount()).toBe(0);
+        expect(totalUnsubscribes()).toBe(1);
+    });
+    it("a genuine unmount→remount (across a task) re-initializes and re-subscribes the slots", async () => {
+        const { observable, subscriberCount, totalSubscribes } = createTrackedObservable();
+        resetProbes(observable);
+        const el = document.createElement("lifecycle-probe-element");
+        document.body.appendChild(el);
+        await el.updateComplete;
+        expect(totalSubscribes()).toBe(1);
+        // Unmount, let finalization run (task boundary), then remount.
+        el.remove();
+        await flushMicrotasks();
+        expect(subscriberCount()).toBe(0);
+        document.body.appendChild(el);
+        await el.updateComplete;
+        // Slots were finalized while detached, so the remount re-subscribed.
+        expect(subscriberCount()).toBe(1);
+        expect(totalSubscribes()).toBe(2);
+        // And the edge primitive reconnected.
+        expect(connectEdges.filter(e => e === "connect").length).toBe(2);
+    });
+    it("a genuine unmount→remount to a DIFFERENT parent (across a task) re-initializes and re-subscribes", async () => {
+        const { observable, subscriberCount, totalSubscribes } = createTrackedObservable();
+        resetProbes(observable);
+        const parentA = document.createElement("div");
+        const parentB = document.createElement("div");
+        document.body.append(parentA, parentB);
+        const el = document.createElement("lifecycle-probe-element");
+        parentA.appendChild(el);
+        await el.updateComplete;
+        expect(totalSubscribes()).toBe(1);
+        // Unmount from A, let finalization run, then remount under a DIFFERENT parent.
+        // The finalization gate reads `isConnected` (not "did it reconnect to the same
+        // node"), so a remount anywhere is handled uniformly.
+        el.remove();
+        await flushMicrotasks();
+        expect(subscriberCount()).toBe(0);
+        parentB.appendChild(el);
+        await el.updateComplete;
+        expect(subscriberCount()).toBe(1);
+        expect(totalSubscribes()).toBe(2);
+        expect(connectEdges.filter(e => e === "connect").length).toBe(2);
+    });
+    it("plain useEffect cleanup does NOT run on a MOVE, and runs (deferred) on a genuine unmount", async () => {
+        const { observable } = createTrackedObservable();
+        resetProbes(observable);
+        const parentA = document.createElement("div");
+        const parentB = document.createElement("div");
+        document.body.append(parentA, parentB);
+        const el = document.createElement("lifecycle-probe-element");
+        parentA.appendChild(el);
+        await el.updateComplete;
+        expect(effectSetups).toBe(1);
+        expect(effectCleanups).toBe(0);
+        // MOVE: the effect slot survives untouched — no cleanup, no re-setup.
+        parentB.appendChild(el);
+        await flushMicrotasks();
+        await el.updateComplete;
+        expect(effectSetups).toBe(1);
+        expect(effectCleanups).toBe(0);
+        // UNMOUNT: cleanup runs on the finalization microtask, not synchronously.
+        el.remove();
+        expect(effectCleanups).toBe(0);
+        await flushMicrotasks();
+        expect(effectCleanups).toBe(1);
+    });
+});
+//# sourceMappingURL=hooks-lifecycle.integration.test.js.map

package/dist/hooks/component/hooks-lifecycle.integration.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks-lifecycle.integration.test.js","sourceRoot":"","sources":["../../../src/hooks/component/hooks-lifecycle.integration.test.ts"],"names":[],"mappings":"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"}

package/dist/hooks/use-connected.d.ts

@@ -1,2 +1,19 @@
 import type { EffectCallback } from "./use-effect.js";
+/**
+ * Run `callback` on every DOM connect edge and its returned teardown on every
+ * disconnect edge — the connectedness primitive for `window` / `document`
+ * listeners, portals, and drag sessions that must attach and detach
+ * *synchronously* as the host enters and leaves the DOM.
+ *
+ * The hooks controller (see `installHooksController`) dispatches the
+ * `"connected"` / `"disconnected"` events synchronously on every raw edge,
+ * including a DOM move, so a move tears the setup down and re-attaches it
+ * deterministically.
+ *
+ * Setup runs exactly ONCE per connect. The teardown handle lives in a ref that
+ * persists across renders, so ordinary re-renders (which re-run this hook body)
+ * neither re-invoke setup nor leak — the setup/teardown pair is driven only from
+ * the edge, never from the render pass. The callback is read live through a ref,
+ * so callers may pass a fresh closure on every render.
+ */
 export declare function useConnected(callback: EffectCallback, dependencies?: unknown[]): void;

package/dist/hooks/use-connected.js

@@ -1,25 +1,53 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import { useEffect } from "./use-effect.js";
+import { useRef } from "./use-ref.js";
 import { Component_stack } from "./component/stack.js";
+/**
+ * Run `callback` on every DOM connect edge and its returned teardown on every
+ * disconnect edge — the connectedness primitive for `window` / `document`
+ * listeners, portals, and drag sessions that must attach and detach
+ * *synchronously* as the host enters and leaves the DOM.
+ *
+ * The hooks controller (see `installHooksController`) dispatches the
+ * `"connected"` / `"disconnected"` events synchronously on every raw edge,
+ * including a DOM move, so a move tears the setup down and re-attaches it
+ * deterministically.
+ *
+ * Setup runs exactly ONCE per connect. The teardown handle lives in a ref that
+ * persists across renders, so ordinary re-renders (which re-run this hook body)
+ * neither re-invoke setup nor leak — the setup/teardown pair is driven only from
+ * the edge, never from the render pass. The callback is read live through a ref,
+ * so callers may pass a fresh closure on every render.
+ */
 export function useConnected(callback, dependencies) {
     const component = Component_stack.active();
-    let disconnect;
-    function onConnect() {
-        if (!disconnect) {
-            disconnect = callback();
-        }
-    }
-    function onDisconnect() {
-        if (disconnect) {
-            disconnect?.();
-            disconnect = undefined;
-        }
-    }
-    //  TODO
-    if (component.isConnected) {
-        onConnect();
-    }
+    // Live-read the latest callback so a fresh closure each render is honored
+    // without re-registering the edge listeners.
+    const callbackRef = useRef(callback);
+    callbackRef.current = callback;
+    // Persistent teardown handle: the cleanup returned by `callback` while
+    // connected, or `undefined` while disconnected. A ref (not a per-render
+    // local) so the "already connected" guard holds across renders — this is
+    // what makes setup idempotent per connect instead of per render.
+    const state = useRef({ disconnect: undefined });
     useEffect(() => {
+        const onConnect = () => {
+            if (!state.current.disconnect) {
+                state.current.disconnect = callbackRef.current();
+            }
+        };
+        const onDisconnect = () => {
+            if (state.current.disconnect) {
+                state.current.disconnect();
+                state.current.disconnect = undefined;
+            }
+        };
+        // On first mount the controller dispatches "connected" during
+        // `addController`, before this effect attaches its listener, so run setup
+        // now if the host is already connected.
+        if (component.isConnected) {
+            onConnect();
+        }
         component.addEventListener("connected", onConnect);
         component.addEventListener("disconnected", onDisconnect);
         return () => {

package/dist/hooks/use-connected.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-connected.js","sourceRoot":"","sources":["../../src/hooks/use-connected.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAGvD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,MAAM,UAAU,YAAY,CAAC,QAAwB,EAAE,YAAwB;IAC3E,MAAM,SAAS,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC;IAE3C,IAAI,UAA+B,CAAC;IACpC,SAAS,SAAS;QACd,IAAI,CAAC,UAAU,EAAE,CAAC;YACd,UAAU,GAAG,QAAQ,EAAE,CAAC;QAC5B,CAAC;IACL,CAAC;IAED,SAAS,YAAY;QACjB,IAAI,UAAU,EAAE,CAAC;YACb,UAAU,EAAE,EAAE,CAAC;YACf,UAAU,GAAG,SAAS,CAAC;QAC3B,CAAC;IACL,CAAC;IAED,QAAQ;IACR,IAAI,SAAS,CAAC,WAAW,EAAE,CAAC;QACxB,SAAS,EAAE,CAAC;IAChB,CAAC;IAED,SAAS,CAAC,GAAG,EAAE;QACX,SAAS,CAAC,gBAAgB,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QACnD,SAAS,CAAC,gBAAgB,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;QAEzD,OAAO,GAAG,EAAE;YACR,SAAS,CAAC,mBAAmB,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;YACtD,SAAS,CAAC,mBAAmB,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;YAE5D,YAAY,EAAE,CAAC;QACnB,CAAC,CAAA;IAEL,CAAC,EAAE,YAAY,CAAC,CAAC;AACrB,CAAC"}
+{"version":3,"file":"use-connected.js","sourceRoot":"","sources":["../../src/hooks/use-connected.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAGvD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,YAAY,CAAC,QAAwB,EAAE,YAAwB;IAC3E,MAAM,SAAS,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC;IAE3C,0EAA0E;IAC1E,6CAA6C;IAC7C,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrC,WAAW,CAAC,OAAO,GAAG,QAAQ,CAAC;IAE/B,uEAAuE;IACvE,wEAAwE;IACxE,yEAAyE;IACzE,iEAAiE;IACjE,MAAM,KAAK,GAAG,MAAM,CAAsC,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;IAErF,SAAS,CAAC,GAAG,EAAE;QACX,MAAM,SAAS,GAAG,GAAG,EAAE;YACnB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;gBAC5B,KAAK,CAAC,OAAO,CAAC,UAAU,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC;YACrD,CAAC;QACL,CAAC,CAAC;QACF,MAAM,YAAY,GAAG,GAAG,EAAE;YACtB,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;gBAC3B,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;gBAC3B,KAAK,CAAC,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;YACzC,CAAC;QACL,CAAC,CAAC;QAEF,8DAA8D;QAC9D,0EAA0E;QAC1E,wCAAwC;QACxC,IAAI,SAAS,CAAC,WAAW,EAAE,CAAC;YACxB,SAAS,EAAE,CAAC;QAChB,CAAC;QACD,SAAS,CAAC,gBAAgB,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QACnD,SAAS,CAAC,gBAAgB,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;QAEzD,OAAO,GAAG,EAAE;YACR,SAAS,CAAC,mBAAmB,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;YACtD,SAAS,CAAC,mBAAmB,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;YAC5D,YAAY,EAAE,CAAC;QACnB,CAAC,CAAC;IACN,CAAC,EAAE,YAAY,CAAC,CAAC;AACrB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-lit",
-  "version": "0.10.14",
+  "version": "0.10.15",
   "description": "Adobe data Lit bindings - hooks, elements, decorators",
   "type": "module",
   "private": false,
@@ -12,7 +12,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@adobe/data": "0.10.14"
+    "@adobe/data": "0.10.15"
   },
   "peerDependencies": {
     "lit": "^3.3.1"

package/src/hooks/component/hooks-controller.test.ts

@@ -7,8 +7,10 @@ import { installHooksController } from "./hooks-controller.js";
 /**
  * Minimal stand-in for a Lit host: an EventTarget that captures the controller
  * installed on it so the test can drive `hostConnected` / `hostDisconnected`
- * directly (a real Lit element would need a DOM). `addController` mirrors Lit's
- * contract of firing `hostConnected` synchronously when already connected.
+ * directly (a real Lit element would need a DOM). `connect()` / `disconnect()`
+ * flip `isConnected` BEFORE dispatching, mirroring the DOM (the callback runs
+ * after connectedness has already changed) — the controller's deferred
+ * finalization reads `isConnected` to tell a move from a genuine unmount.
  */
 class FakeHost extends EventTarget implements Component {
     isConnected = true;
@@ -21,20 +23,21 @@ class FakeHost extends EventTarget implements Component {
     addController(controller: ReactiveController) {
         this.controllers.push(controller);
     }
-    // Simulate Lit dispatching lifecycle to every registered controller.
     connect() {
+        this.isConnected = true;
         for (const c of this.controllers) c.hostConnected?.();
     }
     disconnect() {
+        this.isConnected = false;
         for (const c of this.controllers) c.hostDisconnected?.();
     }
 }
 
-/** Resolves after the current microtask checkpoint, so deferred teardown can run. */
+/** Resolves after the current microtask checkpoint, so deferred finalization can run. */
 const flushMicrotasks = (): Promise<void> => new Promise(resolve => queueMicrotask(resolve));
 
 describe("installHooksController", () => {
-    it("disposes every effect hook and resets the cursor on a genuine disconnect", async () => {
+    it("finalizes every effect hook and resets the cursor on a genuine disconnect", async () => {
         const host = new FakeHost();
         const disposeA = vi.fn();
         const disposeB = vi.fn();
@@ -48,8 +51,8 @@ describe("installHooksController", () => {
 
         installHooksController(host);
         host.disconnect();
-        // Teardown is deferred one microtask (so a move can cancel it); with no
-        // reconnect this is a real unmount, so it runs on the next checkpoint.
+        // Finalization is deferred one microtask (so a move can cancel it); with no
+        // reconnect the host is still disconnected, so it runs on the next checkpoint.
         await flushMicrotasks();
 
         expect(disposeA).toHaveBeenCalledTimes(1);
@@ -58,44 +61,80 @@ describe("installHooksController", () => {
         expect(host.hookIndex).toBe(0);
     });
 
-    it("a synchronous disconnect→reconnect (a MOVE) cancels teardown and forces no re-render", async () => {
+    it("fires the connect / disconnect EDGE synchronously — no microtask needed", () => {
+        const host = new FakeHost();
+        const onConnected = vi.fn();
+        const onDisconnected = vi.fn();
+        host.addEventListener("connected", onConnected);
+        host.addEventListener("disconnected", onDisconnected);
+
+        installHooksController(host);
+        host.connect();
+        expect(onConnected).toHaveBeenCalledTimes(1);
+
+        host.disconnect();
+        // No flush: the edge is synchronous so connectedness hooks (useConnected)
+        // tear down inline. Under the old defer-everything controller this event
+        // only fired on a later microtask.
+        expect(onDisconnected).toHaveBeenCalledTimes(1);
+    });
+
+    it("fires disconnect THEN connect synchronously across a MOVE, and does NOT finalize", async () => {
         const host = new FakeHost();
         const dispose = vi.fn();
         host.hooks = [{ dispose, dependencies: [] }];
         host.hookIndex = 1;
+        const edges: string[] = [];
+        host.addEventListener("disconnected", () => edges.push("disconnect"));
+        host.addEventListener("connected", () => edges.push("connect"));
 
         installHooksController(host);
-        host.connect(); // first mount
         host.requestUpdate.mockClear();
 
-        // Disconnect immediately followed by reconnect, same task — a DOM move.
+        // Move: disconnect immediately followed by reconnect, same task.
         host.disconnect();
         host.connect();
-        await flushMicrotasks();
+        expect(edges).toEqual(["disconnect", "connect"]); // both edges, synchronous, in order
 
-        // Nothing was torn down and no re-render was forced: the hooks survived.
+        await flushMicrotasks();
+        // The slot survived: not disposed, and no re-render was forced.
         expect(dispose).not.toHaveBeenCalled();
         expect(host.hooks).toHaveLength(1);
         expect(host.requestUpdate).not.toHaveBeenCalled();
     });
 
-    it("dispatches connected / disconnected events across the lifecycle", async () => {
+    it("a rapid disconnect→connect→disconnect bounce finalizes exactly once (net state wins)", async () => {
         const host = new FakeHost();
-        const onConnected = vi.fn();
-        const onDisconnected = vi.fn();
-        host.addEventListener("connected", onConnected);
-        host.addEventListener("disconnected", onDisconnected);
+        const dispose = vi.fn();
+        host.hooks = [{ dispose, dependencies: [] }];
 
         installHooksController(host);
+        // Bounce within one task: only one finalization microtask is queued, and it
+        // reads the final isConnected (false) → finalizes once, not per disconnect.
+        host.disconnect();
         host.connect();
-        expect(onConnected).toHaveBeenCalledTimes(1);
-
         host.disconnect();
         await flushMicrotasks();
-        expect(onDisconnected).toHaveBeenCalledTimes(1);
+
+        expect(dispose).toHaveBeenCalledTimes(1);
+        expect(host.hooks).toEqual([]);
+    });
+
+    it("gates finalization on isConnected — a slot that reconnects before the microtask survives", async () => {
+        const host = new FakeHost();
+        const dispose = vi.fn();
+        host.hooks = [{ dispose, dependencies: [] }];
+
+        installHooksController(host);
+        host.disconnect(); // schedules finalization; isConnected now false
+        host.connect(); // reconnects in the same task; isConnected back to true
+        await flushMicrotasks();
+
+        expect(dispose).not.toHaveBeenCalled();
+        expect(host.hooks).toHaveLength(1);
     });
 
-    it("forces a re-render only on a genuine RE-connect, not the first connect", async () => {
+    it("forces a re-render only on a genuine RE-connect, not the first connect or a move", async () => {
         const host = new FakeHost();
         installHooksController(host);
 
@@ -103,8 +142,8 @@ describe("installHooksController", () => {
         expect(host.requestUpdate).not.toHaveBeenCalled();
 
         host.disconnect();
-        await flushMicrotasks(); // genuine unmount: teardown runs
-        host.connect(); // reconnect re-initializes the torn-down hooks
+        await flushMicrotasks(); // genuine unmount: finalization runs
+        host.connect(); // reconnect must re-initialize the finalized hooks
         expect(host.requestUpdate).toHaveBeenCalledTimes(1);
     });