@gtkx/react 1.2.2 → 1.4.0

package/src/prop-types.ts

@@ -3,7 +3,7 @@ import type * as Gdk from "@gtkx/gi/gdk";
 import type * as GLib from "@gtkx/gi/glib";
 import type * as GObject from "@gtkx/gi/gobject";
 import type * as Gtk from "@gtkx/gi/gtk";
-import type { ReactNode } from "react";
+import type { CSSProperties, ReactNode } from "react";
 
 /** One entry of a `GMenu`'s `items` prop; `submenu` and `section` nest further menus. */
 type MenuItem = {
@@ -95,12 +95,95 @@ type ChildrenProps = {
     children?: ReactNode;
 };
 
+/** Paint and typography declarations GTK4 CSS accepts, spelled the way React DOM spells them. */
+type StyleProperties = Pick<
+    CSSProperties,
+    | "animation" |
+    "animationDelay" |
+    "animationDirection" |
+    "animationDuration" |
+    "animationFillMode" |
+    "animationIterationCount" |
+    "animationName" |
+    "animationPlayState" |
+    "animationTimingFunction" |
+    "background" |
+    "backgroundClip" |
+    "backgroundColor" |
+    "backgroundImage" |
+    "backgroundOrigin" |
+    "backgroundPosition" |
+    "backgroundRepeat" |
+    "backgroundSize" |
+    "border" |
+    "borderBottom" |
+    "borderColor" |
+    "borderLeft" |
+    "borderRadius" |
+    "borderRight" |
+    "borderStyle" |
+    "borderTop" |
+    "borderWidth" |
+    "boxShadow" |
+    "caretColor" |
+    "color" |
+    "filter" |
+    "font" |
+    "fontFamily" |
+    "fontSize" |
+    "fontStyle" |
+    "fontVariant" |
+    "fontWeight" |
+    "letterSpacing" |
+    "lineHeight" |
+    "margin" |
+    "marginBottom" |
+    "marginLeft" |
+    "marginRight" |
+    "marginTop" |
+    "minHeight" |
+    "minWidth" |
+    "opacity" |
+    "outline" |
+    "outlineColor" |
+    "outlineOffset" |
+    "outlineStyle" |
+    "outlineWidth" |
+    "padding" |
+    "paddingBottom" |
+    "paddingLeft" |
+    "paddingRight" |
+    "paddingTop" |
+    "textDecoration" |
+    "textDecorationColor" |
+    "textDecorationLine" |
+    "textDecorationStyle" |
+    "textShadow" |
+    "textTransform" |
+    "transform" |
+    "transformOrigin" |
+    "transition" |
+    "transitionDelay" |
+    "transitionDuration" |
+    "transitionProperty" |
+    "transitionTimingFunction"
+>;
+
+/**
+ * Style declarations for one widget. A key starting with `&` nests a block under a selector derived from
+ * it, such as `"&:hover"` or `"& label"`. GTK4 CSS covers paint and typography only, so layout properties
+ * such as `display`, `width` and `gap` are deliberately absent; use the widget's own layout props instead.
+ */
+type Style = StyleProperties & Partial<Record<`&${string}`, StyleProperties>>;
+
 /** Objects a widget takes through a method call rather than a property. */
 type GtkWidgetProps = {
     /** `Gtk.EventController` elements added to the widget. */
     controllers?: ReactNode | null | undefined;
     /** `Gio.ActionGroup` elements inserted into the widget, each under its own `prefix`. */
     actionGroups?: ReactNode | null | undefined;
+    /** Style declarations applied to this widget alone, outranking any class in `cssClasses`. */
+    style?: Style | null | undefined;
 } & ChildrenProps;
 
 /** Props of an action group placed in a widget's `actionGroups` slot. */
@@ -163,6 +246,15 @@ type GtkScaleProps = {
     marks?: ScaleMark[] | null | undefined;
 };
 
+/** Props of a `Gtk.ListBox` element. */
+type GtkListBoxProps = {
+    /**
+     * Index of the row to select; `-1` or `null` selects none. Applied once the row exists, and
+     * re-applied whenever the box's own selection drifts from it. Left alone while the prop is absent.
+     */
+    selectedIndex?: number | null | undefined;
+} & ChildrenProps;
+
 /** Props of a `Gtk.Calendar` element. */
 type GtkCalendarProps = {
     /** Days of the shown month drawn as marked, cleared and re-marked whenever the list changes. */
@@ -230,6 +322,8 @@ export {
     type DragSourceIcon,
     type ChildrenProps,
     type GtkWidgetProps,
+    type Style,
+    type StyleProperties,
     type ActionGroupProps,
     type ActionMapProps,
     type MenuProps,
@@ -239,6 +333,7 @@ export {
     type GtkConstraintLayoutProps,
     type GtkHeaderBarProps,
     type GtkScaleProps,
+    type GtkListBoxProps,
     type GtkCalendarProps,
     type GtkLevelBarProps,
     type GtkSizeGroupProps,

package/src/reconciler/apply-props.ts

@@ -1,10 +1,11 @@
-import type * as GObject from "@gtkx/gi/gobject";
 import type { SignalHandler } from "@gtkx/runtime";
+import * as GObject from "@gtkx/gi/gobject";
 import * as Gtk from "@gtkx/gi/gtk";
-import { drain, isDeepEqual, kebabCase } from "@gtkx/utils";
+import { coerceObjectProperty, getInstanceType, signalForHandlerName, TYPE_INVALID } from "@gtkx/runtime";
+import { drain, isDeepEqual, kebabCase, lowerFirst, unsanitizeIdentifier } from "@gtkx/utils";
 import type { ElementBehavior, Props } from "./registry.js";
 import { applyAccessibleProps, isAccessibleProp } from "../utils/accessible-props.js";
-import { type TypeInfo, typeInfoFor } from "./metadata.js";
+import { getPropertyName, hasProperty, type TypeInfo, typeInfoFor } from "./metadata.js";
 import { type ElementNode, getOrCreateContext, type SignalTarget } from "./node.js";
 import { applyWrite, connectHandler, disconnectHandler } from "./signals.js";
 import { bufferText, hasSameText, isContentPaintableProp, markTextDirty, TEXT_PROP } from "./text.js";
@@ -15,29 +16,53 @@ type PropChange = { prev: Props; next: Props };
 
 const REACT_RESERVED_PROPS = new Set(["children", "ref", "key"]);
 const NOTIFY_PREFIX = "onNotify";
-const HANDLER_PREFIX = "on";
 const HANDLER_NAME = /^on[A-Z]/;
 const flushDirty: Set<ElementNode> = new Set();
 const accessibleDirty: Map<ElementNode, Props> = new Map();
-const mapWatched: WeakSet<ElementNode> = new WeakSet();
+const mapWatched: WeakMap<ElementNode, () => void> = new WeakMap();
 const pendingMap: Set<ElementNode> = new Set();
 
 const isHandlerName = (name: string): boolean => HANDLER_NAME.test(name);
+const notifiedAccessor = (name: string): string => lowerFirst(name.slice(NOTIFY_PREFIX.length));
 
-const signalForProp = (info: TypeInfo, name: string): string => {
+const unknownSignalError = (typeName: string, name: string): Error =>
+    new Error(
+        `The handler prop '${name}' of <${typeName}> names no signal ${typeName} carries. Name a ` +
+        `signal the element carries, or declare the one '${name}' stands for on ${typeName} when ` +
+        "its class is registered.",
+    );
+
+const lookedUpSignal = (target: SignalTarget, name: string): string => {
+    const type = getInstanceType(target.object);
+    const signal = type === TYPE_INVALID ? undefined : signalForHandlerName(type, name);
+
+    if (signal === undefined) {
+        throw unknownSignalError(target.typeName, name);
+    }
+
+    return signal;
+};
+
+const signalForProp = (target: SignalTarget, info: TypeInfo, name: string): string => {
     if (name === NOTIFY_PREFIX) {
         return "notify";
     }
 
     if (name.startsWith(NOTIFY_PREFIX) && name.length > NOTIFY_PREFIX.length) {
-        return `notify::${kebabCase(name.slice(NOTIFY_PREFIX.length))}`;
+        const accessor = notifiedAccessor(name);
+        const property = getPropertyName(target.object, accessor) ?? unsanitizeIdentifier(kebabCase(accessor));
+
+        return `notify::${property}`;
     }
 
-    return info.signals[name] ?? kebabCase(name.slice(HANDLER_PREFIX.length));
+    return info.signals[name] ?? lookedUpSignal(target, name);
 };
 
 const isReservedName = (name: string, info: TypeInfo): boolean =>
-    REACT_RESERVED_PROPS.has(name) || isHandlerName(name) || isAccessibleProp(name) || info.constructOnly.has(name);
+    REACT_RESERVED_PROPS.has(name) ||
+    (isHandlerName(name) && !hasProperty(info, name)) ||
+    (isAccessibleProp(name) && !hasProperty(info, name)) ||
+    info.constructOnly.has(name);
 
 const isSkippedValueName = (name: string, info: TypeInfo, consumed: Set<string>): boolean =>
     isReservedName(name, info) || consumed.has(name);
@@ -47,8 +72,8 @@ const writeValue = (object: GObject.Object, name: string, value: unknown): void
         return;
     }
 
-    applyWrite(() => {
-        Reflect.set(object, name, value);
+    applyWrite(name, () => {
+        Reflect.set(object, name, coerceObjectProperty(object, name, value));
     });
 };
 
@@ -71,7 +96,7 @@ const applyBufferText = (buffer: Gtk.TextBuffer, text: string): void => {
         return;
     }
 
-    applyWrite(() => {
+    applyWrite(TEXT_PROP, () => {
         buffer.beginIrreversibleAction();
         buffer.setText(text, -1);
         buffer.endIrreversibleAction();
@@ -190,24 +215,26 @@ const restoreActionableSensitivity = (node: ElementNode, info: TypeInfo, prev: P
     const desired = "sensitive" in next ? next.sensitive : info.defaults.sensitive;
 
     if (typeof desired === "boolean") {
-        applyWrite(() => {
+        applyWrite("sensitive", () => {
             Reflect.set(node.object, "sensitive", desired);
         });
     }
 };
 
-const applyHandlers = (target: SignalTarget, info: TypeInfo, prev: Props, next: Props): void => {
-    eachChangedName(prev, next, (name) => {
-        if (!isHandlerName(name)) {
-            return;
-        }
+const applyHandler = (target: SignalTarget, info: TypeInfo, name: string, next: Props): void => {
+    const value = next[name];
 
-        const value = next[name];
+    if (typeof value === "function") {
+        connectHandler(target, name, signalForProp(target, info, name), value as SignalHandler);
+    } else {
+        disconnectHandler(target, name);
+    }
+};
 
-        if (typeof value === "function") {
-            connectHandler(target, name, signalForProp(info, name), value as SignalHandler);
-        } else {
-            disconnectHandler(target, name);
+const applyHandlers = (target: SignalTarget, info: TypeInfo, prev: Props, next: Props): void => {
+    eachChangedName(prev, next, (name) => {
+        if (isHandlerName(name) && !hasProperty(info, name)) {
+            applyHandler(target, info, name, next);
         }
     });
 };
@@ -230,6 +257,15 @@ const flushBehaviors = (): void => {
     });
 };
 
+const teardownBehaviors = (node: ElementNode): void => {
+    flushDirty.delete(node);
+    unwatchMap(node);
+
+    for (const [behavior, context] of node.contexts) {
+        behavior.teardown?.(node.object, context);
+    }
+};
+
 const applyAccessible = (object: GObject.Object, prev: Props | null, next: Props): void => {
     if (object instanceof Gtk.Accessible) {
         applyAccessibleProps(object, prev, next);
@@ -259,14 +295,25 @@ const watchMap = (node: ElementNode): void => {
         return;
     }
 
-    mapWatched.add(node);
-
-    object.connect("map", () => {
+    const onMapped = (): undefined => {
         pendingMap.add(node);
         setTimeout(settleAccessible, 0);
+    };
+
+    object.on("map", onMapped);
+
+    mapWatched.set(node, () => {
+        object.off("map", onMapped);
     });
 };
 
+const unwatchMap = (node: ElementNode): void => {
+    mapWatched.get(node)?.();
+    mapWatched.delete(node);
+    pendingMap.delete(node);
+    accessibleDirty.delete(node);
+};
+
 const settleAccessible = (): void => {
     drain(pendingMap, (node) => {
         if (node.object instanceof Gtk.Widget && node.object.getMapped()) {
@@ -318,6 +365,7 @@ export {
     flushAccessible,
     settleAccessible,
     flushBehaviors,
+    teardownBehaviors,
     applyElementProps,
     applyAdoptedProps,
     assertPropsCanChange,

package/src/reconciler/behaviors.ts

@@ -10,8 +10,9 @@ import {
     typeFromName,
     typeIsA,
 } from "@gtkx/runtime";
-import { getOrInsert, isDeepEqual, structuredClone } from "@gtkx/utils";
+import { getOrInsert, isDeepEqual, kebabCase, structuredClone, unsanitizeIdentifier } from "@gtkx/utils";
 import type { DetachInfo, ElementBehavior, PlaceInfo, Props } from "./registry.js";
+import { getPropertyName } from "./metadata.js";
 import { applyWrite } from "./signals.js";
 import { hasSameText } from "./text.js";
 
@@ -32,7 +33,7 @@ type ListHooks<P extends GObject.Object, I, H> = {
 
 type ListEntry = { item: unknown; handle: unknown };
 type ListState = { snapshot: unknown[]; entries: ListEntry[] };
-type DeferredState = { desired: unknown; isPresent: boolean; applied: unknown };
+type DeferredState = { desired: unknown; isPresent: boolean; isScheduled: boolean; disconnect: (() => void) | null };
 type CanApply<P extends GObject.Object, V> = (object: P, value: V) => boolean;
 type ChildSetter = GObject.Object & { setChild: (child: Gtk.Widget | null) => void };
 type ContentSetter<C extends Gtk.Widget> = GObject.Object & { setContent: (content: C | null) => void };
@@ -170,15 +171,13 @@ const list = <P extends GObject.Object, I, H = void>(
     return behavior;
 };
 
-const flushDeferred = <P extends GObject.Object, V>(
+const settleDeferred = <P extends GObject.Object, V>(
     object: GObject.Object,
-    context: unknown,
+    state: DeferredState,
     prop: string,
     canApply: CanApply<P, V> | undefined,
 ): void => {
-    const state = context as DeferredState;
-
-    if (!state.isPresent || Object.is(state.applied, state.desired)) {
+    if (!state.isPresent || Object.is(Reflect.get(object, prop), state.desired)) {
         return;
     }
 
@@ -186,11 +185,53 @@ const flushDeferred = <P extends GObject.Object, V>(
         return;
     }
 
-    applyWrite(() => {
+    applyWrite(prop, () => {
         Reflect.set(object, prop, state.desired);
     });
+};
+
+const scheduleSettle = <P extends GObject.Object, V>(
+    object: GObject.Object,
+    state: DeferredState,
+    prop: string,
+    canApply: CanApply<P, V> | undefined,
+): void => {
+    if (state.isScheduled) {
+        return;
+    }
+
+    state.isScheduled = true;
+
+    queueMicrotask(() => {
+        state.isScheduled = false;
+
+        if (state.disconnect !== null) {
+            settleDeferred(object, state, prop, canApply);
+        }
+    });
+};
 
-    state.applied = state.desired;
+const watchDrift = <P extends GObject.Object, V>(
+    object: GObject.Object,
+    state: DeferredState,
+    prop: string,
+    canApply: CanApply<P, V> | undefined,
+): void => {
+    if (state.disconnect !== null) {
+        return;
+    }
+
+    const signal = `notify::${getPropertyName(object, prop) ?? unsanitizeIdentifier(kebabCase(prop))}`;
+
+    const handler = (): undefined => {
+        scheduleSettle(object, state, prop, canApply);
+    };
+
+    object.on(signal, handler);
+
+    state.disconnect = (): void => {
+        object.off(signal, handler);
+    };
 };
 
 const deferred = <P extends GObject.Object, V>(
@@ -198,7 +239,7 @@ const deferred = <P extends GObject.Object, V>(
     canApply?: CanApply<P, V>,
 ): ElementBehavior<P> => ({
     deferred: [prop],
-    initialize: (): DeferredState => ({ desired: undefined, isPresent: false, applied: undefined }),
+    initialize: (): DeferredState => ({ desired: undefined, isPresent: false, isScheduled: false, disconnect: null }),
     update: (_object, _prev, next, context) => {
         const state = context as DeferredState;
         state.desired = next[prop];
@@ -207,14 +248,21 @@ const deferred = <P extends GObject.Object, V>(
         return [prop];
     },
     flush: (object, context) => {
-        flushDeferred(object, context, prop, canApply);
+        const state = context as DeferredState;
+        settleDeferred(object, state, prop, canApply);
+        watchDrift(object, state, prop, canApply);
+    },
+    teardown: (_object, context) => {
+        const state = context as DeferredState;
+        state.disconnect?.();
+        state.disconnect = null;
     },
 });
 
 const controlledText = (prop: string): ElementBehavior =>
     value(prop, (object, next) => {
         if (!hasSameText(object, prop, next)) {
-            applyWrite(() => {
+            applyWrite(prop, () => {
                 Reflect.set(object, prop, next);
             });
         }

package/src/reconciler/host-config.ts

@@ -14,6 +14,7 @@ import {
     assertPropsCanChange,
     flushAccessible,
     flushBehaviors,
+    teardownBehaviors,
 } from "./apply-props.js";
 import { attachChild, detachChild } from "./child-routing.js";
 import { resolveElementNode } from "./instance.js";
@@ -31,6 +32,7 @@ import {
 } from "./node.js";
 import { isRootElement, type RootElement } from "./root-element.js";
 import { disconnectAllHandlers } from "./signals.js";
+import { releaseStyle } from "./style.js";
 import {
     didUpdateTextSurgically,
     enclosingHost,
@@ -133,7 +135,7 @@ const hostConfig = {
     unhideTextInstance: (): void => undefined,
     detachDeletedInstance: (instance: Instance): void => {
         if (instance.kind === ELEMENT_KIND) {
-            disconnectAllHandlers(instance);
+            detachElement(instance);
         } else if (instance.kind === LAZY_KIND && instance.adopted !== null) {
             disconnectAllHandlers(lazyTarget(instance, instance.adopted));
         }
@@ -160,7 +162,7 @@ const hostConfig = {
     suspendInstance: (): void => undefined,
     waitForCommitToBeReady: (): null => null,
     NotPendingTransition: null,
-    HostTransitionContext: createContext(null) as unknown as ReactReconciler.ReactContext<null>,
+    HostTransitionContext: createContext(null),
 };
 
 const reconciler: ReactReconciler.Reconciler<Container, Instance, TextNode, unknown, unknown, object> =
@@ -187,6 +189,15 @@ function createPriorityTracker(): PriorityTracker {
     };
 }
 
+const detachElement = (instance: ElementNode): void => {
+    disconnectAllHandlers(instance);
+    teardownBehaviors(instance);
+
+    if (instance.object instanceof Gtk.Widget) {
+        releaseStyle(instance.object);
+    }
+};
+
 const updateInstance = (instance: Instance, prev: Props, next: Props): void => {
     if (instance.kind === ELEMENT_KIND) {
         assertPropsCanChange(instance.typeName, prev, next);

package/src/reconciler/metadata.ts

@@ -1,10 +1,21 @@
-import { TYPE_INVALID, typeFromName, typeInterfaces, typeName, typeParent } from "@gtkx/runtime";
+import type * as GObject from "@gtkx/gi/gobject";
+import {
+    type AnyClass,
+    getClassType,
+    getDeclaredPropertyName,
+    TYPE_INVALID,
+    typeFromName,
+    typeInterfaces,
+    typeName,
+    typeParent,
+} from "@gtkx/runtime";
 import { getOrInsert } from "@gtkx/utils";
-import { constructOnlyProps, constructProps, defaultProps, signals, userEventSignals } from "virtual:gtkx-config";
+import { properties, type PropertyEntry, signals, userEventSignals } from "virtual:gtkx-config";
 import { deferredProps, type ElementBehavior, ELEMENTS } from "./registry.js";
 
 type TypeInfo = {
     typeName: string;
+    properties: Record<string, PropertyEntry>;
     signals: Record<string, string>;
     userEventSignals: Set<string>;
     behaviors: ElementBehavior[];
@@ -17,6 +28,12 @@ type TypeInfo = {
     defaults: Record<string, unknown>;
 };
 
+const WRITABLE = 2;
+const CONSTRUCT = 4;
+const CONSTRUCT_ONLY = 8;
+const NAME = 0;
+const FLAGS = 1;
+const DEFAULT_VALUE = 2;
 const ancestryCache: Map<string, string[]> = new Map();
 const typeInfoCache: Map<string, TypeInfo> = new Map();
 
@@ -60,11 +77,29 @@ const addAll = <T>(target: Set<T>, source: Iterable<T> | undefined): void => {
 const accumulateAncestor = (info: TypeInfo, ancestor: string): void => {
     Object.assign(info.signals, signals[ancestor] ?? {});
     addAll(info.userEventSignals, userEventSignals[ancestor]);
-    addAll(info.constructOnly, constructOnlyProps[ancestor]);
-    addAll(info.construct, constructProps[ancestor]);
     info.behaviors.push(...(ELEMENTS[ancestor]?.behaviors ?? []));
 };
 
+const resolveProperty = (info: TypeInfo, name: string, entry: PropertyEntry): void => {
+    if ((entry[FLAGS] & CONSTRUCT_ONLY) !== 0) {
+        info.constructOnly.add(name);
+    }
+
+    if ((entry[FLAGS] & (WRITABLE | CONSTRUCT | CONSTRUCT_ONLY)) !== 0) {
+        info.construct.add(name);
+    }
+
+    if (entry.length > DEFAULT_VALUE) {
+        info.defaults[name] = entry[DEFAULT_VALUE];
+    }
+};
+
+const resolveProperties = (info: TypeInfo): void => {
+    for (const [name, entry] of Object.entries(info.properties)) {
+        resolveProperty(info, name, entry);
+    }
+};
+
 const applyBehaviorFlags = (info: TypeInfo, behavior: ElementBehavior): void => {
     if (behavior.flush !== undefined) {
         info.hasFlush = true;
@@ -85,6 +120,7 @@ const buildTypeInfo = (name: string): TypeInfo => {
 
     const info: TypeInfo = {
         typeName: name,
+        properties: {},
         signals: {},
         userEventSignals: new Set(),
         behaviors: [],
@@ -105,12 +141,32 @@ const buildTypeInfo = (name: string): TypeInfo => {
     info.isLazy = chain.some((ancestor) => ELEMENTS[ancestor]?.isLazy === true);
 
     for (const ancestor of chain.toReversed()) {
-        Object.assign(info.defaults, defaultProps[ancestor] ?? {});
+        Object.assign(info.properties, properties[ancestor] ?? {});
     }
 
+    resolveProperties(info);
+
     return info;
 };
 
 const typeInfoFor = (name: string): TypeInfo => getOrInsert(typeInfoCache, name, buildTypeInfo);
 
-export { typeInfoFor, type TypeInfo };
+const getTypeInfo = (object: GObject.Object): TypeInfo | undefined => {
+    const name = typeName(getClassType(object.constructor as AnyClass));
+
+    return name === null ? undefined : typeInfoFor(name);
+};
+
+const hasProperty = (info: TypeInfo, accessor: string): boolean => Object.hasOwn(info.properties, accessor);
+
+const propertyNameFor = (info: TypeInfo, accessor: string): string | undefined =>
+    info.properties[accessor]?.[NAME];
+
+const getPropertyName = (object: GObject.Object, accessor: string): string | undefined => {
+    const info = getTypeInfo(object);
+
+    return (info === undefined ? undefined : propertyNameFor(info, accessor)) ??
+        getDeclaredPropertyName(object, accessor);
+};
+
+export { getPropertyName, hasProperty, typeInfoFor, type TypeInfo };

package/src/reconciler/placement.ts

@@ -15,7 +15,7 @@ import {
     type PlaceableNode,
     type PlacedChild,
 } from "./node.js";
-import { applyWrite } from "./signals.js";
+import { applyMutation, applyWrite } from "./signals.js";
 import { markTextDirty } from "./text.js";
 
 type AttachContext = { parent: ElementNode; entry: PlacedChild; index: number; sibling: GObject.Object | null };
@@ -78,7 +78,7 @@ const wireBufferView = (node: PlaceableNode, parent: ElementNode): void => {
 };
 
 const writeSlot = (parent: ElementNode, entry: PlacedChild, value: GObject.Object | null): void => {
-    applyWrite(() => {
+    applyWrite(entry.slot, () => {
         Reflect.set(parent.object, entry.slot, value);
     });
 };
@@ -135,7 +135,7 @@ const runAttach = (parent: ElementNode, entry: PlacedChild, index: number, sibli
 };
 
 const attachEntry = (parent: ElementNode, entry: PlacedChild, index: number, sibling: GObject.Object | null): void => {
-    applyWrite(() => {
+    applyMutation(() => {
         runAttach(parent, entry, index, sibling);
     });
 };
@@ -160,7 +160,7 @@ const runDetach = (parent: ElementNode, entry: PlacedChild): void => {
 };
 
 const detachEntry = (parent: ElementNode, entry: PlacedChild): void => {
-    applyWrite(() => {
+    applyMutation(() => {
         runDetach(parent, entry);
     });
 };

package/src/reconciler/registry.ts

@@ -54,6 +54,8 @@ type ElementBehavior<T extends GObject.Object = GObject.Object> = {
     update?: (object: T, prev: Props, next: Props, context: unknown) => Iterable<string> | undefined;
     /** Runs after the commit that touched the node, once every child has been placed. */
     flush?: (object: T, context: unknown) => void;
+    /** Releases whatever `initialize` or a later hook acquired, once the node is destroyed. */
+    teardown?: (object: T, context: unknown) => void;
     /** Props to withhold from the constructor, leaving them for a later hook to apply. */
     deferred?: string[];
     /**

package/src/reconciler/root.ts

@@ -171,7 +171,7 @@ const quit = (): typeof Gdk.EVENT_PROPAGATE | typeof Gdk.EVENT_STOP => {
  * @param container The GObject to render into, or {@link rootElement} to render at the top level.
  */
 const createPortal = (children: ReactNode, container: Container, key?: string): ReactPortal =>
-    reconciler.createPortal(children, container, null, key ?? null) as unknown as ReactPortal;
+    reconciler.createPortal(children, container, null, key ?? null);
 
 export {
     setReconcilerErrorHandler,