@gjsify/adwaita-web 0.64.13 → 0.64.15-next.287

package/src/elements/popover-menu.ts

@@ -47,7 +47,7 @@
 // Copyright (c) GNOME contributors (GTK, libadwaita). LGPLv2.1+.
 
 import { flattenMenu, menuLabelText, menuNodeAt, resolveMenuItemState } from '@gjsify/adwaita-core';
-import type { AdwMenuActions, AdwMenuItem, AdwMenuModel, AdwMenuPath } from '@gjsify/adwaita-core';
+import type { AdwMenuActions, AdwMenuItem, AdwMenuPath, AdwMenuTree } from '@gjsify/adwaita-core';
 
 import { createGtkImage } from './gtk-image.js';
 import type { GtkPopover } from './gtk-popover.js';
@@ -71,7 +71,7 @@ const BACK_LABEL = 'Back';
  * reopens three levels deep is a menu the reader cannot get out of.
  */
 export class PopoverMenuView {
-    private _model: AdwMenuModel = [];
+    private _tree: AdwMenuTree = [];
     private _actions: AdwMenuActions | null = null;
     private _title = '';
     /** The submenu whose items are showing; `[]` is the root page. */
@@ -80,7 +80,7 @@ export class PopoverMenuView {
     private _openers = new Set<HTMLElement>();
     /** The row that LEAVES a page — what ArrowLeft acts on. */
     private _backRow: HTMLElement | null = null;
-    /** The canonical text of the model showing, so an unchanged re-render keeps the page. */
+    /** The canonical text of the tree showing, so an unchanged re-render keeps the page. */
     private _key = '[]';
     private _rows: HTMLButtonElement[] = [];
 
@@ -181,24 +181,34 @@ export class PopoverMenuView {
     }
 
     /**
-     * Named for the value it takes, and NOT `setModel` — the portable LIST model gave
+     * Named for the value it takes, which since ADR 0128 is a TREE and not a model: this
+     * view never holds a `Gio.MenuModel`, it walks the snapshot its element took, and a
+     * `setMenuModel` here would name a type it has no way to read. The element is the one
+     * place that owns the model.
+     *
+     * It was `setMenuModel` for the reason the rename keeps: the portable LIST model gave
      * `ComboState` a `setModel` (ADR 0046), and two methods called `setModel` over two
      * unrelated values on one surface is the collision the vocabulary work exists to
-     * remove. It also un-blinds `check-adwaita-collection-reactivity`, which resolves a
-     * collection call by the setter's name.
+     * remove.
      */
-    setMenuModel(model: AdwMenuModel): void {
-        // A CHANGED model invalidates the open page: the submenu it named may not exist
+    setMenuTree(tree: AdwMenuTree): void {
+        // A CHANGED tree invalidates the open page: the submenu it named may not exist
         // any more, and rendering a page that is gone leaves an empty popover with a
         // back row and no way to see what happened. An UNCHANGED one must not — every
         // element re-render calls this, and resetting unconditionally shut the submenu
         // the reader had just opened.
-        const key = JSON.stringify(model);
+        //
+        // COMPARED BY VALUE, not by identity, which is the opposite of the guard
+        // `SplitButtonState.setMenuModel` has: the element's AUTHORED menu keeps its
+        // identity while its content is replaced (ADR 0128 § 5), so an identity guard
+        // here would never see an edit to a `menu-model="[…]"` attribute and would keep
+        // showing a page that is gone.
+        const key = JSON.stringify(tree);
         if (key !== this._key) {
             this._key = key;
             this._page = [];
         }
-        this._model = model;
+        this._tree = tree;
     }
 
     setActions(actions: AdwMenuActions | null): void {
@@ -215,10 +225,10 @@ export class PopoverMenuView {
     }
 
     /** The items of the page currently showing. */
-    private currentItems(): AdwMenuModel {
-        if (this._page.length === 0) return this._model;
-        const node = menuNodeAt(this._model, this._page);
-        return node !== null && node.kind !== 'item' ? node.items : this._model;
+    private currentItems(): AdwMenuTree {
+        if (this._page.length === 0) return this._tree;
+        const node = menuNodeAt(this._tree, this._page);
+        return node !== null && node.kind !== 'item' ? node.items : this._tree;
     }
 
     /** Rebuild the surface's children from the model. */
@@ -228,7 +238,7 @@ export class PopoverMenuView {
         this._openers = new Set();
         this._backRow = null;
 
-        const open = menuNodeAt(this._model, this._page);
+        const open = menuNodeAt(this._tree, this._page);
         if (this._page.length > 0 && open !== null && open.kind === 'submenu') {
             this.surface.appendChild(this.backRow(open.label));
         } else if (this._title.length > 0) {
@@ -263,7 +273,7 @@ export class PopoverMenuView {
     /** The label of the section at `path`, or `null` when it is not a labelled section. */
     private sectionHeading(path: AdwMenuPath): string | null {
         if (path.length <= this._page.length) return null;
-        const parent = menuNodeAt(this._model, path);
+        const parent = menuNodeAt(this._tree, path);
         return parent !== null && parent.kind === 'section' && parent.label !== undefined ? parent.label : null;
     }
 

package/src/gio-menu.spec.ts

@@ -1,46 +1,85 @@
-// `Gio.Menu` as an authoring door — held against the value it has to produce.
+// `Gio.Menu` as an authoring door, and the `menu-model` PROPERTY the widgets expose.
 //
-// THE CLAIM UNDER TEST is not "the class has methods": it is that a menu BUILT the GJS way
-// and the same menu WRITTEN as an array reduce to one model, so a `menuModel` property
-// cannot tell them apart. Every case below therefore asserts against
-// `normalizeMenuModel(<the array a reader would have written>)` rather than against a
+// THE CLAIM UNDER TEST in the first half is not "the class has methods": it is that a menu
+// BUILT the GJS way and the same menu WRITTEN as the portable tree reduce to one snapshot,
+// so a `menuModel` property cannot tell them apart. Every case there asserts against
+// `normalizeMenuModel(<the tree a reader would have written>)` rather than against a
 // hand-typed expectation — a hand-typed one would agree with whatever this file produces.
 //
-// The class itself lives in `@gjsify/adwaita-core`; what this file drives is the port's
-// own `Gio` DOOR onto it, so a barrel that stops resolving fails here rather than in a
-// consumer.
+// THE SECOND HALF IS WHAT THE CORE SPEC CANNOT DRIVE. ADR 0128 measured two of its tables on
+// WIDGETS and not on the model: `MENU_MODEL_DOOR_VECTORS` (what a `menu-model` write accepts
+// and the words it refuses with) and `MENU_MODEL_NOTIFY_VECTORS` (the identity guard
+// `Adw.SplitButton` has and `Gtk.MenuButton` does not). Both run against BOTH widgets here,
+// because a guard measured on one and applied to the other is the exact mistake the table
+// exists to catch: GJS notifies once for a repeated write on the split button and twice on
+// the menu button, and the asymmetry is upstream's, not a port decision.
+//
+// The classes themselves live in `@gjsify/adwaita-core`; what the first half drives is the
+// port's own `Gio` DOOR onto them, so a barrel that stops resolving fails here rather than
+// in a consumer.
 //
 // Compared as JSON rather than with `toEqual`: `@gjsify/unit`'s `toEqual` is `==`, so two
 // different objects pass it whatever they hold.
 
 import { describe, expect, it } from '@gjsify/unit';
-import { normalizeMenuModel } from '@gjsify/adwaita-core';
+import { ADW_MENU_SURFACE_WEB, buildMenu, menuTree, normalizeMenuModel } from '@gjsify/adwaita-core';
+import { MENU_MODEL_DOOR_VECTORS, MENU_MODEL_NOTIFY_VECTORS } from '@gjsify/adwaita-core/conformance';
+import type { MenuModelHolder, MenuModelWrite } from '@gjsify/adwaita-core/conformance';
+import type { AdwMenuModel, GioMenuModel } from '@gjsify/adwaita-core';
+
+import { Menu, MenuItem, MenuModel } from './namespace/gio.js';
+import { StringList } from './namespace/gtk.js';
+
+/** The snapshot a renderer reads out of a model — what every walker takes. */
+const treeOf = (model: GioMenuModel) => JSON.stringify(menuTree(model));
+
+/** The same menu written the portable way, which is what the model has to reduce to. */
+const written = (tree: readonly unknown[]) => JSON.stringify(normalizeMenuModel(tree as never));
+
+/** A `menu-model` holder, mounted: both widgets take the property and both are measured. */
+interface MenuHolderElement extends HTMLElement {
+    menuModel: AdwMenuModel | string | null;
+}
+
+const TAGS: Record<MenuModelHolder, string> = {
+    'Adw.SplitButton': 'adw-split-button',
+    'Gtk.MenuButton': 'gtk-menu-button',
+};
 
-import { Menu, MenuItem } from './namespace/gio.js';
+function mount(widget: MenuModelHolder): MenuHolderElement {
+    const el = document.createElement(TAGS[widget]) as MenuHolderElement;
+    document.body.appendChild(el);
+    return el;
+}
 
-/** What a `menuModel` property does with a value, on both spellings. */
-const model = (value: readonly unknown[]) => JSON.stringify(normalizeMenuModel(value as never));
+function unmountAll(): void {
+    for (const tag of Object.values(TAGS)) {
+        for (const el of Array.from(document.querySelectorAll(tag))) el.remove();
+    }
+}
 
 export const GioMenuTest = async () => {
-    await describe('Gio.Menu is the array a menuModel already takes', async () => {
-        await it('passes Array.isArray, which is the gate normalizeMenuModel opens on', () => {
-            expect(Array.isArray(new Menu())).toBe(true);
+    await describe('Gio.Menu is the tree a menuModel already takes', async () => {
+        await it('IS a Gio.MenuModel, which is what the property is declared over', () => {
+            // ADR 0128: the door is `value_type=GMenuModel`, so this `instanceof` is the
+            // whole reason a menu can be assigned at all.
+            expect(new Menu() instanceof MenuModel).toBe(true);
         });
 
         await it('starts empty, as g_menu_new() does', () => {
-            expect(new Menu().length).toBe(0);
+            expect(new Menu().get_n_items()).toBe(0);
         });
     });
 
     await describe('Gio.Menu.append', async () => {
-        await it('builds the gallery menu the array spelling builds', () => {
+        await it('builds the gallery menu the portable spelling builds', () => {
             const menu = new Menu();
             menu.append('Save as…', 'app.save-as');
             menu.append('Export', 'app.export');
             menu.append('Print', 'app.print');
 
-            expect(model(menu)).toBe(
-                model([
+            expect(treeOf(menu)).toBe(
+                written([
                     { label: 'Save as…', action: 'app.save-as' },
                     { label: 'Export', action: 'app.export' },
                     { label: 'Print', action: 'app.print' },
@@ -52,7 +91,7 @@ export const GioMenuTest = async () => {
             const menu = new Menu();
             menu.append('Export');
 
-            expect(model(menu)).toBe(model(['Export']));
+            expect(treeOf(menu)).toBe(written(['Export']));
         });
     });
 
@@ -61,7 +100,7 @@ export const GioMenuTest = async () => {
             const menu = new Menu();
             menu.append_item(new MenuItem('Save as…', 'app.save-as'));
 
-            expect(model(menu)).toBe(model([{ label: 'Save as…', action: 'app.save-as' }]));
+            expect(treeOf(menu)).toBe(written([{ label: 'Save as…', action: 'app.save-as' }]));
         });
 
         await it('sets both halves after construction', () => {
@@ -69,19 +108,19 @@ export const GioMenuTest = async () => {
             item.set_label('Print');
             item.set_detailed_action('app.print');
 
-            expect(model([item])).toBe(model([{ label: 'Print', action: 'app.print' }]));
+            const menu = new Menu();
+            menu.append_item(item);
+            expect(treeOf(menu)).toBe(written([{ label: 'Print', action: 'app.print' }]));
         });
 
         await it('REMOVES the attribute on null rather than carrying an undefined one', () => {
             const item = new MenuItem('Print', 'app.print');
             item.set_detailed_action(null);
 
-            expect(Object.hasOwn(item, 'action')).toBe(false);
-            expect(model([item])).toBe(model(['Print']));
-        });
-
-        await it('drops an item carrying neither half — g_menu_item_new(NULL, NULL)', () => {
-            expect(model([new MenuItem()])).toBe(model([]));
+            const menu = new Menu();
+            menu.append_item(item);
+            expect(menu.get_item_attribute_value(0, 'action', null)).toBeNull();
+            expect(treeOf(menu)).toBe(written(['Print']));
         });
     });
 
@@ -93,21 +132,21 @@ export const GioMenuTest = async () => {
             const menu = new Menu();
             menu.append_section(null, section);
 
-            expect(model(menu)).toBe(model([{ section: [{ label: 'Save as…', action: 'app.save-as' }] }]));
+            expect(treeOf(menu)).toBe(written([{ section: [{ label: 'Save as…', action: 'app.save-as' }] }]));
         });
 
         await it('carries the heading when C would have one', () => {
             const menu = new Menu();
-            menu.append_section('Document', ['Export']);
+            menu.append_section('Document', buildMenu(['Export']));
 
-            expect(model(menu)).toBe(model([{ label: 'Document', section: ['Export'] }]));
+            expect(treeOf(menu)).toBe(written([{ label: 'Document', section: ['Export'] }]));
         });
 
         await it('writes NO label attribute when there is none', () => {
             const menu = new Menu();
-            menu.append_section(null, ['Export']);
+            menu.append_section(null, buildMenu(['Export']));
 
-            expect(Object.hasOwn(menu[0] as object, 'label')).toBe(false);
+            expect(menu.get_item_attribute_value(0, 'label', null)).toBeNull();
         });
     });
 
@@ -119,7 +158,107 @@ export const GioMenuTest = async () => {
             const menu = new Menu();
             menu.append_submenu('More', submenu);
 
-            expect(model(menu)).toBe(model([{ label: 'More', submenu: [{ label: 'Print', action: 'app.print' }] }]));
+            expect(treeOf(menu)).toBe(written([{ label: 'More', submenu: [{ label: 'Print', action: 'app.print' }] }]));
         });
     });
+
+    await describe('the menu-model door (ADR 0128 conformance vectors)', async () => {
+        for (const widget of Object.keys(TAGS) as MenuModelHolder[]) {
+            for (const vector of MENU_MODEL_DOOR_VECTORS) {
+                await it(`${widget} ${vector.write}: ${vector.rule}`, () => {
+                    const el = mount(widget);
+                    const before = el.menuModel;
+
+                    // The six writes the table names, built here so the refused ones are
+                    // the values GJS was measured refusing, not stand-ins for them.
+                    const value: unknown = {
+                        menu: () => buildMenu([{ kind: 'item', label: 'Save', action: 'app.save' }]),
+                        null: () => null,
+                        'json-string': () => '[{"label":"Save","action":"app.save"}]',
+                        array: () => [{ label: 'Save' }],
+                        'plain-object': () => ({ label: 'Save' }),
+                        // `Gtk.StringList` is the subset's one registered GObject that is not
+                        // a menu model, so it reaches the TYPE refusal an array never gets to.
+                        'wrong-gobject': () => new StringList({ strings: ['Save'] }),
+                    }[vector.write]();
+
+                    // `in` rather than `??`: a `null` under the key is MEANINGFUL — it says
+                    // this surface accepts a write the shared row refuses. No row overrides
+                    // THIS surface today, and reading the field anyway is the point: the
+                    // NativeScript driver reads the same one, so a second row added there
+                    // cannot quietly mean nothing here.
+                    const override = vector.bySurface !== undefined && ADW_MENU_SURFACE_WEB.name in vector.bySurface;
+                    const expected = override
+                        ? (vector.bySurface as Record<string, string | null>)[ADW_MENU_SURFACE_WEB.name]
+                        : vector.error;
+
+                    if (expected === null) {
+                        el.menuModel = value as AdwMenuModel | string | null;
+                        if (vector.write === 'null') expect(el.menuModel).toBeNull();
+                        // A real model is held BY IDENTITY; a JSON string becomes the
+                        // surface's own authored model, which is a model all the same.
+                        else if (vector.write === 'menu') expect(el.menuModel).toBe(value);
+                        else expect(el.menuModel).not.toBeNull();
+                        unmountAll();
+                        return;
+                    }
+
+                    let message: string | null = null;
+                    try {
+                        el.menuModel = value as AdwMenuModel | string | null;
+                    } catch (error) {
+                        message = (error as Error).message;
+                    }
+                    // A shared row is matched WHOLE; a `bySurface` one is a fragment, because
+                    // the full refusal names the widget class and that belongs to the caller.
+                    if (override) expect(message).toContain(expected);
+                    else expect(message).toBe(expected);
+                    // A refusal leaves the widget holding what it held — the write never
+                    // half-landed, which is what makes the throw safe to catch.
+                    expect(el.menuModel).toBe(before);
+                    unmountAll();
+                });
+            }
+        }
+    });
+
+    await describe('notify::menu-model and the identity guard (ADR 0128 conformance vectors)', async () => {
+        for (const vector of MENU_MODEL_NOTIFY_VECTORS) {
+            const label = `${vector.widget} [${vector.writes.map((w) => w ?? 'null').join(', ')}]`;
+            await it(`${label}: ${vector.rule}`, () => {
+                const el = mount(vector.widget);
+                // TWO DISTINCT models with EQUAL content, which is what separates an
+                // identity guard from a value one: a serialisation-keyed widget would
+                // report no change for the A→B write.
+                const models: Record<'A' | 'B', GioMenuModel> = {
+                    A: buildMenu([{ kind: 'item', label: 'Save', action: 'app.save' }]),
+                    B: buildMenu([{ kind: 'item', label: 'Save', action: 'app.save' }]),
+                };
+
+                let notifies = 0;
+                el.addEventListener('notify::menu-model', () => notifies++);
+
+                const counted: number[] = [];
+                const write = (name: MenuModelWrite) => {
+                    notifies = 0;
+                    el.menuModel = name === null ? null : models[name];
+                    counted.push(notifies);
+                };
+                for (const name of vector.writes) write(name);
+
+                if (vector.mutateHeldModel === true) {
+                    // The last step is a MUTATION of the model the widget already holds.
+                    // It is not a property change: the content arrives over
+                    // `items-changed`, which is why a widget keyed on a serialisation of
+                    // the model reports the wrong thing in both directions.
+                    notifies = 0;
+                    (el.menuModel as unknown as { append(label: string): void }).append('Export');
+                    counted.push(notifies);
+                }
+
+                expect(counted).toStrictEqual([...vector.notifies]);
+                unmountAll();
+            });
+        }
+    });
 };

package/src/gtk-image.spec.ts

@@ -9,6 +9,7 @@
 import { describe, expect, it } from '@gjsify/unit';
 
 import { VIEW_STACK_ICON_NAME_VECTORS } from '@gjsify/adwaita-core/conformance';
+import { buildMenu } from '@gjsify/adwaita-core';
 
 import type { GtkImage } from './elements/gtk-image.js';
 import type { GtkMenuButton } from './elements/gtk-menu-button.js';
@@ -124,11 +125,11 @@ export const GtkImageTest = async () => {
 
         await it('<gtk-menu-button> menu entries guard their icons too', () => {
             const { el, host } = mount<GtkMenuButton>('gtk-menu-button');
-            el.menuModel = [
+            el.menuModel = buildMenu([
                 { label: 'Bad', icon: 'a b' },
                 { label: 'Good', icon: 'view-refresh-symbolic' },
                 { label: 'None' },
-            ];
+            ]);
             const items = [...el.querySelectorAll('.adw-menu-button-item')];
             expect(items.length).toBe(3);
             // An entry that ASKED for an icon keeps its slot even when the name is

package/src/gtk-menu-button.spec.ts

@@ -8,11 +8,11 @@
 
 import { describe, expect, it } from '@gjsify/unit';
 import { MENU_ITEM_STATE_VECTORS, MENU_PARSE_VECTORS, MENU_REFUSAL_VECTORS } from '@gjsify/adwaita-core/conformance';
-import { flattenMenu } from '@gjsify/adwaita-core';
-import type { AdwMenuInput } from '@gjsify/adwaita-core';
+import { buildMenu, flattenMenu } from '@gjsify/adwaita-core';
+import type { AdwMenuModel } from '@gjsify/adwaita-core';
 
 interface MenuButtonElement extends HTMLElement {
-    menuModel: AdwMenuInput;
+    menuModel: AdwMenuModel | string | null;
     actions: Record<string, { enabled?: boolean; state?: string }> | null;
 }
 
@@ -33,12 +33,12 @@ function unmountAll(): void {
 
 export const GtkMenuButtonTest = async () => {
     await describe('<gtk-menu-button> menu attribute', async () => {
-        for (const { json, model, rule } of MENU_PARSE_VECTORS) {
+        for (const { json, tree, rule } of MENU_PARSE_VECTORS) {
             await it(`${rule}`, () => {
                 const { labels } = mountWithMenu(json ?? '');
                 // The rendered rows are what `flattenMenu` says: a section is inlined,
                 // a submenu is ONE row, and both keep their own label.
-                expect(labels).toStrictEqual(flattenMenu(model).map((row) => row.node.label));
+                expect(labels).toStrictEqual(flattenMenu(tree).map((row) => row.node.label));
                 unmountAll();
             });
         }
@@ -71,14 +71,14 @@ export const GtkMenuButtonTest = async () => {
             const el = document.createElement('gtk-menu-button') as MenuButtonElement;
             document.body.appendChild(el);
             expect(el.querySelectorAll('.adw-popover-item').length).toBe(0);
-            el.menuModel = ['New', 'Open'];
+            el.menuModel = buildMenu(['New', 'Open']);
             expect([...el.querySelectorAll('.adw-menu-button-item-label')].map((n) => n.textContent)).toStrictEqual([
                 'New',
                 'Open',
             ]);
             // REPLACED, not merely seeded — the failure mode is a second assignment
             // writing an expando while the first happened to work at connect.
-            el.menuModel = [{ label: 'Only', action: 'app.only' }];
+            el.menuModel = buildMenu([{ label: 'Only', action: 'app.only' }]);
             expect([...el.querySelectorAll('.adw-menu-button-item-label')].map((n) => n.textContent)).toStrictEqual([
                 'Only',
             ]);
@@ -100,11 +100,11 @@ export const GtkMenuButtonTest = async () => {
         await it('draws a section heading, a separator and a submenu page', () => {
             const el = document.createElement('gtk-menu-button') as MenuButtonElement;
             document.body.appendChild(el);
-            el.menuModel = [
+            el.menuModel = buildMenu([
                 { label: 'New' },
                 { section: [{ label: 'Cut' }, { label: 'Copy' }], label: 'Edit' },
                 { label: 'More', submenu: [{ label: 'Rename' }, { label: 'Duplicate' }] },
-            ];
+            ]);
 
             // TWO: a section is separated from what comes before it AND from what comes
             // after, which is what `GtkPopoverMenu` draws for the same model.
@@ -137,7 +137,7 @@ export const GtkMenuButtonTest = async () => {
                 const el = document.createElement('gtk-menu-button') as MenuButtonElement;
                 document.body.appendChild(el);
                 el.actions = { ...actions };
-                el.menuModel = [item];
+                el.menuModel = buildMenu([item]);
                 const row = el.querySelector('.adw-popover-item') as HTMLButtonElement;
                 expect(row.hidden).toBe(!state.visible);
                 expect(row.disabled).toBe(!state.sensitive);
@@ -179,15 +179,15 @@ export const GtkMenuButtonTest = async () => {
 
         await it('menu_model / get_menu_model / set_menu_model mirror menuModel', () => {
             const el = document.createElement('gtk-menu-button') as MenuButtonElement & {
-                menu_model: AdwMenuInput;
+                menu_model: AdwMenuModel | null;
                 get_menu_model(): unknown;
-                set_menu_model(v: AdwMenuInput): void;
+                set_menu_model(v: AdwMenuModel | null): void;
             };
             document.body.appendChild(el);
-            el.set_menu_model(['Save', 'Quit']);
+            el.set_menu_model(buildMenu(['Save', 'Quit']));
             expect(el.get_menu_model()).toBe(el.menuModel);
             expect(el.querySelectorAll('.adw-popover-item').length).toBe(2);
-            el.menu_model = ['Save'];
+            el.menu_model = buildMenu(['Save']);
             expect(el.querySelectorAll('.adw-popover-item').length).toBe(1);
             unmountAll();
         });
@@ -200,13 +200,16 @@ export const GtkMenuButtonTest = async () => {
             unmountAll();
         });
 
-        for (const { model, paths, rule } of MENU_REFUSAL_VECTORS) {
+        for (const { tree, paths, rule } of MENU_REFUSAL_VECTORS) {
             await it(`refusal — ${rule}`, () => {
                 const el = document.createElement('gtk-menu-button') as MenuButtonElement;
                 document.body.appendChild(el);
+                // `buildMenu` is how a tree becomes a model now: the property takes the
+                // real thing (ADR 0128), so the refusal happens on the model's snapshot.
+                const model = buildMenu(tree);
                 if (paths.length === 0) {
                     el.menuModel = model;
-                    expect(el.querySelectorAll('.adw-popover-item').length).toBe(flattenMenu(model).length);
+                    expect(el.querySelectorAll('.adw-popover-item').length).toBe(flattenMenu(tree).length);
                 } else {
                     // LOUD, at the assignment: a `custom` item names an application
                     // widget, and a surface that ignored it would draw a blank row.

package/src/gtk-popover-bin.spec.ts

@@ -9,10 +9,11 @@
 //   · `menu.popup` is an ACTION, so the element exposes it as an event too.
 
 import { describe, expect, it } from '@gjsify/unit';
-import type { AdwMenuInput } from '@gjsify/adwaita-core';
+import { buildMenu } from '@gjsify/adwaita-core';
+import type { AdwMenuModel } from '@gjsify/adwaita-core';
 
 interface PopoverBinElement extends HTMLElement {
-    menuModel: AdwMenuInput;
+    menuModel: AdwMenuModel | string | null;
     // `popoverElement`, not `popover`: `HTMLElement` already declares a `popover` STRING
     // attribute for the DOM Popover API, and an interface cannot narrow that to a widget.
     popoverElement: HTMLElement | null;
@@ -67,7 +68,7 @@ export const GtkPopoverBinTest = async () => {
         await it('setting the model REPLACES the popover', () => {
             const { el } = mount(JSON.stringify(MENU));
             const before = popoverOf(el);
-            el.menuModel = [{ label: 'Only' }];
+            el.menuModel = buildMenu([{ label: 'Only' }]);
             expect(popoverOf(el)).not.toBe(before);
             expect(before?.isConnected).toBe(false);
             unmountAll();
@@ -80,7 +81,7 @@ export const GtkPopoverBinTest = async () => {
             // that is easy to get wrong by keeping them apart.
             const replacement = document.createElement('gtk-popover') as unknown as HTMLElement;
             el.popoverElement = replacement;
-            expect(el.menuModel).toStrictEqual([]);
+            expect(el.menuModel).toBeNull();
             expect(el.popoverElement).toBe(replacement);
             // The old popover is unparented rather than left behind as a second surface:
             // `gtk_popover_bin_set_popover` unparents the one it displaces.
@@ -92,7 +93,7 @@ export const GtkPopoverBinTest = async () => {
             const { el } = mount();
             const seen: unknown[] = [];
             el.addEventListener('notify::menu-model', (event) => seen.push((event as CustomEvent).detail));
-            el.menuModel = MENU;
+            el.menuModel = buildMenu(MENU);
             // GTK notifies `:popover` AND `:menu-model` from BOTH setters
             // (gtkpopoverbin.c:502, :586-587), so one event carrying both is the faithful
             // reading rather than two that can disagree.

package/src/gtk-popover-menu-bar.spec.ts

@@ -5,22 +5,27 @@
 
 import { describe, expect, it } from '@gjsify/unit';
 import { MENU_LABEL_TEXT_VECTORS } from '@gjsify/adwaita-core/conformance';
-import type { AdwMenuInput } from '@gjsify/adwaita-core';
+import { buildMenu } from '@gjsify/adwaita-core';
+import type { AdwMenuModel } from '@gjsify/adwaita-core';
 
 interface MenuBarElement extends HTMLElement {
-    menuModel: AdwMenuInput;
+    menuModel: AdwMenuModel | null;
     actions: Record<string, { enabled?: boolean; state?: string }> | null;
     activeItem: HTMLElement | null;
     selectFirst(): void;
     popup(): void;
 }
 
-/** Three submenus, the shape GTK builds one item for (`tracker_insert`, :422-468). */
-const MENU = [
+/**
+ * Three submenus, the shape GTK builds one item for (`tracker_insert`, :422-468). ONE model
+ * for the whole file, as GTK has it: a menu is a `GMenuModel` and several widgets may hold
+ * the same one.
+ */
+const MENU = buildMenu([
     { label: 'File', submenu: [{ label: 'New' }, { label: 'Open' }] },
     { label: 'Edit', submenu: [{ label: 'Cut' }] },
     { label: 'View', submenu: [{ label: 'Zoom In' }] },
-];
+]);
 
 function mount(json?: string): MenuBarElement {
     const el = document.createElement('gtk-popover-menu-bar') as MenuBarElement;
@@ -299,7 +304,7 @@ export const GtkPopoverMenuBarTest = async () => {
         for (const { label, text, rule } of MENU_LABEL_TEXT_VECTORS) {
             await it(rule, () => {
                 const el = mount();
-                el.menuModel = [{ label, submenu: [{ label: 'Inner' }] }];
+                el.menuModel = buildMenu([{ label, submenu: [{ label: 'Inner' }] }]);
                 expect(buttons(el).map((b) => b.textContent)).toStrictEqual([text]);
                 unmountAll();
             });