@gjsify/gtk-host 0.48.0 → 0.49.0

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

@@ -1,2 +1,33 @@
-import type { WidgetDescriptor } from '../types.js';
+import type { NodePlacement, WidgetDescriptor } from '../types.js';
+/**
+ * The placement every `Gtk.Root` shares — ADR 0054.
+ *
+ * `present` and `destroy` are measured on GTK 4.22.4; the measurements that pick
+ * `destroy` over `close` (a vetoed `close-request` leaves the window up) and that
+ * make the retraction terminal are on `NodePlacement`'s toplevel arm in `types.ts`.
+ *
+ * SHARED WITH `adw.ts`, which imports it: a toplevel is a fact about the TYPE, and
+ * `Gtk.Root`'s presentable implementations are split across the two libraries by
+ * nothing but who owns the class (measured with `GObject.type_is_a`). They are
+ * NAMED rather than inherited for the reason the dialog family is: registration is
+ * exact, so `lookupWidget('GtkMessageDialog')` answers the GENERATED row and an
+ * inherited placement would never be looked up. `is declared by every registered
+ * Gtk.Root` in `placement.spec.ts` is what keeps the list complete, and it holds
+ * the count so no comment has to.
+ *
+ * `GtkDragIcon` is the one `Gtk.Root` deliberately absent: measured, it has no
+ * `present`, no `close` and no `destroy` — GTK creates one for a drag operation and
+ * nothing else ever shows one. It is refused at the insert by `refuseUnparentable`
+ * instead, which is the honest answer for a root that cannot present itself, and
+ * the spec NAMES it so a second such class is a decision rather than a bumped
+ * number.
+ *
+ * CHILDREN STAY UNCURATED on every row that had no policy before this. A window
+ * takes `set_child`, but `GtkDialog` and its five chooser subclasses put children
+ * into a content area (`get_content_area`) that `set_child` would REPLACE, and
+ * `GtkAssistant` addresses pages by index — the `AdwAlertDialog` trap one axis
+ * over. Guessing here buys a warning at exit 0; the tags are creatable,
+ * propertyable and presentable, and a child in one is a named refusal.
+ */
+export declare const TOPLEVEL: NodePlacement;
 export declare const GTK_DESCRIPTORS: readonly WidgetDescriptor[];

package/lib/types/errors.d.ts

@@ -21,6 +21,20 @@ export declare const err: {
     readOnlyProp: (tag: string, prop: string) => GtkHostError;
     noAccessor: (tag: string, prop: string, accessor: string) => GtkHostError;
     badDetailedAction: (label: string, detailed: string, why: string) => GtkHostError;
+    badListModel: (tag: string, prop: string, got: string) => GtkHostError;
+    /**
+     * A list-shaped property the portable list model cannot satisfy.
+     *
+     * `Gtk.ListView:model` is a `Gtk.SelectionModel`, which IS a `Gio.ListModel` — so a
+     * branch keyed on the ParamSpec's list-ness alone would build a `Gtk.StringList` for
+     * it, and GObject's answer to that is SILENCE (measured, GTK 4.22.4): `set_property`
+     * transforms an object of the wrong type into NULL and logs nothing, so the view is
+     * empty at exit 0 and not even the diagnostics gate reports it. The second test in
+     * `coerce` asks whether the property can HOLD what the branch builds; where it
+     * cannot, this names the type GTK wants.
+     */
+    listModelMismatch: (tag: string, prop: string, gtypeName: string) => GtkHostError;
+    badAdjustment: (tag: string, prop: string, got: string) => GtkHostError;
     badEnum: (tag: string, prop: string, nick: string, gtypeName: string) => GtkHostError;
     unknownSignal: (tag: string, prop: string, signal: string) => GtkHostError;
     signalTaken: (tag: string, prop: string, other: string, signal: string) => GtkHostError;
@@ -61,14 +75,32 @@ export declare const err: {
     notAWidget: (tag: string) => GtkHostError;
     occupiedSlot: (parentTag: string, childTag: string, setter: string) => GtkHostError;
     /**
-     * A portal descriptor naming a method the installed class does not have.
+     * A placement naming a method the installed class does not have.
      *
      * `descriptorProblems()` rejects this shape up front, so a BUILT-IN descriptor
      * can never reach here — an application-registered one is checked by nobody,
      * and the alternative is `TypeError: widget[placement.present] is not a
      * function` thrown from inside an insert, naming neither the tag nor the axis.
      */
-    portalMethodMissing: (tag: string, method: string, role: "present" | "close") => GtkHostError;
+    placementMethodMissing: (tag: string, kind: string, method: string, role: "present" | "close") => GtkHostError;
+    /**
+     * A child GTK will not take, refused BEFORE the parent's adder is called.
+     *
+     * THE ONLY REFUSAL IN THIS FILE THAT EXISTS TO PREVENT A PROCESS ABORT rather
+     * than a wrong window. `adw_dialog_root()` answers a parented dialog with
+     * `g_error()` — SIGABRT, exit 134, a core dump — which no `try` catches and no
+     * diagnostics gate counts, so a message can only be produced while there is
+     * still a process to produce it (ADR 0054). Its neighbour is the opposite and
+     * just as wrong: a `GtkRoot` appended to a rooted box is accepted at exit 0
+     * with nothing logged, leaving a toplevel with a parent.
+     *
+     * The class is asked STRUCTURALLY and never by name — `Gtk.Root` for a
+     * toplevel, a `present()` that takes a parent for a portal — so a consumer's
+     * own subclass is refused exactly like a shipped one. A widget that trips the
+     * oracle and really is a child says so with an explicit
+     * `placement: { kind: 'parented' }`.
+     */
+    unparentableChild: (parentTag: string, childTag: string, kind: string, why: string) => GtkHostError;
     notAnElement: (kind: string) => GtkHostError;
     destroyedNode: (tag: string) => GtkHostError;
     notAHostParent: (got: string) => GtkHostError;

package/lib/types/font-families.d.ts

@@ -0,0 +1,40 @@
+/** How a declared family name was found among the families a font map holds. */
+export type FontFamilyMatchKind = 'exact' | 'optical' | 'ambiguous' | 'absent';
+/** What a declared family name resolves to on a given font map. */
+export interface FontFamilyMatch {
+    /** The name the application wrote. */
+    readonly declared: string;
+    /**
+     * The family name to put in a `Pango.FontDescription` or a `font-family` declaration, or
+     * `undefined` when there is no answer this module may give (`absent`, `ambiguous`).
+     */
+    readonly family: string | undefined;
+    readonly kind: FontFamilyMatchKind;
+    /**
+     * Every family on the map that is a plausible reading of `declared`. One entry for `exact`
+     * and `optical`, several for `ambiguous`, none for `absent` — so a caller resolving an
+     * ambiguity has the candidates in hand and does not have to re-derive them.
+     */
+    readonly candidates: readonly string[];
+}
+/**
+ * Resolve one declared family name against the families a font map holds.
+ *
+ * Both directions of the divergence, because it is one fact read from either side: an application
+ * written against the fontconfig name (`Merriweather`) meets `Merriweather 18pt` on Windows, and
+ * one written against the Windows name meets `Merriweather` everywhere else. Neither is more
+ * correct than the other, and an application that hardcodes either has to keep working on the
+ * other platform — which is the whole complaint.
+ */
+export declare function matchFontFamily(declared: string, families: readonly string[]): FontFamilyMatch;
+/** {@link matchFontFamily} over a list, in the order declared. */
+export declare function matchFontFamilies(declared: readonly string[], families: readonly string[]): readonly FontFamilyMatch[];
+/**
+ * One line saying what happened to a declared family, for a caller that wants to print it.
+ *
+ * Exported because the wording is the point: a report that says "not found" leaves the reader
+ * to guess whether the file failed, the map declined it, or the name simply differs here — and
+ * those have three different repairs. The `optical` line is the one that earns its keep, because
+ * a rename is exactly what does NOT look like a problem when the window renders.
+ */
+export declare function describeFontFamilyMatch(match: FontFamilyMatch): string;

package/lib/types/font-families.spec.d.ts

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

package/lib/types/fonts.d.ts

@@ -1,6 +1,20 @@
+import { type FontFamilyMatch } from './font-families.js';
 import { type ResolveFontDirOptions } from './font-dir.js';
+export { describeFontFamilyMatch, matchFontFamilies, matchFontFamily, type FontFamilyMatch, type FontFamilyMatchKind, } from './font-families.js';
 /** Everything {@link resolveFontDir} takes except the environment, which {@link initFonts} reads. */
-export type InitFontsOptions = Omit<ResolveFontDirOptions, 'env'>;
+export interface InitFontsOptions extends Omit<ResolveFontDirOptions, 'env'> {
+    /**
+     * The family names this application will ASK FOR — checked against the map once registration
+     * is done, and reported in {@link InitFontsResult.matches}.
+     *
+     * Optional, and the reason to pass it is that nothing downstream can. A `font-family`
+     * declaration cannot know which file was supposed to back it, and `list_families()` alone
+     * cannot say which of 84 names arrived from the staged directory; this call is the one moment
+     * that has both. Every name that does not resolve is WARNED about here, which is the only
+     * place a missing family is ever loud — Pango substitutes silently and the window renders.
+     */
+    readonly expectedFamilies?: readonly string[];
+}
 /** A face the font map would not take, and why. */
 export interface FontFaceFailure {
     readonly path: string;
@@ -16,6 +30,36 @@ export interface InitFontsResult {
     readonly declined: readonly string[];
     /** Faces that failed for any other reason. Each was warned about; none threw. */
     readonly failed: readonly FontFaceFailure[];
+    /**
+     * The family names the default font map GAINED across this call, sorted.
+     *
+     * THE FIELD #1542 IS ABOUT, and the reason it is a diff rather than a list: a caller can act
+     * only on a family NAME, the name is not derivable from the file, and no caller can take this
+     * measurement afterwards — `list_families()` alone cannot say which of 84 names arrived from
+     * the staged directory. Only the call that registered them is in a position to know.
+     *
+     * NOT a file → family map, and that is a limit rather than a shortcut: Pango exposes no link
+     * from a registered file back to the family it produced, and attributing families by
+     * registering one file at a time would credit a family to whichever of its faces happened to
+     * be registered first — five staged faces of two families would report three files as having
+     * contributed nothing, which reads exactly like three failures.
+     *
+     * EMPTY IS NOT FAILURE, on two live paths: a map that declines runtime registration (macOS,
+     * where a shipped `.app` has already activated the directory through
+     * `ATSApplicationFontsPath` before any code runs) gains nothing here and is CORRECT, and a
+     * face whose family the map already holds adds no new name. {@link matches} is what tells
+     * those apart from nothing having worked, because it asks what the map holds NOW.
+     */
+    readonly families: readonly string[];
+    /**
+     * What each of {@link InitFontsOptions.expectedFamilies} resolves to on the map, in the order
+     * declared. Empty when the caller declared none.
+     *
+     * This is the answer to the darwin row of #1542, where `declined: 5` is consistent BOTH with
+     * everything working and with nothing working: the only thing that separates the two is what
+     * the map holds afterwards, which is what a match reads.
+     */
+    readonly matches: readonly FontFamilyMatch[];
 }
 /**
  * Did the font map decline runtime registration outright?

package/lib/types/generated/enum-values.d.mts

@@ -0,0 +1,38 @@
+/**
+ * The libraries these numbers were read from, in the vocabulary's own provenance
+ * grammar so one parser reads both lines.
+ *
+ * A value, not only a header comment: `generated.spec.ts` compares it with the
+ * running library to decide whether a disagreement is a defect or a version gap.
+ */
+export declare const VALUES_PROVENANCE = "Adw-1/1.9.3 Gtk-4.0/4.22.4 Pango-1.0/1.57.1";
+/** `<enum GType>.<nick>` -> the integer the library registers for it. */
+export declare const ENUM_VALUES: Readonly<Record<string, number>>;
+/**
+ * `<enum GType>.<alias nick>` -> the nick of the same enum it shares a value with.
+ *
+ * Two names, one member. Both names keep an entry in `ENUM_VALUES` carrying the same
+ * number — nothing is lost — and this table says which of them a number should be
+ * spelled back as. `GTK_ALIGN_BASELINE` is here because GTK 4.12 deprecated it in
+ * favour of `GTK_ALIGN_BASELINE_FILL` and gave the new name the same value instead of
+ * adding a member; the typelib's own deprecation flag is what picks the direction.
+ */
+export declare const ENUM_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Every enum nick the installed typelib marks deprecated.
+ *
+ * The input to `ENUM_ALIASES`' direction, kept as its own fact so the choice is
+ * checkable rather than a convention about ordering.
+ */
+export declare const ENUM_DEPRECATED: readonly string[];
+/**
+ * `<enum GType>.<nick>` -> the installed library that has no such member.
+ *
+ * The declared remainder, and the only reason one exists: the vocabulary can describe
+ * a library NEWER than the one installed (ADR 0029 § Amendment), so a nick can be real
+ * and have no number here yet. Every nick in `ENUM_NICKS` is in `ENUM_VALUES` or in
+ * this table — a nick in neither is a silent drop and the gate fails on it. The value
+ * is the library and version that was asked, so the entry says WHICH host produced the
+ * gap rather than only that there is one; regenerating on a newer one empties it.
+ */
+export declare const ENUM_VALUES_UNAVAILABLE: Readonly<Record<string, string>>;

package/lib/types/generated/methods.d.mts

@@ -0,0 +1,46 @@
+/**
+ * The libraries these names were read from, in the vocabulary's own provenance grammar
+ * so one parser reads both lines.
+ *
+ * A value, not only a header comment: `generated.spec.ts` compares it with the running
+ * library to decide whether a missing method is a defect or a version gap.
+ */
+export declare const METHODS_PROVENANCE = "Adw-1/1.9.3 Gtk-4.0/4.22.4";
+/**
+ * GType -> the instance methods that type declares ITSELF, in typelib order.
+ *
+ * Every widget of the runtime table has a row, and so does every ancestor and interface
+ * `ANCESTRY` names, so a union over a chain never stops short. Inherited methods are not
+ * repeated: `AdwActionRow` lists `add_prefix` and not `add_css_class`.
+ */
+export declare const OWN_METHODS: Readonly<Record<string, readonly string[]>>;
+/**
+ * Widget GType -> every ancestor and interface a GJS instance of it carries methods
+ * from, transitively, nearest first — the parent chain to `GObject`, then the
+ * interfaces of each link and their prerequisites.
+ *
+ * Only the runtime table's widgets have a row; a base or an interface has methods in
+ * `OWN_METHODS` and no chain of its own here.
+ */
+export declare const ANCESTRY: Readonly<Record<string, readonly string[]>>;
+/**
+ * What GJS installs on `GObject.Object.prototype` beyond the typelib — measured by
+ * subtraction on the generating host, never authored.
+ *
+ * These are the verbs every GJS snippet writes and no `.gir` declares: `connect`,
+ * `disconnect`, `emit`. A ledger holding a port against the typelib alone would call
+ * them divergences, so they are the fourth table. `set` is here because it IS installed
+ * (the multi-property setter, `widget.set({ label })`), and is the one name in this list
+ * that collides with a different contract on NativeScript's `Observable`.
+ */
+export declare const GJS_OBJECT_METHODS: readonly string[];
+/**
+ * Widget GType -> the installed library that has no such type.
+ *
+ * The declared remainder, and the only reason one exists: the vocabulary can describe a
+ * library NEWER than the one this file was generated on, so a widget can be real and
+ * have no chain here yet. Every widget of the runtime table is in `ANCESTRY` or in this
+ * table — one in neither is a silent drop, and the gate fails on it. Regenerating on a
+ * newer host empties it.
+ */
+export declare const METHODS_UNAVAILABLE: Readonly<Record<string, string>>;

package/lib/types/jsx-runtime.d.ts

@@ -28,12 +28,12 @@
  * keys (TS2411). The camelCase spelling of every property IS checked, which is why
  * both spellings are generated and camelCase is the one to prefer.
  */
-import type { JsxAttributes, WithOnce, WithPortableMenu } from './attrs.js';
+import type { JsxAttributes, WithOnce, WithPortableValues } from './attrs.js';
 import type { HostNode } from './types.js';
 import type { WidgetClassByTag, WidgetPropsByTag } from './generated/props.js';
 /** Every GTK/Adwaita tag, with its properties, its handlers and its `ref`. */
 export type GtkIntrinsicElements = {
-    [K in keyof WidgetPropsByTag]: WithOnce<WithPortableMenu<WidgetPropsByTag[K]>> & JsxAttributes<WidgetClassByTag[K]>;
+    [K in keyof WidgetPropsByTag]: WithOnce<WithPortableValues<WidgetPropsByTag[K]>> & JsxAttributes<WidgetClassByTag[K]>;
 };
 export declare namespace JSX {
     /**

package/lib/types/list-model.d.ts

@@ -0,0 +1,38 @@
+import Gtk from 'gi://Gtk?version=4.0';
+import type { AdwListModel, AdwListModelInput } from '@gjsify/adwaita-core';
+/**
+ * A portable list model as a live `Gtk.StringList`.
+ *
+ * Accepts the AUTHORED form as well as the normalised one: `normalizeComboOptions` is
+ * total and idempotent, so a JSX attribute needs no conversion step of its own, and a
+ * renderer handing its own normalised model back in takes the same door.
+ */
+export declare function buildStringList(input: AdwListModelInput): Gtk.StringList;
+/**
+ * Whether a value is a portable list model rather than a `Gio.ListModel`.
+ *
+ * An ARRAY, and nothing else — the same test `isPortableMenu` makes. A `Gio.ListModel`
+ * is a GObject and never an array, so the imperative path (a real `Gtk.StringList`, a
+ * `Gio.ListStore`) is never mistaken for the portable one.
+ */
+export declare const isPortableListModel: (value: unknown) => value is AdwListModelInput;
+/** The strings a `Gtk.StringList` holds, in order — read off GTK, never off an input. */
+export declare function stringsOf(model: Gtk.StringList): string[];
+/**
+ * Splice a freshly built list's difference into the list `widget[accessor]` holds, if
+ * both are this module's — see the header for the measurement that makes this a rule.
+ *
+ * Answers whether the write is DONE: `true` means the held list now reads as `fresh`
+ * (an equal list is left untouched, so nothing is emitted); `false` means one of the two
+ * is not the seam's, and the caller writes the property as it would any other.
+ */
+export declare function reconcileStringList(widget: object, accessor: string, fresh: unknown): boolean;
+/**
+ * A `Gtk.StringList` back as a portable model — the inverse of {@link buildStringList}
+ * for the half that crosses.
+ *
+ * It exists to make the claim above measurable: `list-model.spec.ts` drives every
+ * `LIST_NORMALIZE_VECTORS` row through the builder and back through this, so a label
+ * that stopped arriving fails a test naming it instead of vanishing from a popup.
+ */
+export declare function fromStringList(model: Gtk.StringList): AdwListModel;

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

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

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

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

package/lib/types/policies.d.ts

@@ -1,3 +1,4 @@
+import GObject from 'gi://GObject?version=2.0';
 import Gtk from 'gi://Gtk?version=4.0';
 import type { ChildPolicy, HostElement, NodePlacement, WidgetDescriptor } from './types.js';
 /** The object the PARENT addresses: a wrapper row when the policy demands one. */
@@ -86,6 +87,10 @@ export declare function setterSlots(policy: ChildPolicy): string[];
  * 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. */
+export type OutsideParent = Exclude<NodePlacement, {
+    kind: 'parented';
+}>;
 /**
  * The declared placement of a node. The ONE place absence is turned into a value.
  *
@@ -94,7 +99,15 @@ export declare function slotOccupant(widget: Gtk.Widget, setter: string): Gtk.Wi
  * falsiness test that a third kind would quietly join.
  */
 export declare const placementOf: (descriptor: WidgetDescriptor) => NodePlacement;
-/** The portal arm, or null. The narrow question four call sites ask. */
+/**
+ * The placement, when it is NOT `parented` — the narrow question every caller asks.
+ *
+ * Returning the arm rather than a boolean is what keeps the two non-parented kinds
+ * ONE question: a caller switches over what it gets and its `never` arm fails to
+ * compile the day a fourth kind arrives.
+ */
+export declare function outsideParentOf(descriptor: WidgetDescriptor): OutsideParent | null;
+/** The portal arm specifically, or null. */
 export declare function portalOf(descriptor: WidgetDescriptor): Extract<NodePlacement, {
     kind: 'portal';
 }> | null;
@@ -102,6 +115,18 @@ export declare function portalOf(descriptor: WidgetDescriptor): Extract<NodePlac
 export declare function unhandledPlacement(placement: never): never;
 /** Is this node placed against its parent rather than into it? */
 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.
+ */
+export declare const isUnparented: (el: HostElement) => boolean;
 /**
  * Show a portal node against its parent — or subscribe and wait, if it is too early.
  *
@@ -150,6 +175,157 @@ export declare function presentPortal(parent: HostElement, child: HostElement, p
 export declare function retractPortal(child: HostElement, portal: Extract<NodePlacement, {
     kind: 'portal';
 }>): void;
+/**
+ * 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.
+ */
+export declare function presentToplevel(child: HostElement, placement: Extract<NodePlacement, {
+    kind: 'toplevel';
+}>): boolean;
+/**
+ * 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.
+ */
+export declare function closeToplevel(child: HostElement, placement: Extract<NodePlacement, {
+    kind: 'toplevel';
+}>): void;
+/**
+ * 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
+ * `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.
+ */
+export declare function detachToplevel(child: HostElement): void;
+/**
+ * Place a node that does NOT go into its parent's child list, and say whether GTK took it.
+ *
+ * The ONE dispatch over the non-parented arms. Every caller in `host.ts` reaches
+ * the axis through this and its two twins below, so a fourth placement kind is
+ * three `never` arms away from compiling rather than a search through the host.
+ */
+export declare function placeOutsideParent(parent: HostElement, child: HostElement, placement: OutsideParent): boolean;
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ *
+ * @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
+ */
+export declare function classPlacementKind(gtype: GObject.GType, present: unknown): OutsideParent['kind'] | null;
+/** `classPlacementKind` for a live widget, which is what the insert path holds. */
+export declare function nodePlacementKind(node: Gtk.Widget): OutsideParent['kind'] | null;
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function refuseUnparentable(parent: HostElement, child: HostElement): void;
 export interface Placement {
     parent: HostElement;
     child: HostElement;

package/lib/types/react-jsx-runtime.d.ts

@@ -33,7 +33,7 @@
  */
 import type { Key, ReactElement, ReactNode, Ref } from 'react';
 import type { WidgetClassByTag, WidgetPropsByTag } from './generated/props.js';
-import type { RawSignalAttributes, SlotAttribute, WithOnce, WithPortableMenu } from './attrs.js';
+import type { RawSignalAttributes, SlotAttribute, WithOnce, WithPortableValues } from './attrs.js';
 export { Fragment } from 'react/jsx-runtime';
 /**
  * React's own factories, RE-TYPED over this package's element list.
@@ -74,7 +74,7 @@ export interface ReactWidgetAttributes<T> extends SlotAttribute, RawSignalAttrib
 }
 /** Every GTK/Adwaita tag, with its properties, its handlers, its `ref` and its `key`. */
 export type GtkReactIntrinsicElements = {
-    [K in keyof WidgetPropsByTag]: WithOnce<WithPortableMenu<WidgetPropsByTag[K]>> & ReactWidgetAttributes<WidgetClassByTag[K]>;
+    [K in keyof WidgetPropsByTag]: WithOnce<WithPortableValues<WidgetPropsByTag[K]>> & ReactWidgetAttributes<WidgetClassByTag[K]>;
 };
 export declare namespace JSX {
     /**

package/lib/types/shared-trees.spec.d.ts

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

package/lib/types/testing/refusal.d.mts

@@ -0,0 +1,2 @@
+/** The refusal code `fn` raises, or what it did instead — so a wrong refusal reads as one. */
+export declare function codeOf(fn: () => unknown): string;