@gjsify/adwaita-core 0.64.12-next.281 → 0.64.13-next.283

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

@@ -1,4 +1,5 @@
-import type { AdwComboOption, AdwListItemsChanged, AdwListModel, AdwListModelInput } from '../list.js';
+import type { AdwComboOption, AdwListItemsChanged, AdwListModel, AdwListModelInput, AdwListModelSource } from '../list.js';
+import { GjsifyOptionList } from '../option-list.js';
 import type { TabViewPagesChange } from '../tab-view.js';
 /** One {@link normalizeComboOptions} expectation. */
 export interface ListNormalizeVector {
@@ -24,6 +25,19 @@ export interface ListNormalizeVector {
  * a citation, and that sentence named no table).
  */
 export declare const LIST_NORMALIZE_VECTORS: ReadonlyArray<ListNormalizeVector>;
+/**
+ * A {@link LIST_NORMALIZE_VECTORS} row as the value a `model` PROPERTY write takes.
+ *
+ * ADR 0122 § 4 took the array arm off that property, so the ARRAY rows go in as a list built
+ * out of the array: the normaliser still runs on them, one step further in, as
+ * {@link GjsifyOptionList}'s own constructor. The model-source rows go STRAIGHT through —
+ * that is the shape the door now takes, and they are what proves a surface reads items by
+ * position rather than recognising one class.
+ *
+ * Lives here rather than in each driving suite because WHICH door a row reaches through is
+ * part of what the table claims, and two copies of that answer are two claims.
+ */
+export declare function listModelForInput(input: AdwListModelInput): AdwListModelSource;
 /** One {@link parseListModel} expectation — the JSON attribute door. */
 export interface ListParseVector {
     /** The attribute value exactly as authored. */
@@ -65,20 +79,21 @@ export interface ListItemsChangedVector {
  * change, which is `g_list_store_splice`'s shape.
  */
 export declare const LIST_ITEMS_CHANGED_VECTORS: ReadonlyArray<ListItemsChangedVector>;
-/** What a caller does to the array it read back out of a `model` accessor. */
+/** What a caller does to the options they hold, or to the model they were handed. */
 export type ListReadbackOp = 'append' | 'relabel-first' | 'remove-first';
-/** One read-mutate-assign expectation — see {@link LIST_MODEL_OWNERSHIP_VECTORS}. */
+/** One ownership expectation — see {@link LIST_MODEL_OWNERSHIP_VECTORS}. */
 export interface ListModelOwnershipVector {
     initial: AdwListModel;
     /**
-     * Which array the caller mutates: the one `model` handed BACK, or the one they
-     * assigned and kept. Two doors into the same failure, and closing one leaves the other.
+     * WHAT the caller mutates. `input` is the array they authored and handed to
+     * `GjsifyOptionList.new`; `options` is the array read back out of `toOptions()`; `model`
+     * is the list itself, through its own `Gio.ListModel` API. The first two must move
+     * nothing and the third must move everything, and which of the three a surface gets
+     * wrong is the difference between a leak and a dropped redraw.
      */
-    source: 'readback' | 'input';
+    source: 'options' | 'input' | 'model';
     op: ListReadbackOp;
-    /** Whether the mutated array is assigned back to `model` afterwards. */
-    assign: boolean;
-    /** The model the surface holds when the row is done. */
+    /** The options the surface holds when the row is done. */
     model: AdwListModel;
     /** The splice the surface emits, or `null` where it emits none. */
     itemsChanged: AdwListItemsChanged | null;
@@ -87,50 +102,42 @@ export interface ListModelOwnershipVector {
     rule: string;
 }
 /**
- * WHO OWNS THE ARRAY a `model` accessor hands back — read, mutate, assign.
+ * WHO OWNS THE OPTIONS — the arrays a caller holds on either side of the model, and the
+ * model itself.
  *
  * The browser suite drives `LIST_MODEL_OWNERSHIP_VECTORS` through `<adw-combo-row>` and
- * `<gtk-drop-down>`, and core drives it through `ComboState` itself, which is the surface
- * where BOTH doors are reachable: the element setters run `normalizeComboOptions` and so
- * close the input door on their own, while `ComboState.setModel` takes a normalised model
- * straight from a caller.
+ * `<gtk-drop-down>`, and core drives it through `ComboState`.
  *
- * THE ROWS EXIST BECAUSE THE SPLICE MADE THIS A SILENT FAILURE. Under the full rebuild
- * every assignment redrew the list, so an aliased array was invisible; the splice decides
- * what to redraw by COMPARING the assignment against the stored model, and an alias makes
- * both sides read the new value — "nothing changed", nothing drawn, no error. `append`
- * with `assign` is the pattern that regressed, `relabel-first` is the same failure one
- * level down through a shared descriptor (which is why the copy is per ITEM and not just
- * per array), and the `assign: false` row is the invariant the other two rest on: what a
- * caller holds is THEIRS, so touching it moves nothing until they hand it back.
+ * READ, MUTATE, ASSIGN IS GONE AS A PATTERN, and that is what reshaped these rows. ADR 0122
+ * § 4 narrows `model` to a real `Gio.ListModel`, so there is no array to assign back: the
+ * only way to change a model in place is its own API, and handing over a DIFFERENT list is a
+ * replacement that resets the selection. What survives from the array era is the half that
+ * was never about assignment — an array a caller holds is THEIRS on both sides, going in
+ * (`GjsifyOptionList` copies each descriptor into an item) and coming out (`toOptions`
+ * copies each item back). `relabel-first` is why the copy is per ITEM rather than per array:
+ * a shared descriptor would let the text under a selection move with nothing emitted, which
+ * is the failure `GjsifyOptionObject`'s read-only `label` exists to prevent.
+ *
+ * The `model` rows are the other side of the same invariant: the ONE door that does move the
+ * list emits the one minimal splice for it, in each of the three directions a splice can go.
  */
 export declare const LIST_MODEL_OWNERSHIP_VECTORS: ReadonlyArray<ListModelOwnershipVector>;
 /**
- * The caller-side half of one {@link LIST_MODEL_OWNERSHIP_VECTORS} row: mutate the array a
- * `model` accessor handed back, IN PLACE, and hand the same array back.
+ * The caller-side half of an `options`/`input` row: mutate the array, IN PLACE, and hand the
+ * same array back.
  *
  * In place and returning its argument is the whole point — a helper that built a new array
  * would test the pattern that never broke.
  */
 export declare function applyListReadback(model: AdwComboOption[], op: ListReadbackOp): AdwComboOption[];
-/** One {@link clampListSelection} expectation. */
-export interface ListSelectionClampVector {
-    selected: number;
-    length: number;
-    result: number;
-    rule: string;
-}
 /**
- * Where a selection lands after the model under it was replaced.
+ * The model-side half: the same three ops through the list's own `Gio.ListModel` API.
  *
- * The browser suite drives `LIST_SELECTION_CLAMP_VECTORS` through `<adw-combo-row>` and
- * through that element only. `<gtk-drop-down>` REFUSES an out-of-range `selected` set
- * outright — its published contract, with `ComboState.hasIndex` as the shared bounds — so
- * the starting index these rows replace cannot be put on that element in the first place.
- * One row is narrower than the vector even on the row, and `adw-row-state.spec.ts` says
- * so in place.
+ * `relabel-first` is a splice rather than an assignment because {@link GjsifyOptionObject}
+ * is read-only — changing what an item says means putting a different item there, which is
+ * also how `Gio.ListStore` would have to spell it.
  */
-export declare const LIST_SELECTION_CLAMP_VECTORS: ReadonlyArray<ListSelectionClampVector>;
+export declare function applyListMutation(model: GjsifyOptionList, op: ListReadbackOp): void;
 /** One {@link tabViewItemsChanged} expectation, with the order it replays. */
 export interface TabPagesItemsChangedVector {
     change: TabViewPagesChange;

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

@@ -1,12 +1,21 @@
-import type { AdwComboOption, ComboStateChange } from '../rows.js';
+import type { AdwComboOption, ComboNotify, ComboStateChange } from '../rows.js';
 /**
  * One mutation in a combo scenario. DATA, not a closure: a renderer suite
  * replays these against a real widget (set the options, pick from the chooser)
  * and compares what the user would see.
+ *
+ * `setModel` carries the model's CONTENTS and not a model object, so the table stays
+ * portable: each renderer builds whatever model it holds — a `GjsifyOptionList` in the
+ * core and in both browser elements, the same on the NativeScript host — out of these
+ * descriptors. `setModelAgain` is the one step that is about the model's IDENTITY rather
+ * than its contents, and it is a step rather than a flag because that is the only way to
+ * spell "assign the object you are already holding" in data.
  */
 export type ComboSelectionStep = {
     op: 'setModel';
     model: ReadonlyArray<AdwComboOption>;
+} | {
+    op: 'setModelAgain';
 } | {
     op: 'setSelectedIndex';
     index: number;
@@ -23,7 +32,7 @@ export interface ComboSelectionVector {
     steps: readonly ComboSelectionStep[];
     /** `selectedIndex` afterwards. */
     selected: number;
-    /** `selectedValue` afterwards — `''` when the index sits outside the options. */
+    /** `selectedValue` afterwards — `''` when nothing is selected. */
     value: string;
     /** `selectedLabel` afterwards — the text the inline value / button shows. */
     label: string;
@@ -33,6 +42,12 @@ export interface ComboSelectionVector {
      * gated on `interactive`.
      */
     emitted: ReadonlyArray<ComboStateChange>;
+    /**
+     * Every `notify::` the scenario owes, flattened in EMISSION ORDER — see the module
+     * header. Driven by the surfaces that have real GObject properties; a DOM renderer
+     * skips it.
+     */
+    notified: ReadonlyArray<ComboNotify>;
     rule: string;
 }
 /**
@@ -46,6 +61,51 @@ export interface ComboSelectionVector {
  * replaced. That first change is in `emitted` for exactly that reason.
  */
 export declare const COMBO_SELECTION_VECTORS: ReadonlyArray<ComboSelectionVector>;
+/** One splice applied to the model a combo state is HOLDING. */
+export interface ComboSpliceStep {
+    position: number;
+    removed: number;
+    added: ReadonlyArray<AdwComboOption>;
+}
+/** One `items-changed` → selection scenario. */
+export interface ComboItemsChangedVector {
+    name: string;
+    /** The model the state holds before the splice. */
+    initial: ReadonlyArray<AdwComboOption>;
+    /** Where the selection sits before the splice — `-1` leaves the sentinel in place. */
+    selected: number;
+    splice: ComboSpliceStep;
+    /** `selectedIndex` after the splice. */
+    result: number;
+    /** `selectedValue` after the splice. */
+    value: string;
+    /** The `notify::` the splice owes, in order — EMPTY where GTK emits none. */
+    notified: ReadonlyArray<ComboNotify>;
+    rule: string;
+}
+/**
+ * What a splice on the HELD model does to the selection — `GtkSingleSelection`'s
+ * `items-changed` handler, which `Adw.ComboRow` and `Gtk.DropDown` both sit on.
+ *
+ * NEW IN ADR 0122, and only reachable since it: while `model` was an Array the only way to
+ * change the list was to replace it, so this whole axis had no spelling. A live
+ * `Gio.ListModel` moves under the widget, and WHERE it moved decides whether the selection
+ * follows the item, shifts with it, or is clamped because the item is gone.
+ *
+ * Every row is MEASURED (`combo-probe2.js`), and the `notified` column is the point of the
+ * table: the order here is the INVERSE of a `selected` write — `selected-item` first,
+ * because what changed is the item and the index is downstream of it. The shift row
+ * notifies `selected` ALONE for the mirror-image reason (the item did not change, only its
+ * position), and the replace-in-place row notifies `selected-item` alone.
+ *
+ * `<adw-combo-row>` drives the table through its own DOM, which is where the splice has to
+ * land for a user to see it: the outcome columns, the rebuilt `<option>` list, and the
+ * SILENCE a DOM surface owes (a model moving underneath is not a user pick, so no
+ * `notify::selected` event). The `notified` column itself stays with the core suite — it is
+ * a GObject property feed, and no port publishes one for this path yet; `subscribeNotify`
+ * is the seam a host that owns real properties will re-emit from.
+ */
+export declare const COMBO_ITEMS_CHANGED_VECTORS: ReadonlyArray<ComboItemsChangedVector>;
 /** One `presentsChooser` expectation. */
 export interface ComboChooserVector {
     count: number;

package/lib/types/conformance/split-button.d.ts

@@ -16,7 +16,10 @@ export interface SplitButtonContentStep {
     mode: SplitButtonContentMode;
     /** `get_label()` after the step. */
     label: string | null;
-    /** `get_icon_name()` after the step. */
+    /**
+     * `get_icon_name()` after the step — the READBACK, so an icon name set to `''` reads
+     * back `null` here, as it does in C.
+     */
     iconName: string | null;
     /** The root style classes after the step. */
     styleClasses: readonly SplitButtonStyleClass[];
@@ -32,8 +35,9 @@ export interface SplitButtonContentVector {
  * The content machine.
  *
  * Two things are easy to get wrong and are asserted explicitly. The `notified` ORDER: C
- * freezes, notifies the slots it is about to CLEAR, sets the new one, notifies it, then
- * thaws — so one `set_label()` can emit three notifications. And `child` is notified far
+ * freezes, notifies the property being SET, then the slots that were filled before the
+ * call, then thaws — so one `set_label()` can emit three notifications, led by `label`
+ * itself. And `child` is notified far
  * more often than a reader expects, because `adw_split_button_get_child()` returns
  * GtkButton's INTERNAL label/image widget in label/icon mode (the upstream suite says so)
  * and the C guard tests that pointer, not whether the app ever set a child.

package/lib/types/default-translate.d.ts

@@ -0,0 +1,6 @@
+/** Translates `text`, disambiguated by the `C_()` `context` when there is one. */
+export type DefaultTranslate = (text: string, context?: string) => string;
+/** Install the translator; the last registration wins, as a later `textdomain()` call would. */
+export declare function registerDefaultTranslate(translate: DefaultTranslate | undefined): void;
+/** The installed translator, or `undefined` when no platform filled the slot. */
+export declare function registeredDefaultTranslate(): DefaultTranslate | undefined;

package/lib/types/default-translate.spec.d.ts

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

package/lib/types/engine.d.ts

@@ -1,16 +1,50 @@
-import type { Binding, BindingFlag, ClassLike, GObjectInstance, ParamSpec, RegisteredClass, SignalHandler } from './gobject.js';
+import type { Binding, BindingFlag, ClassLike, GInterface, GObjectInstance, GType, ParamSpec, RegisteredClass, SignalHandler } from './gobject.js';
+/**
+ * The kinds that carry a VALUE a declaration can also spell as a default — the five the subset
+ * has had since ADR 0105, and the only ones a signal parameter may take.
+ */
+export type ForeignScalarKind = 'string' | 'boolean' | 'int' | 'uint' | 'double';
 /** The property kinds the subset has, and the only ones a declared widget property may take. */
-export type ForeignPropertyKind = 'string' | 'boolean' | 'int' | 'uint' | 'double';
+export type ForeignPropertyKind = ForeignScalarKind | 'object';
 /** One property a widget class declares at its `extends`. `default` is the unset value. */
-export interface ForeignProperty {
-    readonly kind: ForeignPropertyKind;
+export interface ForeignScalarProperty {
+    readonly kind: ForeignScalarKind;
     readonly default?: string | boolean | number | null;
     readonly nick?: string;
     readonly blurb?: string;
 }
-/** One signal a widget class declares at its `extends`, in the subset's parameter vocabulary. */
+/**
+ * A property holding another GObject, or `null` — `Adw.ComboRow:model` (ADR 0122 § 6).
+ *
+ * `valueType` IS REQUIRED, and that is the whole reason this is a separate arm rather than an
+ * optional field on the one above. `g_param_spec_object` takes the object type as an argument and
+ * has no default for it, so a declaration that omitted it would leave the engine to guess between
+ * "any GObject" and the interface the widget actually means — and a `model` that accepted any
+ * GObject is the refusal ADR 0122 § 6 exists to make. It is the subset's own token (`TYPE_OBJECT`
+ * or an interface of the subset), NOT node-gi's: a port that named a real GType would have to
+ * import node-gi to describe its own properties, which is the dependency this vocabulary exists
+ * to keep out. The engine that has node-gi translates.
+ *
+ * There is no `default`. `g_param_spec_object`'s default is always `NULL`, so a declaration
+ * cannot carry another one.
+ */
+export interface ForeignObjectProperty {
+    readonly kind: 'object';
+    readonly valueType: GType | GInterface;
+    readonly nick?: string;
+    readonly blurb?: string;
+}
+/** One property a widget class declares at its `extends`. */
+export type ForeignProperty = ForeignScalarProperty | ForeignObjectProperty;
+/**
+ * One signal a widget class declares at its `extends`, in the subset's parameter vocabulary.
+ *
+ * SCALARS ONLY. An object parameter would need its own type beside the kind, as the property arm
+ * does, and nothing declares one — `items-changed` is three `uint`s. Widening it to
+ * `ForeignPropertyKind` would make `{ kind: 'object' }` spellable with no type and no meaning.
+ */
 export interface ForeignSignal {
-    readonly param_types?: readonly ForeignPropertyKind[];
+    readonly param_types?: readonly ForeignScalarKind[];
 }
 /**
  * What a widget class declares at its `extends` — GJS's `registerClass` meta, in the port's own

package/lib/types/glib.d.ts

@@ -22,6 +22,46 @@ export declare function gStrStrip(value: string): string;
  * subtitle.
  */
 export declare function stringIsNotEmpty(value: string | null | undefined): boolean;
+/**
+ * How a `GtkButton` reads an icon name BACK: `''` becomes `NULL`.
+ *
+ * `gtk_button_set_icon_name` holds the name on an internal `GtkImage`, and an empty name
+ * leaves that image EMPTY — so `gtk_button_get_icon_name` answers `NULL` for a button
+ * whose icon name was set to `''`. Only the readback normalises; the write itself is
+ * accepted and does replace the content widget.
+ *
+ * WHY A PORT NEEDS IT. C's idempotence guard is `g_strcmp0 (icon_name, get_icon_name
+ * (self))` — the incoming value against the READBACK, not against what is stored. The
+ * two differ exactly here, so `g_strcmp0 ('', NULL)` is non-zero and EVERY
+ * `icon_name = ''` write passes the guard, rebuilds the internal image and notifies,
+ * for as long as it is repeated. A port that compares against its own field instead
+ * swallows the second write and goes silent where GTK is loud.
+ *
+ * Measured on GJS 1.88.1 / libadwaita 1.9.4 / GTK 4.22.5: `set_icon_name('')` on a fresh
+ * `Adw.SplitButton` emits `notify::icon-name` and reads `null` back; repeating it emits
+ * `notify::icon-name` and `notify::child` again. An `''` LABEL does not behave this way —
+ * `gtk_button_get_label` reads `''` straight back — which is why this is one function
+ * about one property and not a general "empty means unset" rule.
+ */
+export declare function gtkButtonIconNameReadback(stored: string | null): string | null;
+/**
+ * Whether `adw_action_row_set_subtitle` passes its guard (adw-action-row.c:571):
+ * `g_strcmp0 (gtk_label_get_text (priv->subtitle), subtitle) == 0` returns early.
+ *
+ * `g_strcmp0` orders `NULL` before every string, `''` included, so a `NULL` write is NEVER
+ * equal to the label text — which always reads `''`, never `NULL`. A `null` subtitle therefore
+ * passes the guard, relabels with `""` and notifies on EVERY write, held value unmoved. A
+ * `''` write against `''` is the ordinary idempotent case.
+ *
+ * Measured on GJS 1.88.1 / libadwaita 1.9.4: `subtitle = null` on a fresh `Adw.ActionRow` and
+ * `Adw.ExpanderRow` emits `notify::subtitle` each time and reads `""` back; `subtitle = ''`
+ * emits nothing. `title` was measured on the same rows and does NOT behave this way, so this is one
+ * property's rule, not a general one.
+ *
+ * @param held     The label text now, never `null`.
+ * @param written  What the caller passed.
+ */
+export declare function adwSubtitleWriteNotifies(held: string, written: string | null | undefined): boolean;
 /**
  * GLib's `CLAMP`, which tests the HIGH bound FIRST:
  * `x > high ? high : (x < low ? low : x)`.

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

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

package/lib/types/gtk-platform.d.ts

@@ -42,6 +42,8 @@ export declare const GDK_KEYS: Readonly<{
     readonly KEY_Up: 65362;
     readonly KEY_Right: 65363;
     readonly KEY_Down: 65364;
+    /** XF86Back: the hardware / mouse back key, and what Android's back button is delivered as. */
+    readonly KEY_Back: 269025062;
 }>;
 /** A DOM `key` as the keysym GTK would deliver: a Latin-1 character is its own code point, lowercased. */
 export declare function keyvalOfKey(key: string): number;
@@ -109,6 +111,13 @@ export interface GtkPlatform {
 }
 /** A port is always on a display, so `Settings.get_default()` is never null (real GTK: null before `Gtk.init`). */
 export declare function createGtkPlatform(host: PlatformHost): GtkPlatform;
+/**
+ * Runs `event` through the key controllers attached to `widget`, as GTK does for a key the widget's
+ * toplevel receives: the first controller whose `key-pressed` / `key-released` handler returns true
+ * takes it. For keys the platform delivers by another road than the widget's own key listener (the
+ * Android back button); the result is whether a controller handled it.
+ */
+export declare function deliverKeyToControllers(widget: object, event: HostKeyEvent): boolean;
 /** `Gtk.Widget.add_controller` / `remove_controller` for the widgets of a port. */
 export declare function widgetControllerMembers(host: PlatformHost): {
     add_controller(this: object, controller: EventControllerKey): void;

package/lib/types/index.d.ts

@@ -32,7 +32,7 @@ export { Toast, ToastOverlayQueue, ToastPriority } from './toast-object.js';
 export type { ToastOverlayQueueOptions } from './toast-object.js';
 export { AdwAlertResponses, BottomSheetPresentation, resolveBottomSheetChrome, resolveBottomSheetClose, resolveBottomSheetOpen, resolveBottomSheetSwipeTracker, } from './dialog.js';
 export type { AdwAlertResponse, AdwResponseAppearance, AdwResponseOptions, BottomSheetChrome, BottomSheetChromeState, BottomSheetCloseOutcome, BottomSheetCloseSource, BottomSheetCloseState, BottomSheetLayer, BottomSheetOpenOutcome, BottomSheetOpenSource, BottomSheetOpenState, BottomSheetPresentationListener, BottomSheetPresentationOptions, BottomSheetSwipeTrackerConfig, BottomSheetSwipeTrackerState, BottomSheetTeardownCallback, OrderedConfirmResponses, } from './dialog.js';
-export { ADW_COMBO_NO_SELECTION, clampListSelection, listItemsChanged, normalizeComboOptions, parseListModel, } from './list.js';
+export { ADW_COMBO_NO_SELECTION, listItemsChanged, normalizeComboOptions, parseListModel } from './list.js';
 export type { AdwComboOption, AdwComboOptionInput, AdwListItemsChanged, AdwListModel, AdwListModelInput, } from './list.js';
 export { ADW_COLUMN_VIEW_NO_FIXED_WIDTH, ADW_GRID_VIEW_MAX_COLUMNS, ADW_GRID_VIEW_MIN_COLUMNS, columnViewSort, columnViewTracks, gridViewColumns, listItemField, listViewSelect, listViewSelectAll, ListViewState, normalizeColumnViewColumns, normalizeListSelectionMode, parseColumnViewColumns, } from './list-view.js';
 export type { AdwColumnViewColumn, AdwColumnViewSort, AdwListItemContext, AdwListItemFactory, AdwListItemField, AdwListSelectStep, AdwListSelection, AdwListSelectionMode, AdwListSelectResult, ListViewItemsListener, ListViewSelectionChange, ListViewSelectionListener, } from './list-view.js';
@@ -48,15 +48,19 @@ export { GtkAdjustment } from './gtk-adjustment.js';
 export type { GtkAdjustmentProps } from './gtk-adjustment.js';
 export { GtkStringList, GtkStringObject, INVALID_LIST_POSITION } from './gtk-string-list.js';
 export type { GtkStringListProps } from './gtk-string-list.js';
+export { GjsifyOptionList, GjsifyOptionObject, readModelWrite } from './option-list.js';
+export type { GjsifyOptionListProps } from './option-list.js';
 export { ComboState, ExpanderState, ToggleGroupState, keptToggles, toggleIndexOfName } from './rows.js';
-export type { ComboItemsListener, ComboStateChange, ComboStateListener, ExpanderStateListener, ToggleGroupStateChange, ToggleGroupStateListener, } from './rows.js';
+export type { ComboItemsListener, ComboNotify, ComboNotifyListener, ComboStateChange, ComboStateListener, ComboWatchableModel, ExpanderNotify, ExpanderStateListener, ToggleGroupStateChange, ToggleGroupStateListener, } from './rows.js';
 export { DEFAULT_BOX_SPACING, normalizeBoxOrientation, normalizeBoxSpacing } from './box.js';
 export type { BoxOrientation } from './box.js';
 export { DEFAULT_LABEL_ELLIPSIZE, DEFAULT_LABEL_LINES, DEFAULT_LABEL_MAX_WIDTH_CHARS, DEFAULT_LABEL_WIDTH_CHARS, DEFAULT_LABEL_WRAP_MODE, DEFAULT_LABEL_XALIGN, DEFAULT_LABEL_YALIGN, LABEL_ELLIPSIZE_MODES, LABEL_JUSTIFICATIONS, LABEL_WRAP_MODES, labelDisplayText, labelEffectiveLines, labelEllipsizeOverflowValue, labelMarkupIsUnparseable, labelWidthCharsExtent, labelYalignAlignItems, normalizeLabelEllipsize, normalizeLabelJustify, normalizeLabelLines, normalizeLabelMaxWidthChars, normalizeLabelWidthChars, normalizeLabelWrapMode, normalizeLabelXalign, normalizeLabelYalign, } from './label.js';
 export type { LabelAlignItems, LabelEllipsizeMode, LabelJustification, LabelWidthCharsExtent, LabelWrapMode, } from './label.js';
-export { glibClamp, gStrStrip, stringIsNotEmpty } from './glib.js';
+export { LABEL_MARKUP_STYLE_PLAIN, labelActivateLink, labelHasLinks, labelLinkVisited, labelLinksHaveTooltip, labelLinksInheritVisited, labelMarkupRender, } from './label-markup.js';
+export type { LabelActivateLinkSteps, LabelLink, LabelMarkupRender, LabelMarkupRun, LabelMarkupStyle, } from './label-markup.js';
+export { adwSubtitleWriteNotifies, glibClamp, gStrStrip, gtkButtonIconNameReadback, stringIsNotEmpty } from './glib.js';
 export { AppLaunchContext as GdkAppLaunchContext, ContentFormats, ContentProvider, Clipboard, Display, createGdk, widgetDisplayMembers, } from './gdk.js';
-export { CURRENT_TIME, CssProvider, EventControllerKey, GDK_KEYS, GtkSettings, IconTheme, STYLE_PROVIDER_PRIORITY_APPLICATION, STYLE_PROVIDER_PRIORITY_FALLBACK, STYLE_PROVIDER_PRIORITY_SETTINGS, STYLE_PROVIDER_PRIORITY_THEME, STYLE_PROVIDER_PRIORITY_USER, createGtkPlatform, keyvalOfKey, widgetControllerMembers, } from './gtk-platform.js';
+export { CURRENT_TIME, CssProvider, EventControllerKey, GDK_KEYS, GtkSettings, IconTheme, STYLE_PROVIDER_PRIORITY_APPLICATION, STYLE_PROVIDER_PRIORITY_FALLBACK, STYLE_PROVIDER_PRIORITY_SETTINGS, STYLE_PROVIDER_PRIORITY_THEME, STYLE_PROVIDER_PRIORITY_USER, createGtkPlatform, deliverKeyToControllers, keyvalOfKey, widgetControllerMembers, } from './gtk-platform.js';
 export type { GtkPlatform, HostKeyEvent, PlatformHost } from './gtk-platform.js';
 export { iconLookupNames, lookupResourceIcon } from './icon-theme-resources.js';
 export type { IconDirection, ResourceIconMatch, ResourceIconRequest } from './icon-theme-resources.js';
@@ -111,8 +115,8 @@ export type { AdwSwipeEnd, AdwSwipeEndInput, AdwSwipeRange, AdwSwipeSource } fro
 export { CAROUSEL_SCROLL_TIMEOUT_MS, CAROUSEL_SETTLE_EPSILON, CarouselState, carouselClampPosition, carouselClosestSnapPoint, carouselNavigateTarget, carouselPageAllocation, carouselPageAtPosition, carouselRange, carouselReorderShift, carouselSizesFromSnapPoints, carouselSnapPoints, carouselWheelStep, } from './carousel.js';
 export type { CarouselChangeReason, CarouselDirection, CarouselOrientation, CarouselPageAllocation, CarouselPageChangedListener, CarouselPageMeasurement, CarouselRange, CarouselReorderShiftInput, CarouselScrollOptions, CarouselScrollRequest, CarouselScrollSource, CarouselStateChange, CarouselStateListener, CarouselStateOptions, CarouselWheelInput, } from './carousel.js';
 export { UNTITLED_PAGE_LABEL, collectSearchRows, countVisiblePages, createSearchRowSubtitle, defaultCaseFolder, derivePreferencesGroupHeader, makeComparable, rowMatchesQuery, searchPreferences, } from './preferences.js';
-export { PANGO_MARKUP_TAGS, escapeMarkup, parsePangoMarkup, stripMarkup } from './pango-markup.js';
-export type { PangoMarkupNode, PangoMarkupTag } from './pango-markup.js';
+export { PANGO_MARKUP_TAGS, escapeMarkup, parseLabelMarkup, parsePangoMarkup, stripLabelMarkup, stripMarkup, } from './pango-markup.js';
+export type { LabelMarkupNode, PangoMarkupNode, PangoMarkupTag } from './pango-markup.js';
 export type { CaseFolder, MakeComparableOptions, PreferencesGroupHeaderInput, PreferencesGroupHeaderState, PreferencesSearchEntry, PreferencesSearchGroup, PreferencesSearchPage, PreferencesSearchResult, PreferencesSearchRow, SearchPreferencesOptions, SearchRowSubtitleInput, } from './preferences.js';
 export { ADW_CLAMP_DEFAULTS, ADW_CLAMP_SIZE_CLASSES, ADW_SPINNER_MAX_SIZE, ADW_SPINNER_MIN_SIZE, ADW_TOOLBAR_BAR_CLASSES, ADW_TOOLBAR_VIEW_CLASSES, ADW_TOOLBAR_VIEW_DEFAULTS, clampAllocate, clampChildSize, clampSizeFromChild, clampThresholds, normalizeClampSize, parseToolbarStyle, resolveSpinnerSize, spinnerGeometry, toolbarBarStyleClasses, toolbarViewAllocate, toolbarViewClasses, toolbarViewContentForSize, toolbarViewMeasure, } from './chrome.js';
 export type { AdwClampSizeClass, AdwMeasurement, AdwToolbarStyle, ClampAllocation, ClampParams, ClampThresholds, SpinnerGeometry, ToolbarViewAllocateInput, ToolbarViewAllocation, ToolbarViewClassInput, ToolbarViewClasses, ToolbarViewContentForSize, ToolbarViewContentForSizeInput, ToolbarViewMeasureInput, } from './chrome.js';
@@ -140,8 +144,10 @@ export type { ApplicationHost, GtkApplicationMembers, GtkApplicationConstructor
 export { ActionRegistry, SimpleAction, actionRegistryOf, activateWidgetAction, applicationOfWindow, findActionGroup, insertActionGroup, installActionMap, linkWindow, SimpleActionGroup, } from './gio-actions.js';
 export type { ActionActivateHandler, ActionGroupLike, ActionLike, SimpleActionProps } from './gio-actions.js';
 export type { Binding, BindingFlag, BlueprintTemplate, BuiltTemplate, ClassLike, ClassMeta, GInterface, GObjectConstructor, GObjectDoor, GObjectInstance, GObjectNamespace, GType, ParamKind, RegisterClass, RegisteredClass, SignalHandler, SignalMeta, TemplateScope, } from './gobject.js';
+export { registerDefaultTranslate, registeredDefaultTranslate } from './default-translate.js';
+export type { DefaultTranslate } from './default-translate.js';
 export { engineForTarget, registerGObjectEngine, registeredEngine, resetRegisteredEngine } from './engine.js';
-export type { EngineTarget, ForeignClassMeta, ForeignProperty, ForeignPropertyKind, ForeignSignal, GObjectEngine, } from './engine.js';
+export type { EngineTarget, ForeignClassMeta, ForeignObjectProperty, ForeignProperty, ForeignPropertyKind, ForeignScalarKind, ForeignScalarProperty, ForeignSignal, GObjectEngine, } from './engine.js';
 export { MAXUINT32, buildFilenamev, getCurrentDir, getSystemDataDirs } from './glib-paths.js';
 export { uriEscapeString } from './glib-uri.js';
 export { computeLanguageNames, languageNamesFromTags, localeFromLanguageTag } from './glib-language.js';

package/lib/types/label-markup.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The style one run of text carries, with pango's nesting already resolved.
+ *
+ * The booleans are pango's own tags; a tag nested inside itself is still just set, which
+ * is why they are booleans and not counts. `sizeSteps` IS a count, because `<big>` and
+ * `<small>` are relative and compose: `<big><big>` is two steps up, and `<small>` inside
+ * `<big>` cancels back to zero — pango applies one `PANGO_SCALE_*` factor per element, so
+ * the steps multiply rather than the innermost winning.
+ */
+export interface LabelMarkupStyle {
+    /** `<b>`. */
+    readonly bold: boolean;
+    /** `<i>`. */
+    readonly italic: boolean;
+    /** `<u>`. */
+    readonly underline: boolean;
+    /** `<s>`. */
+    readonly strikethrough: boolean;
+    /** `<tt>`. */
+    readonly monospace: boolean;
+    /** `<big>` minus `<small>`, so a negative value is smaller text. */
+    readonly sizeSteps: number;
+    /** `<sub>` / `<sup>`, the INNERMOST of the two — one run cannot be both. */
+    readonly script: 'sub' | 'sup' | null;
+    /**
+     * The `<span>` attribute sets the run sits inside, OUTERMOST FIRST.
+     *
+     * A STACK and not one merged record, because the attribute→platform mapping is the
+     * renderer's (`font_weight` is an alias of `weight` on the web, `fontWeight` on
+     * NativeScript, and neither list is the other's). A renderer applies them in order and
+     * the innermost therefore wins per platform property — merging here would need pango's
+     * alias table in core, where no port reads it.
+     */
+    readonly spans: readonly Readonly<Record<string, string>>[];
+}
+/** No tag at all — the style a bare text run carries. */
+export declare const LABEL_MARKUP_STYLE_PLAIN: LabelMarkupStyle;
+/** One `<a href>` of a label's markup, over a range of its display text. */
+export interface LabelLink {
+    /** `<a href>`. */
+    readonly href: string;
+    /** `<a title>` — what GTK shows as the label's tooltip over this link. */
+    readonly title: string | null;
+    /** `<a class>` — the CSS class GTK adds to the link's own node. */
+    readonly cssClass: string | null;
+    /** Where the link's text starts in the display text, in UTF-16 code units. */
+    readonly start: number;
+    /** Where it ends, exclusive. `start === end` is a link with nothing to click. */
+    readonly end: number;
+    /** Whether this link has been followed — see {@link labelLinksInheritVisited}. */
+    readonly visited: boolean;
+}
+/** One run of a label's markup: text, the style over it, and the link it sits in. */
+export interface LabelMarkupRun {
+    readonly text: string;
+    readonly style: LabelMarkupStyle;
+    /**
+     * The index into {@link LabelMarkupRender.links} of the link this run is inside, or
+     * `null`. An INDEX rather than the link itself, so a renderer that updates `visited`
+     * replaces one array entry instead of rewriting every run that points at it.
+     */
+    readonly link: number | null;
+}
+/** A label's markup, ready to draw. */
+export interface LabelMarkupRender {
+    /** `gtk_label_get_text()` — the runs' text concatenated. */
+    readonly text: string;
+    /** The styled runs, in reading order. Empty when the markup has no text at all. */
+    readonly runs: readonly LabelMarkupRun[];
+    /** The `<a href>` elements, in reading order. */
+    readonly links: readonly LabelLink[];
+}
+/**
+ * A label's `label` as the runs and links a renderer draws, or `null` when the markup does
+ * not parse — the same `null` {@link parseLabelMarkup} returns, so a caller takes the C
+ * fallback (show the raw string) on exactly the strings GTK takes it on.
+ *
+ * `previous` is the links the label held BEFORE this value, and only `visited` is read from
+ * it: see {@link labelLinksInheritVisited}.
+ */
+export declare function labelMarkupRender(markup: string, previous?: readonly LabelLink[]): LabelMarkupRender | null;
+/**
+ * `visited` carried across a re-parse by URI (gtklabel.c:3635-3647): a link whose `href`
+ * matches one the label already had keeps that link's `visited`, because following a link
+ * and then rewriting the text around it has not un-followed it.
+ *
+ * FIRST match, as in the C: two links to the same URI are one visited state.
+ */
+export declare function labelLinksInheritVisited(links: readonly LabelLink[], previous: readonly LabelLink[]): readonly LabelLink[];
+/**
+ * `gtk_label_ensure_has_tooltip` — a label gets `has-tooltip` when ANY of its links
+ * carries a `title`, because the tooltip is per-link and the widget has to opt in before
+ * `query-tooltip` is ever asked.
+ */
+export declare function labelLinksHaveTooltip(links: readonly LabelLink[]): boolean;
+/**
+ * The `link` CSS class `gtk_label_set_markup` adds to the WIDGET (gtklabel.c:3896) when its
+ * markup carried at least one `<a href>` — libadwaita's stylesheet selects on it, so a
+ * port that draws the link colour without it is styling by its own rule and not GTK's.
+ */
+export declare function labelHasLinks(links: readonly LabelLink[]): boolean;
+/** What one port supplies to one `::activate-link` emission. */
+export interface LabelActivateLinkSteps {
+    /**
+     * `GTK_IS_WINDOW (gtk_widget_get_root (widget))` — the default handler returns FALSE
+     * for a label with no window above it, and then NOTHING is launched. A port answers
+     * this with whatever "is in a presented window" means for it.
+     */
+    readonly rooted: boolean;
+    /** Emit `activate-link` to the USER's handlers and answer whether one handled it. */
+    emit(): boolean;
+    /** `Gio.AppInfo.launch_default_for_uri` — the port's door, ADR 0101. */
+    launch(uri: string): void;
+}
+/**
+ * `emit_activate_link` — `::activate-link` is RUN_LAST with the boolean handled
+ * accumulator (`HandledAccumulator`, `window-members.ts`), so the order is: the user's
+ * handlers, then — only if none handled it — the class handler, which launches the URI and
+ * counts that as handled.
+ *
+ * Returns whether the link becomes VISITED, which is what GTK does with the signal's
+ * result: a handler that returns TRUE has followed the link its own way, and the default
+ * returning TRUE means the URI went to the host. A label with no window above it returns
+ * FALSE and the link stays unvisited — `gtk_label_activate_link`'s first branch, and the
+ * reason it is not simply "launch and say yes".
+ */
+export declare function labelActivateLink(uri: string, steps: LabelActivateLinkSteps): boolean;
+/** The links of `links` with the one at `index` marked visited; the others untouched. */
+export declare function labelLinkVisited(links: readonly LabelLink[], index: number): readonly LabelLink[];

package/lib/types/label-markup.spec.d.ts

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

package/lib/types/label.d.ts

@@ -11,6 +11,12 @@ export type LabelJustification = (typeof LABEL_JUSTIFICATIONS)[number];
  * of the resulting TEXT, so an `_` inside a tag's attributes is not a mnemonic. Doing it
  * the other way round would let `<span font_desc="Sans">` lose its underscore and stop
  * parsing.
+ *
+ * THE PARSE IS THE LABEL'S, `stripLabelMarkup` — pango's tags PLUS `<a href>`, which is
+ * what `gtk_label_get_text()` returns, because `parse_uri_markup` lifts the `<a>` elements
+ * out before pango ever sees the string. A surface that is NOT a label does not come here:
+ * `Gtk.Inscription` has no `::activate-link` and its `markup` goes through
+ * `pango_parse_markup` alone, so `<a>` is an unknown tag there and the raw string stands.
  */
 export declare function labelDisplayText(label: string, useMarkup: boolean, useUnderline: boolean): string;
 /** Whether `label` carries markup that could not be reduced, so the raw string is shown. */

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

@@ -138,10 +138,10 @@ export declare class ListViewState {
      * any selected position the new model does not have.
      *
      * A VIEW DOES NOT AUTOSELECT, and that is the one place this class deliberately
-     * differs from `ComboState`. `clampListSelection` is `GtkSingleSelection`'s
-     * `autoselect`, which exists so a combo row always has a value to SHOW; a list view
-     * has no inline value and GTK's own `GtkMultiSelection` keeps nothing selected after
-     * a model it cannot map. So positions are filtered, not clamped.
+     * differs from `ComboState`, whose model write resets the selection to 0:
+     * `GtkSingleSelection:autoselect` exists so a combo row always has a value to SHOW; a
+     * list view has no inline value and GTK's own `GtkMultiSelection` keeps nothing
+     * selected after a model it cannot map. So positions are filtered, not reset.
      */
     setModel(model: readonly AdwComboOption[] | null | undefined): void;
     /** `Gtk.SelectionModel` choice. Narrowing it drops what the new mode cannot hold. */