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

package/lib/types/list.d.ts

@@ -32,13 +32,16 @@ export interface AdwListModelSource {
     get_item(position: number): unknown;
 }
 /**
- * What a `model` property ACCEPTS: the widened form of {@link AdwListModel}, plus a real
- * {@link AdwListModelSource}.
+ * What {@link normalizeComboOptions} ACCEPTS: the widened form of {@link AdwListModel}, plus a
+ * real {@link AdwListModelSource}.
  *
- * The model arm is new in ADR 0122, which made `Gtk.StringList` a `Gio.ListModel` instead of
- * an `Array` subclass — the one value that used to satisfy BOTH arms at once. It is not a
- * permanent widening: ADR 0122 § 6 narrows `Adw.ComboRow:model` to `Gio.ListModel` alone, and
- * the array arm goes with the widget that still reads a markup attribute.
+ * IT IS THE NORMALISER'S INPUT TYPE AND NOT A PROPERTY TYPE, which is the whole of what ADR
+ * 0122 § 6 changed about it. `Adw.ComboRow:model` and `Gtk.DropDown:model` are a
+ * `Gio.ListModel` and nothing else now — an array assigned to either is a `TypeError` naming
+ * the type. The union stays because the AUTHORED vocabulary is still both: a JSON markup
+ * attribute parses to an array, a `Gtk.StringList` handed to `GjsifyOptionList` is a model,
+ * and both arrive here on their way to becoming descriptors. The arms are the two forms a
+ * caller can WRITE DOWN, not the two values a property will take.
  */
 export type AdwListModelInput = ReadonlyArray<AdwComboOptionInput> | AdwListModelSource;
 /**
@@ -83,23 +86,6 @@ export declare function parseListModel(raw: string | null | undefined): AdwCombo
  * draw a placeholder has nothing to test.
  */
 export declare const ADW_COMBO_NO_SELECTION = -1;
-/**
- * Where a selection lands after the model under it was REPLACED.
- *
- * `GtkSingleSelection` autoselects, so a position the new model does not have falls back
- * to 0 — including the sentinel, which is how a widget recovers a selection when its model
- * grows. An EMPTY model has no 0 to fall back to and lands on
- * {@link ADW_COMBO_NO_SELECTION}.
- *
- * The test is membership and not `selected >= length`: the sentinel is BELOW the range, so
- * a one-sided comparison leaves a `-1` in place and a model that was emptied and refilled
- * comes back with nothing selected.
- *
- * Lifted out of `ComboState.setModel` so a second list widget cannot re-derive it. The
- * cross-renderer rule it encodes was already conformance data — `conformance/rows.ts`
- * carries it as "the ports' shared answer" — it just had no name of its own.
- */
-export declare function clampListSelection(selected: number, length: number): number;
 /**
  * One positional change — `Gio.ListModel::items-changed`'s own three parameters.
  *

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

@@ -0,0 +1,128 @@
+import { GObjectObject, type GType } from './gobject.js';
+import { type AdwComboOption, type AdwComboOptionInput } from './list.js';
+import type { ComboWatchableModel } from './rows.js';
+/**
+ * One selectable item, as the `GObject` a `GListModel` is allowed to hand out.
+ *
+ * Both properties are READ-ONLY, and that is not caution: an item is what a model contains, and
+ * a model reports a content change through `items-changed`. A writable `label` would let the
+ * text under a selection move with nothing emitted, which is the failure
+ * `GtkStringObject`'s read-only `string` exists to prevent.
+ *
+ * It deliberately has NO `string` property. `readListModel` unwraps an item that has one as a
+ * bare string — that is `Gtk.StringObject`'s shape — and an option that answered to it would
+ * lose its `value` on the way out, which is the whole reason this type exists.
+ */
+export declare class GjsifyOptionObject extends GObjectObject {
+    constructor(props?: Record<string, unknown> | null);
+    /** An item holding `value` and `label` — the only way to put either in one. */
+    static new(value: string, label: string): GjsifyOptionObject;
+    /** An item for one authored entry, through the normaliser every surface already shares. */
+    static fromInput(entry: AdwComboOptionInput): GjsifyOptionObject;
+    /** The value this item is addressed by. */
+    get value(): string;
+    set value(_value: string);
+    /** The text this item draws as. */
+    get label(): string;
+    set label(_value: string);
+    /** The descriptor this item holds, as a COPY — nothing hands out the stored record. */
+    toOption(): AdwComboOption;
+}
+/** What `new GjsifyOptionList({ … })` takes. */
+export interface GjsifyOptionListProps {
+    /** The options the list starts with, in any form {@link normalizeComboOptions} accepts. */
+    options?: readonly AdwComboOptionInput[] | null;
+}
+/**
+ * A `Gio.ListModel` of {@link GjsifyOptionObject}s — what a `model` property holds once the
+ * array door is closed.
+ *
+ * `new GjsifyOptionList()` is empty. The instance is a GObject with a real identity, so a
+ * `model` write that assigns the SAME list again is the no-op GTK makes it, and
+ * `row.model === list` answers true.
+ */
+export declare class GjsifyOptionList extends GObjectObject {
+    /** Installed by the core from {@link ListModel}; declared here for the type alone. */
+    readonly get_item: (position: number) => GjsifyOptionObject | null;
+    readonly get_item_type: () => GType;
+    readonly get_n_items: () => number;
+    readonly items_changed: (position: number, removed: number, added: number) => void;
+    constructor(props?: GjsifyOptionListProps | null);
+    /** A list holding `options`, or an empty one for `null` — the markup door's constructor. */
+    static new(options: readonly AdwComboOptionInput[] | null): GjsifyOptionList;
+    /** The item type, which here is the specific one: this list holds nothing else. */
+    get item_type(): GType;
+    set item_type(_value: GType);
+    get itemType(): GType;
+    set itemType(_value: GType);
+    /** `n-items` — the `ParamSpec`'s reader, and `get_n_items`'s answer. */
+    get n_items(): number;
+    set n_items(_value: number);
+    /** `vfunc_get_item_type` — what the interface's `get_item_type()` calls through to. */
+    vfunc_get_item_type(): GType;
+    /** `vfunc_get_n_items`. */
+    vfunc_get_n_items(): number;
+    /** `vfunc_get_item` — `null` past the end, as `g_list_model_get_item` returns `NULL`. */
+    vfunc_get_item(position: number): GjsifyOptionObject | null;
+    /** The descriptors this list holds, as copies — the form every renderer draws from. */
+    toOptions(): AdwComboOption[];
+    /** One more option at the end. */
+    append(option: AdwComboOptionInput): void;
+    /** The option at `position`, which must be in range. */
+    remove(position: number): void;
+    /**
+     * `g_list_store_splice(position, n_removals, additions)` — the C signature, all three
+     * arguments, additions as ONE array, so a hundred-item replacement is one emission.
+     *
+     * Out of range is a CRITICAL and a no-op rather than an exception, which is the shape
+     * `Gtk.StringList` measured for the same call: this door is reachable from a markup
+     * attribute, and an author's slip must not take the widget down.
+     */
+    splice(position: number, nRemovals: number, additions: readonly AdwComboOptionInput[] | null): void;
+    /**
+     * The POSITION of the first option with this value, {@link INVALID_LIST_POSITION} when there
+     * is none — `gtk_string_list_find`'s meaning of the name, over the half a descriptor is
+     * addressed by.
+     */
+    find(value: string): number;
+    /**
+     * Replace the contents with `next` IN PLACE, as the ONE splice that turns one into the
+     * other — {@link listItemsChanged}'s minimal range.
+     *
+     * This is the markup door's update path and it keeps the list's IDENTITY, which is what
+     * makes it different from a `model` write. Re-parsing an attribute must not look to the
+     * widget like a new model: a model REPLACEMENT re-runs autoselect and resets the selection
+     * to 0 (ADR 0122 § 4, measured), while appending one option to the end of the list the
+     * widget already holds moves nothing. An author editing `model='[…]'` means the second.
+     */
+    reconcile(next: readonly AdwComboOptionInput[] | null): void;
+    /** The one mutation, so the emission rule is written once. See the file header. */
+    private spliceItems;
+}
+/**
+ * What a write to a `model` property reads as — the ONE door, for all four surfaces.
+ *
+ * ADR 0122 § 6 makes `model` an object property over `Gio.ListModel`, and § 5 leaves the JSON
+ * markup attribute open, so every `model` setter in this repository has the same three-way
+ * answer to give. It is written here once because it was about to be written four times:
+ *
+ *   - a real model — anything with `get_n_items` and `get_item`, which is what
+ *     {@link AdwListModelSource}'s docblock argues is the test — is handed through by IDENTITY,
+ *     so `widget.model === model` holds as it is measured to in libadwaita;
+ *   - `null` / `undefined` is the "no model" write, which notifies `model` alone;
+ *   - a STRING is the markup attribute, parsed and reconciled into `authored` — the surface's
+ *     OWN list, whose identity survives the edit so an author appending one option to
+ *     `model='[…]'` gets one splice instead of a replacement that resets the selection;
+ *   - anything else, an ARRAY above all, is a `TypeError`.
+ *
+ * THE REFUSAL IS THE PROPERTY'S, not a second opinion: the message comes out of
+ * {@link checkPropertyValue} against `model`'s own ParamSpec, which is where GJS's measured
+ * wording lives. Reaching it is already the failure case, and it always throws for a value that
+ * gets that far — the one thing it accepts is a registered implementor of `Gio.ListModel`, and
+ * the interface installs the two getters the duck test above just failed to find.
+ *
+ * The duck test and not `checkPropertyValue` alone, because a REAL `Gio.ListStore` reached
+ * through node-gi (ADR 0104) is no registered class of this subset and `implementsInterface`
+ * would refuse it — and handing one to `Adw.ComboRow:model` is the whole point of having it.
+ */
+export declare function readModelWrite(value: unknown, authored: GjsifyOptionList): ComboWatchableModel | null;

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

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

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

@@ -17,6 +17,29 @@ export type PangoMarkupNode = {
     readonly attributes: Readonly<Record<string, string>>;
     readonly children: readonly PangoMarkupNode[];
 };
+/**
+ * A piece of LABEL markup: {@link PangoMarkupNode}, plus the `<a href>` run pango knows
+ * nothing about. Every `PangoMarkupNode` IS a `LabelMarkupNode` — the link kind is the
+ * only addition — so a renderer written against this type draws both trees.
+ */
+export type LabelMarkupNode = {
+    readonly kind: 'text';
+    readonly text: string;
+} | {
+    readonly kind: 'element';
+    readonly tag: PangoMarkupTag;
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly children: readonly LabelMarkupNode[];
+} | {
+    readonly kind: 'link';
+    /** `<a>`'s required `href`, entities resolved. */
+    readonly href: string;
+    /** `<a title>`, which GTK shows as the label's tooltip; `null` when absent. */
+    readonly title: string | null;
+    /** `<a class>`, the CSS class GTK puts on the link's own node; `null` when absent. */
+    readonly cssClass: string | null;
+    readonly children: readonly LabelMarkupNode[];
+};
 /**
  * `g_markup_escape_text` — the escape `create_search_row_subtitle` puts a page title
  * through before it becomes a markup subtitle. GLib emits NUMERIC references for the
@@ -50,10 +73,32 @@ export declare function escapeMarkup(text: string): string;
  * discarded).
  */
 export declare function parsePangoMarkup(text: string): PangoMarkupNode[] | null;
+/**
+ * `gtk_label_set_markup`'s whole parse: pango's markup PLUS `<a href>`, which is
+ * `Gtk.Label`'s own extension and not a pango tag at all.
+ *
+ * Same `null`-never-throws contract as {@link parsePangoMarkup}, and the same failures,
+ * with `<a>`'s two added: an attribute other than `href` / `title` / `class`
+ * (`G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE`) and a missing `href`
+ * (`G_MARKUP_ERROR_INVALID_CONTENT`).
+ *
+ * USE THIS ONLY WHERE GTK ITSELF PARSES URI MARKUP — `Gtk.Label`, and the widgets that
+ * are a label (`Gtk.Inscription` is NOT one: it has no `::activate-link`). Everything
+ * else — the search pipeline's `stripMarkup`, `Adw.Banner`, `Adw.AlertDialog` — stays on
+ * {@link parsePangoMarkup}, where `<a>` is an unknown tag and the string falls back to
+ * text, because that is what those surfaces do in the C.
+ */
+export declare function parseLabelMarkup(text: string): LabelMarkupNode[] | null;
 /**
  * The plain text of markup — {@link parsePangoMarkup} reduced to its text runs, and
  * `null` under exactly the same failures. This is what `make_comparable` compares, what
- * `<gtk-label>`/`<gtk-inscription>` show for `use-markup`, and what the C shows when
- * markup does not parse.
+ * `<gtk-inscription>` shows for `markup`, and what the C shows when markup does not parse.
  */
 export declare function stripMarkup(text: string): string | null;
+/**
+ * The plain text of LABEL markup — {@link parseLabelMarkup} reduced the same way, so a
+ * `<a href="…">GTK</a>` shows as `GTK` and not as the raw string. This is what
+ * `gtk_label_get_text` returns: `parse_uri_markup` strips the `<a>` elements out before
+ * pango ever sees the string, and the text GTK keeps is the remainder.
+ */
+export declare function stripLabelMarkup(text: string): string | null;

package/lib/types/rows.d.ts

@@ -1,4 +1,4 @@
-import type { AdwComboOption, AdwListItemsChanged } from './list.js';
+import type { AdwComboOption, AdwListItemsChanged, AdwListModelSource } from './list.js';
 export { ADW_COMBO_NO_SELECTION, normalizeComboOptions } from './list.js';
 export type { AdwComboOption, AdwComboOptionInput } from './list.js';
 export { SpinState } from './adjustment.js';
@@ -6,21 +6,43 @@ export type { SpinStateChange, SpinStateListener, SpinStateRangeListener } from
 /** Subscriber for {@link ExpanderState} changes — receives the new expanded flag. */
 export type ExpanderStateListener = (expanded: boolean) => void;
 /**
- * The disclosure state of an expander row: a single boolean that toggles between
- * revealed and collapsed. Idempotent — setting the current value again is a no-op
- * and fires no notification. Both programmatic and interactive changes notify (as
- * `Adw.ExpanderRow` does).
+ * The `notify::*` an expander-row write emits, in emission order. A renderer that owns real
+ * GObject properties re-emits it verbatim; `expanded` leads `enable-expansion` because the
+ * C setter cross-writes `expanded` before it notifies its own property.
+ */
+export type ExpanderNotify = 'expanded' | 'enable-expansion';
+/**
+ * The state of an expander row: whether the disclosure is revealed, and whether it may be.
+ *
+ * The two are coupled the way `adw-expander-row.c` couples them. `setExpanded` coerces
+ * `expanded && enableExpansion` before its equal-return (C:264), so opening a disabled row is
+ * a silent no-op rather than a refusal. `setEnableExpansion` stores, drives `expanded` to the
+ * new value (C:310) and only then notifies its own property — enabling EXPANDS, disabling
+ * COLLAPSES. Idempotent — setting a current value again fires nothing. Both programmatic and
+ * interactive changes notify (as `Adw.ExpanderRow` does).
  */
 export declare class ExpanderState {
     private _expanded;
+    private _enableExpansion;
     private readonly _listeners;
     /** Subscribe to expanded-state changes. Returns an unsubscribe function. */
     subscribe(listener: ExpanderStateListener): () => void;
     private _emit;
     /** Whether the disclosure is revealed. */
     get expanded(): boolean;
-    /** Set the expanded flag. Notifies only on an actual change. Returns whether it changed. */
+    /** Whether the row can be expanded at all. */
+    get enableExpansion(): boolean;
+    /**
+     * Set the expanded flag, held `false` while expansion is disabled. Notifies only on an
+     * actual change. Returns whether it changed.
+     */
     setExpanded(value: boolean): boolean;
+    /**
+     * Set `enable-expansion` and drive `expanded` to the same value. Returns the properties
+     * the write notifies, in order: empty for an equal write, `['enable-expansion']` when
+     * `expanded` already held the value, `['expanded', 'enable-expansion']` otherwise.
+     */
+    setEnableExpansion(value: boolean): readonly ExpanderNotify[];
     /** Flip expanded↔collapsed (the disclosure tap). Returns whether it changed. */
     toggle(): boolean;
     /** Reveal the disclosure. Returns whether it changed. */
@@ -43,6 +65,29 @@ export interface ComboStateChange {
 export type ComboStateListener = (change: ComboStateChange) => void;
 /** Subscriber for {@link ComboState} MODEL changes — one `items-changed` per replacement. */
 export type ComboItemsListener = (change: AdwListItemsChanged) => void;
+/**
+ * A GObject property of `Adw.ComboRow` / `Gtk.DropDown` whose `notify::` a renderer owes its
+ * widget — the three ADR 0122 § 5's table is written in terms of.
+ */
+export type ComboNotify = 'selected' | 'selected-item' | 'model';
+/** Subscriber for the `notify::*` a {@link ComboState} transition owes, in emission ORDER. */
+export type ComboNotifyListener = (property: ComboNotify) => void;
+/**
+ * What {@link ComboState} needs off a model to WATCH it, beyond reading it.
+ *
+ * Optional, and duck-typed for the reason `AdwListModelSource` is: a real `Gio.ListModel` has
+ * `connect`, and so does every model this repository builds, but the reader in `list.ts` accepts
+ * anything with the two getters and a state machine that DEMANDED a signal surface would refuse
+ * models it can otherwise read perfectly.
+ *
+ * EXPORTED because it is the published type of a `model` property now (ADR 0122 § 4). Left
+ * un-exported it still reached the `.d.ts`, so a consumer could satisfy it and not NAME it —
+ * which is the shape that makes a caller declare its own copy.
+ */
+export interface ComboWatchableModel extends AdwListModelSource {
+    connect?: (signal: string, handler: (...args: unknown[]) => void) => number;
+    disconnect?: (id: number) => void;
+}
 /**
  * The selection state of a combo row: a portable list model (`AdwListModel`) plus
  * the selected index, with a two-way index↔value mapping and empty/out-of-range guards.
@@ -60,12 +105,39 @@ export type ComboItemsListener = (change: AdwListItemsChanged) => void;
  * assignment.
  */
 export declare class ComboState {
+    /** The model's IDENTITY — the object `model` hands back, never a copy (ADR 0122 § 4). */
+    private _model;
+    /** The descriptors the held model holds, re-read whenever it says it changed. */
     private _options;
     private _selected;
+    /** Detaches this state from the held model's `items-changed`. */
+    private _unwatch;
     private readonly _listeners;
     private readonly _itemListeners;
+    private readonly _notifyListeners;
     /** Subscribe to selection changes. Returns an unsubscribe function. */
     subscribe(listener: ComboStateListener): () => void;
+    /**
+     * Subscribe to the `notify::*` each transition owes, delivered one at a time IN ORDER.
+     *
+     * Separate from {@link subscribe} because the two answer different questions and the
+     * ordering is the whole content of this one. It is the seam for a renderer that owns real
+     * GObject properties — none does today: both ports render DOM or NativeScript views and
+     * use {@link subscribe}, so this channel is measured in core alone (its table says so).
+     * Re-emitting it verbatim is what a host with real properties has to do, and the reason
+     * the order is recorded here rather than re-derived there.
+     *
+     * The ORDER is not derived, it is measured, and it is not the same on both paths
+     * (`~/.cache/gjsify-android/combo-probe2.js`, GJS 1.88.01 / libadwaita 1.9.4):
+     *
+     *   - a `model` write notifies `selected`, `selected-item`, `model` — in that order, and
+     *     ALL THREE even when `selected` ends on the value it already had;
+     *   - a `selected` write notifies `selected`, then `selected-item`;
+     *   - an `items-changed` on the HELD model notifies `selected-item` BEFORE `selected`.
+     *
+     * The third is the inverse of the second, which is why no single rule is written here.
+     */
+    subscribeNotify(listener: ComboNotifyListener): () => void;
     /**
      * Subscribe to MODEL changes — `Gio.ListModel::items-changed`, one splice per
      * {@link setModel}. Returns an unsubscribe function.
@@ -78,61 +150,112 @@ export declare class ComboState {
      */
     subscribeItems(listener: ComboItemsListener): () => void;
     private _emit;
+    /** Deliver one `notify::`, snapshotted for the reason `_emit` states. */
+    private _notify;
+    /** Deliver one `items-changed`, snapshotted for the reason `_emit` states. */
+    private _emitItems;
     private _setIndex;
     /**
-     * The list model — `Adw.ComboRow:model` / `Gtk.DropDown:model`, in portable form.
+     * The list model — `Adw.ComboRow:model` / `Gtk.DropDown:model`, by IDENTITY.
      *
-     * A COPY, items included, and that is load-bearing rather than defensive. The splice
-     * (ADR 0046) decides what changed by COMPARING the assigned model against the stored
-     * one, so anything that leaks a reference into `_options` makes the comparison read the
-     * new value on both sides and answer "nothing changed". Handing back `_options` itself
-     * did exactly that, and it turned a pattern that WORKED under the old full rebuild into
-     * a silent no-op:
+     * The OBJECT that was assigned, never a copy and never a snapshot of its items: ADR 0122
+     * § 4 makes `model` an object-kind property over a real `Gio.ListModel`, and `row.model
+     * === model` is measured to hold in libadwaita. The copy this getter used to hand back
+     * belonged to the Array era, where the model WAS its items and the splice was computed by
+     * comparing two arrays — which made `const m = row.model; m.push(x); row.model = m` a
+     * silent no-op the copy existed to prevent. A live model has no such round trip: items go
+     * in through the model's own API, and it says so itself with `items-changed`.
      *
-     * ```ts
-     * const m = row.model; m.push(item); row.model = m;   // → no splice, DOM unchanged
-     * ```
+     * The normalised `{ value, label }` descriptors moved to {@link options}, which is what a
+     * renderer drawing the list wants and is still a copy.
+     */
+    get model(): ComboWatchableModel | null;
+    /**
+     * The held model's items as the normalised `{ value, label }` descriptors (ADR 0046's item
+     * vocabulary), re-read whenever the model says it changed.
      *
-     * Fresh items and not just a fresh array, because the same failure sits one level down:
-     * `m[0].label = 'x'` through a shared descriptor mutates the stored one too, and the
-     * comparison is by BOTH halves. A frozen item would have made the mutation loud; a copy
-     * makes the round trip CORRECT, which is the difference between documenting the hazard
-     * and removing it.
+     * A COPY, items included, for the reason the cache exists: `_options` is what every label
+     * lookup on this class reads, so a caller that retained it and mutated an item would move
+     * the row's inline text without the model knowing. The copy is what keeps the model the
+     * single source — mutate the MODEL and the descriptors follow, which is the whole point of
+     * holding one.
      *
      * Cost, MEASURED rather than assumed (Node 24.19, `{value,label}` records): linear, about
      * four nanoseconds per item — so a read is well under a microsecond at every size a combo
-     * row actually holds, and the assignment beside it already costs more. What the shape
-     * rules out is a per-item read: the three call sites that had one — `_applyItemsChanged`
-     * in each browser selector and `_filter` in `<gtk-drop-down>`, which runs per row per
-     * keystroke — hoist it out of their loop, so a read is O(n) once per operation instead of
-     * O(n²). Nothing reads it per frame. A model large enough for the linear term to matter is
-     * a `Gtk.ListView` and belongs to `ListController`'s virtualisation, which ADR 0046 § 7
-     * keeps out of this class on purpose.
-     */
-    get model(): AdwComboOption[];
-    /**
-     * Replace the model: emit the splice that turns the old one into the new
-     * ({@link subscribeItems}), then notify the SELECTION (`interactive: false`) so the
-     * renderer re-syncs the inline value label — which may change even at an unchanged
-     * index, because the label is read out of the model.
-     *
-     * Replacing the model re-runs autoselect ({@link clampListSelection}), so an index the
-     * new one does not have falls back to 0 — including the sentinel, which is how a row
-     * recovers a selection when its model grows. An EMPTY model has no 0 to fall back to
-     * and lands on {@link ADW_COMBO_NO_SELECTION}.
-     *
-     * The selection notify is UNCONDITIONAL while the splice is not: an assignment of an
-     * equal model emits no `items-changed` (GTK emits none either) but still re-runs the
-     * label sync, because that is the behaviour every renderer has depended on since this
-     * class existed and nothing measured says it is wrong.
-     */
-    setModel(model: AdwComboOption[]): void;
-    /**
-     * The selected option index, or {@link ADW_COMBO_NO_SELECTION}. May also sit PAST the
-     * options length: {@link setSelectedIndex} is deliberately permissive, mirroring a
-     * `guint` property that takes any position. {@link selectedValue} reads `''` in both
-     * cases, which is why the sentinel is what distinguishes "nothing selected" from "an
-     * empty label".
+     * row actually holds. What the shape rules out is a per-item read: the call sites that had
+     * one — `_applyItemsChanged` in each browser selector, `_filter` in `<gtk-drop-down>` which
+     * runs per row per keystroke — hoist it out of their loop, so a read is O(n) once per
+     * operation instead of O(n²). Nothing reads it per frame. A model large enough for the
+     * linear term to matter is a `Gtk.ListView` and belongs to `ListController`'s
+     * virtualisation, which ADR 0046 § 7 keeps out of this class on purpose.
+     */
+    get options(): AdwComboOption[];
+    /**
+     * The selected ITEM — `Adw.ComboRow:selected-item` / `Gtk.DropDown:selected-item`.
+     *
+     * The model's OWN item at {@link selectedIndex}, read through `get_item`, so
+     * `row.selectedItem === model.get_item(row.selectedIndex)` the way it is measured to hold
+     * in libadwaita. Not a descriptor: the item is whatever the model holds — a
+     * `GjsifyOptionObject`, a `Gtk.StringObject`, an application object — and handing back the
+     * normalised `{ value, label }` instead would make the identity comparison every
+     * `selected-item` consumer writes fail. {@link selectedValue} / {@link selectedLabel} are
+     * the descriptor side of the same question.
+     *
+     * `null` for the sentinel, for no model, and for an item the model declines to hand over.
+     */
+    get selectedItem(): unknown;
+    /**
+     * Replace the model — the `model` property write of ADR 0122 § 5.
+     *
+     * Assigning the model the state ALREADY holds does nothing at all: no splice, no selection
+     * emit, no `notify::`. Identity is the test, because identity is now what the property
+     * holds — two distinct models with equal contents are two different values of `model`, and
+     * GTK treats them that way.
+     *
+     * Otherwise the state detaches from the old model's `items-changed`, attaches to the new
+     * one's, re-reads the descriptors, and RE-RUNS AUTOSELECT: the selection lands on 0, or on
+     * {@link ADW_COMBO_NO_SELECTION} when the new model is empty. Not a clamp of the old index
+     * — measured, a replacement resets the selection to 0 even when the old index exists in the
+     * new model (`combo-probe2.js`: selected 2, new model of 3 → selected 0).
+     *
+     * The `notify::` set is measured and is NOT conditional on anything having changed: a
+     * non-null model notifies `selected`, `selected-item`, `model` in that order, even when the
+     * selection ends on the value it already had; `model = null` notifies `model` ALONE, and
+     * the selection goes to the sentinel silently.
+     *
+     * The splice ({@link subscribeItems}) is emitted first and only when the descriptors
+     * actually differ, because that channel is a renderer's instruction to move item views and
+     * an empty instruction is noise. It is NOT `Gio.ListModel::items-changed` — no model emits
+     * one when a WIDGET swaps which model it points at — it is this class telling its renderer
+     * what the swap did to the drawn list.
+     */
+    setModel(model: ComboWatchableModel | null): void;
+    /**
+     * The held model moved under us — `Gio.ListModel::items-changed`, forwarded to the
+     * renderer and then applied to the selection the way `GtkSingleSelection` applies it.
+     *
+     * Four cases, all MEASURED (`combo-probe2.js`, GJS 1.88.01 / GTK 4.22.5), and the notify
+     * ORDER here is the inverse of the `selected`-write path — `selected-item` comes FIRST,
+     * because the item under the selection changed before the index did:
+     *
+     *   - nothing selected → autoselect takes 0 as soon as the model has one, notifying
+     *     `selected-item` then `selected`;
+     *   - the change sits entirely AFTER the selection → the index still addresses the same
+     *     item, no notify at all;
+     *   - entirely BEFORE it → the item did not change, only its position did, so the index
+     *     shifts by `added - removed` and ONLY `selected` notifies;
+     *   - the change COVERS the selection → the selected item is gone, so the index clamps to
+     *     `min(position, n_items - 1)` (the sentinel for an emptied model) and `selected-item`
+     *     notifies whether or not the index moved — which is what makes a replace-in-place
+     *     (`removed: 1, added: 1` at the selection) notify `selected-item` alone.
+     */
+    private _onItemsChanged;
+    /**
+     * The selected option index, or {@link ADW_COMBO_NO_SELECTION}.
+     *
+     * Always either the sentinel or a position the model HAS: every door that writes it
+     * ({@link setSelectedIndex}, {@link select}, autoselect) refuses an index the model does
+     * not address, so this is the one place "nothing selected" is spelled.
      */
     get selectedIndex(): number;
     /**
@@ -142,7 +265,16 @@ export declare class ComboState {
      * nothing.
      */
     get presentsChooser(): boolean;
-    /** Programmatic index set — notifies `interactive: false`. Returns whether it changed. */
+    /**
+     * Programmatic index set — notifies `interactive: false`. Returns whether it changed.
+     *
+     * An index the model does not have is IGNORED, silently: no change, no notify, no error.
+     * That is measured on both widgets (`combo-probe2.js`: `selected = 5` on a model of 3, and
+     * `selected = GTK_INVALID_LIST_POSITION` on a non-empty model, each leave `selected` where
+     * it was and emit nothing). `Adw.ComboRow` forwards the position to
+     * `gtk_single_selection_set_selected`, which validates it — so this is not a renderer
+     * policy and no renderer states its own answer any more.
+     */
     setSelectedIndex(index: number): boolean;
     /** The selected option's `value`, or `''` when out of range. */
     get selectedValue(): string;
@@ -151,17 +283,13 @@ export declare class ComboState {
     /** Programmatic value set — moves the index to the first option with this `value`. No-op for an unknown value. */
     setSelectedValue(value: string): boolean;
     /**
-     * Whether `index` addresses an option that exists.
-     *
-     * The bounds arithmetic lives here; the POLICY for a programmatic out-of-range set does
-     * not, because this tree cannot settle it: `adw_combo_row_set_selected` forwards the
-     * position straight to `gtk_single_selection_set_selected` and documents
-     * `GTK_INVALID_LIST_POSITION` as a legal argument, but `refs/gtk` is EMPTY so what
-     * GtkSingleSelection does with it is not verifiable here. Each renderer therefore states
-     * its own answer against this one predicate: {@link setSelectedIndex} keeps the permissive
-     * model (an index past the end is how "nothing selected" is spelled and
-     * {@link selectedValue} reads `''`), while `<gtk-drop-down>` rejects the set, as its
-     * published `selected` docs promise.
+     * Whether `index` addresses an item the held model has.
+     *
+     * The ONE bounds predicate: {@link setSelectedIndex} and {@link select} both refuse what it
+     * refuses, so a programmatic set and a user pick agree about what is out of range. They
+     * once did not — `refs/gtk` is empty, so what `gtk_single_selection_set_selected` does with
+     * `GTK_INVALID_LIST_POSITION` was not verifiable in this tree and each renderer stated its
+     * own answer. It is now measured (see {@link setSelectedIndex}) and there is one.
      */
     hasIndex(index: number): boolean;
     /**