@adobe/data-lit 0.10.9 → 0.10.11

package/README.md

@@ -1,6 +1,7 @@
 # @adobe/data-lit
 
-Lit bindings for [@adobe/data](https://www.npmjs.com/package/@adobe/data) — hooks, elements, and decorators for building reactive UIs with the @adobe/data ECS database and observables.
+Lit bindings for [@adobe/data](https://www.npmjs.com/package/@adobe/data): hooks, elements, and decorators
+for building reactive UIs with the @adobe/data ECS database and observables.
 
 ## Install
 
@@ -15,4 +16,21 @@ import { ApplicationHost, DatabaseElement } from "@adobe/data-lit";
 import { createDatabase } from "@adobe/data/ecs";
 ```
 
+## Hooks and the disconnect lifecycle
+
+Hooks (`useState`, `useEffect`, `useObservable`, `useObservableValues`, `useMemo`, `useRef`, ...) follow
+React's unmount semantics. When a hook-using element is disconnected from the DOM, **all of its hook state is
+reset**:
+
+- every `useEffect` cleanup runs, so observable subscriptions and event listeners are torn down, and
+- all stored values (`useState`, `useMemo`, `useRef`) are discarded.
+
+On the next connect the element renders fresh from its initial hook state.
+
+> **Footgun:** because a disconnect is a full reset, a DOM *move* (`el.remove()` then re-appending it, or
+> reparenting the element) is treated as a full unmount followed by a remount. Any local UI state held in
+> hooks is silently lost across the move: toggle positions, uncontrolled input values, scroll offsets. If a
+> piece of state must survive a reparent, keep it in the `@adobe/data` database/service rather than in element
+> hook state.
+
 See the `data-lit-todo` sample in this repository for a full example.

package/dist/hooks/component/hooks-controller.d.ts

@@ -0,0 +1,28 @@
+import type { Component } from "./component.js";
+/**
+ * Give a hook host a real disconnect edge.
+ *
+ * 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.
+ *
+ * This installs a single Lit {@link ReactiveController} — the one hook-friendly
+ * path to a genuine `hostDisconnected` — that:
+ *  - on connect, dispatches `"connected"`, and on every *re*-connect forces a
+ *    re-render so the (previously torn-down) hooks re-initialize and
+ *    re-subscribe;
+ *  - on disconnect, dispatches `"disconnected"` then disposes and clears all
+ *    hook slots (full unmount semantics).
+ *
+ * It is installed lazily from inside the wrapped `render` (see {@link withHooks}),
+ * which runs after `connectedCallback`, so `addController` fires `hostConnected`
+ * synchronously on the first mount. The install is idempotent per host.
+ *
+ * Non-Lit hosts (no `addController`) are skipped; they may dispatch the
+ * lifecycle events themselves.
+ */
+export declare function installHooksController(host: Component): void;

package/dist/hooks/component/hooks-controller.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,74 @@
+// © 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";
+/**
+ * Real-DOM regression test for the hook-disposal fix. Where the sibling
+ * hooks-controller.test.ts drives a hand-rolled FakeHost, this mounts a genuine
+ * LitElement in a happy-dom document, so it exercises the actual bug path:
+ * `withHooks` installs the controller, `addController` fires `hostConnected`
+ * synchronously during the real connect, and a real `useObservable` subscription
+ * is torn down when the element leaves the DOM (instead of leaking and firing
+ * `requestUpdate` on a detached element).
+ */
+/** An Observe whose live subscriber count the test can inspect. */
+function createTrackedObservable() {
+    const subscribers = new Set();
+    let current = 0;
+    const observable = observer => {
+        subscribers.add(observer);
+        observer(current);
+        return () => {
+            subscribers.delete(observer);
+        };
+    };
+    return {
+        observable,
+        emit: value => {
+            current = value;
+            for (const observer of subscribers)
+                observer(value);
+        },
+        subscriberCount: () => subscribers.size,
+    };
+}
+class HookProbeElement extends LitElement {
+    constructor() {
+        super();
+        attachDecorator(this, "render", withHooks);
+    }
+    render() {
+        const value = useObservable(this.observable);
+        return html `<span>${value ?? ""}</span>`;
+    }
+}
+customElements.define("hook-probe-element", HookProbeElement);
+describe("hook disposal on real DOM disconnect", () => {
+    it("tears down a useObservable subscription and stops requestUpdate when the element is removed", async () => {
+        const { observable, emit, subscriberCount } = createTrackedObservable();
+        const el = document.createElement("hook-probe-element");
+        el.observable = observable;
+        document.body.appendChild(el);
+        await el.updateComplete;
+        // Mounted: the render subscribed exactly once.
+        expect(subscriberCount()).toBe(1);
+        // Track any requestUpdate that fires AFTER the element is removed.
+        let updatesAfterRemove = 0;
+        const originalRequestUpdate = el.requestUpdate.bind(el);
+        el.requestUpdate = (...args) => {
+            updatesAfterRemove++;
+            originalRequestUpdate(...args);
+        };
+        el.remove();
+        // Disconnect ran the effect cleanup: the subscription is gone.
+        expect(subscriberCount()).toBe(0);
+        // A later emit reaches no leaked subscriber, so the detached element is
+        // never asked to update. Without the disposal fix, this would be >= 1.
+        emit(99);
+        expect(updatesAfterRemove).toBe(0);
+    });
+});
+//# sourceMappingURL=hooks-controller.integration.test.js.map

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

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

package/dist/hooks/component/hooks-controller.js

@@ -0,0 +1,96 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * Per-host flag marking that the hook-lifecycle controller is already
+ * installed, so repeated renders (and double-wrapped `render` methods) do
+ * not register duplicate controllers.
+ */
+const HOOKS_CONTROLLER = Symbol("data-lit.hooksController");
+function isReactiveHost(host) {
+    return "addController" in host && typeof host.addController === "function";
+}
+/**
+ * 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.
+ */
+function disposeHooks(host) {
+    const { hooks } = host;
+    if (hooks) {
+        for (const hook of hooks) {
+            hook?.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.
+ *
+ * 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.
+ *
+ * This installs a single Lit {@link ReactiveController} — the one hook-friendly
+ * path to a genuine `hostDisconnected` — that:
+ *  - on connect, dispatches `"connected"`, and on every *re*-connect forces a
+ *    re-render so the (previously torn-down) hooks re-initialize and
+ *    re-subscribe;
+ *  - on disconnect, dispatches `"disconnected"` then disposes and clears all
+ *    hook slots (full unmount semantics).
+ *
+ * It is installed lazily from inside the wrapped `render` (see {@link withHooks}),
+ * which runs after `connectedCallback`, so `addController` fires `hostConnected`
+ * synchronously on the first mount. The install is idempotent per host.
+ *
+ * Non-Lit hosts (no `addController`) are skipped; they may dispatch the
+ * lifecycle events themselves.
+ */
+export function installHooksController(host) {
+    if (!isReactiveHost(host) || host[HOOKS_CONTROLLER]) {
+        return;
+    }
+    // Mark installed BEFORE addController below: on an already-connected host
+    // addController fires hostConnected synchronously, and setting the flag first
+    // guards against a re-entrant render re-installing a duplicate controller.
+    host[HOOKS_CONTROLLER] = true;
+    let connectedOnce = false;
+    const controller = {
+        hostConnected() {
+            // 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.
+            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.
+                host.requestUpdate();
+            }
+            connectedOnce = true;
+        },
+        hostDisconnected() {
+            host.dispatchEvent(new Event("disconnected"));
+            disposeHooks(host);
+        },
+    };
+    try {
+        host.addController(controller);
+    }
+    catch (error) {
+        // addController failed, so no controller is registered. Clear the flag so a
+        // later render can retry the install instead of being permanently skipped.
+        host[HOOKS_CONTROLLER] = undefined;
+        throw error;
+    }
+}
+//# sourceMappingURL=hooks-controller.js.map

package/dist/hooks/component/hooks-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks-controller.js","sourceRoot":"","sources":["../../../src/hooks/component/hooks-controller.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAKvD;;;;GAIG;AACH,MAAM,gBAAgB,GAAG,MAAM,CAAC,0BAA0B,CAAC,CAAC;AAI5D,SAAS,cAAc,CAAC,IAAe;IACnC,OAAO,eAAe,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,aAAa,KAAK,UAAU,CAAC;AAC/E,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CAAC,IAAe;IACjC,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;IACvB,IAAI,KAAK,EAAE,CAAC;QACR,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACtB,IAA6C,EAAE,OAAO,EAAE,EAAE,CAAC;QAChE,CAAC;IACL,CAAC;IACD,iFAAiF;IACjF,mFAAmF;IACnF,iFAAiF;IACjF,gFAAgF;IAChF,8EAA8E;IAC9E,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;IAChB,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAe;IAClD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAClD,OAAO;IACX,CAAC;IACD,0EAA0E;IAC1E,8EAA8E;IAC9E,2EAA2E;IAC3E,IAAI,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC;IAE9B,IAAI,aAAa,GAAG,KAAK,CAAC;IAC1B,MAAM,UAAU,GAAuB;QACnC,aAAa;YACT,2EAA2E;YAC3E,2EAA2E;YAC3E,6EAA6E;YAC7E,oDAAoD;YACpD,IAAI,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;YAC3C,IAAI,aAAa,EAAE,CAAC;gBAChB,gEAAgE;gBAChE,4DAA4D;gBAC5D,IAAI,CAAC,aAAa,EAAE,CAAC;YACzB,CAAC;YACD,aAAa,GAAG,IAAI,CAAC;QACzB,CAAC;QACD,gBAAgB;YACZ,IAAI,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;YAC9C,YAAY,CAAC,IAAI,CAAC,CAAC;QACvB,CAAC;KACJ,CAAC;IACF,IAAI,CAAC;QACD,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,4EAA4E;QAC5E,2EAA2E;QAC3E,IAAI,CAAC,gBAAgB,CAAC,GAAG,SAAS,CAAC;QACnC,MAAM,KAAK,CAAC;IAChB,CAAC;AACL,CAAC"}

package/dist/hooks/component/hooks-controller.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/component/hooks-controller.test.js

@@ -0,0 +1,85 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, it, expect, vi } from "vitest";
+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.
+ */
+class FakeHost extends EventTarget {
+    constructor() {
+        super(...arguments);
+        this.isConnected = true;
+        this.hookIndex = 0;
+        this.hooks = [];
+        this.updatedListeners = new Set();
+        this.requestUpdate = vi.fn();
+        this.controllers = [];
+    }
+    addController(controller) {
+        this.controllers.push(controller);
+    }
+    // Simulate Lit dispatching lifecycle to every registered controller.
+    connect() {
+        for (const c of this.controllers)
+            c.hostConnected?.();
+    }
+    disconnect() {
+        for (const c of this.controllers)
+            c.hostDisconnected?.();
+    }
+}
+describe("installHooksController", () => {
+    it("disposes every effect hook and resets the cursor on disconnect", () => {
+        const host = new FakeHost();
+        const disposeA = vi.fn();
+        const disposeB = vi.fn();
+        host.hooks = [
+            { dispose: disposeA, dependencies: [] },
+            42, // a value slot (useState) — must be skipped, not crash
+            { dispose: disposeB, dependencies: [] },
+            { current: null }, // a ref slot — no dispose
+        ];
+        host.hookIndex = 4;
+        installHooksController(host);
+        host.disconnect();
+        expect(disposeA).toHaveBeenCalledTimes(1);
+        expect(disposeB).toHaveBeenCalledTimes(1);
+        expect(host.hooks).toEqual([]);
+        expect(host.hookIndex).toBe(0);
+    });
+    it("dispatches connected / disconnected events across the lifecycle", () => {
+        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();
+        expect(onDisconnected).toHaveBeenCalledTimes(1);
+    });
+    it("forces a re-render only on RE-connect, not the first connect", () => {
+        const host = new FakeHost();
+        installHooksController(host);
+        host.connect(); // first mount
+        expect(host.requestUpdate).not.toHaveBeenCalled();
+        host.disconnect();
+        host.connect(); // reconnect
+        expect(host.requestUpdate).toHaveBeenCalledTimes(1);
+    });
+    it("is idempotent — repeated installs register a single controller", () => {
+        const host = new FakeHost();
+        installHooksController(host);
+        installHooksController(host);
+        installHooksController(host);
+        expect(host.controllers).toHaveLength(1);
+    });
+    it("skips hosts that are not reactive controller hosts", () => {
+        const host = new EventTarget();
+        expect(() => installHooksController(host)).not.toThrow();
+    });
+});
+//# sourceMappingURL=hooks-controller.test.js.map

package/dist/hooks/component/hooks-controller.test.js.map

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

package/dist/hooks/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./component/component.js";
 export * from "./component/stack.js";
+export * from "./component/hooks-controller.js";
 export * from "./use-state.js";
 export * from "./use-effect.js";
 export * from "./use-connected.js";

package/dist/hooks/index.js

@@ -1,6 +1,7 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 export * from "./component/component.js";
 export * from "./component/stack.js";
+export * from "./component/hooks-controller.js";
 export * from "./use-state.js";
 export * from "./use-effect.js";
 export * from "./use-connected.js";

package/dist/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iCAAiC,CAAC;AAChD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC"}

package/dist/hooks/with-hooks.js

@@ -1,8 +1,13 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import { Component_stack } from "./component/stack.js";
+import { installHooksController } from "./component/hooks-controller.js";
 export function withHooks(target, propertyKey, descriptor) {
     const originalMethod = descriptor.value;
     descriptor.value = function (...args) {
+        // Give the host a real disconnect edge so effect/subscription cleanups
+        // actually run on unmount. Idempotent per host, so double-wrapped
+        // `render` methods install it only once.
+        installHooksController(this);
         Component_stack.push(this);
         try {
             return originalMethod.apply(this, args);

package/dist/hooks/with-hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"with-hooks.js","sourceRoot":"","sources":["../../src/hooks/with-hooks.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAGvD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,MAAM,UAAU,SAAS,CACrB,MAAc,EACd,WAAmB,EACnB,UAA0E;IAE1E,MAAM,cAAc,GAAG,UAAU,CAAC,KAAM,CAAC;IACzC,UAAU,CAAC,KAAK,GAAG,UAAsB,GAAG,IAAU;QAClD,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,CAAC;YACD,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC5C,CAAC;gBACO,CAAC;YACL,eAAe,CAAC,GAAG,EAAE,CAAC;QAC1B,CAAC;IACL,CAAC,CAAA;IACD,OAAO,UAAU,CAAC;AACtB,CAAC"}
+{"version":3,"file":"with-hooks.js","sourceRoot":"","sources":["../../src/hooks/with-hooks.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAGvD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAEzE,MAAM,UAAU,SAAS,CACrB,MAAc,EACd,WAAmB,EACnB,UAA0E;IAE1E,MAAM,cAAc,GAAG,UAAU,CAAC,KAAM,CAAC;IACzC,UAAU,CAAC,KAAK,GAAG,UAAsB,GAAG,IAAU;QAClD,uEAAuE;QACvE,kEAAkE;QAClE,yCAAyC;QACzC,sBAAsB,CAAC,IAAI,CAAC,CAAC;QAC7B,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,CAAC;YACD,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC5C,CAAC;gBACO,CAAC;YACL,eAAe,CAAC,GAAG,EAAE,CAAC;QAC1B,CAAC;IACL,CAAC,CAAA;IACD,OAAO,UAAU,CAAC;AACtB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/data-lit",
-  "version": "0.10.9",
+  "version": "0.10.11",
   "description": "Adobe data Lit bindings - hooks, elements, decorators",
   "type": "module",
   "private": false,
@@ -12,12 +12,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@adobe/data": "0.10.9"
+    "@adobe/data": "0.10.11"
   },
   "peerDependencies": {
     "lit": "^3.3.1"
   },
   "devDependencies": {
+    "happy-dom": "^20.14.0",
     "lit": "^3.3.1",
     "typescript": "^5.8.3",
     "vitest": "^1.6.0"

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

@@ -0,0 +1,88 @@
+// © 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";
+
+/**
+ * Real-DOM regression test for the hook-disposal fix. Where the sibling
+ * hooks-controller.test.ts drives a hand-rolled FakeHost, this mounts a genuine
+ * LitElement in a happy-dom document, so it exercises the actual bug path:
+ * `withHooks` installs the controller, `addController` fires `hostConnected`
+ * synchronously during the real connect, and a real `useObservable` subscription
+ * is torn down when the element leaves the DOM (instead of leaking and firing
+ * `requestUpdate` on a detached element).
+ */
+
+/** An Observe whose live subscriber count the test can inspect. */
+function createTrackedObservable(): {
+    observable: Observe<number>;
+    emit: (value: number) => void;
+    subscriberCount: () => number;
+} {
+    const subscribers = new Set<(value: number) => void>();
+    let current = 0;
+    const observable: Observe<number> = observer => {
+        subscribers.add(observer);
+        observer(current);
+        return () => {
+            subscribers.delete(observer);
+        };
+    };
+    return {
+        observable,
+        emit: value => {
+            current = value;
+            for (const observer of subscribers) observer(value);
+        },
+        subscriberCount: () => subscribers.size,
+    };
+}
+
+class HookProbeElement extends LitElement {
+    observable!: Observe<number>;
+    constructor() {
+        super();
+        attachDecorator(this, "render", withHooks);
+    }
+    render() {
+        const value = useObservable(this.observable);
+        return html`<span>${value ?? ""}</span>`;
+    }
+}
+customElements.define("hook-probe-element", HookProbeElement);
+
+describe("hook disposal on real DOM disconnect", () => {
+    it("tears down a useObservable subscription and stops requestUpdate when the element is removed", async () => {
+        const { observable, emit, subscriberCount } = createTrackedObservable();
+
+        const el = document.createElement("hook-probe-element") as HookProbeElement;
+        el.observable = observable;
+        document.body.appendChild(el);
+        await el.updateComplete;
+
+        // Mounted: the render subscribed exactly once.
+        expect(subscriberCount()).toBe(1);
+
+        // Track any requestUpdate that fires AFTER the element is removed.
+        let updatesAfterRemove = 0;
+        const originalRequestUpdate = el.requestUpdate.bind(el);
+        el.requestUpdate = (...args: Parameters<HookProbeElement["requestUpdate"]>) => {
+            updatesAfterRemove++;
+            originalRequestUpdate(...args);
+        };
+
+        el.remove();
+
+        // Disconnect ran the effect cleanup: the subscription is gone.
+        expect(subscriberCount()).toBe(0);
+
+        // A later emit reaches no leaked subscriber, so the detached element is
+        // never asked to update. Without the disposal fix, this would be >= 1.
+        emit(99);
+        expect(updatesAfterRemove).toBe(0);
+    });
+});

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

@@ -0,0 +1,94 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, it, expect, vi } from "vitest";
+import type { ReactiveController } from "lit";
+import type { Component } from "./component.js";
+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.
+ */
+class FakeHost extends EventTarget implements Component {
+    isConnected = true;
+    hookIndex = 0;
+    hooks: any[] = [];
+    updatedListeners = new Set<() => void>();
+    requestUpdate = vi.fn();
+    controllers: ReactiveController[] = [];
+
+    addController(controller: ReactiveController) {
+        this.controllers.push(controller);
+    }
+    // Simulate Lit dispatching lifecycle to every registered controller.
+    connect() {
+        for (const c of this.controllers) c.hostConnected?.();
+    }
+    disconnect() {
+        for (const c of this.controllers) c.hostDisconnected?.();
+    }
+}
+
+describe("installHooksController", () => {
+    it("disposes every effect hook and resets the cursor on disconnect", () => {
+        const host = new FakeHost();
+        const disposeA = vi.fn();
+        const disposeB = vi.fn();
+        host.hooks = [
+            { dispose: disposeA, dependencies: [] },
+            42, // a value slot (useState) — must be skipped, not crash
+            { dispose: disposeB, dependencies: [] },
+            { current: null }, // a ref slot — no dispose
+        ];
+        host.hookIndex = 4;
+
+        installHooksController(host);
+        host.disconnect();
+
+        expect(disposeA).toHaveBeenCalledTimes(1);
+        expect(disposeB).toHaveBeenCalledTimes(1);
+        expect(host.hooks).toEqual([]);
+        expect(host.hookIndex).toBe(0);
+    });
+
+    it("dispatches connected / disconnected events across the lifecycle", () => {
+        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();
+        expect(onDisconnected).toHaveBeenCalledTimes(1);
+    });
+
+    it("forces a re-render only on RE-connect, not the first connect", () => {
+        const host = new FakeHost();
+        installHooksController(host);
+
+        host.connect(); // first mount
+        expect(host.requestUpdate).not.toHaveBeenCalled();
+
+        host.disconnect();
+        host.connect(); // reconnect
+        expect(host.requestUpdate).toHaveBeenCalledTimes(1);
+    });
+
+    it("is idempotent — repeated installs register a single controller", () => {
+        const host = new FakeHost();
+        installHooksController(host);
+        installHooksController(host);
+        installHooksController(host);
+        expect(host.controllers).toHaveLength(1);
+    });
+
+    it("skips hosts that are not reactive controller hosts", () => {
+        const host = new EventTarget() as unknown as Component;
+        expect(() => installHooksController(host)).not.toThrow();
+    });
+});