@gjsify/gtk-host 0.44.0 → 0.46.0

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

@@ -1,3 +1,3 @@
 import type { GeneratedWidget } from '../types.js';
-export declare const GENERATED_PROVENANCE: "Gtk-4.0 Adw-1";
+export declare const GENERATED_PROVENANCE: "Gtk-4.0/4.23.3 Adw-1/1.10.0";
 export declare const GENERATED_WIDGETS: readonly GeneratedWidget[];

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):
@@ -23,7 +23,7 @@
  *    arrives as `unknown` so using it fails (TS2345). A generated surface that
  *    typed handlers loosely would break every handler that names its parameter.
  */
-import type { SurfaceModel } from './surface.mjs';
+import type { SurfaceModel } from './model.mjs';
 /**
  * Volar's own resolution rule, reproduced so the generator can SEE the gap.
  *

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

@@ -17,8 +17,7 @@
  * answer. The machine-INDEPENDENT check is the runtime one that already exists —
  * `descriptorProblems()` against the installed typelib.
  */
-import type { ChildPolicy, WidgetDescriptor } from '../types.js';
-import type { GirClass, GirNamespace } from './gir.mjs';
+import type { WidgetDescriptor } from '../types.js';
 /**
  * The `gi://` import a generated table needs, per GIR namespace.
  *
@@ -29,12 +28,23 @@ import type { GirClass, GirNamespace } from './gir.mjs';
  * trust.
  */
 export declare const GJS_MODULES: Readonly<Record<string, string>>;
+/** What a widget row needs. Three fields, not a GIR class — see `girs-vocabulary.mts`. */
+export interface WidgetRow {
+    readonly gtype: string;
+    readonly namespace: string;
+    readonly name: string;
+}
 export interface EmitInput {
-    readonly namespaces: readonly GirNamespace[];
-    readonly widgets: readonly GirClass[];
+    /** The provenance line, verbatim: `Gtk-4.0/4.23.3 Adw-1/1.8.0`. */
+    readonly provenance: string;
+    readonly widgets: readonly WidgetRow[];
+    /**
+     * Every GType the vocabulary knows, widgets and bases alike. G1 asks whether a curated
+     * row names something that exists, and a widget-only set would report every curated
+     * base as missing.
+     */
+    readonly knownGTypes: ReadonlySet<string>;
     readonly curated: readonly WidgetDescriptor[];
-    /** `methodsOf` from the conformance module — one extractor, not a second copy. */
-    readonly methodsOf: (policy: ChildPolicy) => string[];
     /** GIR namespace -> `gi://` import. Defaults to the GTK/Adwaita pair. */
     readonly modules?: Readonly<Record<string, string>>;
 }

package/lib/types/generator/girs-vocabulary.d.mts

@@ -0,0 +1,45 @@
+/**
+ * Read the widget vocabulary from `@girs/<ns>/vocabulary` and build the emitter's model.
+ *
+ * WHY THIS REPLACED A GIR READER. This package used to parse the `.gir` XML itself, which
+ * made it the SECOND reader of a format ts-for-gir already reads — and two readers of one
+ * format are two truths that drift apart silently. ADR 0029 moved the vocabulary into
+ * `@girs/*` so there is one. What stays here is the DIALECT: kebab tags, the camelCase
+ * second spelling, `on<Signal>` prop names, Vue's Volar aliases. None of that is in the
+ * vocabulary and none of it belongs there, as its own header says.
+ *
+ * WHY IT READS BOTH HALVES. The runtime `.js` carries the facts as values (`OWN_PROPS`,
+ * `DECLS`, `OWN_SIGNALS`, `ENUM_NICKS`), which is what a check can compare against a live
+ * typelib. The `.d.ts` carries the rendered TypeScript for each property, which no amount
+ * of runtime data can reconstruct: `GtkBaselinePositionNick | Gtk.BaselinePosition`
+ * depends on that file's own imports. So the types come from the declarations and the
+ * facts come from the values, and neither is re-derived from the other.
+ *
+ * The `.d.ts` half is READ in `vocabulary-dts.mts`, which touches no file and so
+ * imports no `gi://` — that is what lets `generator.spec.ts` pin its regexes against
+ * literal fixtures instead of against whichever `@girs` happens to be installed.
+ */
+import type { SurfaceModel } from './model.mjs';
+/** The three fields `emit-types.mts` reads off a widget. Not a GIR class any more. */
+export interface WidgetRef {
+    readonly gtype: string;
+    readonly namespace: string;
+    readonly name: string;
+}
+export interface VocabularySource {
+    /** Import name, e.g. `gtk-4.0`. */
+    readonly pkg: string;
+    /** GType prefix, e.g. `Gtk`. */
+    readonly prefix: string;
+}
+/**
+ * Load the vocabulary packages and build the model the emitters already consume.
+ *
+ * `dir` is the `node_modules/@girs` root; the caller resolves it, because a generator
+ * should not guess where its own dependencies live.
+ */
+export declare function buildFromVocabulary(dir: string, sources: readonly VocabularySource[]): Promise<{
+    model: SurfaceModel;
+    widgets: WidgetRef[];
+    provenance: string;
+}>;

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

@@ -1,15 +1,23 @@
 /**
  * The generator CLI.
  *
- *   gjsify run generate -- [--gir-dir DIR]... [--out DIR]
+ *   gjsify run generate -- [--girs-dir DIR] [--out DIR]
  *
- * WHY THE GIR PATH IS AN ARGUMENT AND NOT A DEPENDENCY. The GIR files are not in
- * this repository and should not be: `Gtk-4.0.gir` alone is 6.2 MB, they are
- * distro artefacts, and four different GTK versions sit on the maintainer
- * workstation. So the ARTEFACT is committed (ADR 0028 § Implementation) and the
- * input is located at generation time — from `--gir-dir`, from `GJSIFY_GIR_DIR`,
- * or from the search list below. A fresh clone builds, checks, packs and tests
- * with no GIR present at all; only regenerating needs one.
+ * WHERE THE VOCABULARY COMES FROM. The input used to be GIR XML: distro artefacts
+ * that are not in this repository, 6.2 MB for `Gtk-4.0.gir` alone, with four GTK
+ * versions on the maintainer workstation and no way to know which one a build saw.
+ * It is now the `@girs/<ns>/vocabulary` subpath (ADR 0029), which is an ordinary
+ * dependency, resolved like any other. That closes the provenance question the old
+ * route could only answer by convention: each vocabulary states the namespace,
+ * version and library version it was generated from, and this generator copies that
+ * into the artefact header instead of naming the files it happened to read.
+ *
+ * `--girs-dir` stays an argument so a locally built `@girs` can be generated against
+ * before it is published. Without it the directory is found by walking up from the
+ * working directory, which is what makes `npm run generate` work from the package.
+ *
+ * The ARTEFACT remains committed (ADR 0028 § Implementation): a fresh clone builds,
+ * checks, packs and tests without regenerating anything.
  *
  * THERE IS NO `--check` MODE, and the attempt to add one is worth recording: the
  * `generate` script pipes the output through `gjsify format`, which reflows it

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

@@ -0,0 +1,95 @@
+/**
+ * The declaration graph the type surfaces are emitted from — the shape only.
+ *
+ * ONE INTERFACE PER DECLARATION, carrying its OWN members and extending its bases —
+ * not one flat interface per widget. The measurement decides it: the concrete widgets
+ * have thousands of writable property slots between them and a few hundred distinct
+ * property names. Flattening would emit the same `visible?: boolean` once per widget;
+ * mirroring the inheritance the vocabulary reports emits it once, on `GtkWidgetProps`,
+ * and the diff of a GTK update then shows what actually changed.
+ *
+ * WHO FILLS IT. `girs-vocabulary.mts`, from `@girs/<ns>/vocabulary`. This module used
+ * to hold a `buildSurface()` that filled the same shape from GIR XML this package
+ * parsed itself; ADR 0029 moved the vocabulary into `@girs/*` so there is one reader
+ * of that format instead of two. Only the shape survived, which is why the file is
+ * `model.mts` and no longer `surface.mts`: `surface` now names the `@girs` subpath.
+ */
+import type { WidgetRow } from './emit.mjs';
+export interface PropMember {
+    readonly kebab: string;
+    readonly camel: string;
+    readonly ts: string;
+    /**
+     * The hover blurb, from the JSDoc above the property in the vocabulary's `.d.ts`.
+     *
+     * The typelib strips documentation by design — which is why gi-docgen reads the
+     * GIR — and hover text is what a published type surface is FOR (ADR 0028 § 6). So
+     * the doc travels with the rendered type, out of the half of the vocabulary that
+     * can carry it; the runtime half is values, and a value cannot hold a comment.
+     */
+    readonly doc?: string;
+    readonly deprecated: boolean;
+    readonly since?: string;
+}
+export interface SignalMember {
+    readonly signal: string;
+    readonly prop: string;
+    /** Already rendered — `Gtk.ListBox.SignalSignatures['row-activated']`. */
+    readonly ts: string;
+    readonly doc?: string;
+    readonly deprecated: boolean;
+    readonly since?: string;
+}
+export interface Declaration {
+    /** Namespace-qualified — `Gtk.Box`. The graph is keyed on this, the way GIR references. */
+    readonly key: string;
+    readonly gtype: string;
+    readonly kind: 'class' | 'interface';
+    /** `GtkBoxProps`. */
+    readonly iface: string;
+    readonly bases: readonly string[];
+    readonly props: readonly PropMember[];
+    readonly signals: readonly SignalMember[];
+    readonly doc?: string;
+    /**
+     * The library release this TYPE arrived in, where GIR states one.
+     *
+     * Distinct from a member's `since`: it answers "does the installed library have
+     * this class at all", which is the question a bare `ctor()` returning `undefined`
+     * used to ask by crashing. Only about 11% of GIR classes carry a `version`, so an
+     * absent value means "not stated", never "has always existed".
+     */
+    readonly since?: string;
+}
+export interface SurfaceModel {
+    /**
+     * The widget rows, sorted by GType name.
+     *
+     * The same three fields the table emitter takes, so the type comes from there
+     * rather than being restated — a second spelling of a row is a second thing to
+     * keep in step with `girs-vocabulary.mts`, which fills both.
+     */
+    readonly widgets: readonly WidgetRow[];
+    readonly declarations: ReadonlyMap<string, Declaration>;
+    /** Widget GType -> the GTypes of every declaration its members come from, self first. */
+    readonly closure: ReadonlyMap<string, readonly string[]>;
+    /** Enum GType -> nicks, for the emitted aliases and for the runtime nick check. */
+    readonly enumNicks: ReadonlyMap<string, readonly string[]>;
+    readonly namespacesUsed: ReadonlySet<string>;
+    /** Namespace -> the `@girs` package that types it, so the emitter needs no second source. */
+    readonly packages: Readonly<Record<string, string>>;
+    /**
+     * Base -> members it must not contribute, because a nearer declaration disagrees.
+     *
+     * EMPTY TODAY, AND NOT DEFENSIVE MACHINERY. TypeScript requires a multiply
+     * inherited member to be IDENTICAL in every base — `string` and `string | null`
+     * are not — and GTK's interfaces do redeclare class properties, so a base that
+     * loses a member has to be emitted as `Omit<Base, 'name'>`: a local redeclaration
+     * does NOT repair incompatible bases, it turns one error into another. The GIR
+     * route computed those conflicts here; the published vocabulary resolves them
+     * upstream, so the map now arrives empty. It stays because `emit-types.mts`
+     * renders `Omit<>` from it, and a vocabulary that reintroduces a conflict needs a
+     * way to say so — the alternative is a surface that does not compile.
+     */
+    readonly omissions: ReadonlyMap<string, ReadonlyMap<string, readonly string[]>>;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * The two name transforms this package's DIALECT owns.
+ *
+ * Everything else that used to live here — the GIR-type-to-TypeScript mapper, the
+ * enum-nick unions, the `@girs` package map — moved into `@girs/<ns>/vocabulary`
+ * with ADR 0029, which renders each property's type in its own `.d.ts` and ships
+ * the nicks as data. What no vocabulary can answer is how a FRAMEWORK spells a
+ * member, because every framework spells it differently; that is dialect, it stays
+ * here, and it is why this file is `names.mts` and no longer `tsmap.mts`.
+ *
+ * Both are also read by `generated.spec.ts`, which runs them against the host's own
+ * inverse (`toSignalName`) over every generated name. Two independent
+ * implementations checked against each other is the point: nothing made them agree,
+ * and the first run of that check found that they did not.
+ */
+/** `row-activated` -> `onRowActivated`; `notify` handled by the caller. */
+export declare const eventPropOf: (signal: string) => string;
+/** `can-focus` -> `canFocus`. The inverse of the host's `toPropertyName`. */
+export declare const camelOf: (kebab: string) => string;

package/lib/types/generator/vocabulary-dts.d.mts

@@ -0,0 +1,47 @@
+/** One member, as the `.d.ts` renders it: the TS text plus whatever JSDoc sits above. */
+export interface DeclaredProp {
+    readonly ts: string;
+    readonly doc?: string;
+    readonly since?: string;
+    readonly deprecated: boolean;
+}
+/** One `export interface <GType>Props` — its own JSDoc, and its own members. */
+export interface DeclaredInterface {
+    readonly doc?: string;
+    readonly props: Map<string, DeclaredProp>;
+}
+interface DocBlock {
+    readonly doc?: string;
+    readonly since?: string;
+    readonly deprecated: boolean;
+}
+/**
+ * The JSDoc block directly above a declaration, or nothing.
+ *
+ * ADJACENCY IS THE WHOLE RULE. `text` is everything preceding the declaration, so the
+ * nearest block above it may belong to a sibling several members up. Requiring
+ * whitespace only between that block's terminator and the declaration is what
+ * separates "this member is documented" from "some earlier member was".
+ */
+export declare function readDocBlock(text: string): DocBlock;
+/**
+ * Read the namespace imports a vocabulary declares: `import type Gdk from
+ * '@girs/gdk-4.0'`.
+ *
+ * These are the only honest answer to "which namespaces do the rendered types reach
+ * into". Deriving it from the source list instead emitted `Gdk.RGBA` with no Gdk
+ * import — TS2503, in a file nobody edits by hand.
+ */
+export declare function readNamespaceImports(text: string, ownPkg: string): Map<string, string>;
+/**
+ * The interfaces a vocabulary `.d.ts` declares, with each property's rendered type.
+ *
+ * Brace-matched rather than terminated on a closing brace at column 0: an interface
+ * body can contain a nested object type, and a reader that stops at the first one
+ * silently truncates it. That exact shortcut is already recorded as a defect in two
+ * sibling scripts.
+ */
+export declare function readDeclaredInterfaces(text: string): Map<string, DeclaredInterface>;
+/** Property lines plus the JSDoc block immediately above each one. */
+export declare function readProps(body: string): Map<string, DeclaredProp>;
+export {};

package/lib/types/host.d.ts

@@ -1,4 +1,4 @@
-import GObject from 'gi://GObject';
+import GObject from 'gi://GObject?version=2.0';
 import type Gtk from '@girs/gtk-4.0';
 import type { HostAnchor, HostElement, HostNode, HostText, WidgetDescriptor } from './types.js';
 export declare function createElement(tag: string, props?: Record<string, unknown>): HostElement;
@@ -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;

package/lib/types/policies.d.ts

@@ -9,8 +9,14 @@ export declare function addressOf(el: HostElement): Gtk.Widget;
  * is the spelling anyone reaching for `activatable` or `selectable` uses, and
  * wrapping a row inside a second row nests two selectable widgets and detaches
  * activation from the one the author configured.
+ *
+ * A `slotted` policy reaches this too, per SLOT: an adder that hands the child to an
+ * inner `Gtk.ListBox` needs exactly the same wrap, and `Adw.ExpanderRow`'s `add_row` is
+ * one. The measurement behind that is on `ChildPolicy`'s `wrapSlots`; the short version
+ * is that `gtk_list_box_remove` does not unwrap, so without this the child leaks behind
+ * one `Gtk-WARNING` at unmount.
  */
-export declare function makeWrapper(policy: ChildPolicy, child: Gtk.Widget): Gtk.Widget | null;
+export declare function makeWrapper(policy: ChildPolicy, child: Gtk.Widget, slot: string | null): Gtk.Widget | null;
 /**
  * A container the host owns that no window shows — the DOM's detached `<div>`.
  *
@@ -52,6 +58,17 @@ export declare const makeDetachedContainer: () => Gtk.Widget;
  */
 export declare function unhandledPolicy(policy: never): never;
 export declare function setterSlotOf(parent: HostElement, child: HostElement): string | null;
+/**
+ * The slots this policy fills with an ADDER, by slot name.
+ *
+ * `set_`-prefixed or not is the whole distinction, and TWO decisions turn on it,
+ * which is why the predicate is here once rather than spelled out at each. A
+ * setter-backed slot is emptied by writing `null` back through itself, so
+ * `policyProblems()` lets such a policy name no `remove`; and it holds one child,
+ * so `rotateTail` returns before touching it — a policy with no adder slot at all
+ * has no order to pay for, which is what `reorderMode()` reports.
+ */
+export declare function adderSlots(policy: ChildPolicy): string[];
 /** Every one-child slot this policy has, by setter name — `single` has exactly one. */
 export declare function setterSlots(policy: ChildPolicy): string[];
 /**

package/lib/types/probe.d.ts

@@ -1,4 +1,5 @@
 import Adw from 'gi://Adw?version=1';
+import Gtk from 'gi://Gtk?version=4.0';
 /** Record one assertion. A `false` is a finding; nothing else is. */
 export type ProbeCheck = (what: string, ok: boolean) => void;
 /** What a showcase gives the harness. */
@@ -85,3 +86,51 @@ export declare function runHostProbe<T>(probe: HostProbe<T>): Promise<number>;
  * and hangs a view load on its spinner (the class `@gjsify/adwaita-app` documents).
  */
 export declare function runHostProbeApp<T>(probe: HostProbeApp<T>): Promise<void>;
+/**
+ * Rasterise one widget. `@gjsify/devtools`' `captureWidgetPng` has this shape;
+ * `null` means the widget has no renderer or no size yet, never "the image is empty".
+ */
+export type CaptureWidget = (widget: Gtk.Widget) => Uint8Array | null;
+/** What a picture of a subtree is worth, in numbers a `check` can read. */
+export interface ShotEvidence {
+    /**
+     * STRICT descendants of the container in the REAL GTK tree.
+     *
+     * The decisive number, and the cheapest. `0` is not "a small tree": it is a
+     * container nothing was rendered into, which is what a refused render, an
+     * unmounted root and a component that returned `null` all look like from here.
+     */
+    widgets: number;
+    width: number;
+    height: number;
+    /** PNG byte count, `0` when `capture` produced none. */
+    bytes: number;
+}
+/**
+ * Count what a shot of `container` would be a picture OF.
+ *
+ * Reads the real GTK tree (`get_first_child`/`get_next_sibling`) rather than any
+ * host bookkeeping — the shadow tree would agree with itself here, which is the
+ * whole reason `conformance/` exists.
+ */
+export declare function shotEvidence(container: Gtk.Widget, capture: CaptureWidget): ShotEvidence;
+/**
+ * Why a shot of this evidence would be blank — or `null` when it would not.
+ *
+ * Ordered by what a reader can act on. "Nothing was rendered" and "the renderer had
+ * no surface yet" are different bugs with the same photograph, and a message that
+ * cannot tell them apart sends the reader back to guessing — the state
+ * `describeLogRecord` exists to end one layer down.
+ *
+ * A NON-EMPTY PNG IS NOT PROOF, which is why byte count is the LAST question rather
+ * than the only one: a window with a refused tree still rasterises to several KB of
+ * perfectly valid background.
+ */
+export declare function blankReason(evidence: ShotEvidence): string | null;
+/**
+ * Record "this actually rendered" as a probe check, named.
+ *
+ * Takes the evidence rather than the widget so a caller that already shot it does
+ * not rasterise twice, and so the reason lands in the failure list verbatim.
+ */
+export declare function checkRendered(check: ProbeCheck, what: string, evidence: ShotEvidence): void;

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

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

package/lib/types/props.d.ts

@@ -1,4 +1,4 @@
-import GObject from 'gi://GObject';
+import GObject from 'gi://GObject?version=2.0';
 import type { WidgetDescriptor } from './types.js';
 /** `backgroundColor` and `background-color` both name the GObject property `background-color`. */
 export declare function toPropertyName(name: string): string;
@@ -33,6 +33,18 @@ export declare function constructOnlyNames(klass: GObject.ObjectClass, gtypeName
  * assumed. Also the primitive a renderer needs for a "did you mean" diagnostic.
  */
 export declare const lookupEnumNick: (gtypeName: string, nick: string) => number | undefined;
+/**
+ * The member names an installed enum registers, or `undefined` if this host has none.
+ *
+ * The INVERSE of {@link lookupEnumNick}, and it exists for the one question that
+ * function cannot answer: a nick the vocabulary never emitted is absent from every
+ * list a check could iterate, so only the host's own members can reveal it. Read off
+ * the same `ENUM_NAMESPACES` table, so the two cannot disagree about where an enum
+ * lives — a second copy of that list is what made `Pango` missing once already.
+ *
+ * `$gtype` and anything non-numeric are not members; GJS puts both on the same object.
+ */
+export declare function enumMembers(gtypeName: string): string[] | undefined;
 /**
  * Turn an authored value into one GObject will actually store.
  *

package/lib/types/registry.d.ts

@@ -1,4 +1,4 @@
-import GObject from 'gi://GObject';
+import GObject from 'gi://GObject?version=2.0';
 import type { WidgetDescriptor } from './types.js';
 export declare function registerWidget(descriptor: WidgetDescriptor): void;
 export declare function registerWidgets(descriptors: readonly WidgetDescriptor[]): void;

package/lib/types/signals.d.ts

@@ -18,9 +18,11 @@ export declare function parseEventProp(prop: string, aliases?: Readonly<Record<s
 export declare const toSignalName: (prop: string, aliases?: Readonly<Record<string, string>>) => string;
 /** An event prop is `on:` + a raw signal name, or `on` + an uppercase letter. */
 export declare function isEventProp(prop: string): boolean;
-export declare const beginHostWrite: () => void;
+export declare const beginHostWrite: (target?: object | null) => void;
 export declare const endHostWrite: () => void;
 export declare const inHostWrite: () => boolean;
+/** Is this object one whose property the host is writing at this instant? */
+export declare const isHostWriteTarget: (o: object) => boolean;
 export declare function setHandler(el: HostElement, prop: string, next: ((...args: unknown[]) => unknown) | null): void;
 /** Disconnect every handler on a node. The only place a handler dies. */
 export declare function clearHandlers(el: HostElement): void;