@gjsify/gtk-host 0.53.0 → 0.54.0

package/lib/types/policies.d.ts

@@ -9,10 +9,8 @@ export declare function addressOf(el: HostElement): Gtk.Widget;
  * GTK SPELLS ONE PLACEMENT TWICE and both spellings reach the same widget:
  * `adw_header_bar_buildable_add_child`'s `<child type="title">` branch calls
  * `adw_header_bar_set_title_widget`, i.e. writes the `title-widget` property. An authored
- * tree carries whichever spelling its SOURCE had — a Blueprint `[title]` bracket is the
- * first, a `title-widget:` property-valued child the second — and `SharedTreeNode.slot`
- * conflates the two by construction (the projection's own header records that, and that it
- * cannot be inverted). A descriptor declaring only the buildable type would therefore refuse
+ * tree carries whichever spelling its SOURCE had, and `SharedTreeNode.slot` conflates the
+ * two by construction. A descriptor declaring only the buildable type would therefore refuse
  * a placement GTK itself accepts.
  *
  * A CASE RULE OVER THE SETTER'S OWN NAME, never a table: an ADDER (`pack_start`,
@@ -23,27 +21,24 @@ export declare function slotPropertyOf(method: string): string | null;
 /**
  * Every name a policy answers to — what a refusal lists.
  *
- * Each declared key is followed by the property spelling it also answers to, so the order is
- * `['start', 'title', 'title-widget', 'end']` and not the keys first. That is deliberate: a
- * reader matching their own `slot="title-widget"` against the list finds it beside the key it
- * resolves to, rather than in a second group they have to pair up themselves.
+ * Each declared key is followed by the property spelling it also answers to, so a reader
+ * matching their own `slot="title-widget"` finds it beside the key it resolves to rather
+ * than in a second group they have to pair up themselves.
  */
 export declare function slotNames(policy: ChildPolicy): string[];
 /**
  * The DECLARED slot key an authored name asks for, or the default when it asks for nothing.
  *
  * EVERY read of `child.slot` in this file goes through here, so the property spelling
- * {@link slotPropertyOf} admits is canonical everywhere at once: a placement resolved
- * through `title-widget` and a detach resolved through `title` would otherwise be two
- * different keys to `policy.slots[…]`, and the child would leak at unmount.
- *
- * THE DEFAULT IS CHECKED LIKE ANY OTHER NAME, and it is the one that has no author to
- * blame. `defaultSlot` and `slots` are two fields of a descriptor, and an application
- * registers descriptors of its own — nothing else in this package holds the two together.
- * An unchecked default reaches `policy.slots[slot]` as `undefined` and the caller calls it:
- * `TypeError: host[undefined] is not a function`, which is exactly the shape
- * {@link errors.unknownSlot} exists to replace. Returning only keys that are IN `slots` is
- * what makes the lookup at every call site total.
+ * {@link slotPropertyOf} admits is canonical everywhere at once: a placement resolved through
+ * `title-widget` and a detach resolved through `title` would otherwise be two different keys
+ * to `policy.slots[…]`, and the child would leak at unmount.
+ *
+ * THE DEFAULT IS CHECKED LIKE ANY OTHER NAME, and it is the one with no author to blame:
+ * `defaultSlot` and `slots` are two fields of a descriptor and nothing else in this package
+ * holds them together. An unchecked default reaches `policy.slots[slot]` as `undefined` and
+ * the caller calls it: `TypeError: host[undefined] is not a function`, exactly the shape
+ * {@link errors.unknownSlot} exists to replace.
  */
 export declare function slottedSlot(policy: Extract<ChildPolicy, {
     kind: 'slotted';
@@ -51,44 +46,38 @@ export declare function slottedSlot(policy: Extract<ChildPolicy, {
 /**
  * A slot the parent cannot honour is refused BY NAME, whatever its policy kind.
  *
- * `slotted` already refused an unknown slot; every OTHER kind read `child.slot` as nothing
- * at all, so a name it has no destination for put the widget in the one place it does have
- * and said nothing. That is the defect measured on a real `.blp`: an authored placement
- * dropped, the widget on screen in the wrong container, exit 0. A `single` parent accepts
- * the property its own setter writes (`AdwApplicationWindow` + `set_content` accepts
- * `content`) and nothing else; `keyed` reads the slot as its page NAME, which is a
- * destination, so it is left alone.
+ * `slotted` already refused an unknown slot; every OTHER kind read `child.slot` as nothing at
+ * all, so a name it has no destination for put the widget in the one place it does have and
+ * said nothing — measured on a real `.blp`: an authored placement dropped, the widget on
+ * screen in the wrong container, exit 0. A `single` parent accepts the property its own
+ * setter writes (`AdwApplicationWindow` + `set_content` accepts `content`) and nothing else;
+ * `keyed` reads the slot as its page NAME, which is a destination, so it is left alone.
  */
 export declare function refuseUnknownSlot(parent: HostElement, child: HostElement): void;
 /**
  * `Gtk.ListBox` and `Gtk.FlowBox` wrap arbitrary children; the wrap is the host's job.
  *
- * Unless the author already wrote the row themselves — `<GtkListBox><GtkListBoxRow>`
- * 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.
+ * Unless the author already wrote the row themselves — `<GtkListBox><GtkListBoxRow>` 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.
+ * A `slotted` policy reaches this too, per SLOT: an adder that hands the child to an inner
+ * `Gtk.ListBox` needs the same wrap, and `Adw.ExpanderRow`'s `add_row` is one.
+ * `gtk_list_box_remove` does not unwrap, so without this the child leaks behind one
+ * `Gtk-WARNING` at unmount.
  */
 export declare function makeWrapper(descriptor: WidgetDescriptor, child: Gtk.Widget, slot: string | null): Gtk.Widget | null;
 /**
  * A container the host owns that no window shows — the DOM's detached `<div>`.
  *
- * `<KeepAlive>` and `<Suspense>` ask a renderer for off-screen storage:
- * `KeepAliveImpl.setup` opens with `createElement("div")` and `SuspenseImpl` does
- * the same for its `hiddenContainer`. The Vue adapter answered that with its own
- * `gi://Gtk` import and a literal `new Gtk.Box()` — the ONE runtime toolkit import
- * and the ONE concrete widget class in any adapter, i.e. exactly the widget
- * knowledge ADR 0027 § 7 forbids one. It lives here because this is already the
- * file that builds widgets the author did not write (see `makeWrapper`), and it is
- * the only one with a runtime `gi://Gtk` import.
- *
- * A `Gtk.Box` and not an `Adw.Bin`: the deactivated subtree may hold SEVERAL
- * children, and a one-child container would silently keep the last.
+ * `<KeepAlive>` and `<Suspense>` ask a renderer for off-screen storage. It lives here because
+ * this is already the file that builds widgets the author did not write (see `makeWrapper`),
+ * and it is the only one with a runtime `gi://Gtk` import — which is what ADR 0027 § 7 forbids
+ * in an adapter.
+ *
+ * A `Gtk.Box` and not an `Adw.Bin`: the deactivated subtree may hold SEVERAL children, and a
+ * one-child container would silently keep the last.
  */
 export declare const makeDetachedContainer: () => Gtk.Widget;
 /**
@@ -106,25 +95,21 @@ export declare const makeDetachedContainer: () => Gtk.Widget;
 /**
  * Compile-time exhaustiveness, which this package does NOT get for free.
  *
- * `tsconfig.json` sets `strict: false`, so a switch that stops covering its union
- * simply falls through and returns `undefined` — no error. Adding the `uncurated`
- * policy kind passed `tsc` cleanly while five switches silently ignored it, which
- * is exactly the class of green-and-wrong this package exists to prevent
- * elsewhere. Assignability to `never` is not a strictness option, so a `default`
- * arm calling this DOES fail the build (measured) and is the only mechanism that
- * makes the next union member impossible to forget.
+ * `tsconfig.json` sets `strict: false`, so a switch that stops covering its union simply
+ * falls through and returns `undefined` — no error. Adding the `uncurated` policy kind
+ * passed `tsc` cleanly while five switches silently ignored it. Assignability to `never` is
+ * not a strictness option, so a `default` arm calling this DOES fail the build (measured)
+ * and is the only mechanism that makes the next union member impossible to forget.
  */
 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
+ * `set_`-prefixed or not is the whole distinction, and TWO decisions turn on it: 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.
+ * `policyProblems()` lets such a policy name no `remove`; and it holds one child, so
+ * `rotateTail` returns before touching it.
  */
 export declare function adderSlots(policy: ChildPolicy): string[];
 /** Every one-child slot this policy has, by setter name — `single` has exactly one. */
@@ -132,16 +117,13 @@ export declare function setterSlots(policy: ChildPolicy): string[];
 /**
  * Who GTK says is in a one-child slot. `undefined` means there is no getter to ask.
  *
- * The slot's own getter is the ONLY honest reader of this, and a child-list walk
- * is not a substitute: measured on gtk 4.22.4 / libadwaita 1.9.3, a FRESH widget
- * already has direct children the application never put there —
- * `Gtk.ScrolledWindow` two `GtkScrollbar`s, `Adw.ToolbarView` two
- * `GtkRevealer`s, `Adw.Window` an `AdwDialogHost` + an `AdwGizmo`,
- * `Adw.StatusPage` a `GtkScrolledWindow` — while every one of those widgets
- * answers `null` from its getter. The getter also survives GTK wrapping the
- * child: `Gtk.ScrolledWindow.set_child(label)` reports a `GtkViewport`, not the
- * label, so callers may compare occupants for IDENTITY but never assume the
- * occupant is the widget they handed over.
+ * The slot's own getter is the ONLY honest reader of this, and a child-list walk is not a
+ * substitute: measured on gtk 4.22.4 / libadwaita 1.9.3, a FRESH widget already has direct
+ * children the application never put there, while every one of those widgets answers `null`
+ * from its getter. The getter also survives GTK wrapping the child:
+ * `Gtk.ScrolledWindow.set_child(label)` reports a `GtkViewport`, not the label — so callers
+ * may compare occupants for IDENTITY but never assume the occupant is the widget they handed
+ * over.
  */
 export declare function slotOccupant(widget: Gtk.Widget, setter: string): Gtk.Widget | null | undefined;
 /** A placement that does NOT put the node into its parent's child list. */
@@ -175,13 +157,11 @@ export declare const isPortal: (el: HostElement) => boolean;
 /**
  * Does this node take NO position in its parent's child list?
  *
- * The question four sibling walks ask, and it is the placement AXIS rather than
- * the portal arm: a toplevel occupies a parent's child list exactly as little as a
- * portal does. Asking `isPortal` there was correct while `portal` was the only
- * non-parented kind and became a silent hole the moment it was not — counting a
- * toplevel as a sibling shifts every later child by one and hands
- * `insert_child_after` a widget that is not in the container (a critical at exit 0),
- * and rotating one calls the parent's adder on a node that must never enter it.
+ * The question four sibling walks ask, and it is the placement AXIS rather than the portal
+ * arm: a toplevel occupies a parent's child list exactly as little as a portal does. Counting
+ * a toplevel as a sibling shifts every later child by one and hands `insert_child_after` a
+ * widget that is not in the container (a critical at exit 0), and rotating one calls the
+ * parent's adder on a node that must never enter it.
  */
 export declare const isUnparented: (el: HostElement) => boolean;
 /**
@@ -189,30 +169,26 @@ export declare const isUnparented: (el: HostElement) => boolean;
  *
  * Returns whether GTK has actually taken the node, which is what `attached` means.
  *
- * WHY THE WAIT IS THE FEATURE. Every framework builds bottom-up: React creates the
- * whole subtree, appends its children, and inserts the ROOT into the container
- * last, so at the moment a `<Modal>` is inserted its parent is usually not in a
- * window yet. MEASURED on libadwaita 1.9.3 / GTK 4.22.4, presenting against an
- * unrooted box: `adw_dialog_present` finds no `AdwDialogHost` among the parent's
- * ancestors and takes its documented other branch, `present_as_window` — the
- * dialog opens as a SEPARATE `GtkWindow`, `win.visibleDialog` stays false, exit 0,
- * no diagnostic. A modal that floats out of its own application is exactly the
- * green-and-wrong this host exists to refuse, and nothing in the shadow tree can
- * see it.
- *
- * `notify::root` is the instrument. MEASURED: it fires on a GRANDCHILD box when
- * the toplevel takes the subtree (root -> AdwWindow), and again on unroot (root ->
- * null). The subscription STAYS for the life of the attachment rather than being
- * one-shot, because re-rooting is real: measured, unrooting the parent leaves an
- * already-presented dialog in the OLD window's host — `w1.visibleDialog` still
- * true after `w1.set_content(null)` — so a subtree moved to a second window would
- * silently keep showing its modal in the first.
- *
- * SYMMETRIC, and the second direction is not free. GTK does not take the dialog
- * down when the anchor loses its window, so losing a toplevel RETRACTS the node
- * rather than merely failing to present it (see `placeAgainst`). Without that, a
- * subtree that is detached and never re-rooted keeps its sheet on screen in the
- * window it left, and only a re-root — which such a subtree never gets — repairs it.
+ * WHY THE WAIT IS THE FEATURE. Every framework builds bottom-up: React creates the whole
+ * subtree, appends its children, and inserts the ROOT into the container last, so at the
+ * moment a `<Modal>` is inserted its parent is usually not in a window yet. MEASURED on
+ * libadwaita 1.9.3 / GTK 4.22.4, presenting against an unrooted box: `adw_dialog_present`
+ * finds no `AdwDialogHost` among the parent's ancestors and takes its documented other
+ * branch, `present_as_window` — the dialog opens as a SEPARATE `GtkWindow`,
+ * `win.visibleDialog` stays false, exit 0, no diagnostic. A modal that floats out of its own
+ * application is exactly the green-and-wrong this host exists to refuse.
+ *
+ * `notify::root` is the instrument. MEASURED: it fires on a GRANDCHILD box when the toplevel
+ * takes the subtree (root -> AdwWindow), and again on unroot (root -> null). The
+ * subscription STAYS for the life of the attachment rather than being one-shot, because
+ * re-rooting is real: measured, unrooting the parent leaves an already-presented dialog in
+ * the OLD window's host — `w1.visibleDialog` still true after `w1.set_content(null)` — so a
+ * subtree moved to a second window would silently keep showing its modal in the first.
+ *
+ * SYMMETRIC, and the second direction is not free: GTK does not take the dialog down when
+ * the anchor loses its window, so losing a toplevel RETRACTS the node (see
+ * `placeAgainst`). Without that, a subtree that is detached and never re-rooted keeps its
+ * sheet on screen in the window it left.
  */
 export declare function presentPortal(parent: HostElement, child: HostElement, portal: Extract<NodePlacement, {
     kind: 'portal';
@@ -220,14 +196,13 @@ export declare function presentPortal(parent: HostElement, child: HostElement, p
 /**
  * Take a portal node back down, with no probe and no `attached` guard.
  *
- * UNCONDITIONALLY, twice over, and both halves are measured. The method the
- * descriptor names is the FORCED close (`force_close`, not `close`): an unmount is
- * not a user request, and `close()` on a dialog whose `can-close` is FALSE returns
- * FALSE, emits `close-attempt` and leaves it on screen. And `force_close()` on a
- * node that was never presented is silent, where `close()` is
- * `Adwaita-CRITICAL **: Trying to close … that's not presented` at exit 0 — so the
- * host needs no "is it up?" question, which is the one it could not answer without
- * knowing what a dialog is.
+ * UNCONDITIONALLY, twice over, and both halves are measured. The method the descriptor names
+ * is the FORCED close (`force_close`, not `close`): an unmount is not a user request, and
+ * `close()` on a dialog whose `can-close` is FALSE returns FALSE, emits `close-attempt` and
+ * leaves it on screen. And `force_close()` on a node that was never presented is silent,
+ * where `close()` is `Adwaita-CRITICAL **: Trying to close … that's not presented` at exit
+ * 0 — so the host needs no "is it up?" question, which is the one it could not answer
+ * without knowing what a dialog is.
  */
 export declare function retractPortal(child: HostElement, portal: Extract<NodePlacement, {
     kind: 'portal';
@@ -235,23 +210,22 @@ export declare function retractPortal(child: HostElement, portal: Extract<NodePl
 /**
  * Show a toplevel node — and it needs nothing from its parent, which is the point.
  *
- * NO ANCHOR, NO WAIT, NO SUBSCRIPTION. A portal has two positions in the tree and
- * defers until the parent supplies the second one; a toplevel HAS no second
- * position, so the whole `notify::root` machinery next door has nothing to watch
- * for. Measured: `gtk_window_present` takes 0 arguments where
- * `adw_dialog_present` takes 1, and that arity is exactly the difference.
- *
- * Returns whether GTK has taken the node — always true once there is a widget,
- * because a root is taken by nobody: measured, a presented window answers
- * `get_parent() === null` and `get_root() === itself`. That is not the portal's
- * "claimed but not yet taken" state, it is the finished one.
- *
- * AN AUTHORED `visible: false` IS HONOURED rather than overwritten. `present()`
- * sets the window visible (measured), so presenting unconditionally would make
- * `<gtk-window visible={false}>` a property this host silently reverses — the
- * exact shape it exists to refuse. The node is still `attached`: GTK holds it as
- * its own root whether or not it is on screen, and a later `setProp(el,
- * 'visible', true)` shows it through the ordinary property path.
+ * NO ANCHOR, NO WAIT, NO SUBSCRIPTION. A portal has two positions in the tree and defers
+ * until the parent supplies the second one; a toplevel HAS no second position, so the whole
+ * `notify::root` machinery next door has nothing to watch for. Measured: `gtk_window_present`
+ * takes 0 arguments where `adw_dialog_present` takes 1, and that arity is exactly the
+ * difference.
+ *
+ * Returns whether GTK has taken the node — always true once there is a widget, because a root
+ * is taken by nobody: measured, a presented window answers `get_parent() === null` and
+ * `get_root() === itself`. That is not the portal's "claimed but not yet taken" state, it is
+ * the finished one.
+ *
+ * AN AUTHORED `visible: false` IS HONOURED rather than overwritten. `present()` sets the
+ * window visible (measured), so presenting unconditionally would make `<gtk-window
+ * visible={false}>` a property this host silently reverses. The node is still `attached`:
+ * GTK holds it as its own root whether or not it is on screen, and a later
+ * `setProp(el, 'visible', true)` shows it through the ordinary property path.
  */
 export declare function presentToplevel(child: HostElement, placement: Extract<NodePlacement, {
     kind: 'toplevel';
@@ -260,19 +234,15 @@ export declare function presentToplevel(child: HostElement, placement: Extract<N
  * Take a toplevel back down — the FORCED call, and it is TERMINAL.
  *
  * `destroy` and not `close`, measured on GTK 4.22.4: `gtk_window_close()` emits
- * `close-request`, and an application handler returning TRUE leaves the window
- * mapped and visible. That veto is how an application asks the USER to confirm,
- * and an unmount is not a user request — the same reasoning that makes the portal
- * arm name `force_close`.
- *
- * Unconditional for the same reason too: measured, `destroy()` on a window that
- * was never presented is silent, so no "is it up?" probe is needed. What differs
- * from the portal is that there IS no way back — measured, `present()` after a
- * destroy (or after a `close()`, whose default handler destroys) answers
- * `Gtk-WARNING **: A window is shown after it has been destroyed`.
- *
- * SO THIS IS `destroy`'s CALL AND NOT `remove`'s, which is the whole reason
- * `detachToplevel` exists next door. `remove` documents itself as reversible.
+ * `close-request`, and an application handler returning TRUE leaves the window mapped and
+ * visible. That veto is how an application asks the USER to confirm, and an unmount is not a
+ * user request — the same reasoning that makes the portal arm name `force_close`.
+ *
+ * Unconditional for the same reason too: measured, `destroy()` on a window that was never
+ * presented is silent, so no "is it up?" probe is needed. What differs from the portal is that
+ * there IS no way back — measured, `present()` after a destroy (or after a `close()`, whose
+ * default handler destroys) answers `Gtk-WARNING **: A window is shown after it has been
+ * destroyed`.
  */
 export declare function closeToplevel(child: HostElement, placement: Extract<NodePlacement, {
     kind: 'toplevel';
@@ -280,31 +250,26 @@ export declare function closeToplevel(child: HostElement, placement: Extract<Nod
 /**
  * Take a toplevel OFF SCREEN, reversibly — `remove`'s call.
  *
- * `remove` is documented as a detach that a later `insert` undoes ("Frameworks
- * move nodes; `remove` must not destroy one"), and Solid takes it literally: its
- * `removeNode` calls `remove(node)` for a move and reaches `destroy` only through
- * the root disposer. Running the declared, TERMINAL close there made a move
- * `destroy()` the window and then present the corpse —
- * `Gtk-WARNING **: A window is shown after it has been destroyed`, at exit 0,
- * visible only because `installDiagnosticsGate()` was watching.
- *
- * A PROPERTY WRITE AND NOT A DECLARED METHOD, and that is the honest shape rather
- * than a shortcut: a window's presence on screen IS its `visible` property — which
- * is why `presentToplevel` already reads it — so every toplevel detaches the same
- * way and a per-row name would be the same string once per declared row. The portal
- * arm needs no counterpart at all, because its declared close is ALREADY reversible.
- *
- * MEASURED on GTK 4.22.4, one window, in order: `set_visible(false)` leaves it
- * `visible` false with one `unmap`, emits NO `close-request`, and keeps it in
+ * `remove` is documented as a detach that a later `insert` undoes ("Frameworks move nodes;
+ * `remove` must not destroy one"), and Solid takes it literally: its `removeNode` calls
+ * `remove(node)` for a move. Running the declared, TERMINAL close there made a move
+ * `destroy()` the window and then present the corpse — `Gtk-WARNING **: A window is shown
+ * after it has been destroyed`, at exit 0.
+ *
+ * A PROPERTY WRITE AND NOT A DECLARED METHOD, and that is the honest shape rather than a
+ * shortcut: a window's presence on screen IS its `visible` property — which is why
+ * `presentToplevel` already reads it. The portal arm needs no counterpart, because its
+ * declared close is ALREADY reversible.
+ *
+ * MEASURED on GTK 4.22.4, one window, in order: `set_visible(false)` leaves it `visible`
+ * false with one `unmap`, emits NO `close-request`, and keeps it in
  * `Gtk.Window.list_toplevels()` — so it is a detach and not a teardown; `present()`
- * afterwards maps it again with no diagnostic at all; a second `set_visible(false)`
- * is a no-op; and `destroy()` on the hidden window adds no `unmap` and DOES drop it
- * from the toplevel list. `set_visible` rather than the deprecated `hide()`, which
- * is the same call one rename older.
- *
- * Unbracketed, unlike `writeVisible`'s host writes: this is not bookkeeping around
- * a libadwaita defect that the consumer's model never mentions — the window really
- * did leave the screen, and a bound `notify::visible` is entitled to hear it.
+ * afterwards maps it again with no diagnostic at all. `set_visible` rather than the
+ * deprecated `hide()`, which is the same call one rename older.
+ *
+ * Unbracketed, unlike `writeVisible`'s host writes: this is not bookkeeping around a
+ * libadwaita defect the consumer's model never mentions — the window really did leave the
+ * screen, and a bound `notify::visible` is entitled to hear it.
  */
 export declare function detachToplevel(child: HostElement): void;
 /**
@@ -318,47 +283,41 @@ export declare function placeOutsideParent(parent: HostElement, child: HostEleme
 /**
  * The REVERSIBLE take-down — what `remove` means, per arm.
  *
- * THE TWO ARMS DIFFER HERE AND NOWHERE ELSE, which is why one function could not
- * serve both: measured, `force_close()` followed by `present(parent)` re-hosts a
- * dialog against the SAME parent with no diagnostic, while `destroy()` followed by
- * `present()` is `Gtk-WARNING **: A window is shown after it has been destroyed`.
- * The portal arm therefore never showed this defect and the toplevel arm shipped
- * with it: a single `retractOutsideParent` treated a reversible verb and a terminal
- * one as the same thing.
+ * THE TWO ARMS DIFFER HERE AND NOWHERE ELSE, which is why one function cannot serve both:
+ * measured, `force_close()` followed by `present(parent)` re-hosts a dialog against the SAME
+ * parent with no diagnostic, while `destroy()` followed by `present()` is `Gtk-WARNING **: A
+ * window is shown after it has been destroyed`.
  */
 export declare function detachOutsideParent(child: HostElement, placement: OutsideParent): void;
 /**
  * The TERMINAL take-down — what `destroy` means, and what a DISCARD means.
  *
- * Its one caller is `releaseWidget` in `host.ts`, which is every place the host
- * drops `el.widget`: a toplevel is held by GTK's own list rather than by a parent
- * (measured, `list_toplevels()` holds a window from CONSTRUCTION and loses it only
- * on `destroy`), so a discard that merely detached would leak one window each time
- * — per construct-only write, and per half-built element a failed replay rolls back.
+ * Its one caller is `releaseWidget` in `host.ts`, which is every place the host drops
+ * `el.widget`: a toplevel is held by GTK's own list rather than by a parent, so a discard
+ * that merely detached would leak one window each time — per construct-only write, and per
+ * half-built element a failed replay rolls back.
  */
 export declare function closeOutsideParent(child: HostElement, placement: OutsideParent): void;
 /**
  * The placement the installed libraries give this class, or null for an ordinary child.
  *
- * STRUCTURAL, never a name. ADR 0027 rule 1 forbids widget knowledge in the host,
- * and a list of gtypes here would be exactly that — so the class is asked two
- * questions it answers itself. Both were measured over the WHOLE shipped table on
- * GTK 4.22.4 / libadwaita 1.9.3 rather than over a sample, which is what makes the
- * second one a partition and not an observation:
- *
- *  - `Gtk.Root` is GTK's OWN word for "this widget is a toplevel", and every class
- *    in the table implementing it — `GtkWindow` through `GtkPrintUnixDialog` — is
- *    one no parent may legally take.
- *  - A `present()` that TAKES AN ARGUMENT is a node presented AGAINST something.
- *    In the table that set is EXACTLY the `Adw.Dialog` descendants and nothing
- *    else — the ones whose `root` vfunc calls `g_error()`.
- *    `Gtk.Popover.present()` is the discriminator that makes the ARITY part of the
- *    question rather than the name: it exists, it takes 0 arguments, and a popover
- *    is parented with `set_parent()` like any other child.
- *
- * The order matters and is not alphabetical: every `Gtk.Root` in the table that has
- * a `present` at all has a 0-argument one, and `GtkDragIcon` has none — so the root
- * test has to come first and cannot be replaced by an arity test.
+ * STRUCTURAL, never a name. ADR 0027 rule 1 forbids widget knowledge in the host, and a
+ * list of gtypes here would be exactly that — so the class is asked two questions it answers
+ * itself. Both were measured over the WHOLE shipped table on GTK 4.22.4 / libadwaita 1.9.3,
+ * which is what makes the second one a partition and not an observation:
+ *
+ *  - `Gtk.Root` is GTK's OWN word for "this widget is a toplevel", and every class in the
+ *    table implementing it — `GtkWindow` through `GtkPrintUnixDialog` — is one no parent may
+ *    legally take.
+ *  - A `present()` that TAKES AN ARGUMENT is a node presented AGAINST something. In the table
+ *    that set is EXACTLY the `Adw.Dialog` descendants and nothing else — the ones whose `root`
+ *    vfunc calls `g_error()`. `Gtk.Popover.present()` is the discriminator that makes the
+ *    ARITY part of the question rather than the name: it exists, it takes 0 arguments, and a
+ *    popover is parented with `set_parent()` like any other child.
+ *
+ * The order matters and is not alphabetical: every `Gtk.Root` in the table that has a
+ * `present` at all has a 0-argument one, and `GtkDragIcon` has none — so the root test has
+ * to come first and cannot be replaced by an arity test.
  *
  * @param gtype the class's GType — `type_is_a` walks interfaces as well as parents
  * @param present the class's own `present`, or the value found on an instance
@@ -369,18 +328,16 @@ export declare function nodePlacementKind(node: Gtk.Widget): OutsideParent['kind
 /**
  * Refuse a child the installed libraries will not adopt, BEFORE the adder runs.
  *
- * This is the catchable half of the abort class (ADR 0054). `descriptorProblems()`
- * says the same thing about the whole TABLE up front, which is what keeps the
- * shipped rows honest — but `registerWidget` takes descriptors from applications
- * and nothing checks those, and for one of the two families the consequence is not
- * a wrong window: `adw_dialog_root()` is `g_error()`, so the process is gone before
- * any handler runs. A refusal is only possible while there is still a process.
+ * This is the catchable half of the abort class (ADR 0054). `descriptorProblems()` says the
+ * same thing about the whole TABLE up front, but `registerWidget` takes descriptors from
+ * applications and nothing checks those — and for one of the two families the consequence is
+ * not a wrong window: `adw_dialog_root()` is `g_error()`, so the process is gone before any
+ * handler runs. A refusal is only possible while there is still a process.
  *
  * ONLY WHERE THE DESCRIPTOR IS SILENT, and that is the escape hatch rather than an
- * oversight. `placement` present — including an explicit `{ kind: 'parented' }` —
- * means the author has answered this question, and the host does not overrule an
- * answer with a heuristic. A consumer widget that trips the `present(parent)` half
- * of the oracle while really being a child says so in one line.
+ * oversight. `placement` present — including an explicit `{ kind: 'parented' }` — means the
+ * author has answered this question, and the host does not overrule an answer with a
+ * heuristic.
  */
 export declare function refuseUnparentable(parent: HostElement, child: HostElement): void;
 export interface Placement {

package/lib/types/props.d.ts

@@ -5,16 +5,13 @@ export declare function toPropertyName(name: string): string;
 /**
  * A props object without the keys a framework reserves for itself.
  *
- * The SET is per-framework and stays with the adapter that owns it — Vue's is
- * `@vue/shared`'s `isReservedProp`, React's is `children` — but the LOOP was
- * written twice, byte-for-byte apart from the identifier names. That is the second
- * copy this repo lifts on: the two would drift, and the drifted one fails in a
- * consumer while the host stays green.
+ * The SET is per-framework and stays with the adapter that owns it; the LOOP is here because two
+ * adapters each wrote their own, and the drifted one fails in a consumer while the host stays
+ * green.
  *
  * `undefined` rather than `{}` for an empty result, and that is load-bearing:
- * `createElement(tag, undefined)` skips the property loop entirely, so a vnode
- * whose props are ALL reserved must not look like a vnode with one unknown
- * property.
+ * `createElement(tag, undefined)` skips the property loop entirely, so a vnode whose props are ALL
+ * reserved must not look like a vnode with one unknown property.
  */
 export declare function withoutKeys(props: Record<string, unknown> | null | undefined, skip: ReadonlySet<string>): Record<string, unknown> | undefined;
 /** All ParamSpecs of a class, by kebab name. Cached per GType — `list_properties()` is not cheap. */
@@ -26,50 +23,40 @@ export declare function constructOnlyNames(klass: GObject.ObjectClass, gtypeName
 /**
  * The GType a name registers on this host, forcing the registration if it has to.
  *
- * `type_from_name` is asked FIRST because it is the answer that needs no table. It
- * answers null until something has touched the type, which is why the table is still
- * reachable at all: reading `Gio.PasswordSave` is what registers `GPasswordSave`.
+ * `type_from_name` is asked FIRST because it is the answer that needs no table. It answers null
+ * until something has touched the type, which is why the table is still reachable at all: reading
+ * `Gio.PasswordSave` is what registers `GPasswordSave`.
  *
- * NEITHER BRANCH IS THE FIX ALONE, and the order is what makes the measured case work:
- * a type nobody has read is absent from `type_from_name`, and a name
- * {@link giTypeObject} cannot reach is absent from the table. Exported because it is
- * THE answer to "does this host have that type" — a consumer gating on a GTK version
- * asks here rather than walking a namespace list of its own.
+ * NEITHER BRANCH IS THE FIX ALONE, and the order is what makes the measured case work: a type
+ * nobody has read is absent from `type_from_name`, and a name {@link giTypeObject} cannot reach is
+ * absent from the table.
  */
 export declare function gtypeOfName(gtypeName: string): GObject.GType | undefined;
 /**
  * The value a nick names on an enum or bitfield GType, or undefined if it names none.
  *
- * Exported for the generated surface's own check: the type surface offers a union
- * of nicks per enum, and a nick this host cannot resolve would type-check and then
- * be refused at runtime. `generated.spec.ts` resolves every emitted nick through
- * this function, so the GIR-member-to-nick spelling is measured rather than
- * assumed. Also the primitive a renderer needs for a "did you mean" diagnostic.
+ * Exported for the generated surface's own check: the type surface offers a union of nicks per
+ * enum, and a nick this host cannot resolve would type-check and then be refused at runtime.
+ * Also the primitive a renderer needs for a "did you mean" diagnostic.
  *
- * The NAME is kept in the signature although a GType would need no lookup, because
- * every caller has the name and not the type — the check reads it off a generated
- * table, a renderer off `GObject.type_name(spec.value_type)`.
+ * The NAME is kept in the signature although a GType would need no lookup, because every caller
+ * has the name and not the type.
  */
 export declare const lookupEnumNick: (gtypeName: string, nick: string) => number | undefined;
 /**
  * The member names an installed enum or bitfield 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. GJS
- * offers no route to a `GEnumClass`, so the members come off the namespace object —
- * which is the whole remaining reason {@link GI_NAMESPACES} exists.
+ * 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. GJS offers no route to a `GEnumClass`, so the members
+ * come off the namespace object — the whole remaining reason {@link GI_NAMESPACES} exists.
  *
  * `$gtype` and anything non-numeric are not members; GJS puts both on the same object.
  *
- * AND THE TYPE HAS TO BE ONE, or the widened {@link giTypeObject} turns this into a
- * second answer rather than a wider one. It now returns a CLASS as readily as an enum,
- * and a class carries no numeric members — `undefined` would be wrong (the type is
- * there) and `[]` is worse (it reads as "an enum that registers nothing", which is the
- * claim every caller is entitled to trust). The GType the lookup already confirmed is
- * what asks, so this is the same predicate the nicks branches above are routed on
- * rather than a new way of spelling it.
+ * AND THE TYPE HAS TO BE ONE, or the widened {@link giTypeObject} turns this into a second answer
+ * rather than a wider one: a CLASS carries no numeric members, and `[]` would read as "an enum
+ * that registers nothing", which is the claim every caller is entitled to trust.
  */
 export declare function enumMembers(gtypeName: string): string[] | undefined;
 /**