@gjsify/gtk-host 0.47.0 → 0.49.0

package/lib/types/adjustment.d.ts

@@ -0,0 +1,28 @@
+import Gtk from 'gi://Gtk?version=4.0';
+import type { AdwAdjustment, AdwAdjustmentInput } from '@gjsify/adwaita-core';
+/**
+ * A portable adjustment as a live `Gtk.Adjustment`.
+ *
+ * `value` is written LAST, and the core has clamped it before it gets here, so neither
+ * half of the two-clamp hazard applies: GTK's own `set_value` clamps against whatever
+ * range is installed at the moment the property is written, and the order
+ * `g_object_new` writes two properties in is not a contract. A value that is already
+ * inside the range survives either order.
+ */
+export declare function buildAdjustment(input: AdwAdjustmentInput): Gtk.Adjustment;
+/**
+ * Whether a value is a portable adjustment rather than a `Gtk.Adjustment`.
+ *
+ * A plain OBJECT: not null, not an array, not a GObject. A bare number is NOT one — the
+ * decision is ADR 0047 § 1's, and `coerce` refuses it by name rather than reading it as
+ * the value, because `value` is a property of its own on every widget that takes an
+ * adjustment and two spellings of one write is what the whole convergence removes.
+ */
+export declare const isPortableAdjustment: (value: unknown) => value is AdwAdjustmentInput;
+/**
+ * A `Gtk.Adjustment` back as the portable value — the inverse of {@link buildAdjustment}.
+ *
+ * Six numbers read off the real object, so `adjustment.spec.ts` can compare what GTK
+ * holds against what the core said it would, row for row.
+ */
+export declare function fromAdjustment(adjustment: Gtk.Adjustment): AdwAdjustment;

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

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

package/lib/types/attrs.d.ts

@@ -1,4 +1,7 @@
+import type Gio from '@girs/gio-2.0';
 import type GObject from '@girs/gobject-2.0';
+import type Gtk from '@girs/gtk-4.0';
+import type { AdwAdjustmentInput, AdwListModelInput, AdwMenuInput } from '@gjsify/adwaita-core';
 import type { HostNode } from './types.js';
 /**
  * A `notify::` handler.
@@ -99,4 +102,80 @@ export interface JsxAttributes<T> extends SlotAttribute, RawSignalAttributes {
  */
 export interface VueAttributes extends SlotAttribute, RawSignalAttributes {
 }
+/**
+ * The properties whose GObject type is a `GMenuModel`, in both spellings.
+ *
+ * A NAME LIST, not a type test, and the reason is measured rather than stylistic: the
+ * obvious `Gio.MenuModel extends NonNullable<T[K]> ? …` also matches every property
+ * typed as a wider GObject — `Gio.MenuModel extends GObject.Object` is TRUE — so the
+ * widening would leak onto properties that take an entirely different object. The three
+ * names below are the whole set on the shipped table (`menu-model` on the two menu
+ * buttons, the popover menu and the menu bar; `extra-menu` on the text widgets;
+ * `secondary-menu` on `AdwToolbarView`'s header bar), and `type-tests/` holds the
+ * widening against real markup in both dialects.
+ */
+type MenuModelProp = 'menuModel' | 'menu-model' | 'extraMenu' | 'extra-menu' | 'secondaryMenu' | 'secondary-menu';
+/**
+ * A props interface with every `GMenuModel` property widened to accept the PORTABLE
+ * menu model as well (ADR 0042).
+ *
+ * `Gio.MenuModel` is a GObject with no literal spelling, so before this a declarative
+ * dialect could not express a menu at all — the website gallery refused a Solid, Vue and
+ * React snippet for `Adw.SplitButton`, `Gtk.MenuButton` and `Gtk.PopoverMenu` for
+ * exactly that reason. The runtime half is `coerce`'s `GMenuModel` branch, which turns
+ * an authored array into a real `Gio.Menu` at the ParamSpec seam; this is the type that
+ * lets the array be written.
+ *
+ * A widget with NO such property is returned unchanged: `Omit` over a key it has not got
+ * is a no-op, and `MenuModelProp & keyof T` is then empty, so nothing is added either.
+ */
+export type WithPortableMenu<T> = Omit<T, MenuModelProp> & {
+    [K in MenuModelProp & keyof T]?: T[K] | AdwMenuInput;
+};
+/** `A` and `B` are the SAME type — assignable both ways, tuple-wrapped so a union does not distribute. */
+type Same<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+/**
+ * The property name a list model travels under, and it is deliberately NOT enough on
+ * its own: `model` is also `Gtk.ListView`'s `Gtk.SelectionModel`, `Gtk.TreeView`'s
+ * `Gtk.TreeModel` and `Gtk.ColumnView`'s selection. The name picks the candidates; the
+ * declared TYPE decides, exactly as the runtime branch keys on the ParamSpec.
+ */
+type ListModelProp = 'model';
+/**
+ * A props interface with every `Gio.ListModel`-typed `model` widened to accept the
+ * PORTABLE list model as well (ADR 0046 § Amendment).
+ *
+ * Widened only where the declared type IS `Gio.ListModel` — both directions, so a
+ * `Gtk.SelectionModel` (which extends it) stays as generated. `type-tests/` holds
+ * `<gtk-list-view model={[…]}>` as a compile error, and `coerce` refuses the same
+ * write by name at runtime (`list-model-mismatch`): one keying, two layers.
+ */
+export type WithPortableList<T> = Omit<T, ListModelProp> & {
+    [K in ListModelProp & keyof T]?: Same<NonNullable<T[K]>, Gio.ListModel> extends true ? T[K] | AdwListModelInput : T[K];
+};
+/**
+ * The spellings an adjustment property has on the shipped table — `adjustment` on the
+ * widgets that hold one, `hadjustment`/`vadjustment` on `GtkScrollable` and
+ * `GtkScrolledWindow`. The name picks the candidates; the declared TYPE decides.
+ */
+type AdjustmentProp = 'adjustment' | 'hadjustment' | 'vadjustment';
+/**
+ * A props interface with every `Gtk.Adjustment`-typed property widened to accept the
+ * PORTABLE adjustment as well (ADR 0047 § Amendment).
+ *
+ * `AdwAdjustmentInput` is any SUBSET of the six numbers, so `{}` is legal (the shared
+ * defaults) and a bare number is not — ADR 0047 § 1's decision, held at compile time
+ * here and by name at runtime (`bad-adjustment`).
+ */
+export type WithPortableAdjustment<T> = Omit<T, AdjustmentProp> & {
+    [K in AdjustmentProp & keyof T]?: Same<NonNullable<T[K]>, Gtk.Adjustment> extends true ? T[K] | AdwAdjustmentInput : T[K];
+};
+/**
+ * All three portable values on one props interface — what every dialect surface applies.
+ *
+ * One name so the three surfaces cannot each apply a different subset of the
+ * widenings: the menu was on all three, and the list and the adjustment join it here
+ * rather than in three files.
+ */
+export type WithPortableValues<T> = WithPortableMenu<WithPortableList<WithPortableAdjustment<T>>>;
 export {};

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

@@ -1,8 +1,28 @@
 export { describeLogRecord, installDiagnosticsGate, isEnvironmentDiagnostic, type DiagnosticsGate, } from './diagnostics.js';
+export { windowChromeCensus, windowChromeProblems, type WindowChromeCensus } from './window-chrome.js';
 import type Gtk from '@girs/gtk-4.0';
-import type { ChildPolicy, HostElement, WidgetDescriptor } from '../types.js';
+import type { ChildPolicy, HostElement, NodePlacement, WidgetDescriptor } from '../types.js';
 /** Every method name a policy names, so the check does not have to know the shapes. */
 export declare function methodsOf(policy: ChildPolicy): string[];
+/**
+ * Every method a PLACEMENT names — the second axis's answer to `methodsOf`.
+ *
+ * Separate from `methodsOf` rather than folded into it, because the two are
+ * checked against different things: a child policy's methods are called on the
+ * PARENT and a placement's on the NODE ITSELF, so a single list would make the
+ * message name the wrong object.
+ */
+export declare function placementMethodsOf(placement: NodePlacement): string[];
+/**
+ * How many arguments this placement's `present` must take, or null when it names none.
+ *
+ * THE ARITY IS THE DISCRIMINATOR between the two non-parented arms, measured on
+ * GTK 4.22.4 / libadwaita 1.9.3: `adw_dialog_present` takes 1 and
+ * `gtk_window_present` takes 0. A zero-argument `present` called with a widget
+ * ignores it silently and opens a window of its own; a one-argument one called
+ * with nothing has no host to reach. Both are exit 0, so the check is here.
+ */
+export declare function presentArityOf(placement: NodePlacement): number | null;
 export interface DescriptorProblem {
     gtype: string;
     problem: string;
@@ -16,34 +36,13 @@ export interface DescriptorProblem {
  * the check runs up front and names the widget.
  */
 export declare function descriptorProblems(descriptors?: readonly WidgetDescriptor[]): DescriptorProblem[];
-/** Direct GTK children of a widget, in GTK's own order. */
-export declare function gtkChildren(widget: Gtk.Widget): Gtk.Widget[];
-/** GType names of a widget's direct children — the cheap shape assertion. */
-export declare const gtkChildTypes: (widget: Gtk.Widget) => string[];
-/** The addresses a host element's element-children occupy, in shadow order. */
-export declare function addressesOf(el: HostElement): Gtk.Widget[];
-/**
- * First STRICT descendant matching `pred`, breadth-first over the REAL GTK tree.
- *
- * Both showcase probes wrote this, identically. It excludes the root on purpose:
- * every caller is asking "what did the renderer put INSIDE this", and a root that
- * matches its own predicate answers a different question.
- *
- * Breadth-first is not incidental either — `findDescendant(root, w => w instanceof
- * Gtk.Box)` on an Adwaita window finds an INTERNAL box of the header bar before
- * anything the author wrote, which is why a probe that needs a specific widget
- * reaches it through a landmark (a button's `get_parent()`) rather than by type.
- * Measured: with a search-by-type version, authoring `orientation="horizontal"`
- * still printed PROBE: PASS with byte-identical output.
- */
-export declare function findDescendant(root: Gtk.Widget, pred: (widget: Gtk.Widget) => boolean): Gtk.Widget | null;
+export { descendants, dumpTree, findDescendant, gtkChildTypes, gtkChildren } from './tree.js';
 /**
- * Every widget in a subtree, ROOT FIRST and depth-first — GTK's own document order.
+ * The addresses a host element's element-children occupy, in shadow order.
  *
- * Depth-first and not breadth-first, because the callers that collect (rather than
- * search) are asserting on ORDER: "the rows land before the counter row" is only a
- * claim about the tree if the walk visits it the way the tree reads.
+ * A NON-PARENTED child occupies none — a portal is presented against this element
+ * and lives under the toplevel's dialog host, a toplevel is its own root — so
+ * including either would make every vector that compares this against the real
+ * child list disagree by a node that is not there.
  */
-export declare function descendants(root: Gtk.Widget): Gtk.Widget[];
-/** Recursive GType dump — what a devtools tree walk would show. */
-export declare function dumpTree(widget: Gtk.Widget, depth?: number): string;
+export declare function addressesOf(el: HostElement): Gtk.Widget[];

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

@@ -0,0 +1,30 @@
+import type Gtk from '@girs/gtk-4.0';
+/** Direct GTK children of a widget, in GTK's own order. */
+export declare function gtkChildren(widget: Gtk.Widget): Gtk.Widget[];
+/** GType names of a widget's direct children — the cheap shape assertion. */
+export declare const gtkChildTypes: (widget: Gtk.Widget) => string[];
+/**
+ * First STRICT descendant matching `pred`, breadth-first over the REAL GTK tree.
+ *
+ * Both showcase probes wrote this, identically. It excludes the root on purpose:
+ * every caller is asking "what did the renderer put INSIDE this", and a root that
+ * matches its own predicate answers a different question.
+ *
+ * Breadth-first is not incidental either — `findDescendant(root, w => w instanceof
+ * Gtk.Box)` on an Adwaita window finds an INTERNAL box of the header bar before
+ * anything the author wrote, which is why a probe that needs a specific widget
+ * reaches it through a landmark (a button's `get_parent()`) rather than by type.
+ * Measured: with a search-by-type version, authoring `orientation="horizontal"`
+ * still printed PROBE: PASS with byte-identical output.
+ */
+export declare function findDescendant(root: Gtk.Widget, pred: (widget: Gtk.Widget) => boolean): Gtk.Widget | null;
+/**
+ * Every widget in a subtree, ROOT FIRST and depth-first — GTK's own document order.
+ *
+ * Depth-first and not breadth-first, because the callers that collect (rather than
+ * search) are asserting on ORDER: "the rows land before the counter row" is only a
+ * claim about the tree if the walk visits it the way the tree reads.
+ */
+export declare function descendants(root: Gtk.Widget): Gtk.Widget[];
+/** Recursive GType dump — what a devtools tree walk would show. */
+export declare function dumpTree(widget: Gtk.Widget, depth?: number): string;

package/lib/types/conformance/vectors.d.mts

@@ -30,5 +30,11 @@ export interface VectorHarness {
  * `gated` rather than a bare `describe`: `@gjsify/unit` keeps ONE
  * `beforeEach`/`afterEach` slot per module and nulls both when a describe returns,
  * so hooks registered outside the block cover exactly one sibling.
+ *
+ * CORRECTED 2026-09-04 (#1554): hooks are SCOPED now — one frame per `describe`,
+ * popped when it returns — so hooks registered outside the block cover every
+ * sibling, and two registrations in one scope both run. `gated` stays because it
+ * keeps one declaration of what a gated block means, not because the runner
+ * forgets.
  */
 export declare function runAdapterVectors(harness: VectorHarness, gate: DiagnosticsGate): Promise<void>;

package/lib/types/conformance/window-chrome.d.ts

@@ -0,0 +1,29 @@
+import Gtk from 'gi://Gtk?version=4.0';
+/** What a window's chrome actually draws, per side of the decoration layout. */
+export interface WindowChromeCensus {
+    /** Mapped, non-empty `GtkWindowControls` packed at the start of their header bar. */
+    readonly start: number;
+    /** The same at the end. On a GNOME host with a `:close` layout this is the close button. */
+    readonly end: number;
+    /** Mapped header bars, for the report. NOT the invariant — see the header. */
+    readonly headerBars: number;
+    /** Whether the root is mapped at all, i.e. whether the three counts mean anything. */
+    readonly mapped: boolean;
+}
+/**
+ * Count what the window's chrome draws.
+ *
+ * `get_empty()` is asked as well as `get_mapped()` because a `GtkWindowControls` is
+ * mapped on both sides of every header bar and draws buttons only on the side the
+ * decoration layout puts them: measured, a GNOME `:close` layout leaves six of the
+ * eight controls in a three-bar window empty and invisible.
+ */
+export declare function windowChromeCensus(root: Gtk.Widget): WindowChromeCensus;
+/**
+ * Every way this window's chrome is wrong, in sentences.
+ *
+ * An empty array is the only clean answer, and it is not reachable by accident: an
+ * unmapped root and a window whose chrome draws nothing at all are both named, so
+ * "no duplicates" cannot be produced by a tree that draws no chrome to duplicate.
+ */
+export declare function windowChromeProblems(root: Gtk.Widget): string[];

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

@@ -19,6 +19,22 @@ export declare const err: {
     missingConstructProp: (tag: string, prop: string) => GtkHostError;
     unknownProp: (tag: string, prop: string) => GtkHostError;
     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;
@@ -58,6 +74,33 @@ export declare const err: {
     siblingCycle: (parentTag: string) => GtkHostError;
     notAWidget: (tag: string) => GtkHostError;
     occupiedSlot: (parentTag: string, childTag: string, setter: string) => GtkHostError;
+    /**
+     * 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.
+     */
+    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/index.d.ts

@@ -1,7 +1,7 @@
 export * from './types.js';
 export { GtkHostError } from './errors.js';
 export { adopt, createAnchor, createDetachedContainer, createElement, createText, destroyChildren, destroy, disconnectHandlers, firstChild, insert, isHostElement, isText, materialize, mountRoot, nextSibling, parentNode, prevSibling, remove, setElementText, setEventHandler, setProp, setSlot, setText, widgetOf, } from './host.js';
-export { addressOf, reorderMode } from './policies.js';
+export { addressOf, isPortal, placementOf, portalOf, 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';

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 } 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<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;