@gtkx/react 1.0.0-rc.2 → 1.0.0-rc.4

package/src/hooks/use-bind-setting.ts

@@ -6,22 +6,23 @@ import type { SettingsSchema, SettingsSchemaKeys } from "../utils/settings.js";
 import { type RefProp, resolveRefProp } from "../utils/ref-prop.js";
 import { useSettings } from "./use-setting.js";
 
+/** Options for {@link useBindSetting}. */
 type UseBindSettingOptions<K extends SettingsSchemaKeys> = {
+    /** Schema the settings object is opened from. */
     schema: SettingsSchema<K>;
+    /** Key of that schema to bind. */
     key: keyof K & string;
+    /** Object holding the property, given directly or as a ref; nothing is bound while it is absent. */
     object: RefProp<GObject.Object>;
+    /** camelCase name of the property to keep in sync with the key. */
     property: string;
+    /** Direction and conversion behavior of the bind; defaults to `Gio.SettingsBindFlags.DEFAULT`. */
     flags?: Gio.SettingsBindFlags;
 };
 
 /**
- * Binds a GSettings key to a property of a GObject, keeping the two in sync for the object's lifetime.
- *
- * @param options.schema The schema reference identifying the settings backend.
- * @param options.key The key within the schema to bind.
- * @param options.object The GObject whose property is bound to the setting.
- * @param options.property The name of the object property to bind.
- * @param options.flags Flags controlling the binding's direction and behaviour.
+ * Binds a GSettings key to a property of a GObject, keeping the two in sync until the component unmounts.
+ * `property` is given in camelCase, and `flags` defaults to `Gio.SettingsBindFlags.DEFAULT`, a two-way bind.
  */
 function useBindSetting<K extends SettingsSchemaKeys>({
     schema,

package/src/hooks/use-parent-window.ts

@@ -4,7 +4,9 @@ import { type Context, createContext, use } from "react";
 const ParentWindowContext: Context<Gtk.Window | null> = createContext<Gtk.Window | null>(null);
 
 /**
- * Returns the `Gtk.Window` provided by the nearest window ancestor, or `null` when there is none.
+ * Returns the `Gtk.Window` of the nearest window ancestor. This is `null` on the first render even inside a
+ * window, because a window provides itself only once its GObject exists, and stays `null` outside one. The
+ * component re-renders when it resolves, so derive from the value rather than reading it once.
  */
 const useParentWindow = (): Gtk.Window | null => use(ParentWindowContext);
 

package/src/hooks/use-property.ts

@@ -4,14 +4,14 @@ import type { RefProp } from "../utils/ref-prop.js";
 import { useObjectValue } from "./use-object-value.js";
 
 type Properties<T extends GObject.Object> = NonNullable<T["__properties__"]>;
+/** Every property `T` declares that is also readable off the instance, in camelCase. */
 type PropertyName<T extends GObject.Object> = keyof Properties<T> & keyof T;
 
 /**
  * Subscribes to a GObject property and returns its current value, re-rendering when the property changes.
  *
- * @param object The GObject (or ref to one) whose property to observe.
  * @param propertyName The camelCase name of a readable property on the object.
- * @returns The current property value, or `undefined` when the object is not resolved.
+ * @returns The current value, or `undefined` while the object is null or an unresolved ref.
  */
 function useProperty<T extends GObject.Object, P extends PropertyName<T>>(
     object: RefProp<T>,

package/src/hooks/use-setting.ts

@@ -16,9 +16,8 @@ const useSettings = <K extends SettingsSchemaKeys>({ id, path }: UseSettingsProp
 /**
  * Reads and writes a single key of a GSettings schema, re-rendering when the stored value changes.
  *
- * @param schema The schema reference identifying the settings backend.
- * @param key The key within the schema to read and write.
- * @returns A tuple of the current value and a setter that persists a new value.
+ * @returns The current value, and a setter that writes a new one back to GSettings.
+ * @throws When the key is not declared in the schema.
  */
 function useSetting<K extends SettingsSchemaKeys, P extends keyof K>(
     schema: SettingsSchema<K>,

package/src/hooks/use-signal.ts

@@ -4,8 +4,13 @@ import { useEffectEvent, useLayoutEffect } from "react";
 import { type RefProp, resolveRefProp } from "../utils/ref-prop.js";
 
 type Signals<T extends GObject.Object> = NonNullable<T["__signals__"]>;
+/** Every signal name `T` declares, on its own or narrowed by a `::detail` suffix. */
 type SignalName<T extends GObject.Object> = keyof Signals<T> | `${keyof Signals<T> & string}::${string}`;
 
+/**
+ * The handler signature `T` declares for signal `S`, looked up through any `::detail` suffix and
+ * falling back to an untyped `SignalHandler` when the object declares no such signal.
+ */
 type TypedSignalHandler<T extends GObject.Object, S extends string> = S extends keyof Signals<T>
     ? Signals<T>[S]
     : S extends `${infer TBase}::${string}`
@@ -14,9 +19,12 @@ type TypedSignalHandler<T extends GObject.Object, S extends string> = S extends
             : SignalHandler
         : SignalHandler;
 
+/** Options for {@link useSignal}. */
 type UseSignalOptions = {
-    after?: boolean;
-    immediate?: boolean;
+    /** Runs the handler after the object's own default handler rather than before it. */
+    isAfter?: boolean;
+    /** Invokes the handler once, with no arguments, as soon as the signal is connected. */
+    isImmediate?: boolean;
 };
 
 /**
@@ -25,16 +33,18 @@ type UseSignalOptions = {
  * Each emission runs the handler from the latest render, so it does not have to be stable and a
  * changing handler never reconnects the signal.
  *
- * @param object The GObject (or ref to one) to connect to.
- * @param signal The signal name, optionally with a detail suffix.
- * @param handler The callback invoked when the signal is emitted.
- * @param options Connection options such as running after the default handler or invoking immediately.
+ * On React 19.2 this does not hold inside a component wrapped in `memo` or `forwardRef`, where every emission
+ * runs the handler captured on the first render. Keep the calling component unwrapped, or read the values the
+ * handler needs off the GObject itself. React fixes this on the 19.3 line.
+ *
+ * @param signal The signal name, optionally with a `::detail` suffix.
+ * @param options `isAfter` runs the handler after the default handler; `isImmediate` also invokes it on connect.
  */
 function useSignal<T extends GObject.Object, S extends SignalName<T> & string>(
     object: RefProp<T>,
     signal: S,
     handler: TypedSignalHandler<T, S>,
-    { after = false, immediate = false }: UseSignalOptions = {},
+    { isAfter = false, isImmediate = false }: UseSignalOptions = {},
 ): void {
     const emit = useEffectEvent(handler as SignalHandler);
 
@@ -45,16 +55,16 @@ function useSignal<T extends GObject.Object, S extends SignalName<T> & string>(
             return;
         }
 
-        resolved.on(signal, emit, after);
+        resolved.on(signal, emit, isAfter);
 
-        if (immediate) {
+        if (isImmediate) {
             emit();
         }
 
         return () => {
             resolved.off(signal, emit);
         };
-    }, [object, signal, after, immediate]);
+    }, [object, signal, isAfter, isImmediate]);
 }
 
 export { useSignal, type SignalName, type TypedSignalHandler };

package/src/index.ts

@@ -1,14 +1,22 @@
 import "./bootstrap.js";
 
+/** @public */
 export { useApplication } from "./hooks/use-application.js";
+/** @public */
 export { useBindSetting } from "./hooks/use-bind-setting.js";
+/** @public */
 export { useParentWindow } from "./hooks/use-parent-window.js";
+/** @public */
 export { useProperty } from "./hooks/use-property.js";
+/** @public */
 export { useSetting } from "./hooks/use-setting.js";
+/** @public */
 export { useSignal } from "./hooks/use-signal.js";
-export type { MenuItem, VflConstraints } from "./prop-types.js";
+/** @public */
 export { type RootElement, rootElement } from "./reconciler/root-element.js";
+/** @public */
 export { createPortal, createRoot, quit, type Root } from "./reconciler/root.js";
+/** @public */
 export type { AccessibleProps } from "./utils/accessible-props.js";
+/** @public */
 export type { RefProp } from "./utils/ref-prop.js";
-export type { SettingsSchema, SettingsSchemaKeys, SettingValue } from "./utils/settings.js";

package/src/internal.ts

@@ -1,13 +1,15 @@
 import "./bootstrap.js";
 
+/** @internal */
 export { createApplicationComponent } from "./components/application.js";
 export { createElementComponent } from "./components/element.js";
+/** @internal */
 export { createWindowComponent } from "./components/window.js";
-export { ApplicationContext } from "./hooks/use-application.js";
 export { useMergedRef } from "./hooks/use-merged-refs.js";
-export { useObjectValue } from "./hooks/use-object-value.js";
 export type * from "./prop-types.js";
+export type { ModuleExport } from "./reconciler/registry.js";
 export { isRootElement } from "./reconciler/root-element.js";
 export { createReconcilerRoot, type ReconcilerRoot, setReconcilerErrorHandler } from "./reconciler/root.js";
+export { applyWrite } from "./reconciler/signals.js";
 export { getAccessibleMetadata } from "./utils/accessible-metadata.js";
-export { type RefProp, resolveRefProp } from "./utils/ref-prop.js";
+export type { SettingsSchema, SettingsSchemaKeys, SettingValue } from "./utils/settings.js";

package/src/prop-types.ts

@@ -5,110 +5,191 @@ import type { ReactNode } from "react";
 
 /** One entry of a `GMenu`'s `items` prop; `submenu` and `section` nest further menus. */
 type MenuItem = {
+    /** Text shown for the entry, or the heading of the submenu or section it introduces. */
     label?: string | null;
+    /** Detailed action name the entry activates, ignored when `submenu` or `section` is given. */
     action?: string | null;
+    /** Entries of a separate menu the labelled entry opens. */
     submenu?: MenuItem[];
+    /** Entries appended below the label as an inline section, used only when `submenu` is absent. */
     section?: MenuItem[];
 };
 
 /** One Visual Format Language block applied to a `Gtk.ConstraintLayout`. */
 type VflConstraints = {
+    /** Format lines, each describing every constraint on one row or column. */
     lines: string[];
+    /** Default horizontal spacing the `-` operator stands for; defaults to 0. */
     hspacing?: number;
+    /** Default vertical spacing the `-` operator stands for; defaults to 0. */
     vspacing?: number;
+    /** Targets the view names in `lines` refer to; defaults to none. */
     views?: Map<string, Gtk.ConstraintTarget>;
 };
 
 /** One mark on a `Gtk.Scale`. */
-type ScaleMark = { value?: number; position: Gtk.PositionType; markup?: string | null };
+type ScaleMark = {
+    /** Point on the scale the mark is drawn at; defaults to 0. */
+    value?: number;
+    /** Side of the scale the mark and its label sit on. */
+    position: Gtk.PositionType;
+    /** Pango markup drawn beside the mark, or `null` for an unlabelled one. */
+    markup?: string | null;
+};
+
 /** One labelled offset on a `Gtk.LevelBar`. */
-type LevelBarOffset = { name: string; value?: number };
+type LevelBarOffset = {
+    /** Style class applied to the bar's blocks while the value falls in this offset's interval. */
+    name: string;
+    /** Upper bound of that interval; defaults to 0. */
+    value?: number;
+};
+
 /** One credit section on a `Gtk.AboutDialog`. */
-type CreditSection = { sectionName: string; people: string[] };
+type CreditSection = {
+    /** Heading the names are listed under. */
+    sectionName: string;
+    /** Names listed in the section. */
+    people: string[];
+};
+
 /** One accelerator binding on a `Gtk.Application`. */
-type ActionAccel = { detailedActionName: string; accels: string[] };
+type ActionAccel = {
+    /** Action the accelerators activate, such as `app.quit` or `win.open('file')`. */
+    detailedActionName: string;
+    /** Accelerators in `Gtk.acceleratorParse` syntax, cleared when the entry goes away. */
+    accels: string[];
+};
+
 /** The drag icon of a `Gtk.DragSource`, with its hotspot. */
-type DragSourceIcon = { paintable?: Gdk.Paintable | null; hotX?: number; hotY?: number };
+type DragSourceIcon = {
+    /** Image shown under the pointer during the drag; defaults to none. */
+    paintable?: Gdk.Paintable | null;
+    /** Horizontal offset of the pointer within the image; defaults to 0. */
+    hotX?: number;
+    /** Vertical offset of the pointer within the image; defaults to 0. */
+    hotY?: number;
+};
 
 /** Props of an element that accepts children. */
 type ChildrenProps = {
+    /** Elements attached to the element's default child slot, or its text for elements that hold text. */
     children?: ReactNode;
 };
 
+/** 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;
 } & ChildrenProps;
 
+/** Props of an action group placed in a widget's `actionGroups` slot. */
 type GActionGroupProps = {
+    /** Prefix the group's actions are addressed by, such as `win`; defaults to the empty string. */
     prefix?: string | null | undefined;
 };
 
+/** Props of an element implementing `Gio.ActionMap`. */
 type GActionMapProps = {
+    /** `Gio.Action` elements added to the map, removed again by their `name`. */
     actions?: ReactNode | null | undefined;
 };
 
+/** Props of a `Gio.Menu` element. */
 type GMenuProps = {
+    /** Entries the menu is rebuilt from whenever they change. */
     items?: MenuItem[] | null | undefined;
 };
 
+/** Props of a `Gtk.ShortcutController` element. */
 type GtkShortcutControllerProps = {
+    /** `Gtk.Shortcut` elements the controller watches for. */
     shortcuts?: ReactNode | null | undefined;
 };
 
+/** Props of a `Gtk.Overlay` element, whose `children` is the widget the overlays sit above. */
 type GtkOverlayProps = {
+    /** Widgets stacked over the main child. */
     overlays?: ReactNode | null | undefined;
 } & ChildrenProps;
 
+/** Props of a `Gtk.ConstraintLayout` element. */
 type GtkConstraintLayoutProps = {
+    /** `Gtk.Constraint` elements added to the layout. */
     constraints?: ReactNode | null | undefined;
+    /** `Gtk.ConstraintGuide` elements added to the layout as invisible spacers. */
     guides?: ReactNode | null | undefined;
+    /** Visual Format Language blocks whose constraints are added alongside `constraints`. */
     vfl?: VflConstraints[] | null | undefined;
 };
 
 /** Props of `GtkTextChildAnchor`, which embeds either a child widget or a paintable in a text buffer. */
 type GtkTextChildAnchorProps = {
+    /** Image inserted into the buffer instead of an anchored widget; giving both is an error. */
     paintable?: Gdk.Paintable | null | undefined;
 } & ChildrenProps;
 
+/** Props of a `Gtk.HeaderBar` or `Gtk.ActionBar` element. */
 type GtkHeaderBarProps = {
+    /** Widgets packed at the start of the bar. */
     start?: ReactNode | null | undefined;
+    /** Widgets packed at the end of the bar. */
     end?: ReactNode | null | undefined;
 };
 
+/** Props of a `Gtk.Scale` element. */
 type GtkScaleProps = {
+    /** Marks drawn along the scale, cleared and re-added whenever the list changes. */
     marks?: ScaleMark[] | null | undefined;
 };
 
+/** Props of a `Gtk.Calendar` element. */
 type GtkCalendarProps = {
+    /** Days of the shown month drawn as marked, cleared and re-marked whenever the list changes. */
     markedDays?: number[] | null | undefined;
 };
 
+/** Props of a `Gtk.LevelBar` element. */
 type GtkLevelBarProps = {
+    /** Offsets that split the bar's range into differently styled intervals. */
     offsets?: LevelBarOffset[] | null | undefined;
 };
 
+/** Props of a `Gtk.SizeGroup` element. */
 type GtkSizeGroupProps = {
+    /** Widgets the group keeps at a common size. */
     widgets?: Gtk.Widget[] | null | undefined;
 };
 
+/** Props of a `Gtk.AboutDialog` element. */
 type GtkAboutDialogProps = {
+    /** Extra sections appended to the dialog's credits, which GTK offers no way to remove. */
     creditSections?: CreditSection[] | null | undefined;
 };
 
+/** Props of a `Gtk.Application` element, whose `children` are the windows it owns. */
 type GtkApplicationProps = {
+    /** Accelerators bound to the application's actions. */
     actionAccels?: ActionAccel[] | null | undefined;
 } & ChildrenProps;
 
+/** Props of a `Gtk.DropTarget` element. */
 type GtkDropTargetProps = {
+    /** GTypes the target accepts a drop of. */
     types?: GObject.Type[] | null | undefined;
 };
 
+/** Props of a `Gtk.DrawingArea` element. */
 type GtkDrawingAreaProps = {
+    /** Callback that draws the area's contents; setting it queues a redraw. */
     drawFunc?: Gtk.DrawingAreaDrawFunc | null | undefined;
 };
 
+/** Props of a `Gtk.DragSource` element. */
 type GtkDragSourceProps = {
+    /** Icon shown under the pointer while a drag started from this source is in flight. */
     icon?: DragSourceIcon | null | undefined;
 };
 

package/src/reconciler/apply-props.ts

@@ -6,7 +6,7 @@ import type { ElementBehavior, Props } from "./registry.js";
 import { applyAccessibleProps, isAccessibleProp } from "../utils/accessible-props.js";
 import { type TypeInfo, typeInfoFor } from "./metadata.js";
 import { type ElementNode, getOrCreateContext, type SignalTarget } from "./node.js";
-import { connectHandler, disconnectHandler } from "./signals.js";
+import { applyWrite, connectHandler, disconnectHandler } from "./signals.js";
 import { bufferText, hasSameText, isContentPaintableProp, markTextDirty, TEXT_PROP } from "./text.js";
 
 type PropDelta = { name: string; value: unknown; prevValue: unknown };
@@ -43,7 +43,9 @@ const writeValue = (object: GObject.Object, name: string, value: unknown): void
         return;
     }
 
-    Reflect.set(object, name, value);
+    applyWrite(() => {
+        Reflect.set(object, name, value);
+    });
 };
 
 const resetPlain = (object: GObject.Object, info: TypeInfo, name: string): void => {
@@ -65,9 +67,11 @@ const applyBufferText = (buffer: Gtk.TextBuffer, text: string): void => {
         return;
     }
 
-    buffer.beginIrreversibleAction();
-    buffer.setText(text, -1);
-    buffer.endIrreversibleAction();
+    applyWrite(() => {
+        buffer.beginIrreversibleAction();
+        buffer.setText(text, -1);
+        buffer.endIrreversibleAction();
+    });
 };
 
 const isBufferText = (node: ElementNode, name: string): node is ElementNode & { object: Gtk.TextBuffer } =>
@@ -169,7 +173,9 @@ const restoreActionableSensitivity = (node: ElementNode, info: TypeInfo, prev: P
     const desired = "sensitive" in next ? next.sensitive : info.defaults.sensitive;
 
     if (typeof desired === "boolean") {
-        Reflect.set(node.object, "sensitive", desired);
+        applyWrite(() => {
+            Reflect.set(node.object, "sensitive", desired);
+        });
     }
 };
 

package/src/reconciler/behaviors.ts

@@ -3,6 +3,7 @@ import type * as Gtk from "@gtkx/gi/gtk";
 import { getInstanceType, TYPE_INVALID, typeFromName, typeIsA } from "@gtkx/runtime";
 import { getOrInsert, isDeepEqual, structuredClone } from "@gtkx/utils";
 import type { DetachInfo, ElementBehavior, PlaceInfo, Props } from "./registry.js";
+import { applyWrite } from "./signals.js";
 import { hasSameText } from "./text.js";
 
 type SlotHooks<P extends GObject.Object, C extends GObject.Object> = {
@@ -22,7 +23,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; present: boolean; applied: unknown };
+type DeferredState = { desired: unknown; isPresent: boolean; applied: unknown };
 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 };
@@ -66,7 +67,6 @@ const slotAttach =
             return attach(object as P, child as C, info) ?? true;
         };
 
-/** Builds a behavior for a named child slot holding children of `childType`, claiming matches only. */
 const slot = <P extends GObject.Object, C extends GObject.Object>(
     slotName: string,
     childType: string,
@@ -93,7 +93,6 @@ const slot = <P extends GObject.Object, C extends GObject.Object>(
     return behavior;
 };
 
-/** Builds a scalar-prop behavior that invokes `apply` whenever the value changes, and claims the prop. */
 const value = <P extends GObject.Object, V>(
     prop: string,
     apply: ValueApply<P, V>,
@@ -129,11 +128,6 @@ const teardownList = <P extends GObject.Object, I, H>(
     }
 };
 
-/**
- * Builds an array-prop behavior that adds, removes, and clears its items, reapplying on structural
- * change. `add` may return a handle that the same item's later `remove` receives, for items whose
- * teardown needs what `add` produced (as VFL constraints need the objects the layout created).
- */
 const list = <P extends GObject.Object, I, H = void>(
     prop: string,
     hooks: ListHooks<P, I, H>,
@@ -141,7 +135,7 @@ const list = <P extends GObject.Object, I, H = void>(
     const { add } = hooks;
 
     return {
-        createContext: (): ListState => ({ snapshot: [], entries: [] }),
+        initialize: (): ListState => ({ snapshot: [], entries: [] }),
         update: (object, _prev, next, context) => {
             const state = context as ListState;
             const raw = next[prop];
@@ -168,7 +162,7 @@ const flushDeferred = <P extends GObject.Object, V>(
 ): void => {
     const state = context as DeferredState;
 
-    if (!state.present || Object.is(state.applied, state.desired)) {
+    if (!state.isPresent || Object.is(state.applied, state.desired)) {
         return;
     }
 
@@ -176,21 +170,23 @@ const flushDeferred = <P extends GObject.Object, V>(
         return;
     }
 
-    Reflect.set(object, prop, state.desired);
+    applyWrite(() => {
+        Reflect.set(object, prop, state.desired);
+    });
+
     state.applied = state.desired;
 };
 
-/** Builds a behavior for a prop applied after the surrounding commit, deferred until `canApply` returns true. */
 const deferred = <P extends GObject.Object, V>(
     prop: string,
     canApply?: CanApply<P, V>,
 ): ElementBehavior<P> => ({
     deferred: [prop],
-    createContext: (): DeferredState => ({ desired: undefined, present: false, applied: undefined }),
+    initialize: (): DeferredState => ({ desired: undefined, isPresent: false, applied: undefined }),
     update: (_object, _prev, next, context) => {
         const state = context as DeferredState;
         state.desired = next[prop];
-        state.present = next[prop] !== undefined;
+        state.isPresent = next[prop] !== undefined;
 
         return [prop];
     },
@@ -199,15 +195,15 @@ const deferred = <P extends GObject.Object, V>(
     },
 });
 
-/** Builds a behavior for a text prop kept in controlled-input sync: set when provided, never reset. */
 const controlledText = (prop: string): ElementBehavior =>
     value(prop, (object, next) => {
         if (!hasSameText(object, prop, next)) {
-            Reflect.set(object, prop, next);
+            applyWrite(() => {
+                Reflect.set(object, prop, next);
+            });
         }
     });
 
-/** Behavior for a container that installs its single child with `setChild`. */
 const childSetterSlot = <P extends ChildSetter>(): ElementBehavior<P> =>
     slot<P, Gtk.Widget>("children", "GtkWidget", {
         attach: (parent, child) => {
@@ -218,7 +214,6 @@ const childSetterSlot = <P extends ChildSetter>(): ElementBehavior<P> =>
         },
     });
 
-/** Behavior for a container that installs its single child with `setContent`. */
 const contentSetterSlot = <P extends ContentSetter<C>, C extends Gtk.Widget = Gtk.Widget>(
     childType = "GtkWidget",
 ): ElementBehavior<P> =>
@@ -231,7 +226,6 @@ const contentSetterSlot = <P extends ContentSetter<C>, C extends Gtk.Widget = Gt
         },
     });
 
-/** Behavior for a `GtkBox`-style container that orders children by sibling. */
 const boxSlot = <P extends BoxLike>(): ElementBehavior<P> =>
     slot<P, Gtk.Widget>("children", "GtkWidget", {
         attach: (box, child, info) => box.insertChildAfter(child, info.sibling as Gtk.Widget | null),
@@ -243,7 +237,6 @@ const boxSlot = <P extends BoxLike>(): ElementBehavior<P> =>
         },
     });
 
-/** Behavior for a container whose children are added and removed by a pair of methods. */
 const addRemoveSlot = <C extends GObject.Object, P extends GObject.Object>(
     slotName: string,
     childType: string,
@@ -251,7 +244,6 @@ const addRemoveSlot = <C extends GObject.Object, P extends GObject.Object>(
     remove: (parent: P, child: C) => void,
 ): ElementBehavior => slot<P, C>(slotName, childType, { attach: add, detach: remove });
 
-/** Behavior for a `children` slot whose attach call returns the page object the container adopts. */
 const adoptedChildrenSlot = <P extends GObject.Object, C extends GObject.Object>(
     childType: string,
     add: (parent: P, item: C) => unknown,
@@ -294,7 +286,6 @@ const removeWrappedRow = (
     }
 };
 
-/** Behavior for an index-placed container that wraps each child in `Wrapper` before adding it. */
 const wrappingIndexedSlot = <W extends Gtk.Widget, P extends IndexedInserter>(
     Wrapper: new (props: Props) => W,
     setChild: (wrapper: W, inner: Gtk.Widget) => void,
@@ -306,7 +297,7 @@ const wrappingIndexedSlot = <W extends Gtk.Widget, P extends IndexedInserter>(
             removeWrappedRow(Wrapper, parent, child, info.context as RowCache);
         },
     }),
-    createContext: (): RowCache => new WeakMap(),
+    initialize: (): RowCache => new WeakMap(),
 });
 
 export {

package/src/reconciler/host-config.ts

@@ -32,7 +32,7 @@ import {
     type TextNode,
 } from "./node.js";
 import { isRootElement, type RootElement } from "./root-element.js";
-import { beginSuppression, disconnectAllHandlers, endSuppression } from "./signals.js";
+import { disconnectAllHandlers } from "./signals.js";
 import {
     didUpdateTextSurgically,
     enclosingHost,
@@ -41,7 +41,7 @@ import {
     validateContentMix,
 } from "./text.js";
 
-/** A top-level container an element tree can be mounted into. */
+/** What a tree is rendered into: any GObject, or the {@link RootElement} marker to render at the top level. */
 type Container = RootElement | GObject.Object;
 
 type PriorityTracker = {
@@ -88,15 +88,10 @@ const hostConfig = {
     getRootHostContext: (): Record<string, never> => HOST_CONTEXT,
     getChildHostContext: (parent: Record<string, never>): Record<string, never> => parent,
     getPublicInstance: (instance: Instance): object => getPublicInstance(instance),
-    prepareForCommit: (): null => {
-        beginSuppression();
-
-        return null;
-    },
+    prepareForCommit: (): null => null,
     resetAfterCommit: (): void => {
         flushTextHosts();
         flushBehaviors();
-        endSuppression();
     },
     preparePortalMount: (): void => undefined,
     clearContainer: (): void => undefined,

package/src/reconciler/instance.ts

@@ -69,7 +69,7 @@ const createObject = (typeName: string, type: bigint, input: Props): GObject.Obj
 const resolveElementNode = (typeName: string, props: Props, dispatch: Dispatch): ElementNode | LazyNode => {
     const info = typeInfoFor(typeName);
 
-    if (info.lazy) {
+    if (info.isLazy) {
         return createLazyNode(typeName, props, dispatch);
     }