@gjsify/adwaita-core 0.47.0 → 0.49.0

package/lib/types/menu.d.ts

@@ -0,0 +1,366 @@
+/**
+ * The values `hidden-when` is documented to take.
+ *
+ * A union rather than `string` because each one has its OWN visibility rule in
+ * {@link resolveMenuItemState}; an unrecognised value is ignored by C on purpose ("this
+ * code may be running in context of a desktop shell … and should not spew criticals"),
+ * which {@link normalizeMenuModel} reproduces by dropping it.
+ */
+export type AdwMenuHiddenWhen = 'action-disabled' | 'action-missing' | 'macos-menubar';
+/** A section's `display-hint`, which asks for a row of buttons instead of a list. */
+export type AdwMenuDisplayHint = 'horizontal-buttons' | 'circular-buttons' | 'inline-buttons';
+/** A section's `text-direction`, read only when {@link AdwMenuDisplayHint} is horizontal. */
+export type AdwMenuTextDirection = 'ltr' | 'rtl' | 'none';
+/**
+ * One menu item — the attributes `GtkPopoverMenu` documents, plus `id`.
+ *
+ * `id` is OURS and has no meaning to GTK. It survives the round trip anyway, because a
+ * `GMenuModel`'s attribute space is open (`g_menu_item_set_attribute` takes any name and
+ * GTK ignores what it does not know), so carrying it is not a divergence — it is an
+ * unread attribute, exactly like an application's own. It exists because the two
+ * renderers' activation events already reported one, falling back to the label.
+ */
+export interface AdwMenuItem {
+    readonly kind: 'item';
+    /** The user-visible string. `''` for an item that has none — never `undefined`. */
+    readonly label: string;
+    /**
+     * The DETAILED action name — `app.save-as`, `app.view::list`, `win.zoom(2)`.
+     *
+     * One string rather than an action plus a target, because that is what
+     * `g_menu_item_set_detailed_action` takes and what `g_action_parse_detailed_name`
+     * can read back for every `GVariant` target type. {@link parseDetailedAction} splits
+     * it where a surface needs the halves.
+     */
+    readonly action?: string;
+    /** Symbolic icon name shown beside the label. */
+    readonly icon?: string;
+    /** Icon for the button form a `display-hint` section draws instead of a row. */
+    readonly verbIcon?: string;
+    /** Accelerator text, e.g. `<Control>s`. Display only — it binds nothing. */
+    readonly accel?: string;
+    /** When this item disappears rather than merely dimming. */
+    readonly hiddenWhen?: AdwMenuHiddenWhen;
+    /** Names an application widget the surface must host in place of a row. */
+    readonly custom?: string;
+    /** Whether {@link label} is Pango markup. */
+    readonly useMarkup?: boolean;
+    /** Stable identifier for activation reporting; defaults to {@link label}. */
+    readonly id?: string;
+}
+/**
+ * A `section` link: items drawn inline, separated from their neighbours.
+ *
+ * A section is NOT a container the user opens — it is a visual grouping, which is why a
+ * flat surface may inline it ({@link flattenMenu}) without losing an item.
+ */
+export interface AdwMenuSection {
+    readonly kind: 'section';
+    /** Optional heading above the group. */
+    readonly label?: string;
+    readonly displayHint?: AdwMenuDisplayHint;
+    readonly textDirection?: AdwMenuTextDirection;
+    readonly items: readonly AdwMenuNode[];
+}
+/**
+ * A `submenu` link: a nested menu the user opens.
+ *
+ * `submenuAction` is documented under ITEMS (`gtkpopovermenu.c:106-107`) rather than
+ * under submenus, and it is here anyway: it names the action that tracks whether the
+ * submenu is OPEN, so the only item it can sit on is the one carrying the link — which
+ * in this model IS this node. `gtkmenutrackeritem.c:822` and `:1049` read it, and both
+ * paths are submenu paths.
+ */
+export interface AdwMenuSubmenu {
+    readonly kind: 'submenu';
+    readonly label: string;
+    readonly icon?: string;
+    /** Action tracking whether this submenu is shown (`submenu-action`). */
+    readonly submenuAction?: string;
+    /**
+     * `gtk-macos-special` — macOS menu-bar meaning, ignored everywhere else
+     * (`gtkpopovermenu.c:130-131`, read at `gtkmenutrackeritem.c:761`).
+     *
+     * Carried and never acted on here: no renderer in this workspace exports a macOS
+     * menu bar. It is in the model so that a menu written for one survives the trip,
+     * which is the whole lossless claim.
+     */
+    readonly macosSpecial?: string;
+    readonly items: readonly AdwMenuNode[];
+}
+/** Any node of a normalised model. */
+export type AdwMenuNode = AdwMenuItem | AdwMenuSection | AdwMenuSubmenu;
+/**
+ * A normalised menu: the value a renderer walks and the GTK host converts.
+ *
+ * `readonly` throughout, because every renderer holds one across a render and a shared
+ * mutable tree is how two widgets showing the same menu would diverge.
+ */
+export type AdwMenuModel = readonly AdwMenuNode[];
+/** An item as authored — `kind` is implied by the absence of a link. */
+export interface AdwMenuItemInput {
+    label?: unknown;
+    action?: unknown;
+    icon?: unknown;
+    verbIcon?: unknown;
+    accel?: unknown;
+    hiddenWhen?: unknown;
+    custom?: unknown;
+    useMarkup?: unknown;
+    id?: unknown;
+}
+/** A section as authored — the `section` key IS the link. */
+export interface AdwMenuSectionInput {
+    section: readonly AdwMenuEntryInput[];
+    label?: unknown;
+    displayHint?: unknown;
+    textDirection?: unknown;
+}
+/** A submenu as authored — the `submenu` key IS the link. */
+export interface AdwMenuSubmenuInput {
+    submenu: readonly AdwMenuEntryInput[];
+    label?: unknown;
+    icon?: unknown;
+    submenuAction?: unknown;
+    macosSpecial?: unknown;
+}
+/**
+ * One authored entry.
+ *
+ * A BARE STRING is a label-only item, and that form is not a NativeScript leftover: it
+ * is the model's own shorthand, the same one {@link normalizeComboOptions} gives an
+ * option list, and it is now accepted on every surface rather than on one. What it
+ * cannot carry — an action, an icon, a section — is exactly what made
+ * `button.menu = ['Save as…']` unable to grow, so the shorthand widens INTO this union
+ * instead of standing beside it.
+ */
+export type AdwMenuEntryInput = string | AdwMenuItemInput | AdwMenuSectionInput | AdwMenuSubmenuInput;
+/** A menu as authored, before {@link normalizeMenuModel} has seen it. */
+export type AdwMenuInput = readonly AdwMenuEntryInput[];
+/**
+ * Authored entries → the normalised model every renderer walks.
+ *
+ * TOTAL BY CONSTRUCTION. The input reaches this function from author-written markup (a
+ * JSON attribute, an XML attribute, a JSX expression), and a typo must not take the
+ * widget down with it — the same rule the `menu` attribute parser it replaces already
+ * had. So an unusable entry is DROPPED and an unusable attribute is omitted; nothing
+ * here throws. The loud half is {@link assertMenuRenderable}, which runs against a
+ * SURFACE and can therefore say something true about what will not be drawn.
+ *
+ * A link wins over the attributes beside it: `{ label: 'More', submenu: [...] }` is a
+ * submenu with a label, never an item that happens to carry a list, because that is how
+ * `g_menu_item_get_link` reads the same object.
+ */
+export declare function normalizeMenuModel(input: AdwMenuInput | null | undefined): AdwMenuModel;
+/**
+ * A `menu` ATTRIBUTE — a JSON array — as a model.
+ *
+ * Total for the same reason {@link normalizeMenuModel} is, and it adds the one failure
+ * markup can produce that a JS value cannot: `JSON.parse` genuinely throws on a typo,
+ * and the widget must degrade to "no menu" rather than fail to upgrade.
+ */
+export declare function parseMenuModel(json: string | null | undefined): AdwMenuModel;
+/**
+ * Where a node sits: the index chain from the model's root.
+ *
+ * A `GMenuModel` addresses its items BY POSITION and a link is a model of its own, so a
+ * position inside a submenu is only meaningful together with the positions above it.
+ * Resolving a choice by LABEL instead silently dispatches the first of two identically
+ * named entries — the defect the split button's activation vectors already pin down, one
+ * level deeper now that a menu can nest.
+ */
+export type AdwMenuPath = readonly number[];
+/** The node at a path, or `null` when the path names none. */
+export declare function menuNodeAt(model: AdwMenuModel, path: AdwMenuPath): AdwMenuNode | null;
+/** The item at a path — `null` for a path that names a section, a submenu or nothing. */
+export declare function menuItemAt(model: AdwMenuModel, path: AdwMenuPath): AdwMenuItem | null;
+/** One row of a {@link flattenMenu} walk. */
+export interface AdwMenuFlatRow {
+    /** The node this row draws. Sections never appear — they become {@link separated}. */
+    readonly node: AdwMenuItem | AdwMenuSubmenu;
+    /**
+     * Where it lives, for {@link menuItemAt}.
+     *
+     * It is also the depth: `path.length` counts the links walked to reach the row.
+     * There is no separate `depth` field, because nothing would indent by it — GTK
+     * draws a section flush with its neighbours — and a field only its own vectors read
+     * is a claim nothing holds.
+     */
+    readonly path: AdwMenuPath;
+    /** Whether a separator belongs above this row — a section boundary. */
+    readonly separated: boolean;
+}
+/**
+ * ONE LEVEL of a model as the ordered rows a list draws.
+ *
+ * SECTIONS ARE INLINED, SUBMENUS ARE NOT, and that asymmetry is `GMenuModel`'s own: a
+ * section is a visual grouping that `GtkPopoverMenu` itself draws inline with a
+ * separator, so inlining it loses a rule and no item; a submenu is a menu the user
+ * OPENS, so inlining it would put its items where they were never offered. A submenu
+ * row therefore stays a row, and a surface shows its contents by flattening THAT node's
+ * `items` when the user asks — a second popover page on the web, a second sheet on
+ * NativeScript. {@link AdwMenuFlatRow.path} is what makes the second call addressable.
+ *
+ * `separated` marks the FIRST row after a boundary and is never set on the first row of
+ * all, because a separator above nothing is a line at the top of the menu.
+ */
+export declare function flattenMenu(model: AdwMenuModel, path?: AdwMenuPath): readonly AdwMenuFlatRow[];
+/** What a `GActionGroup` publishes about one action, in portable form. */
+export interface AdwMenuAction {
+    /** `g_action_group_get_action_enabled`. Absent counts as enabled. */
+    readonly enabled?: boolean;
+    /**
+     * `g_action_group_get_action_state`, as its CONTENT in text: `true`/`false` for a
+     * toggle, `list` for a radio whose targets are strings.
+     *
+     * NOT the `GVariant` TEXT form, which would quote the string —
+     * `GLib.Variant.new_string('list').print(false)` is `'list'`, with the quotes. A
+     * consumer bridging a real `GActionGroup` writes `state.get_string()[0]` for a
+     * string and `String(state.get_boolean())` for a boolean; reading `print(false)`
+     * instead is what makes every radio row render OFF, because the target it is
+     * compared against ({@link AdwDetailedAction.target}) is unquoted too.
+     */
+    readonly state?: string;
+}
+/**
+ * The actions a surface knows about — the portable stand-in for a `GActionGroup`.
+ *
+ * Keyed by the action's own name, prefix included (`app.save-as`), which is the key a
+ * detailed action name yields. An action ABSENT from the map is missing, not disabled,
+ * and the two differ: `hidden-when="action-missing"` hides one and shows the other.
+ *
+ * NO MAP AT ALL IS A THIRD THING, and the distinction is load-bearing rather than
+ * pedantic: `{}` is a group that knows no actions, so every item in it is insensitive;
+ * `undefined` is a surface with no action group to consult, so nothing is known and
+ * nothing is dimmed. MEASURED — collapsing the two made every actioned item in the
+ * browser renderer arrive `disabled`, because the common case is a menu whose actions
+ * the host dispatches itself and never declares.
+ */
+export type AdwMenuActions = Readonly<Record<string, AdwMenuAction>>;
+/** `GtkMenuTrackerItemRole`. */
+export type AdwMenuItemRole = 'normal' | 'check' | 'radio';
+/** What an item's action makes of it. */
+export interface AdwMenuItemState {
+    /** `GTK_STATE_FLAG_INSENSITIVE`'s inverse — the action's `enabled`. */
+    readonly sensitive: boolean;
+    /** Whether the check/radio decoration is drawn. */
+    readonly toggled: boolean;
+    readonly role: AdwMenuItemRole;
+    /** Whether the item is drawn at all — `hidden-when`, folded. */
+    readonly visible: boolean;
+}
+/** An action name and the target text beside it. */
+export interface AdwDetailedAction {
+    readonly name: string;
+    /**
+     * The target's CONTENT — `list` for `app.view::list` AND for `app.view('list')`,
+     * `2` for `win.zoom(2)`.
+     *
+     * Never the `GVariant` TEXT, which would quote a string: the two spellings of the
+     * same target must compare equal, or a radio written one way and an action state
+     * read the other way disagree. MEASURED: without the unquoting,
+     * `parseDetailedAction("app.v('list')")` answered `'list'` WITH quotes and every
+     * such radio row rendered OFF against a state of `list`.
+     */
+    readonly target?: string;
+}
+/**
+ * `app.view::list` → `{ name: 'app.view', target: 'list' }`.
+ *
+ * The two forms `g_action_parse_detailed_name` accepts, and no third: `::` for a string
+ * target and `(…)` for a `GVariant` text one. A quoted `(…)` target is UNQUOTED, so
+ * `app.v::list` and `app.v('list')` — the same detailed action to GLib — yield the same
+ * target here; without that they did not, and every radio written the second way read
+ * OFF.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO is parse the `GVariant`. The target is the text
+ * between the delimiters with its quotes removed, so comparing it against an action's
+ * `state` is a STRING comparison. That is exact for the string and boolean targets a
+ * menu actually uses, and it does not canonicalise WHITESPACE: `win.zoom(2)` and
+ * `win.zoom( 2 )` name the same action to GLib and different targets here. A portable
+ * model with no `GVariant` implementation cannot close that, and pretending otherwise
+ * would be a wrong answer instead of a stated one.
+ *
+ * IT IS ALSO NOT A VALIDATOR. It never throws and answers something for every string,
+ * because it runs on the display side of a menu that has already been accepted. GIO is
+ * the authority on whether a detailed action name is legal, and `@gjsify/gtk-host`'s
+ * `buildGioMenu` asks it — see {@link AdwMenuItem.action}.
+ */
+export declare function parseDetailedAction(detailed: string | undefined): AdwDetailedAction | null;
+/**
+ * `sensitive`, `toggled`, `role` and `visible` for one item — `gtk_menu_tracker_item_*`
+ * as a pure fold.
+ *
+ * This is the whole answer to "where does a menu carry enabled and checked", and the
+ * answer is that it does not. C reads all three off the ACTION: `sensitive` is the
+ * action's `enabled` flag (c:332), `role` is RADIO when the item has a target and the
+ * action has a state (c:336-340), CHECK when the state is a boolean and there is no
+ * target (c:342-346), and `toggled` compares the two. An item with no `action` attribute
+ * at all is SENSITIVE — C sets it explicitly in the else branch
+ * (`gtkmenutrackeritem.c:594`) rather than leaving the field false, because a label with
+ * no action is not a disabled command.
+ *
+ * TWO PLACES THIS IS NOT C, both because a portable action map carries no `GVariantType`:
+ *
+ *   · `can_activate`'s TYPE check. C refuses to activate an item whose target type does
+ *     not match the action's parameter type, and that refusal feeds
+ *     `hidden-when="action-missing"`. Here "missing" means only that the action is
+ *     absent from {@link AdwMenuActions} — a present action with a mistyped target reads
+ *     as activatable where GTK would hide it.
+ *   · A boolean state is the TEXT `'true'`/`'false'`, since the state is text. A radio
+ *     whose targets are literally those two strings would therefore read as a check.
+ *     GTK tells them apart by `GVariant` type; nothing here can.
+ *
+ * `macos-menubar` hides an item only in the macOS menubar export (C guards it with
+ * `mac_os_mode`, c:534-535), which no renderer here is, so it stays visible.
+ */
+export declare function resolveMenuItemState(item: AdwMenuItem, actions?: AdwMenuActions): AdwMenuItemState;
+/**
+ * What a surface can draw.
+ *
+ * ONE CAPABILITY, because one is what actually differs in a way a reader could not
+ * otherwise see. All three surfaces nest (GTK slides a page, the browser swaps the
+ * popover's page, NativeScript opens a second sheet) and all three draw every
+ * attribute they have a place for, so a field for those would be `true` everywhere and
+ * a refusal arm nothing could ever reach — the shape this repository pays most for. A
+ * second field lands with the first surface that needs it.
+ */
+export interface AdwMenuSurface {
+    /** A name for the diagnostic — `adwaita-web`, `nativescript`. */
+    readonly name: string;
+    /** Can it host an application widget named by `custom`? Only GTK can. */
+    readonly custom: boolean;
+}
+/** The browser popover: it has no `add_child` for a `custom` item to name. */
+export declare const ADW_MENU_SURFACE_WEB: AdwMenuSurface;
+/** The NativeScript action sheet: its rows are STRINGS, so a `custom` widget has no home. */
+export declare const ADW_MENU_SURFACE_NATIVESCRIPT: AdwMenuSurface;
+/** One thing a surface will not draw, with where it is. */
+export interface AdwMenuRefusal {
+    readonly path: AdwMenuPath;
+    /** The attribute that cannot be honoured. */
+    readonly what: 'custom';
+    readonly message: string;
+}
+/**
+ * Every part of a model the surface cannot render — empty when it can render all of it.
+ *
+ * IT LISTS WHAT WOULD VANISH, NOT WHAT WOULD LOOK DIFFERENT. An icon a sheet cannot show
+ * is a decoration and the row is still there; a `custom` item is a PLACEHOLDER for an
+ * application widget, so a surface that ignores it draws a blank row where a control
+ * belongs, and the reader has no way to tell. That is the distinction the three-way
+ * split in this file's header draws, and it is why refusing everything unsupported
+ * would be useless: NativeScript renders no icon and no accelerator on any menu, so a
+ * refusal per decoration would fire on every well-formed menu and be switched off.
+ */
+export declare function menuRefusals(model: AdwMenuModel, surface: AdwMenuSurface, path?: AdwMenuPath): AdwMenuRefusal[];
+/**
+ * Throw if the surface cannot render the model.
+ *
+ * Called by a renderer when a menu is SET, so the throw names the assignment rather than
+ * arriving as a missing row three interactions later. The message carries every refusal,
+ * not the first: a menu written for GTK typically has all of its `custom` items at once,
+ * and reporting them one run at a time is how a port becomes a series of identical bug
+ * reports.
+ */
+export declare function assertMenuRenderable(model: AdwMenuModel, surface: AdwMenuSurface): void;

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

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

package/lib/types/rows.d.ts

@@ -1,3 +1,8 @@
+import type { AdwComboOption, AdwListItemsChanged } from './list.js';
+export { ADW_COMBO_NO_SELECTION, normalizeComboOptions } from './list.js';
+export type { AdwComboOption, AdwComboOptionInput } from './list.js';
+export { SpinState } from './adjustment.js';
+export type { SpinStateChange, SpinStateListener, SpinStateRangeListener } from './adjustment.js';
 /** Subscriber for {@link ExpanderState} changes — receives the new expanded flag. */
 export type ExpanderStateListener = (expanded: boolean) => void;
 /**
@@ -23,44 +28,6 @@ export declare class ExpanderState {
     /** Collapse the disclosure. Returns whether it changed. */
     collapse(): boolean;
 }
-/** One selectable option in a {@link ComboState}. */
-export interface AdwComboOption {
-    /** Display label shown in the row + chooser. */
-    label: string;
-    /** Underlying value returned by {@link ComboState.selectedValue}. */
-    value: string;
-}
-/**
- * What an author may write for one option before {@link normalizeComboOptions}
- * has seen it: a bare string (value === label, the `Gtk.StringList` case), or a
- * partial descriptor where either half may stand in for the other.
- */
-export type AdwComboOptionInput = string | {
-    value?: unknown;
-    label?: unknown;
-};
-/**
- * Raw authored options → the stable `{ value, label }` descriptors every combo surface
- * works with.
- *
- * A bare string is both value and label (`Gtk.StringList`'s model, which is what
- * `Adw.ComboRow` is fed in the common case). In a descriptor either half stands in for the
- * missing other, so `{ label: 'Apple' }` is addressable by the value `'Apple'` rather than
- * by `undefined`. ONE home for the rule, so `<adw-combo-row>` and `<gtk-drop-down>` cannot
- * accept two different option vocabularies.
- */
-export declare function normalizeComboOptions(raw: ReadonlyArray<AdwComboOptionInput> | null | undefined): AdwComboOption[];
-/**
- * The "no item is selected" index — the TS mirror of `GTK_INVALID_LIST_POSITION`
- * (`AdwComboRow:selected`'s default and empty value).
- *
- * libadwaita spells it `G_MAXUINT` because the property is a `guint`; `-1` is the idiomatic
- * TS sentinel and the spelling {@link ADW_SIDEBAR_NO_SELECTION} uses for the same GTK
- * constant. Without it, an EMPTY model and a model whose first item has an empty label are
- * indistinguishable — both report index 0 with `selectedValue === ''` — so a renderer that
- * wants to draw a placeholder has nothing to test.
- */
-export declare const ADW_COMBO_NO_SELECTION = -1;
 /** Payload of a {@link ComboState} change. */
 export interface ComboStateChange {
     /** The (new) selected index, or {@link ADW_COMBO_NO_SELECTION}. */
@@ -72,41 +39,94 @@ export interface ComboStateChange {
     /** True for a user pick ({@link ComboState.select}); false for a programmatic set. */
     interactive: boolean;
 }
-/** Subscriber for {@link ComboState} changes. */
+/** Subscriber for {@link ComboState} selection changes. */
 export type ComboStateListener = (change: ComboStateChange) => void;
+/** Subscriber for {@link ComboState} MODEL changes — one `items-changed` per replacement. */
+export type ComboItemsListener = (change: AdwListItemsChanged) => void;
 /**
- * The selection state of a combo row: an options list plus the selected index,
- * with a two-way index↔value mapping and empty/out-of-range guards. Mirrors
- * `Adw.ComboRow`: a programmatic set ({@link setSelectedIndex} / {@link setSelectedValue}
- * / {@link setOptions}) updates silently (`interactive: false` — the renderer refreshes
- * the inline value but re-emits no `notify::selected`), while {@link select} is the
- * user pick that notifies (`interactive: true`).
+ * 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.
+ * Mirrors `Adw.ComboRow`: a programmatic set ({@link setSelectedIndex} /
+ * {@link setSelectedValue} / {@link setModel}) updates silently (`interactive: false` —
+ * the renderer refreshes the inline value but re-emits no `notify::selected`), while
+ * {@link select} is the user pick that notifies (`interactive: true`).
+ *
+ * TWO SIGNALS, because they answer different questions and a renderer needs both
+ * (ADR 0046). {@link subscribe} reports the SELECTION; {@link subscribeItems} reports WHERE
+ * the model changed, so a renderer splices its item views instead of rebuilding them.
+ * `Adw.ComboRow` gets both from GTK for free — the first is `notify::selected`, the second
+ * is `Gio.ListModel::items-changed` on the model it holds — and this class had only the
+ * first, which is why both browser selectors dropped every option node on every
+ * assignment.
  */
 export declare class ComboState {
     private _options;
     private _selected;
     private readonly _listeners;
+    private readonly _itemListeners;
     /** Subscribe to selection changes. Returns an unsubscribe function. */
     subscribe(listener: ComboStateListener): () => void;
+    /**
+     * Subscribe to MODEL changes — `Gio.ListModel::items-changed`, one splice per
+     * {@link setModel}. Returns an unsubscribe function.
+     *
+     * Fires BEFORE the selection change {@link setModel} also emits, which is the order
+     * that makes it usable: the selection subscriber writes the new index into the item
+     * views, so those views have to exist by then. The rebuild path had the inverse
+     * ordering hazard written down in `<adw-combo-row>` — "AFTER the rebuild, never during
+     * it" — and this is what removes it rather than documenting it again.
+     */
+    subscribeItems(listener: ComboItemsListener): () => void;
     private _emit;
     private _setIndex;
-    /** The selectable options. */
-    get options(): AdwComboOption[];
     /**
-     * Replace the options, then notify (`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.
+     * The list model — `Adw.ComboRow:model` / `Gtk.DropDown:model`, in portable form.
+     *
+     * 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:
+     *
+     * ```ts
+     * const m = row.model; m.push(item); row.model = m;   // → no splice, DOM unchanged
+     * ```
+     *
+     * 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.
+     *
+     * 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, 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}.
+     * 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 check is `hasIndex`, 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.
+     * 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.
      */
-    setOptions(options: AdwComboOption[]): void;
+    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
@@ -157,57 +177,6 @@ export declare class ComboState {
     /** Number of options. */
     get count(): number;
 }
-/** Payload of a {@link SpinState} change. */
-export interface SpinStateChange {
-    /** The new value (already clamped to `[min, max]`). */
-    value: number;
-    /** True for a stepper press ({@link SpinState.increment}/{@link SpinState.decrement}); false for a programmatic set/re-clamp. */
-    interactive: boolean;
-}
-/** Subscriber for {@link SpinState} changes. */
-export type SpinStateListener = (change: SpinStateChange) => void;
-/**
- * The numeric adjustment state of a spin row: `value` bounded by `[min, max]` and
- * stepped by `step`. Every mutation clamps into range. Mirrors `Adw.SpinRow`: a
- * programmatic {@link setValue} (or a re-clamp from a moved {@link setMin}/{@link setMax})
- * notifies `interactive: false` (the renderer refreshes the display but re-emits no
- * `notify::value`), while {@link increment}/{@link decrement} are the stepper presses
- * that notify `interactive: true`.
- */
-export declare class SpinState {
-    private _value;
-    private _min;
-    private _max;
-    private _step;
-    private readonly _listeners;
-    /** Subscribe to value changes. Returns an unsubscribe function. */
-    subscribe(listener: SpinStateListener): () => void;
-    private _emit;
-    private _clamp;
-    private _bump;
-    /** Re-clamp the current value after a bound moved; notifies `interactive: false` on change. */
-    private _reclamp;
-    /** The current numeric value (always within `[min, max]`). */
-    get value(): number;
-    /** Lower bound. */
-    get min(): number;
-    /** Upper bound. */
-    get max(): number;
-    /** Increment/decrement step applied per stepper press. */
-    get step(): number;
-    /** Programmatic value set — clamp, notify `interactive: false` on change. Returns whether it changed. */
-    setValue(value: number): boolean;
-    /** Set the lower bound and re-clamp the value into range. Returns whether the value changed. */
-    setMin(value: number): boolean;
-    /** Set the upper bound and re-clamp the value into range. Returns whether the value changed. */
-    setMax(value: number): boolean;
-    /** Set the step. A non-positive or non-finite step falls back to `1`. */
-    setStep(value: number): void;
-    /** Step up by `step`, clamped to `max`. Notifies `interactive: true` on change. Returns whether it changed. */
-    increment(): boolean;
-    /** Step down by `step`, clamped to `min`. Notifies `interactive: true` on change. Returns whether it changed. */
-    decrement(): boolean;
-}
 /** Payload of a {@link ToggleGroupState} change. */
 export interface ToggleGroupStateChange {
     /** The newly-selected segment index. */

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

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