@adobe/data-lit 0.10.14 → 0.10.16

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

@@ -17,59 +17,64 @@ function isReactiveHost(host: Component): host is ReactiveHost {
 }
 
 /**
- * Dispose every effect-style hook slot and reset the hook cursor so the next
- * render re-initializes hooks from scratch. Only slots that expose a
- * `dispose` function (effects, subscriptions) are torn down; value slots
- * (state, memo, ref) are simply dropped.
+ * Finalize a host: dispose every hook slot's cleanup and clear the slots so the
+ * next render re-initializes from scratch. Only slots that expose a `dispose`
+ * function (effects, subscriptions) are torn down; value slots (state, memo,
+ * ref) are simply dropped.
  */
-function disposeHooks(host: Component): void {
+function finalizeHooks(host: Component): void {
     const { hooks } = host;
     if (hooks) {
         for (const hook of hooks) {
             (hook as { dispose?: () => void } | undefined)?.dispose?.();
         }
     }
-    // Invariant: every live subscription (useEffect / useObservable / ...) exposes a
-    // `dispose` and is torn down in the loop above, so nothing should fire after this.
-    // A useState setter closure that still runs post-disconnect would write into the
-    // emptied array and requestUpdate a detached host. That signals an un-torn-down
-    // subscription (a bug at the subscription site), not something to guard here.
     host.hooks = [];
     host.hookIndex = 0;
 }
 
 /**
- * Give a hook host a real disconnect edge.
+ * Give a hook host a correct lifecycle by separating two concerns that the DOM
+ * connect/disconnect edge conflates.
  *
- * The hook model stores every effect's cleanup in `host.hooks[i].dispose`,
- * but {@link useEffect} only invokes it when dependencies change — never when
- * the element leaves the DOM. Left alone, every `useObservable` /
- * `useObservableValues` / `useEffect` subscription leaks on unmount and keeps
- * firing `requestUpdate` on a detached element. `useConnected` is likewise
- * inert because nothing dispatches the `"connected"` / `"disconnected"`
- * events it listens for.
+ * A hook host has two kinds of slot:
  *
- * This installs a single Lit {@link ReactiveController} — the one hook-friendly
- * path to a genuine `hostDisconnected` — that:
- *  - on disconnect, *schedules* (on a microtask) dispatching `"disconnected"`,
- *    disposing every hook slot, and clearing the cursor (full unmount semantics);
- *  - on connect, if a teardown is still pending it CANCELS it (the disconnect
- *    was half of a DOM move — hooks are intact, so nothing re-subscribes and no
- *    re-render is forced); otherwise it dispatches `"connected"` and, on a true
- *    reconnect, forces a re-render so the torn-down hooks re-initialize.
+ *  - **Value / subscription slots** — {@link useState}, {@link useRef},
+ *    {@link useMemo}, and effect-backed subscriptions ({@link useEffect},
+ *    {@link useObservable}, {@link useObservableValues}). These are *stateful*
+ *    and *expensive to rebuild*. They must SURVIVE a DOM move and be finalized
+ *    only when the element is genuinely gone.
+ *  - **Connectedness edges** — {@link useConnected}, the primitive for window /
+ *    document listeners, portals, drag sessions: things that track raw DOM
+ *    connectedness and must attach/detach *synchronously* on every edge.
  *
- * ## Why disposal is deferred
+ * The trap: the DOM fires `disconnectedCallback` then `connectedCallback`
+ * **synchronously, in the same task,** whenever a connected element is merely
+ * *moved* (a Lit `repeat` reorder, a list re-parenting, a drag-reorder). There
+ * is no synchronous signal that distinguishes a move from a genuine unmount, so
+ * this controller does not try to classify the edge. Instead it handles each
+ * concern with the policy that concern actually wants:
  *
- * The DOM fires `disconnectedCallback` then `connectedCallback` **synchronously,
- * in the same task,** whenever a connected element is merely *moved* — a Lit
- * `repeat` reorder, a list re-parenting, a drag-reorder. Disposing inline would
- * tear down and rebuild every subscription (re-running uncached producers) plus
- * force a re-render on every such move, with the hook state momentarily reset —
- * the studio-page lag, refresh churn, and transient empty lists on project
- * switch (FFP-111900). Deferring teardown one microtask lets a synchronous
- * reconnect distinguish a move (cancel) from a genuine unmount (let it run), so
- * a move is a no-op and only a real unmount disposes. A late reconnect (a
- * different task) is treated as unmount+remount, which is correct.
+ *  - **Edges fire synchronously, every time.** `hostConnected` /
+ *    `hostDisconnected` dispatch the `"connected"` / `"disconnected"` events
+ *    inline on every raw edge, so {@link useConnected} tears down and re-attaches
+ *    deterministically — including across a move (cheap, and exactly what a
+ *    listener/portal wants).
+ *  - **Slot finalization is deferred behind an `isConnected` re-check.** A
+ *    disconnect schedules a microtask; when it runs it disposes the slots only
+ *    if the host is STILL disconnected. A move has reconnected by then, so its
+ *    subscription/value slots survive untouched — no re-subscribe, no state
+ *    reset. A genuine unmount is still disconnected, so it finalizes, preserving
+ *    the unmount-leak fix.
+ *  - **Every RE-connect forces one `requestUpdate`.** The DOM does not re-render
+ *    an element on a bare re-parent, so without this an element whose render
+ *    reads mutable non-hook state (a plain field, an ancestor value) would show
+ *    stale output after a move. The re-render is cheap: across a move the slots
+ *    are preserved, so it does NOT re-subscribe or re-run producers — it is a Lit
+ *    diff over unchanged hook state. Across a genuine remount the slots were
+ *    finalized (cleared), so the same re-render re-initializes and re-subscribes
+ *    them. (The perf win is not re-running producers on a move — never the cheap
+ *    re-render.)
  *
  * It is installed lazily from inside the wrapped `render` (see {@link withHooks}),
  * which runs after `connectedCallback`, so `addController` fires `hostConnected`
@@ -87,42 +92,51 @@ export function installHooksController(host: Component): void {
     // guards against a re-entrant render re-installing a duplicate controller.
     host[HOOKS_CONTROLLER] = true;
 
+    // First connect is the initial mount (Lit renders it anyway); only a RE-connect
+    // needs a forced re-render.
     let connectedOnce = false;
-    // True between a disconnect and its scheduled teardown. A reconnect that sees
-    // this flag set is the tail of a move and cancels the teardown.
-    let pendingDisposal = false;
+    // A finalization microtask is already queued; don't queue a second.
+    let finalizationQueued = false;
+
     const controller: ReactiveController = {
         hostConnected() {
-            if (pendingDisposal) {
-                // Tail of a MOVE: the just-fired disconnect scheduled a teardown that
-                // has not run yet. Cancel it — the hooks are untouched, so there is
-                // nothing to re-subscribe and no reason to force a re-render.
-                pendingDisposal = false;
-                return;
-            }
-            // The "connected" / "disconnected" events are for EXTERNAL listeners only.
-            // The internal useConnected does NOT depend on them: this fires before the
-            // render body attaches any listener, so useConnected is driven by its direct
-            // isConnected check plus useEffect cleanup instead.
+            // Fire the connect edge synchronously on EVERY connect (mount / move /
+            // remount) so edge hooks (useConnected) run their setup deterministically.
             host.dispatchEvent(new Event("connected"));
             if (connectedOnce) {
-                // Reconnect: the previous disconnect disposed and cleared every
-                // hook slot, so re-render to re-run hooks and re-subscribe.
+                // Re-render on EVERY reconnect — a move as well as a genuine remount.
+                // The subscription slots are PRESERVED across a move (finalization is
+                // gated on isConnected below), so this re-render does NOT re-subscribe
+                // or re-run producers — it is a cheap Lit diff. It is required for
+                // correctness: an element whose render reads mutable non-hook state
+                // (a plain field, an ancestor value) would otherwise show stale output
+                // after a move, since Lit does not re-render on a bare re-parent. On a
+                // genuine remount the slots were finalized (cleared), so this same
+                // re-render re-initializes and re-subscribes them.
                 host.requestUpdate();
             }
             connectedOnce = true;
         },
         hostDisconnected() {
-            // Defer teardown one microtask so a synchronous reconnect (a DOM move)
-            // can cancel it above. Only a genuine unmount reaches the callback.
-            pendingDisposal = true;
+            // Fire the disconnect edge synchronously on EVERY disconnect (unmount /
+            // move) so edge hooks tear down synchronously.
+            host.dispatchEvent(new Event("disconnected"));
+            // Defer slot finalization behind an isConnected re-check: a DOM move has
+            // reconnected by the time the microtask runs, so its value/subscription
+            // slots survive untouched; only a genuine unmount (still detached) is
+            // finalized. This is what keeps a move from churning subscriptions while
+            // still disposing them on a real unmount.
+            if (finalizationQueued) {
+                return;
+            }
+            finalizationQueued = true;
             queueMicrotask(() => {
-                if (!pendingDisposal) {
+                finalizationQueued = false;
+                if (host.isConnected) {
+                    // Moved / reconnected within the task — keep every slot alive.
                     return;
                 }
-                pendingDisposal = false;
-                host.dispatchEvent(new Event("disconnected"));
-                disposeHooks(host);
+                finalizeHooks(host);
             });
         },
     };

package/src/hooks/component/hooks-lifecycle.integration.test.ts

@@ -0,0 +1,354 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// @vitest-environment happy-dom
+import { describe, it, expect } from "vitest";
+import { LitElement, html } from "lit";
+import type { Observe } from "@adobe/data/observe";
+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 = (): Promise<void> => new Promise(resolve => queueMicrotask(resolve));
+
+/** An Observe whose subscribe/unsubscribe churn the test can inspect. */
+function createTrackedObservable(initial = 0): {
+    observable: Observe<number>;
+    subscriberCount: () => number;
+    totalSubscribes: () => number;
+    totalUnsubscribes: () => number;
+} {
+    const subscribers = new Set<(value: number) => void>();
+    let subscribes = 0;
+    let unsubscribes = 0;
+    const observable: Observe<number> = 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: string[] = [];
+let disconnectEdges: string[] = [];
+let openResources = 0;
+let effectSetups = 0;
+let effectCleanups = 0;
+let renderCount = 0;
+let observableUnderTest: Observe<number>;
+
+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);
+
+/**
+ * Renders a plain mutable field (no hook, no requestUpdate on change). Used to prove
+ * that a reconnect forces a re-render so mutable non-hook state refreshes after a move.
+ */
+class MutableProbeElement extends LitElement {
+    flag = "INITIAL";
+    rendered = "";
+    constructor() {
+        super();
+        attachDecorator(this, "render", withHooks);
+    }
+    render() {
+        this.rendered = this.flag;
+        return html`<span>${this.flag}</span>`;
+    }
+}
+customElements.define("mutable-probe-element", MutableProbeElement);
+
+function resetProbes(obs: Observe<number>): void {
+    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") as LifecycleProbeElement;
+        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") as LifecycleProbeElement;
+        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") as LifecycleProbeElement;
+        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 (no re-subscribe), and the reconnect re-renders once", 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") as LifecycleProbeElement;
+        parentA.appendChild(el);
+        await el.updateComplete;
+        expect(totalSubscribes()).toBe(1);
+        const rendersBeforeMove = renderCount;
+
+        parentB.appendChild(el);
+        await flushMicrotasks();
+        await el.updateComplete;
+
+        // The subscription is untouched — this is the perf win (no re-subscribe, no
+        // producer re-run, no state reset)...
+        expect(subscriberCount()).toBe(1);
+        expect(totalSubscribes()).toBe(1);
+        expect(totalUnsubscribes()).toBe(0);
+        // ...but the reconnect forces exactly one re-render (a cheap Lit diff over the
+        // preserved hook state) so an element reading mutable non-hook state refreshes.
+        expect(renderCount).toBe(rendersBeforeMove + 1);
+    });
+
+    it("an element reading MUTABLE non-hook state refreshes across a MOVE (the reconnect re-render)", async () => {
+        // Regression: a move fires no DOM re-render, so without the controller's forced
+        // reconnect re-render an element whose render reads a plain mutable field shows
+        // stale output after a re-parent.
+        const { observable } = createTrackedObservable();
+        resetProbes(observable);
+        const parentA = document.createElement("div");
+        const parentB = document.createElement("div");
+        document.body.append(parentA, parentB);
+        const el = document.createElement("mutable-probe-element") as MutableProbeElement;
+        parentA.appendChild(el);
+        await el.updateComplete;
+        expect(el.rendered).toBe("INITIAL");
+
+        el.flag = "CHANGED"; // mutate a plain field (no hook, no requestUpdate)
+        parentB.appendChild(el); // MOVE
+        await flushMicrotasks();
+        await el.updateComplete;
+
+        expect(el.isConnected).toBe(true);
+        expect(el.rendered).toBe("CHANGED");
+    });
+
+    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") as LifecycleProbeElement;
+        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") as LifecycleProbeElement;
+        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") as LifecycleProbeElement;
+        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") as LifecycleProbeElement;
+        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);
+    });
+
+    it("a subscription that has not yet emitted heals on a post-MOVE emit (preserved-subscription data contract)", async () => {
+        // Data-layer contract: the move preserves the single mount-time subscription, so
+        // a source that emits only LATER still reaches the element. This guards against a
+        // regression that tears subscriptions down on move (which would strand a source
+        // that does not replay-on-subscribe — the root of the studio "renders nothing").
+        let deliver: ((value: number) => void) | undefined;
+        const stalled: Observe<number> = observer => {
+            deliver = observer; // note: does NOT emit synchronously on subscribe
+            return () => {
+                deliver = undefined;
+            };
+        };
+        resetProbes(stalled);
+        const parentA = document.createElement("div");
+        const parentB = document.createElement("div");
+        document.body.append(parentA, parentB);
+        const el = document.createElement("lifecycle-probe-element") as LifecycleProbeElement;
+        parentA.appendChild(el);
+        await el.updateComplete;
+        expect(el.shadowRoot?.textContent).toContain("41:"); // value undefined, not yet emitted
+
+        // Move BEFORE the source emits, then emit.
+        parentB.appendChild(el);
+        await flushMicrotasks();
+        deliver?.(99);
+        await el.updateComplete;
+
+        // The preserved subscription delivered the post-move emit → element healed.
+        expect(el.shadowRoot?.textContent).toContain("99");
+    });
+});

package/src/hooks/use-connected.ts

@@ -2,40 +2,66 @@
 
 import type { EffectCallback } from "./use-effect.js";
 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: EffectCallback, dependencies?: unknown[]) {
     const component = Component_stack.active();
 
-    let disconnect: (() => void) | void;
-    function onConnect() {
-        if (!disconnect) {
-            disconnect = callback();
-        }
-    }
-
-    function onDisconnect() {
-        if (disconnect) {
-            disconnect?.();
-            disconnect = undefined;
-        }
-    }
+    // 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;
 
-    //  TODO
-    if (component.isConnected) {
-        onConnect();
-    }
+    // 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: (() => void) | void }>({ 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 () => {
             component.removeEventListener("connected", onConnect);
             component.removeEventListener("disconnected", onDisconnect);
-
             onDisconnect();
-        }
-
+        };
     }, dependencies);
-}
+}