@gjsify/gtk-host 0.43.0 → 0.45.0

package/lib/types/adapters/react.d.ts

@@ -4,8 +4,6 @@ import { adopt, widgetOf } from '../host.js';
 import type { HostElement, HostNode, HostText } from '../types.js';
 /** What React hands `createInstance`: the vnode props, `children` included. */
 export type ReactProps = Record<string, unknown>;
-/** One authored property that changed: name, next value, previous value. */
-type PropChange = readonly [key: string, next: unknown, prev: unknown];
 /**
  * The HostConfig, exported because it IS the contract.
  *
@@ -21,6 +19,8 @@ export declare const gtkHostConfig: {
     supportsPersistence: boolean;
     supportsHydration: boolean;
     isPrimaryRenderer: boolean;
+    supportsResources: boolean;
+    supportsSingletons: boolean;
     noTimeout: -1;
     scheduleTimeout: typeof setTimeout;
     cancelTimeout: typeof clearTimeout;
@@ -42,8 +42,8 @@ export declare const gtkHostConfig: {
      * flag only when `shouldSetTextContent` was true for the PREVIOUS props.
      */
     shouldSetTextContent: () => boolean;
-    getRootHostContext: () => null;
-    getChildHostContext: (parentHostContext: null) => null;
+    getRootHostContext: () => object;
+    getChildHostContext: (parentHostContext: object) => object;
     /**
      * What a `ref` receives — the author's widget, never the host's wrapper.
      *
@@ -55,8 +55,10 @@ export declare const gtkHostConfig: {
     prepareForCommit: () => null;
     resetAfterCommit: () => void;
     preparePortalMount: () => void;
+    getCurrentUpdatePriority: () => number;
+    setCurrentUpdatePriority: (priority: number) => void;
     /**
-     * The priority every update outside React's own event system gets.
+     * The priority an update gets when React is not already inside a lane.
      *
      * React DOM derives this from the DOM event being handled (a click is
      * discrete, a scroll continuous). A GTK signal handler is not a DOM event and
@@ -67,7 +69,11 @@ export declare const gtkHostConfig: {
      * iteration. `flushSync` is the escape hatch, and the spec pumps the main
      * context to prove the scheduled path works at all under GJS.
      */
-    getCurrentEventPriority: () => number;
+    resolveUpdatePriority: () => number;
+    shouldAttemptEagerTransition: () => boolean;
+    trackSchedulerEvent: () => void;
+    resolveEventType: () => null;
+    resolveEventTimeStamp: () => number;
     appendChild: (parent: HostElement, child: HostNode) => void;
     appendChildToContainer: (container: HostElement, child: HostNode) => void;
     insertBefore: (parent: HostElement, child: HostNode, before: HostNode) => void;
@@ -90,8 +96,17 @@ export declare const gtkHostConfig: {
      * for the life of the process.
      */
     clearContainer: (container: HostElement) => void;
-    prepareUpdate: (_instance: HostElement, _type: string, oldProps: ReactProps, newProps: ReactProps) => PropChange[] | null;
-    commitUpdate: (instance: HostElement, updatePayload: PropChange[]) => void;
+    /**
+     * Diff AND apply — one phase, because React 19 deleted the other one.
+     *
+     * The argument list is the change with teeth: React 18 passed
+     * `(instance, updatePayload, type, prevProps, nextProps, handle)` and 19 passes
+     * `(instance, type, prevProps, nextProps, handle)`. The payload slot was
+     * removed from the FRONT, so an adapter that kept the old signature would read
+     * the type string as its payload and iterate a string — which is why this is
+     * spelled out rather than left to positional luck.
+     */
+    commitUpdate: (instance: HostElement, _type: string, prevProps: ReactProps, nextProps: ReactProps) => void;
     commitTextUpdate: (textInstance: HostText, _oldText: string, newText: string) => void;
     commitMount: () => void;
     resetTextContent: (instance: HostElement) => void;
@@ -111,17 +126,30 @@ export declare const gtkHostConfig: {
     getInstanceFromScope: () => null;
     prepareScopeUpdate: () => void;
     beforeActiveInstanceBlur: () => void;
-    afterActiveInstanceBlur: () => void;
+    maySuspendCommit: () => boolean;
+    maySuspendCommitOnUpdate: () => boolean;
+    maySuspendCommitInSyncRender: () => boolean;
+    preloadInstance: () => boolean;
+    startSuspendingCommit: () => void;
+    suspendInstance: () => void;
+    waitForCommitToBeReady: () => null;
+    requestPostPaintCallback: () => void;
+    NotPendingTransition: any;
+    HostTransitionContext: import("react").Context<any>;
+    resetFormInstance: () => void;
     detachDeletedInstance: () => void;
 };
 export type GtkHostConfig = typeof gtkHostConfig;
 /**
  * Run `fn` and flush every update it schedules before returning.
  *
- * The default lane is concurrent (see `getCurrentEventPriority`), so a `setState`
+ * The default lane is concurrent (see `resolveUpdatePriority`), so a `setState`
  * from a GTK signal handler lands on a later main-loop iteration. In an
  * application that is right — GTK is running a main loop. Outside one, and in a
  * test, this is how a change becomes visible without pumping.
+ *
+ * `reconciler.flushSync` was RENAMED to `flushSyncFromReconciler` in React 19.
+ * The rename is the harmless half; see `createRoot` for the half that is not.
  */
 export declare const flushSync: <T>(fn: () => T) => T;
 export interface ReactRoot {
@@ -144,6 +172,27 @@ export interface ReactRootOptions {
      * and asserts nothing arrived.
      */
     onRecoverableError?(error: Error): void;
+    /**
+     * An error NO error boundary caught. React 19 split this out of the single
+     * callback React 18 had, and it is the one that means the tree is broken.
+     *
+     * SUPPLYING THIS TURNS OFF THE RETHROW. By default `render()` throws the first
+     * uncaught error rather than returning normally, because a host refusal that
+     * only reaches a log has bought nothing. An application with its own error
+     * surface should not also get a throw — but it then owns reporting entirely.
+     */
+    onUncaughtError?(error: Error): void;
+    /**
+     * An error an error boundary DID catch — reported, then handled by the boundary.
+     *
+     * The default reports through `console.error`, which under GJS routes into the
+     * GLib log system at CRITICAL — so `installDiagnosticsGate()` COUNTS it, and a
+     * spec that deliberately renders a failing boundary will be told GTK reported a
+     * diagnostic. Such a spec should pass its own recorder here. Left as
+     * `console.error` because that is the right channel for an application, and a
+     * quieter default would be the wrong trade for the common case.
+     */
+    onCaughtError?(error: Error): void;
 }
 /**
  * A React root over a widget the application owns.

package/lib/types/adapters/solid.d.ts

@@ -1,5 +1,6 @@
 import type Gtk from '@girs/gtk-4.0';
 import { widgetOf } from '../host.js';
+import type { ListRowKey, ListRowSink } from '../list/index.js';
 import type { HostNode } from '../types.js';
 export declare const render: (code: () => HostNode, node: HostNode) => () => void, effect: <T>(fn: (prev?: T) => T, init?: T) => void, memo: <T>(fn: () => T, equal: boolean) => () => T, createComponent: <T>(Comp: (props: T) => HostNode, props: T) => HostNode, createElement: (tag: string) => HostNode, createTextNode: (value: string) => HostNode, insertNode: (parent: HostNode, node: HostNode, anchor?: HostNode) => void, insert: <T>(parent: any, accessor: T | (() => T), marker?: any | null, initial?: any) => HostNode, spread: <T>(node: any, accessor: (() => T) | T, skipChildren?: boolean) => void, setProp: <T>(node: HostNode, name: string, value: T, prev?: T) => T, mergeProps: (...sources: unknown[]) => unknown, use: <A, T>(fn: (element: HostNode, arg: A) => T, element: HostNode, arg: A) => T;
 /**
@@ -14,6 +15,40 @@ export declare const render: (code: () => HostNode, node: HostNode) => () => voi
  * disconnects the signal handlers.
  */
 export declare function mount(code: () => HostNode, container: Gtk.Widget): () => void;
+/**
+ * What `listRows` keeps for one ROW WIDGET: a way to show a row in it, and a way to
+ * let go. Opaque to the controller, which stores it and hands it back.
+ */
+export interface ListRowHandle<Row extends ListRowKey> {
+    show(row: Row | null, index: number): void;
+    dispose(): void;
+}
+/**
+ * Solid's half of a `Gtk.ListView`, for `ListController` in `@gjsify/gtk-host/list`.
+ *
+ * The controller owns the model, the factory and the key diff — none of which has a
+ * framework in it. This supplies the three callbacks it cannot have: what to put in a
+ * row widget, what to show there, and how to let go.
+ *
+ * ONE REACTIVE ROOT PER ROW WIDGET, created in `mountRow` and never again, for two
+ * reasons that are not the same kind of thing. The carrier is taken ONCE because taking
+ * it per bind is REFUSED: `adopt` snapshots what a container already held and cannot
+ * tell our own previous child from application chrome, and the same carrier comes back
+ * on the next show, so the second one reads our own row as someone else's and raises
+ * `occupied-slot` (measured against this seam; `host.spec.ts` pins the same refusal
+ * from the host's side). The row's signals live INSIDE the root rather than beside it
+ * for a documented reason rather than a measured one — Solid never disposes a
+ * computation created with no owner, which for a per-row memo would be one leak per
+ * row.
+ *
+ * What the row sees is an ACCESSOR, not a value, and that is the capability this seam
+ * buys over re-rendering: when `setRows` finds unchanged keys over changed content, the
+ * controller shows every live row again, this writes one signal, and Solid updates the
+ * properties that actually changed — the widgets stay. Only the transition between
+ * "holds a row" and "holds nothing" rebuilds the subtree, which is what `present`
+ * isolates.
+ */
+export declare function listRows<Row extends ListRowKey>(renderRow: (row: () => Row, index: () => number) => HostNode): ListRowSink<Row, ListRowHandle<Row>>;
 /** `<For each={items}>` — keyed by item identity, so a reorder MOVES nodes. */
 export declare const For: <T>(props: {
     each: readonly T[] | undefined | null | false;

package/lib/types/conformance/diagnostics.d.ts

@@ -1,10 +1,20 @@
 export interface DiagnosticsGate {
-    /** Warning-or-worse messages seen since the last `reset()`. */
+    /** Warning-or-worse messages ABOUT THE TREE, seen since the last `reset()`. */
     readonly seen: readonly string[];
+    /**
+     * Warning-or-worse messages about the HOST's graphics stack, kept apart.
+     *
+     * Recorded rather than dropped: `assertQuiet` names the count so a run is
+     * never quietly forgiven, and a caller that genuinely wants to assert on the
+     * environment can read them.
+     */
+    readonly environment: readonly string[];
     reset(): void;
-    /** Throw if anything was recorded, naming every message. */
+    /** Throw if anything about the tree was recorded, naming every message. */
     assertQuiet(context?: string): void;
 }
+/** Whether `message` describes the host's graphics stack rather than the tree. */
+export declare function isEnvironmentDiagnostic(message: string): boolean;
 /**
  * Install the writer func once per process and return the gate.
  *
@@ -21,7 +31,7 @@ export interface DiagnosticsGate {
  * arrive without one. The first version answered `String(raw ?? '')`, so such a
  * record was counted and then described as nothing: a CI run failed with
  * `GTK reported 1 diagnostic(s) that would have passed at exit 0:` followed by a
- * BLANK LIST, over a test that had just constructed 164 widgets. A gate that can
+ * BLANK LIST, over a test that had just constructed the whole table. A gate that can
  * count a failure but not name it sends the reader back to guessing, which is the
  * state this whole module exists to end.
  *

package/lib/types/conformance/index.d.ts

@@ -1,4 +1,4 @@
-export { describeLogRecord, installDiagnosticsGate, type DiagnosticsGate } from './diagnostics.js';
+export { describeLogRecord, installDiagnosticsGate, isEnvironmentDiagnostic, type DiagnosticsGate, } from './diagnostics.js';
 import type Gtk from '@girs/gtk-4.0';
 import type { ChildPolicy, HostElement, WidgetDescriptor } from '../types.js';
 /** Every method name a policy names, so the check does not have to know the shapes. */

package/lib/types/descriptors/index.d.ts

@@ -20,8 +20,8 @@ export declare const CURATED_DESCRIPTORS: readonly WidgetDescriptor[];
  * that merely LISTS such a tag hands a renderer a way to kill the process, and
  * `descriptorProblems()` cannot see it because it never instantiates anything.
  *
- * MEASURED bare-constructing all 164 generated rows on gjs 1.88.1 / GTK 4.22.4 /
- * Adw 1.10, resuming past each abort: **163 construct, one does not**, and not a
+ * MEASURED bare-constructing every generated row on gjs 1.88.1 / GTK 4.22.4 /
+ * libadwaita 1.9.3, resuming past each abort: **all but one construct**, and not a
  * single row throws. So this map is one entry rather than a policy — and
  * `constructsEveryDescriptor` in `generated.spec.ts` is what keeps it one entry.
  *

package/lib/types/errors.d.ts

@@ -43,6 +43,16 @@ export declare const err: {
     textNotAccepted: (tag: string, text: string) => GtkHostError;
     unclaimedChild: (parentTag: string, childTag: string) => GtkHostError;
     unknownSlot: (parentTag: string, slot: string, known: string[]) => GtkHostError;
+    /**
+     * An adder-backed slot with nothing that takes the child back out.
+     *
+     * `descriptorProblems()` rejects this shape up front, so a BUILT-IN descriptor can
+     * never reach here — but `registerWidget` takes descriptors from applications, which
+     * run no such check. Without this the unmount would be
+     * `TypeError: host[undefined] is not a function`, blaming the host for a claim the
+     * descriptor made.
+     */
+    slotNeedsRemove: (parentTag: string, slot: string, adder: string) => GtkHostError;
     rejectedChild: (parentTag: string, childTag: string, reason: string) => GtkHostError;
     uncuratedPlacement: (parentTag: string, childTag: string) => GtkHostError;
     siblingCycle: (parentTag: string) => GtkHostError;

package/lib/types/generated/props.d.ts

@@ -1586,6 +1586,35 @@ export interface AdwToggleGroupProps extends GtkWidgetProps, GtkAccessibleProps,
     onNotifyCanShrink?: NotifyHandler;
     onNotifyHomogeneous?: NotifyHandler;
 }
+/** A toggle within [class@ToggleGroup]. */
+export interface AdwToggleProps extends GObjectProps {
+    /** The toggle child. */
+    child?: Gtk.Widget | null;
+    /** The description of the toggle. */
+    description?: string;
+    /** Whether this toggle is enabled. */
+    enabled?: boolean;
+    /** The toggle icon name. */
+    iconName?: string;
+    'icon-name'?: string;
+    /** The toggle label. */
+    label?: string;
+    /** The toggle name. */
+    name?: string;
+    /** The tooltip of the toggle. */
+    tooltip?: string;
+    /** Whether an embedded underline in the label indicates a mnemonic. */
+    useUnderline?: boolean;
+    'use-underline'?: boolean;
+    onNotifyChild?: NotifyHandler;
+    onNotifyDescription?: NotifyHandler;
+    onNotifyEnabled?: NotifyHandler;
+    onNotifyIconName?: NotifyHandler;
+    onNotifyLabel?: NotifyHandler;
+    onNotifyName?: NotifyHandler;
+    onNotifyTooltip?: NotifyHandler;
+    onNotifyUseUnderline?: NotifyHandler;
+}
 /** A widget containing a page, as well as top and/or bottom bars. */
 export interface AdwToolbarViewProps extends GtkWidgetProps, GtkAccessibleProps, GtkBuildableProps, GtkConstraintTargetProps {
     /** Appearance of the bottom bars. */
@@ -2267,6 +2296,15 @@ export interface GtkColorDialogButtonProps extends GtkWidgetProps, GtkAccessible
     onNotifyDialog?: NotifyHandler;
     onNotifyRgba?: NotifyHandler;
 }
+/** Represents items in a cell in [class@Gtk.ColumnView]. */
+export interface GtkColumnViewCellProps extends GtkListItemProps {
+    /** Widget used for display. */
+    child?: Gtk.Widget | null;
+    /** If the item can be focused with the keyboard. */
+    focusable?: boolean;
+    onNotifyChild?: NotifyHandler;
+    onNotifyFocusable?: NotifyHandler;
+}
 /** Presents a large dynamic list of items using multiple columns with headers. */
 export interface GtkColumnViewProps extends GtkWidgetProps, GtkAccessibleProps, GtkBuildableProps, GtkConstraintTargetProps, GtkScrollableProps {
     /** Allow rubberband selection. */
@@ -3369,6 +3407,35 @@ export interface GtkListBoxRowProps extends GtkWidgetProps, GtkAccessibleProps,
     onNotifyChild?: NotifyHandler;
     onNotifySelectable?: NotifyHandler;
 }
+/** Used by list widgets to represent the headers they display. */
+export interface GtkListHeaderProps extends GObjectProps {
+    /** Widget used for display. */
+    child?: Gtk.Widget | null;
+    onNotifyChild?: NotifyHandler;
+}
+/** Used by list widgets to represent items in a [iface@Gio.ListModel]. */
+export interface GtkListItemProps extends GObjectProps {
+    /** The accessible description to set on the listitem. */
+    accessibleDescription?: string;
+    'accessible-description'?: string;
+    /** The accessible label to set on the listitem. */
+    accessibleLabel?: string;
+    'accessible-label'?: string;
+    /** If the item can be activated by the user. */
+    activatable?: boolean;
+    /** Widget used for display. */
+    child?: Gtk.Widget | null;
+    /** If the item can be focused with the keyboard. */
+    focusable?: boolean;
+    /** If the item can be selected by the user. */
+    selectable?: boolean;
+    onNotifyAccessibleDescription?: NotifyHandler;
+    onNotifyAccessibleLabel?: NotifyHandler;
+    onNotifyActivatable?: NotifyHandler;
+    onNotifyChild?: NotifyHandler;
+    onNotifyFocusable?: NotifyHandler;
+    onNotifySelectable?: NotifyHandler;
+}
 /** Presents a large dynamic list of items. */
 export interface GtkListViewProps extends GtkListBaseProps, GtkAccessibleProps, GtkBuildableProps, GtkConstraintTargetProps, GtkOrientableProps, GtkScrollableProps {
     /** Allow rubberband selection. */
@@ -5037,6 +5104,7 @@ export interface WidgetPropsByTag {
     'adw-tab-overview': AdwTabOverviewProps;
     'adw-tab-view': AdwTabViewProps;
     'adw-toast-overlay': AdwToastOverlayProps;
+    'adw-toggle': AdwToggleProps;
     'adw-toggle-group': AdwToggleGroupProps;
     'adw-toolbar-view': AdwToolbarViewProps;
     'adw-view-stack': AdwViewStackProps;
@@ -5066,6 +5134,7 @@ export interface WidgetPropsByTag {
     'gtk-color-chooser-widget': GtkColorChooserWidgetProps;
     'gtk-color-dialog-button': GtkColorDialogButtonProps;
     'gtk-column-view': GtkColumnViewProps;
+    'gtk-column-view-cell': GtkColumnViewCellProps;
     'gtk-combo-box': GtkComboBoxProps;
     'gtk-combo-box-text': GtkComboBoxTextProps;
     'gtk-dialog': GtkDialogProps;
@@ -5100,6 +5169,8 @@ export interface WidgetPropsByTag {
     'gtk-link-button': GtkLinkButtonProps;
     'gtk-list-box': GtkListBoxProps;
     'gtk-list-box-row': GtkListBoxRowProps;
+    'gtk-list-header': GtkListHeaderProps;
+    'gtk-list-item': GtkListItemProps;
     'gtk-list-view': GtkListViewProps;
     'gtk-lock-button': GtkLockButtonProps;
     'gtk-media-controls': GtkMediaControlsProps;
@@ -5204,6 +5275,7 @@ export interface WidgetPropsByGType {
     AdwTabOverview: AdwTabOverviewProps;
     AdwTabView: AdwTabViewProps;
     AdwToastOverlay: AdwToastOverlayProps;
+    AdwToggle: AdwToggleProps;
     AdwToggleGroup: AdwToggleGroupProps;
     AdwToolbarView: AdwToolbarViewProps;
     AdwViewStack: AdwViewStackProps;
@@ -5233,6 +5305,7 @@ export interface WidgetPropsByGType {
     GtkColorChooserWidget: GtkColorChooserWidgetProps;
     GtkColorDialogButton: GtkColorDialogButtonProps;
     GtkColumnView: GtkColumnViewProps;
+    GtkColumnViewCell: GtkColumnViewCellProps;
     GtkComboBox: GtkComboBoxProps;
     GtkComboBoxText: GtkComboBoxTextProps;
     GtkDialog: GtkDialogProps;
@@ -5267,6 +5340,8 @@ export interface WidgetPropsByGType {
     GtkLinkButton: GtkLinkButtonProps;
     GtkListBox: GtkListBoxProps;
     GtkListBoxRow: GtkListBoxRowProps;
+    GtkListHeader: GtkListHeaderProps;
+    GtkListItem: GtkListItemProps;
     GtkListView: GtkListViewProps;
     GtkLockButton: GtkLockButtonProps;
     GtkMediaControls: GtkMediaControlsProps;
@@ -5320,7 +5395,7 @@ export interface WidgetPropsByGType {
 /**
  * Kebab keys for the widgets Volar's camelize cannot reach from their GType name.
  *
- * 1 of 164. Generated, not curated: any future GType with two adjacent
+ * 1 of 168. Generated, not curated: any future GType with two adjacent
  * capitals lands here by itself instead of becoming a bug report.
  */
 export interface WidgetPropsVueAliases {
@@ -5388,6 +5463,7 @@ export interface WidgetClassByTag {
     'adw-tab-overview': Adw.TabOverview;
     'adw-tab-view': Adw.TabView;
     'adw-toast-overlay': Adw.ToastOverlay;
+    'adw-toggle': Adw.Toggle;
     'adw-toggle-group': Adw.ToggleGroup;
     'adw-toolbar-view': Adw.ToolbarView;
     'adw-view-stack': Adw.ViewStack;
@@ -5417,6 +5493,7 @@ export interface WidgetClassByTag {
     'gtk-color-chooser-widget': Gtk.ColorChooserWidget;
     'gtk-color-dialog-button': Gtk.ColorDialogButton;
     'gtk-column-view': Gtk.ColumnView;
+    'gtk-column-view-cell': Gtk.ColumnViewCell;
     'gtk-combo-box': Gtk.ComboBox;
     'gtk-combo-box-text': Gtk.ComboBoxText;
     'gtk-dialog': Gtk.Dialog;
@@ -5451,6 +5528,8 @@ export interface WidgetClassByTag {
     'gtk-link-button': Gtk.LinkButton;
     'gtk-list-box': Gtk.ListBox;
     'gtk-list-box-row': Gtk.ListBoxRow;
+    'gtk-list-header': Gtk.ListHeader;
+    'gtk-list-item': Gtk.ListItem;
     'gtk-list-view': Gtk.ListView;
     'gtk-lock-button': Gtk.LockButton;
     'gtk-media-controls': Gtk.MediaControls;

package/lib/types/generator/emit-types.d.mts

@@ -1,5 +1,5 @@
 /**
- * Emit the TYPE surfaces: one interface per GIR declaration, two tag maps.
+ * Emit the TYPE surfaces: one interface per GIR declaration, four tag maps.
  *
  * WHAT THE DIALECTS FORCED, all of it measured rather than assumed (ADR 0028 § 7,
  * and the numbers live there):

package/lib/types/generator/gir.d.mts

@@ -56,8 +56,16 @@ export interface GirProperty {
  * GIR writes `baseline_fill`; the nick GObject registered is `baseline-fill`. This
  * is the FALLBACK for a `<member>` with no `glib:nick` — the attribute itself is
  * the answer wherever it exists, because the substitution is right for Gtk and Adw
- * by luck and not by construction: across every GIR in this workspace 40,940
- * members carry the attribute and 97 disagree with it.
+ * by luck and not by construction: some nicks keep an underscore it would have
+ * replaced, and nothing but the attribute knows which one survived.
+ *
+ * The count that used to sit here is now `ts-for-gir/scripts/check-nick-derivation.mjs`,
+ * which owns the corpus this measures over. It also settles what looked like a
+ * contradiction: this file said 97 and ts-for-gir said 889 over the SAME 705 GIRs,
+ * and both were right — the derivations differ. 889 counts a fallback that also
+ * lowercases, which adds the 792 members whose GIR name carries uppercase and whose
+ * nick preserves it. This one does not lowercase, so 97 is its number. Quote a
+ * derived-nick count without naming its derivation and you get that pair back.
  */
 export declare const nickOf: (member: string) => string;
 export interface GirParam {
@@ -154,3 +162,29 @@ export declare function declarations(cls: GirClass, index: Map<string, GirClass>
  * where an off-by-one is invisible.
  */
 export declare function concreteWidgets(namespaces: readonly GirNamespace[], root?: string): GirClass[];
+/**
+ * The placement carriers: concrete classes that are NOT widgets and yet hold one.
+ *
+ * GTK4's list widgets do not take children. A `Gtk.ListView` installs no `append`,
+ * `add`, `insert`, `prepend`, `remove` or `set_child` at all — measured against its
+ * prototype — because what it takes is a factory, and the factory hands back a
+ * carrier whose `child` is where a row's subtree goes. Those carriers are plain
+ * `GObject.Object` descendants: `GObject.type_is_a(Gtk.ListItem, Gtk.Widget)` is
+ * FALSE, measured on gjs 1.88.1 / GTK 4.22.4.
+ *
+ * So "every concrete descendant of GtkWidget" is one class short of the set a
+ * renderer must be able to name, and this is the other half. It is a RULE and not a
+ * list on purpose: a hand-written list is the kind of curated data ADR 0028 § 2
+ * reserves for what the GIR cannot express, and the GIR expresses this perfectly
+ * well — a carrier is a concrete non-widget that declares both halves of a
+ * one-child slot.
+ *
+ * Measured across Gtk-4.0 + Adw-1, the rule selects exactly four:
+ * `GtkListItem`, `GtkListHeader`, `GtkColumnViewCell` and `AdwToggle`. The fourth is
+ * the argument for the rule — it was not on the hand-written list that preceded it,
+ * has the identical shape, and would have been an arbitrary gap.
+ *
+ * What this does NOT do is give them a policy. A generated row is always
+ * `uncurated`; which method adopts the child stays curated, exactly as for widgets.
+ */
+export declare function placementCarriers(namespaces: readonly GirNamespace[]): GirClass[];

package/lib/types/host.d.ts

@@ -107,7 +107,7 @@ export declare function destroy(node: HostNode): void;
  * `GObject.registerClass` subclass inherits its ancestor's policy. Guessing a
  * method name here would be the generic `add` that GTK4 deliberately removed.
  */
-export declare function mountRoot(el: HostElement, container: Gtk.Widget): void;
+export declare function mountRoot(el: HostElement, container: GObject.Object): void;
 /**
  * The materialised widget of a host node — for a `ref`, or for a test.
  *
@@ -149,7 +149,7 @@ export declare const createDetachedContainer: () => HostElement;
  * through `nearestRegistered`, so an application's own `GObject.registerClass`
  * subclass inherits its ancestor's placement rules instead of failing.
  */
-export declare function adopt(container: Gtk.Widget): HostElement;
+export declare function adopt(container: GObject.Object): HostElement;
 export declare const parentNode: (node: HostNode) => HostElement | null;
 export declare const firstChild: (el: HostElement) => HostNode | null;
 export declare const nextSibling: (node: HostNode) => HostNode | null;

package/lib/types/index.d.ts

@@ -5,7 +5,7 @@ export { addressOf, reorderMode } from './policies.js';
 export { toSignalName, isEventProp } from './signals.js';
 export { constructOnlyNames, isConstructOnly, isWritable, lookupEnumNick, paramSpecs, toPropertyName, } from './props.js';
 export { assertInjective, tagOf } from './tags.js';
-export { probeEnabled, runHostProbe, runHostProbeApp, type HostProbe, type HostProbeApp, type ProbeCheck, } from './probe.js';
+export { blankReason, checkRendered, probeEnabled, runHostProbe, runHostProbeApp, shotEvidence, type CaptureWidget, type HostProbe, type HostProbeApp, type ProbeCheck, type ShotEvidence, } from './probe.js';
 export type { ElementChild, ElementChildren, JsxAttributes, RawSignalAttributes, SlotAttribute, VueAttributes, WithOnce, } from './attrs.js';
 export { clearRegistry, hasWidget, lookupWidget, nearestRegistered, registerWidget, registerWidgets, registeredTags, } from './registry.js';
 export { ADW_DESCRIPTORS, BUILTIN_DESCRIPTORS, CURATED_DESCRIPTORS, GENERATED_PROVENANCE, GENERATED_WIDGETS, GTK_DESCRIPTORS, mergeGenerated, registerBuiltinWidgets, tableProvenance, } from './descriptors/index.js';

package/lib/types/list/controller.d.ts

@@ -0,0 +1,112 @@
+import Gtk from 'gi://Gtk?version=4.0';
+/**
+ * A row's identity, and the only thing this layer reads off a row.
+ *
+ * `key` decides whether the model has to be rebuilt at all. Everything else a dialect
+ * wants to carry — a render function, a component, a plain record — rides along in the
+ * type parameter and is handed straight back to `showRow`.
+ */
+export interface ListRowKey {
+    readonly key: string;
+}
+/**
+ * The dialect's half of a list — three callbacks, one per factory phase that needs one.
+ *
+ * `Handle` is whatever the dialect needs to keep per ROW WIDGET: a React root, a Solid
+ * disposer plus a setter, a Vue app instance. The controller stores it, hands it back,
+ * and never looks inside it.
+ */
+export interface ListRowSink<Row extends ListRowKey, Handle> {
+    /**
+     * GTK made a row widget's carrier; put something in it and keep what you need.
+     *
+     * Called from `setup`, ONCE per row widget, and that is not a convenience: `adopt`'s
+     * `foreign` snapshot cannot tell the host's own previous child from application
+     * chrome, so taking the carrier a SECOND time reads our own row as someone else's
+     * and refuses with `occupied-slot`. `host.spec.ts` pins that refusal.
+     *
+     * TWO routes reach it, and the nearer one is not the obvious one. GTK reusing a
+     * carrier across `bind`/`unbind` is the route people expect, and it needs scrolling
+     * or recycling to happen at all. The route that fires FIRST is `setRows` over
+     * unchanged keys: it shows every live row again through the same handle, with no
+     * GTK involvement, so a dialect that adopts per show meets the refusal on its first
+     * content change — measured, and it is what `list.spec.ts`'s in-place vector
+     * exercises. Adopt here, keep the element in the handle.
+     */
+    mountRow(item: Gtk.ListItem): Handle;
+    /**
+     * Show `row` in the widget behind `handle`, or empty it when `row` is `null`.
+     *
+     * Called from `bind`, from `unbind` with `null`, and again for every live row when
+     * `setRows` sees unchanged keys over changed content — which GTK does not re-bind
+     * for us (the splice measurement in the header says why).
+     */
+    showRow(handle: Handle, row: Row | null, index: number): void;
+    /** GTK is done with this row widget, or the controller is. Let go of everything. */
+    disposeRow(handle: Handle): void;
+}
+/**
+ * WHERE A SINK'S OWN THROW GOES, because there are TWO paths and they differ.
+ *
+ * `setRows` over unchanged keys calls `showRow` DIRECTLY — no GTK in between — so a
+ * throw there propagates out of `setRows` to whoever called it, and a dialect can catch
+ * it. Every other call (`setup`, `bind`, `unbind`, `teardown`) runs inside a GObject
+ * signal callback, where GJS does not let an exception cross the C frame: it is swallowed
+ * and logged as `Gjs-CRITICAL … JS ERROR`, the emission continues, and the controller
+ * carries on with a row that never rendered. A diagnostics gate sees that; nothing else
+ * does.
+ *
+ * The asymmetry is not fixable from here — it is GJS's signal boundary — so it is
+ * DECLARED instead, and it decides where a sink should put its own error handling. It
+ * bites unevenly: React Native's sink only fills a Map on this path and cannot really
+ * throw, while Solid's `show()` runs the row's reactive updates synchronously inside
+ * `batch()`, so an error in application code lands here.
+ *
+ * Note what is NOT the answer: `@gjsify/react-native`'s `onRowError` is React's own root
+ * error channel, not this seam's. A sink that needs one owns it, because only the
+ * dialect knows what a row's error means — a controller-level hook would have to decide
+ * whether to keep binding, and neither answer is right for every renderer.
+ */
+/**
+ * A `Gtk.ListView`'s model, factory and per-row handles.
+ *
+ * Constructed by a dialect with its `ListRowSink`, attached to a view someone else
+ * created, disposed from that someone's own cleanup. Nothing here is reactive:
+ * `setRows` is called with the current rows and works out whether GTK has to hear
+ * about it.
+ */
+export declare class ListController<Row extends ListRowKey, Handle> {
+    #private;
+    constructor(sink: ListRowSink<Row, Handle>);
+    /**
+     * Give the view its model and factory.
+     *
+     * `Gtk.NoSelection` and not the store directly: `Gtk.ListView:model` is a
+     * `Gtk.SelectionModel`, and a plain `Gio.ListModel` is not one. `NoSelection` is the
+     * wrapper that says "no selection", and it is what this controller installs because
+     * a `Gtk.SingleSelection` would give rows a selected state nothing here would ever
+     * clear. Selection is a dialect-level feature nobody has asked for yet; adding it
+     * means widening `attach`, not reaching around it.
+     */
+    attach(view: Gtk.ListView): void;
+    /**
+     * The rows GTK should be showing.
+     *
+     * The model is only touched when the KEYS changed. When they did not, every row's
+     * subtree is shown again instead — a row whose key is the same but whose data
+     * changed has to repaint, and the splice measurement says GTK will not re-bind it
+     * for us. That is strictly cheaper than a splice, which tears down every row.
+     */
+    setRows(rows: readonly Row[]): void;
+    /** How many rows GTK is currently holding a widget for. A spec seam and a leak detector. */
+    get liveRows(): number;
+    /**
+     * Release every row, disconnect every handler, and let go of the view.
+     *
+     * Called from the owner's cleanup, which runs while JS callbacks still work —
+     * unlike GTK's own `teardown`, which fires during GC sweeping when the view is
+     * collected and is BLOCKED there (measured, see the header). Idempotent, because an
+     * owner's cleanup and an explicit dispose both reach it.
+     */
+    dispose(): void;
+}

package/lib/types/list/index.d.ts

@@ -0,0 +1,2 @@
+export { ListController, type ListRowKey, type ListRowSink } from './controller.js';
+export { onScrollNearEnd } from './scroll.js';

package/lib/types/list/list.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/list/scroll.d.ts

@@ -0,0 +1,26 @@
+import type Gtk from '@girs/gtk-4.0';
+/**
+ * Call `listener` when the scroller gets within `threshold` page-lengths of the end.
+ *
+ * `Gtk.Adjustment`, because that is where GTK keeps a scroll position: the scrolled
+ * window has no scroll signal of its own, and `notify::value` on the adjustment behind
+ * `hadjustment`/`vadjustment` is the only place the position is observable. MEASURED: a
+ * `Gtk.ScrolledWindow` hands out its adjustments with no window anywhere, and
+ * `set_value` on one raised `notify::value` — so this is drivable, and asserted, in a
+ * spec that presents nothing.
+ *
+ * `upper` and `page-size` are subscribed too, and not for completeness: `upper` grows
+ * when rows are added, which is the event that ARMS the next call — a list that grew has
+ * a new end.
+ *
+ * A list with nothing to scroll (`upper <= page-size`) never fires. That is the state
+ * every list is in before it has been allocated, and firing there would call the
+ * listener on mount for every list in the application.
+ *
+ * ONCE PER ARRIVAL, and this is the one policy here that came from a framework: it is
+ * React Native's `onEndReached` semantics. It is the core's behaviour anyway because
+ * every "load more" caller wants it — firing on every frame while the user rests at the
+ * bottom would issue a page request per frame. A dialect that wants the raw stream has
+ * the adjustment and can subscribe to it directly; this function is the debounced edge.
+ */
+export declare function onScrollNearEnd(scroller: Gtk.ScrolledWindow, axis: 'horizontal' | 'vertical', threshold: number, listener: (distanceFromEnd: number) => void): () => void;