@gjsify/adwaita-core 0.64.13 → 0.64.14

package/lib/types/gio-menu.d.ts

@@ -1,46 +1,329 @@
-import type { AdwMenuEntryInput, AdwMenuItemInput } from './menu.js';
+import { Variant } from './glib-variant.js';
+import { GIR_TYPE, GObjectObject } from './gobject.js';
+import type { AdwMenuInput, AdwMenuTree } from './menu.js';
+/** `G_MENU_ATTRIBUTE_ACTION`. */
+export declare const MENU_ATTRIBUTE_ACTION = "action";
+/** `G_MENU_ATTRIBUTE_ACTION_NAMESPACE` — carried, and never interpreted by the port. */
+export declare const MENU_ATTRIBUTE_ACTION_NAMESPACE = "action-namespace";
+/** `G_MENU_ATTRIBUTE_ICON`. The NAME is shared with GIO even where the type diverges. */
+export declare const MENU_ATTRIBUTE_ICON = "icon";
+/** `G_MENU_ATTRIBUTE_LABEL`. */
+export declare const MENU_ATTRIBUTE_LABEL = "label";
+/** `G_MENU_ATTRIBUTE_TARGET` — the one attribute whose variant type varies by target. */
+export declare const MENU_ATTRIBUTE_TARGET = "target";
+/** `G_MENU_LINK_SECTION`. */
+export declare const MENU_LINK_SECTION = "section";
+/** `G_MENU_LINK_SUBMENU`. */
+export declare const MENU_LINK_SUBMENU = "submenu";
 /**
- * One menu item, built the way `g_menu_item_new` builds one.
+ * `G_MENU_EXPORTER_MAX_SECTION_SIZE`.
  *
- * IT IS ITSELF A PORTABLE ENTRY — `implements AdwMenuItemInput` — so `append_item` pushes
- * the instance and `normalizeMenuModel` reads its fields like any authored object. A
- * separate internal shape would need a conversion the model does not ask for.
+ * Nothing in the port enforces it and nothing should — it is a D-Bus exporter limit. It is
+ * exported so a caller reading it is handed the real number rather than `undefined`, which
+ * is the failure mode of a port that exports only the constants it happens to use itself.
+ */
+export declare const MENU_EXPORTER_MAX_SECTION_SIZE = 1000;
+/**
+ * One menu item, as `g_menu_item_new` builds one.
  *
- * Both halves are nullable, as they are in C: `g_menu_item_new(NULL, NULL)` is legal and
- * produces an item carrying neither, which {@link normalizeMenuModel} drops rather than
- * drawing an empty, unactionable row.
+ * IT IS A SNAPSHOT, and that is the measured fact a reader coming from the old `Array`
+ * version gets wrong: appending an item COPIES what it carries, so a later `set_label` on
+ * the same object does not reach the menu (`MENU_MODEL_DIVERGENCE_VECTORS`,
+ * `item-is-a-snapshot`). It is a builder for one position, not a view onto it.
+ *
+ * Both halves of the constructor are nullable, as they are in C: `g_menu_item_new(NULL,
+ * NULL)` is legal and produces an item carrying neither attribute.
  */
-export declare class GioMenuItem implements AdwMenuItemInput {
-    /** The user-visible string; ABSENT rather than `undefined` when the item has none. */
-    label?: string;
-    /** The DETAILED action name — `app.save-as`, `app.view::list` (ADR 0042 § divergence 2). */
-    action?: string;
+export declare class GioMenuItem extends GObjectObject {
+    static [GIR_TYPE]: string;
     constructor(label?: string | null, detailedAction?: string | null);
+    /** `g_menu_item_new_section` — an item whose whole content is the `section` link. */
+    static new_section(label: string | null, section: GioMenuModel): GioMenuItem;
+    /** `g_menu_item_new_submenu`. */
+    static new_submenu(label: string | null, submenu: GioMenuModel): GioMenuItem;
+    /**
+     * `g_menu_item_new_from_model` — a COPY of what the model holds at `itemIndex`.
+     *
+     * The copy is the point: this is how an item is edited at all, since a position is not
+     * addressable and {@link GioMenu.remove} plus an insert is the only way back in.
+     */
+    static new_from_model(model: GioMenuModel, itemIndex: number): GioMenuItem;
     /** `g_menu_item_set_label`. `null` REMOVES the attribute, which is what C does. */
     set_label(label: string | null): void;
-    /** `g_menu_item_set_detailed_action`, and `null` is `g_menu_item_set_action_and_target(…, NULL)`. */
+    /**
+     * `g_menu_item_set_detailed_action` — the action NAME and its target, parsed apart.
+     *
+     * The parse is why the model carries one string: `app.view::list` becomes `action` plus
+     * a `target` of the target's own type, and {@link printDetailedName} puts it back
+     * together. A malformed name is REFUSED here rather than stored — see
+     * {@link parseDetailedName} for why that is the twin's own decision and not GIO's.
+     */
     set_detailed_action(detailedAction: string | null): void;
+    /** `g_menu_item_set_action_and_target_value`; a `null` action removes the target too. */
+    set_action_and_target_value(action: string | null, target: Variant | null): void;
+    /**
+     * `g_menu_item_set_attribute_value`. `null` is a DELETE, never a stored empty value.
+     *
+     * A bare JS string is refused in GJS's own words (measured): the convenience of passing
+     * text belongs to `g_menu_item_set_attribute`, which is varargs and therefore not part
+     * of the surface a port owes.
+     */
+    set_attribute_value(name: string, value: Variant | null): void;
+    /** `g_menu_item_get_attribute_value` — see {@link GioMenuModel.get_item_attribute_value}. */
+    get_attribute_value(name: string, expectedType?: string | null): Variant | null;
+    /** `g_menu_item_set_link`. `null` removes it; any link name is legal, as in C. */
+    set_link(name: string, model: GioMenuModel | null): void;
+    /** `g_menu_item_get_link` — the INSTANCE, not a copy. */
+    get_link(name: string): GioMenuModel | null;
+    /** `g_menu_item_set_section`. */
+    set_section(section: GioMenuModel | null): void;
+    /** `g_menu_item_set_submenu`. */
+    set_submenu(submenu: GioMenuModel | null): void;
+}
+/**
+ * `Gio.MenuAttributeIter` — the attributes of one item, in insertion order.
+ *
+ * `next()` BEFORE the first read, as in C: an iterator starts before the beginning, so a
+ * loop is `while (iter.next())` and `get_name()` is only valid inside it. Only the
+ * attributes actually SET are yielded (measured: a section item carrying a heading yields
+ * `label` alone, not both link names with one empty).
+ */
+export declare class GioMenuAttributeIter extends GObjectObject {
+    static [GIR_TYPE]: string;
+    constructor(entries?: ReadonlyArray<readonly [string, Variant]>);
+    /** `g_menu_attribute_iter_next`. */
+    next(): boolean;
+    /** `g_menu_attribute_iter_get_name` — `null` outside a successful `next()`. */
+    get_name(): string | null;
+    /** `g_menu_attribute_iter_get_value`. */
+    get_value(): Variant | null;
+    /** `g_menu_attribute_iter_get_next` — the three out-arguments GJS returns as a tuple. */
+    get_next(): [boolean, string | null, Variant | null];
+}
+/** `Gio.MenuLinkIter` — the same walk over an item's links, and the value is a MODEL. */
+export declare class GioMenuLinkIter extends GObjectObject {
+    static [GIR_TYPE]: string;
+    constructor(entries?: ReadonlyArray<readonly [string, GioMenuModel]>);
+    /** `g_menu_link_iter_next`. */
+    next(): boolean;
+    /** `g_menu_link_iter_get_name`. */
+    get_name(): string | null;
+    /** `g_menu_link_iter_get_value` — the linked model itself. */
+    get_value(): GioMenuModel | null;
+    /** `g_menu_link_iter_get_next`. */
+    get_next(): [boolean, string | null, GioMenuModel | null];
+}
+/**
+ * `Gio.MenuModel` — what a `menu-model` property takes, and it cannot be constructed.
+ *
+ * `new Gio.MenuModel()` throws `Cannot instantiate abstract type GMenuModel` (measured), so
+ * this constructor refuses too: a base a caller can instantiate is a type GTK does not have,
+ * and a widget door accepting one would accept a model with no items and no way to get any.
+ *
+ * THE READS DELEGATE TO VFUNCS, as they do in C — `g_menu_model_get_n_items` calls
+ * `GMenuModelClass->get_n_items`. {@link GioMenu} is the only subclass the port ships, but a
+ * CALLER's subclass is the reason the indirection is here: a model backed by something else
+ * overrides `vfunc_get_n_items` and the public reads, `menuTree` and every renderer follow it.
+ *
+ * `items-changed` is declared HERE and inherited, which is where it is in GTK —
+ * `GObject.signal_lookup('items-changed', Gio.MenuModel.$gtype)` is non-zero (measured), and
+ * `findSignal` walks the static chain, so a `GioMenu` instance resolves it from this class.
+ */
+export declare abstract class GioMenuModel extends GObjectObject {
+    static [GIR_TYPE]: string;
+    constructor();
+    /** `g_menu_model_is_mutable`. */
+    is_mutable(): boolean;
+    /** `g_menu_model_get_n_items`. */
+    get_n_items(): number;
+    /**
+     * `g_menu_model_get_item_attribute_value`.
+     *
+     * `expectedType` is a type STRING and not a `GLib.VariantType`, which the variant subset
+     * does not have (`MENU_MODEL_DIVERGENCE_VECTORS`, `variant-type-is-a-string`). A
+     * mismatch answers `null` rather than converting or throwing, as GIO does.
+     */
+    get_item_attribute_value(itemIndex: number, attribute: string, expectedType?: string | null): Variant | null;
+    /** `g_menu_model_get_item_link` — the linked model INSTANCE, or `null`. */
+    get_item_link(itemIndex: number, link: string): GioMenuModel | null;
+    /** `g_menu_model_iterate_item_attributes`. */
+    iterate_item_attributes(itemIndex: number): GioMenuAttributeIter;
+    /** `g_menu_model_iterate_item_links`. */
+    iterate_item_links(itemIndex: number): GioMenuLinkIter;
+    /**
+     * `g_menu_model_items_changed` — PUBLIC, and it changes nothing.
+     *
+     * Measured: `model.items_changed(3, 2, 1)` emits that triple and leaves the count alone,
+     * because it is how a SUBCLASS reports a splice it made in its own storage. A lying triple
+     * is not policed, here or in GIO.
+     */
+    items_changed(position: number, removed: number, added: number): void;
+    /** `GMenuModelClass->is_mutable`; a model is immutable unless it says otherwise. */
+    vfunc_is_mutable(): boolean;
+    abstract vfunc_get_n_items(): number;
+    abstract vfunc_get_item_attribute_value(itemIndex: number, attribute: string, expectedType: string | null): Variant | null;
+    abstract vfunc_get_item_link(itemIndex: number, link: string): GioMenuModel | null;
+    abstract vfunc_iterate_item_attributes(itemIndex: number): GioMenuAttributeIter;
+    abstract vfunc_iterate_item_links(itemIndex: number): GioMenuLinkIter;
 }
 /**
- * A menu under construction — `Gio.Menu`'s four append entry points over the portable model.
+ * `Gio.Menu` — a mutable `Gio.MenuModel`, and what every menu in the port is.
  *
- * `new GioMenu()` is empty, as `g_menu_new()` is. Every `append*` puts one entry on the end,
- * and the instance IS the value a `menuModel` property takes.
+ * ONE `items-changed` PER MUTATOR, with the triple each one emits held by
+ * `MENU_MUTATOR_EMISSION_VECTORS`. The row that separates this from `Gtk.StringList`:
+ * `remove_all()` on an EMPTY menu STILL emits `(0, 0, 0)` (measured), so the no-op skip ADR
+ * 0122 § 3 is right about for a list store is wrong here, and neither {@link remove_all} nor
+ * {@link insertEntry} has one.
+ *
+ * An item is COPIED IN. `append_item(item)` takes what the item carries at that moment and a
+ * later `set_label` on the same object reaches nothing — see {@link GioMenuItem}.
  */
-export declare class GioMenu extends Array<AdwMenuEntryInput> {
-    /** `g_menu_append` — the convenience C implements as `menu_item_new` + `append_item`. */
+export declare class GioMenu extends GioMenuModel {
+    static [GIR_TYPE]: string;
+    constructor();
+    /** `g_menu_new`. */
+    static new(): GioMenu;
+    /** `g_menu_insert` — a plain item at `position`. */
+    insert(position: number, label: string | null, detailedAction?: string | null): void;
+    /** `g_menu_append`. */
     append(label: string | null, detailedAction?: string | null): void;
+    /** `g_menu_prepend`. */
+    prepend(label: string | null, detailedAction?: string | null): void;
+    /** `g_menu_insert_item` — the item's attributes and links, copied. */
+    insert_item(position: number, item: GioMenuItem): void;
     /** `g_menu_append_item`. */
     append_item(item: GioMenuItem): void;
+    /** `g_menu_prepend_item`. */
+    prepend_item(item: GioMenuItem): void;
+    /** `g_menu_insert_section` — ONE item of this menu, however many the section holds. */
+    insert_section(position: number, label: string | null, section: GioMenuModel): void;
+    /** `g_menu_append_section`. */
+    append_section(label: string | null, section: GioMenuModel): void;
+    /** `g_menu_prepend_section`. */
+    prepend_section(label: string | null, section: GioMenuModel): void;
+    /** `g_menu_insert_submenu`. */
+    insert_submenu(position: number, label: string | null, submenu: GioMenuModel): void;
+    /** `g_menu_append_submenu`. */
+    append_submenu(label: string | null, submenu: GioMenuModel): void;
+    /** `g_menu_prepend_submenu`. */
+    prepend_submenu(label: string | null, submenu: GioMenuModel): void;
+    /** `g_menu_remove` — one item, reported where it was. */
+    remove(position: number): void;
+    /**
+     * `g_menu_remove_all`.
+     *
+     * It emits on an EMPTY menu too — `(0, 0, 0)`, measured. A renderer may therefore drop
+     * every row it holds on this one emission without reading the count first.
+     */
+    remove_all(): void;
     /**
-     * `g_menu_append_section` — the `section` LINK, whose items are drawn inline with a
-     * separator rather than behind a further click.
+     * `g_menu_freeze` — a FLAG, not a lock.
      *
-     * The label is optional in C and stays optional here: a section with none is a plain
-     * group, and writing `label: null` onto the entry would be an attribute the model
-     * then has to ignore.
+     * Measured both ways: `is_mutable()` flips to false and the mutators keep working, so a
+     * twin that refused a post-freeze append would break a caller GIO lets through
+     * (`MENU_MODEL_DIVERGENCE_VECTORS`, `freeze-does-not-lock`).
      */
-    append_section(label: string | null, section: readonly AdwMenuEntryInput[]): void;
-    /** `g_menu_append_submenu` — the `submenu` LINK: a nested menu the user opens. */
-    append_submenu(label: string | null, submenu: readonly AdwMenuEntryInput[]): void;
+    freeze(): void;
+    vfunc_is_mutable(): boolean;
+    vfunc_get_n_items(): number;
+    vfunc_get_item_attribute_value(itemIndex: number, attribute: string, expectedType: string | null): Variant | null;
+    vfunc_get_item_link(itemIndex: number, link: string): GioMenuModel | null;
+    vfunc_iterate_item_attributes(itemIndex: number): GioMenuAttributeIter;
+    vfunc_iterate_item_links(itemIndex: number): GioMenuLinkIter;
+    /** The one insert, so the emission rule is written once. Out of range clamps, as C does. */
+    private insertEntry;
 }
+/**
+ * An authored or normalised menu TREE as a live {@link GioMenu} — the one-way street.
+ *
+ * It takes the AUTHORED form as well as the normalised one because `normalizeMenuModel` is
+ * idempotent, so a JSX attribute needs no conversion step of its own. This is the only way
+ * an array becomes a model now that `menuModel` refuses one: ADR 0128 § 4 closed the door
+ * and this is the door's replacement, named so a caller can find it.
+ */
+export declare function buildMenu(input: AdwMenuInput | AdwMenuTree): GioMenu;
+/**
+ * A `Gio.MenuModel` as a portable TREE — the inverse of {@link buildMenu}.
+ *
+ * THIS IS THE ONE BRIDGE every renderer crosses, and it crosses it ONCE PER RENDER. The
+ * tree walkers (`menuNodeAt`, `flattenMenu`, `menuRefusals`, `assertMenuRenderable`) all take
+ * an `AdwMenuTree` rather than a model, because a walker reading through the model would make
+ * every path lookup a chain of `get_item_link` calls and every renderer's loop a different
+ * number of them. One snapshot, then plain data.
+ *
+ * IT IS A DEEP SNAPSHOT, which is the measured behaviour and not a convenience: an item read
+ * out of a `Gio.Menu` is a copy (`MENU_MODEL_DIVERGENCE_VECTORS`, `item-is-a-snapshot`), so a
+ * tree that aliased the model would promise a sharing GIO does not do. A mutation arrives
+ * through `items-changed` and the renderer takes a new snapshot — see {@link watchMenuModel}.
+ *
+ * It reads what GTK reads plus `id`, so an application's own extra attributes do not survive
+ * the trip. Stated rather than implied: this is the inverse of the builder above, not a
+ * general `GMenuModel` serialiser. Both edges a hand-built menu can reach are GTK's own: an
+ * item carrying BOTH links reads as a SECTION (`gtkmenutracker.c:317-352` decides the same
+ * way), and a non-string `label` reads as `''` (so does `g_menu_item_get_attribute(…, "&s")`).
+ */
+export declare function menuTree(model: GioMenuModel): AdwMenuTree;
+/**
+ * Connect `handler` to `model` and to every model it LINKS TO, recursively.
+ *
+ * THIS IS WHY IT EXISTS: a section's own `items-changed` does NOT bubble to the menu holding
+ * it (measured — `MENU_LINK_VECTORS`, `link-emission-does-not-bubble`), while the link read
+ * reflects the change at once. A renderer connected to the root alone therefore shows a stale
+ * section for ever. The defect was unreachable while a menu was an array, because every
+ * mutation went through a re-parse of the whole tree; it arrives WITH the real model, so the
+ * watcher arrives with it.
+ *
+ * The returned function disconnects every handler it made. It is RE-RUN on each emission by
+ * its caller — a renderer calls `watchMenuModel` again after it re-snapshots — because a
+ * mutation can add a link that was not there to connect to.
+ */
+export declare function watchMenuModel(model: GioMenuModel, handler: () => void): () => void;
+/**
+ * The menu a SURFACE owns, so an authored `menuModel` attribute keeps its identity.
+ *
+ * ONE instance per element, re-parsed INTO rather than replaced: a `menu-model` write notifies
+ * and rebuilds the popover, while an edit to the same `menu='[…]'` attribute is a content
+ * change the popover already open should follow. Mirrors `GjsifyOptionList` (ADR 0122 § 5),
+ * and it is the same reason — the authored door is the one place the port, not GIO, decides.
+ */
+export declare class GjsifyMenu extends GioMenu {
+    /**
+     * Replace the contents with `next` IN PLACE, keeping this menu's identity.
+     *
+     * EQUAL CONTENT EMITS NOTHING, so re-rendering an unchanged attribute does not reopen a
+     * popover; anything else is ONE `items-changed(0, old, new)`. Not the minimal splice
+     * `GjsifyOptionList` computes: a menu is a TREE, so "the one splice that turns one into
+     * the other" is not a position and a length, and a renderer re-snapshots the whole tree
+     * on any emission anyway ({@link menuTree}).
+     */
+    reconcile(next: AdwMenuInput | AdwMenuTree | null | undefined): void;
+}
+/**
+ * What a write to a `menu-model` property reads as — the ONE door, for all four surfaces.
+ *
+ * ADR 0128 § 4 makes `menu-model` an object property over `Gio.MenuModel` and § 7 leaves the
+ * JSON markup attribute open, so every `menuModel` setter in this repository has the same
+ * four-way answer to give. It is written here once because it was about to be written fifteen
+ * times, and it mirrors `readModelWrite` (`option-list.ts`) deliberately — the two doors
+ * answer the same question about two different models, and a reader who knows one knows this.
+ *
+ *   - `null` / `undefined` is the "no menu" write, which clears the popover;
+ *   - a STRING is the markup attribute, parsed and reconciled into `authored` — the surface's
+ *     OWN menu, whose identity survives the edit;
+ *   - a real model is handed through by IDENTITY, so `widget.menuModel === model` holds as it
+ *     is measured to in libadwaita;
+ *   - anything else, an ARRAY above all, is a `TypeError`.
+ *
+ * THE DUCK TEST, and not `instanceof` alone, because a REAL `Gio.Menu` reached through node-gi
+ * (ADR 0104) is no registered class of this subset — and handing one to `Gtk.MenuButton`
+ * is the whole point of having the property.
+ *
+ * THE TYPE REFUSAL IS THE PORT'S OWN, which is the one place this door is wider than
+ * `checkPropertyValue`. A `TYPE_OBJECT` spec catches a non-object and an unregistered object,
+ * and that is all it can catch: `G_TYPE_OBJECT` accepts ANY GObject, so a registered
+ * `Gtk.StringList` passes the value check and still cannot be a menu. GJS raises
+ * `Object is of type … - cannot convert to GMenuModel` at the GValue conversion that follows
+ * (measured with a `Gtk.Label`); the subset has no such conversion, so the message is raised
+ * here, with the GType found by walking the constructor chain.
+ */
+export declare function readMenuModelWrite(value: unknown, authored: GjsifyMenu): GioMenuModel | null;

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

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

package/lib/types/index.d.ts

@@ -97,14 +97,14 @@ export { ADW_SWIPE_BORDER, DEFAULT_MAX_SIDEBAR_WIDTH, DEFAULT_MIN_SIDEBAR_WIDTH,
 export type { AdwPackType, AdwTextDirection, NavigationActionInput, NavigationActionResult, NavigationPageRef, NavigationSplitViewChange, NavigationSplitViewHandlers, NavigationSplitViewLayout, NavigationSplitViewListener, NavigationSplitViewOptions, NavigationSplitViewProperty, NavigationStackPlan, OverlaySplitViewChange, OverlaySplitViewLayout, OverlaySplitViewListener, OverlaySplitViewOptions, OverlaySplitViewProperty, SidebarBounds, SidebarWidthInput, SidebarWidthSpec, SplitViewAnimation, SplitViewAnimationRequest, SplitViewAnimator, SplitViewMeasureInput, SplitViewPane, SplitViewPaneRect, SwipeReleasePlan, } from './split-view.js';
 export { DEFAULT_DROPDOWN_TOOLTIP, SPLIT_BUTTON_DISABLED_OPACITY, SplitButtonState, isSplitButtonDirection, menuButtonArrowIcon, menuButtonPopupDirection, resolveDropdownTooltip, splitButtonArrowIcon, splitButtonPopupDirection, splitButtonRootState, splitButtonStyleClasses, } from './split-button.js';
 export type { AdwArrowIcon, SplitButtonChange, SplitButtonContentMode, SplitButtonDirection, SplitButtonHalfState, SplitButtonListener, SplitButtonProperty, SplitButtonStyleClass, } from './split-button.js';
-export { GioMenu, GioMenuItem } from './gio-menu.js';
+export { GioMenu, GioMenuAttributeIter, GioMenuItem, GioMenuLinkIter, GioMenuModel, GjsifyMenu, MENU_ATTRIBUTE_ACTION, MENU_ATTRIBUTE_ACTION_NAMESPACE, MENU_ATTRIBUTE_ICON, MENU_ATTRIBUTE_LABEL, MENU_ATTRIBUTE_TARGET, MENU_EXPORTER_MAX_SECTION_SIZE, MENU_LINK_SECTION, MENU_LINK_SUBMENU, buildMenu, menuTree, readMenuModelWrite, watchMenuModel, } from './gio-menu.js';
 export { activateMenuItem, menuActionsFor } from './menu-actions.js';
 export { assertPopupMenuPlan, planPopupMenu } from './popup-menu-plan.js';
 export type { PopupMenuEntryPlan, PopupMenuGroupPlan, PopupMenuItemPlan, PopupMenuLevelPlan, PopupMenuPlan, PopupMenuRefusal, PopupMenuSubmenuPlan, } from './popup-menu-plan.js';
 export { menuAssignments } from './menu-tree.js';
 export type { MenuTreeNode } from './menu-tree.js';
 export { ADW_MENU_SURFACE_NATIVESCRIPT, ADW_MENU_SURFACE_WEB, assertMenuRenderable, flattenMenu, menuItemAt, menuLabelText, menuNodeAt, menuRefusals, normalizeMenuModel, parseDetailedAction, parseMenuModel, resolveMenuItemState, } from './menu.js';
-export type { AdwDetailedAction, AdwMenuAction, AdwMenuActions, AdwMenuDisplayHint, AdwMenuEntryInput, AdwMenuFlatRow, AdwMenuHiddenWhen, AdwMenuInput, AdwMenuItem, AdwMenuItemInput, AdwMenuItemRole, AdwMenuItemState, AdwMenuModel, AdwMenuNode, AdwMenuPath, AdwMenuRefusal, AdwMenuSection, AdwMenuSectionInput, AdwMenuSubmenu, AdwMenuSubmenuInput, AdwMenuSurface, AdwMenuTextDirection, } from './menu.js';
+export type { AdwDetailedAction, AdwMenuAction, AdwMenuActions, AdwMenuDisplayHint, AdwMenuEntryInput, AdwMenuFlatRow, AdwMenuHiddenWhen, AdwMenuInput, AdwMenuItem, AdwMenuItemInput, AdwMenuItemRole, AdwMenuItemState, AdwMenuModel, AdwMenuNode, AdwMenuPath, AdwMenuRefusal, AdwMenuSection, AdwMenuSectionInput, AdwMenuSubmenu, AdwMenuSubmenuInput, AdwMenuSurface, AdwMenuTextDirection, AdwMenuTree, } from './menu.js';
 export { DEFAULT_INDICATOR_DESCRIPTION_STRINGS, INLINE_VIEW_SWITCHER_DISPLAY_MODES, VIEW_SWITCHER_BADGE_LIMIT, VIEW_SWITCHER_DRAG_SWITCH_DELAY, VIEW_SWITCHER_FALLBACK_ICON, VIEW_SWITCHER_NO_SELECTION, VIEW_SWITCHER_POLICIES, ViewSwitcherBarState, ViewSwitcherDragSwitch, ViewSwitcherState, buildInlineToggles, buildViewSwitcherButtons, createViewSwitcherPage, inlineToggleTooltip, isInlineViewSwitcherDisplayMode, isViewSwitcherButtonVisible, isViewSwitcherPolicy, pageIndexForToggle, shouldRevealViewSwitcherBar, stripMnemonic, toggleIndexForPage, viewSwitcherBadgeLabel, viewSwitcherButtonOrientation, viewSwitcherIconName, viewSwitcherIndicatorDescription, viewSwitcherLabel, viewSwitcherPageFromStackPage, viewSwitcherPagesFromStack, viewSwitcherSidebarSections, } from './view-switcher.js';
 export type { AdwInlineViewSwitcherDisplayMode, AdwViewSwitcherPage, AdwViewSwitcherPageInit, AdwViewSwitcherPolicy, IndicatorDescriptionStrings, InlineToggleModel, ViewSwitcherBarChange, ViewSwitcherBarListener, ViewSwitcherButtonModel, ViewSwitcherDragSwitchOptions, ViewSwitcherScheduler, ViewSwitcherSidebarSection, ViewSwitcherStateChange, ViewSwitcherStateListener, ViewSwitcherStateOptions, ViewSwitcherTimerHandle, } from './view-switcher.js';
 export { DEFAULT_TAB_AUTOHIDE, TabViewState, isDescendantOfPage, successorAfterClose, tabCloseVisible, tabIconState, tabSearchMatches, tabTooltip, tabTooltipIsMarkup, tabViewItemsChanged, tabsRevealed, } from './tab-view.js';

package/lib/types/menu-actions.d.ts

@@ -1,13 +1,13 @@
-import type { AdwMenuActions, AdwMenuModel, AdwMenuItem } from './menu.js';
+import type { AdwMenuActions, AdwMenuItem, AdwMenuTree } from './menu.js';
 type Parent = (node: object) => object | null | undefined;
 /**
- * The actions the model's items name, as `widget` resolves them. An action the walk does not find,
+ * The actions the tree's items name, as `widget` resolves them. An action the walk does not find,
  * because no group has its prefix or the group lacks it, is left out, which is "missing" and makes
  * the item insensitive. That is GTK's answer, measured on GJS (`menu-actions.gjs.spec.ts`), and it
  * overrules ADR 0097 § 3's "no group dims nothing": an application that dispatches an action
  * itself declares it, or passes `actions` to say what it knows.
  */
-export declare function menuActionsFor(model: AdwMenuModel, widget: object, parent: Parent): AdwMenuActions;
+export declare function menuActionsFor(tree: AdwMenuTree, widget: object, parent: Parent): AdwMenuActions;
 /**
  * Fire the action an item names, the way `GtkMenuTrackerItem` does on activation. A target is
  * passed as its text: `GLib.Variant` is outside the subset until stage 3.

package/lib/types/menu-tree.d.ts

@@ -1,4 +1,4 @@
-import type { AdwMenuModel } from './menu.js';
+import type { AdwMenuTree } from './menu.js';
 /** The slice of a tree node this reads. */
 export interface MenuTreeNode {
     readonly tag: string;
@@ -6,7 +6,7 @@ export interface MenuTreeNode {
     readonly menuModels?: Readonly<Record<string, readonly unknown[]>>;
 }
 /**
- * The menus a node assigns, as `[property, model]`: the root menu `menu-model: id` names, and each
- * model written at a property. An id with no root menu is refused by name.
+ * The menus a node assigns, as `[property, tree]`: the root menu `menu-model: id` names, and each
+ * tree written at a property. An id with no root menu is refused by name.
  */
-export declare function menuAssignments(node: MenuTreeNode, menus: Readonly<Record<string, readonly unknown[]>> | undefined): Array<[string, AdwMenuModel]>;
+export declare function menuAssignments(node: MenuTreeNode, menus: Readonly<Record<string, readonly unknown[]>> | undefined): Array<[string, AdwMenuTree]>;

package/lib/types/menu.d.ts

@@ -1,3 +1,4 @@
+import type { GioMenuModel } from './gio-menu.js';
 /**
  * The values `hidden-when` is documented to take.
  *
@@ -91,12 +92,28 @@ export interface AdwMenuSubmenu {
 /** 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.
+ * A normalised menu TREE: 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.
+ *
+ * IT IS NOT {@link AdwMenuModel} ANY MORE, and that split is ADR 0128. A menu MODEL is a
+ * `Gio.MenuModel` — the object a `menu-model` property takes, which emits `items-changed`
+ * and which the two widgets declare `value_type=GMenuModel` for. A menu TREE is the plain
+ * data the model is built from and snapshotted back into: `normalizeMenuModel` produces
+ * one, `buildMenu` turns one into a model, `menuTree` takes one out of a model, and every
+ * walker below takes one. The old name meant both, which is exactly what made
+ * `menuModel: [...]` and `menuModel: menu` look like the same write.
+ */
+export type AdwMenuTree = readonly AdwMenuNode[];
+/**
+ * A menu model — `Gio.MenuModel`, re-exported under the name the port's surfaces use.
+ *
+ * The alias and not a direct import, because `menuModel` is the PROPERTY on fifteen
+ * widgets and `AdwMenuModel` is the name their signatures have always read; what changed
+ * is what the name means. See {@link AdwMenuTree} for the half that is still plain data.
  */
-export type AdwMenuModel = readonly AdwMenuNode[];
+export type AdwMenuModel = GioMenuModel;
 /** An item as authored — `kind` is implied by the absence of a link. */
 export interface AdwMenuItemInput {
     label?: unknown;
@@ -151,7 +168,7 @@ export type AdwMenuInput = readonly AdwMenuEntryInput[];
  * 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;
+export declare function normalizeMenuModel(input: AdwMenuInput | null | undefined): AdwMenuTree;
 /**
  * A `menu` ATTRIBUTE — a JSON array — as a model.
  *
@@ -159,7 +176,7 @@ export declare function normalizeMenuModel(input: AdwMenuInput | null | undefine
  * 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;
+export declare function parseMenuModel(json: string | null | undefined): AdwMenuTree;
 /**
  * Where a node sits: the index chain from the model's root.
  *
@@ -171,9 +188,9 @@ export declare function parseMenuModel(json: string | null | undefined): AdwMenu
  */
 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;
+export declare function menuNodeAt(tree: AdwMenuTree, 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;
+export declare function menuItemAt(tree: AdwMenuTree, 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}. */
@@ -204,7 +221,7 @@ export interface AdwMenuFlatRow {
  * `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[];
+export declare function flattenMenu(tree: AdwMenuTree, 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. */
@@ -366,9 +383,9 @@ export interface AdwMenuRefusal {
  * 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[];
+export declare function menuRefusals(tree: AdwMenuTree, surface: AdwMenuSurface, path?: AdwMenuPath): AdwMenuRefusal[];
 /**
- * Throw if the surface cannot render the model.
+ * Throw if the surface cannot render the menu TREE.
  *
  * 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,
@@ -376,4 +393,4 @@ export declare function menuRefusals(model: AdwMenuModel, surface: AdwMenuSurfac
  * 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;
+export declare function assertMenuRenderable(tree: AdwMenuTree, surface: AdwMenuSurface): void;

package/lib/types/popup-menu-plan.d.ts

@@ -1,4 +1,4 @@
-import type { AdwMenuActions, AdwMenuModel, AdwMenuPath } from './menu.js';
+import type { AdwMenuActions, AdwMenuPath, AdwMenuTree } from './menu.js';
 /** An item of the plan; `path` maps a tap back to the model. */
 export interface PopupMenuItemPlan {
     readonly kind: 'item';
@@ -41,7 +41,7 @@ export interface PopupMenuPlan {
     readonly level: PopupMenuLevelPlan;
     readonly refusals: readonly PopupMenuRefusal[];
 }
-/** Lower `model` for `PopupMenu`. `actions` is what {@link resolveMenuItemState} reads. */
-export declare function planPopupMenu(model: AdwMenuModel, actions?: AdwMenuActions): PopupMenuPlan;
+/** Lower `tree` for `PopupMenu`. `actions` is what {@link resolveMenuItemState} reads. */
+export declare function planPopupMenu(tree: AdwMenuTree, actions?: AdwMenuActions): PopupMenuPlan;
 /** Throw naming every refusal, as `assertMenuRenderable` does for the sheet. */
 export declare function assertPopupMenuPlan(plan: PopupMenuPlan): void;

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

@@ -1,4 +1,4 @@
-import type { AdwMenuInput, AdwMenuItem, AdwMenuModel, AdwMenuPath } from './menu.js';
+import type { AdwMenuItem, AdwMenuModel, AdwMenuPath } from './menu.js';
 /**
  * The four mutually exclusive content slots of the action half. `'empty'` is the
  * initial state — `label`, `icon-name` and `child` are all `NULL`.
@@ -190,28 +190,23 @@ export declare class SplitButtonState {
      * PROPERTY lives here; the `_S` → underlined-S derivation belongs to `GtkLabel`.
      */
     setUseUnderline(value: boolean): boolean;
-    /** The menu model, or `null` when none is set. Always normalised (ADR 0042). */
+    /** The menu model, or `null` when none is set. */
     get menuModel(): AdwMenuModel | null;
     /**
      * Set the menu model, dissociating any popover and replacing it with the model-derived
      * one.
      *
-     * NORMALISES AT THE DOOR, so every surface stores the same shape whatever it was
-     * handed — a JSON attribute, a bare `string[]`, a JSX array of descriptors. It is
-     * {@link normalizeMenuModel}'s idempotence that makes `setMenuModel(state.menuModel)`
-     * a no-op rather than a quiet flattening.
-     *
-     * DELIBERATE NORMALISATION: an EMPTY list is stored as "no menu model". C can hold a
-     * non-`NULL` but empty `GMenu`, which leaves the dropdown live and pops up an empty
-     * popover; collapsing the two is what makes "no menu ⇒ insensitive dropdown" hold
-     * from a renderer's point of view. A model that is non-empty but draws nothing — one
-     * empty section — is NOT collapsed: it has a node, so it is a menu, which is the
-     * answer GTK gives for the same `GMenu`.
+     * `null` is the ONLY spelling of "no menu" (ADR 0128). MEASURED: an empty but
+     * non-`NULL` `Gio.Menu` written at `Adw.SplitButton.menu-model` still builds a
+     * `GtkPopoverMenu`, so the dropdown is live and pops up an empty popover. While the
+     * port's menu was an array this class had to collapse `[]` onto "no menu" — an array
+     * cannot be both empty and present — and that collapse was a divergence. A real model
+     * can be empty, so the collapse is gone.
      *
      * Notifies both properties per {@link DROPDOWN_NOTIFY_ORDER}; the guard is on the
      * menu model ALONE, so clearing it on a popover-only button emits nothing.
      */
-    setMenuModel(input: AdwMenuInput | null | undefined): boolean;
+    setMenuModel(next: AdwMenuModel | null): boolean;
     /** The popover: the one the app set, or the model-derived stand-in, or `null`. */
     get popover(): object | null;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/adwaita-core",
-    "version": "0.64.13",
+    "version": "0.64.14",
     "description": "Headless Adwaita widget behavior (breakpoint condition grammar + apply/unapply state machine, color-scheme observable, avatar derivation) shared by the web and NativeScript Adwaita renderers — pure TS, no platform imports",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -67,9 +67,9 @@
         "headless"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.64.13",
+        "@gjsify/cli": "^0.64.14",
         "@gjsify/node-gi": "file:../../../packages/node-gi/node-gi",
-        "@gjsify/unit": "^0.64.13",
+        "@gjsify/unit": "^0.64.14",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },