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

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/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/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,17 @@ 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, 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 { 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';
@@ -141,7 +143,7 @@ export { ActionRegistry, SimpleAction, actionRegistryOf, activateWidgetAction, a
 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 { 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/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. */

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;