Use FinalizationRegistry to unmount trees for garbage-collected root nodes

src/crank.ts

@@ -905,9 +905,28 @@ export class Renderer<
 	 */
 	declare cache: WeakMap<object, Retainer<TNode, TScope>>;
 	declare adapter: RenderAdapter<TNode, TScope, TRoot, TResult>;
+	/**
+	 * @internal
+	 * FinalizationRegistry to automatically unmount when root nodes are garbage collected.
+	 */
+	declare registry:
+		| FinalizationRegistry<{
+				adapter: RenderAdapter<TNode, TScope, TRoot, TResult>;
+				ret: Retainer<TNode, TScope>;
+		  }>
+		| undefined;
 	constructor(adapter: Partial<RenderAdapter<TNode, TScope, TRoot, TResult>>) {
 		this.cache = new WeakMap();
 		this.adapter = {...defaultAdapter, ...adapter};
+		// Only create FinalizationRegistry if it's available (not in all environments)
+		if (typeof FinalizationRegistry !== "undefined") {
+			this.registry = new FinalizationRegistry(({adapter, ret}) => {
+				// Check if the retainer hasn't already been unmounted
+				if (!getFlag(ret, IsUnmounted)) {
+					unmount(adapter, ret, ret.ctx, ret, false);
+				}
+			});
+		}
 	}
 
 	/**
@@ -989,6 +1008,10 @@ function getRootRetainer<
 		// remember that typeof null === "object"
 		if (typeof root === "object" && root !== null && children != null) {
 			renderer.cache.set(root, ret);
+			// Register root node for automatic unmounting when garbage collected
+			if (renderer.registry) {
+				renderer.registry.register(root, {adapter, ret}, ret);
+			}
 		}
 	} else if (ret.ctx !== bridgeCtx) {
 		throw new Error(
@@ -998,6 +1021,10 @@ function getRootRetainer<
 		ret.el = createElement(Portal, {children, root, hydrate});
 		if (typeof root === "object" && root !== null && children == null) {
 			renderer.cache.delete(root);
+			// Unregister from FinalizationRegistry when explicitly unmounting
+			if (renderer.registry) {
+				renderer.registry.unregister(ret);
+			}
 		}
 	}
 

test/finalization.tsx

@@ -0,0 +1,130 @@
+import {createElement} from "../src/crank.js";
+import {renderer} from "../src/dom.js";
+import {suite} from "uvu";
+import * as Assert from "uvu/assert";
+
+const test = suite("finalization");
+
+test.skip("automatic unmount on garbage collection", async () => {
+	// Note: This test is difficult to write reliably because garbage collection
+	// timing is non-deterministic. We're skipping it but keeping it here to
+	// document the expected behavior.
+
+	let unmounted = false;
+
+	function* Component() {
+		try {
+			while (true) {
+				yield <div>Hello</div>;
+			}
+		} finally {
+			unmounted = true;
+		}
+	}
+
+	// Create a root element that we can garbage collect
+	let root: HTMLDivElement | null = document.createElement("div");
+	document.body.appendChild(root);
+
+	// Render component
+	renderer.render(<Component />, root);
+	Assert.is(root.innerHTML, "<div>Hello</div>");
+	Assert.is(unmounted, false);
+
+	// Remove root from DOM and clear reference
+	document.body.removeChild(root);
+	root = null;
+
+	// Force garbage collection (this is not standard and won't work in all environments)
+	// In a real browser environment, we'd need to wait for GC to happen naturally
+	if ((globalThis as any).gc) {
+		(globalThis as any).gc();
+		// Even with explicit gc(), FinalizationRegistry callbacks are async
+		await new Promise((resolve) => setTimeout(resolve, 100));
+		Assert.is(unmounted, true);
+	}
+});
+
+test("manual unmount still works", () => {
+	let unmounted = false;
+
+	function* Component() {
+		try {
+			while (true) {
+				yield <div>Hello</div>;
+			}
+		} finally {
+			unmounted = true;
+		}
+	}
+
+	const root = document.createElement("div");
+	document.body.appendChild(root);
+
+	// Render component
+	renderer.render(<Component />, root);
+	Assert.is(root.innerHTML, "<div>Hello</div>");
+	Assert.is(unmounted, false);
+
+	// Manual unmount by rendering null
+	renderer.render(null, root);
+	Assert.is(root.innerHTML, "");
+	Assert.is(unmounted, true);
+
+	document.body.removeChild(root);
+});
+
+test("FinalizationRegistry is used when available", () => {
+	// Simply verify that the registry property exists on the renderer
+	// when FinalizationRegistry is available
+	if (typeof FinalizationRegistry !== "undefined") {
+		Assert.ok(renderer.registry instanceof FinalizationRegistry);
+	} else {
+		Assert.is(renderer.registry, undefined);
+	}
+});
+
+test("multiple roots can be tracked independently", () => {
+	const unmountedRoots: string[] = [];
+
+	function* Component({id}: {id: string}) {
+		try {
+			while (true) {
+				yield <div>Component {id}</div>;
+			}
+		} finally {
+			unmountedRoots.push(id);
+		}
+	}
+
+	const root1 = document.createElement("div");
+	const root2 = document.createElement("div");
+	document.body.appendChild(root1);
+	document.body.appendChild(root2);
+
+	// Render to both roots
+	renderer.render(<Component id="1" />, root1);
+	renderer.render(<Component id="2" />, root2);
+
+	Assert.is(root1.innerHTML, "<div>Component 1</div>");
+	Assert.is(root2.innerHTML, "<div>Component 2</div>");
+	Assert.equal(unmountedRoots, []);
+
+	// Unmount first root
+	renderer.render(null, root1);
+	Assert.is(root1.innerHTML, "");
+	Assert.equal(unmountedRoots, ["1"]);
+
+	// Second root should still be mounted
+	Assert.is(root2.innerHTML, "<div>Component 2</div>");
+
+	// Unmount second root
+	renderer.render(null, root2);
+	Assert.is(root2.innerHTML, "");
+	Assert.equal(unmountedRoots, ["1", "2"]);
+
+	document.body.removeChild(root1);
+	document.body.removeChild(root2);
+});
+
+test.run();