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

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

@@ -32,7 +32,8 @@
 //   handle-input  — boolean, default FALSE — GTK's default. When set, a right click and a
 //                   long press open the popover at the pointer.
 // Properties:
-//   menuModel     — the model, normalised (get/set). Setting it REPLACES any popover.
+//   menuModel     — the real `Gio.MenuModel`, or `null` (get/set; ADR 0128). Setting it
+//                   REPLACES any popover.
 //   popoverElement — the `<gtk-popover>` this bin presents (get/set; setting it drops
 //                   the model, as GTK does). `GtkPopoverBin`'s own name for it is `popover`,
 //                   which `HTMLElement` already spells as a string attribute for the DOM
@@ -60,14 +61,9 @@
 // Copyright (c) GNOME contributors (GTK, libadwaita). LGPLv2.1+
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
-import {
-    ADW_MENU_SURFACE_WEB,
-    assertMenuRenderable,
-    menuRefusals,
-    normalizeMenuModel,
-    parseMenuModel,
-} from '@gjsify/adwaita-core';
-import type { AdwMenuActions, AdwMenuInput, AdwMenuModel } from '@gjsify/adwaita-core';
+import type { AdwMenuActions, AdwMenuModel } from '@gjsify/adwaita-core';
+
+import { MenuSlot } from './menu-slot.js';
 
 // Both definitions have to be there before this module's own can build them in
 // `connectedCallback`; a combined `import { GtkPopoverMenu }` would be elided, because the
@@ -82,7 +78,14 @@ import { WidgetElement } from '../widget-element.js';
 const LONG_PRESS_MS = 500;
 
 export class GtkPopoverBin extends WidgetElement {
-    private _model: AdwMenuModel = [];
+    /**
+     * The model's door and `items-changed` subscription (ADR 0128), with NOTHING to do
+     * when the menu it holds mutates: this bin draws no rows. The `<gtk-popover-menu>` it
+     * built holds the SAME model and watches it through a slot of its own, so the rows
+     * follow one level down — and GTK sends no `notify::menu-model` for a mutation either
+     * (measured, `MENU_MODEL_NOTIFY_VECTORS`).
+     */
+    private readonly _slot = new MenuSlot(() => undefined);
     private _popover: GtkPopoverMenu | null = null;
     private _actions: AdwMenuActions | null = null;
     private _initialized = false;
@@ -92,9 +95,9 @@ export class GtkPopoverBin extends WidgetElement {
         return ['menu-model', 'handle-input'];
     }
 
-    /** The menu model, normalised (ADR 0042). */
-    get menuModel(): AdwMenuModel {
-        return this._model;
+    /** The menu this bin pops up, by identity, or `null` (ADR 0128). */
+    get menuModel(): AdwMenuModel | null {
+        return this._slot.model;
     }
 
     /**
@@ -102,9 +105,8 @@ export class GtkPopoverBin extends WidgetElement {
      * setters clear each other (gtkpopoverbin.c:474-500, :543-551). A model REPLACES the
      * popover; a popover DROPS the model, and both notify for both properties.
      */
-    set menuModel(value: AdwMenuInput | AdwMenuModel) {
-        this._model = normalizeMenuModel(value as AdwMenuInput);
-        assertMenuRenderable(this._model, ADW_MENU_SURFACE_WEB);
+    set menuModel(value: AdwMenuModel | string | null) {
+        this._slot.write(value);
         this._adoptPopover(this._buildPopover());
         this._notifyModel();
     }
@@ -123,7 +125,7 @@ export class GtkPopoverBin extends WidgetElement {
     }
 
     set popoverElement(value: GtkPopoverMenu | null) {
-        this._model = [];
+        this._slot.write(null);
         this._adoptPopover(value);
         this._notifyModel();
     }
@@ -157,8 +159,8 @@ export class GtkPopoverBin extends WidgetElement {
         this.addEventListener('contextmenu', (event) => this._onContextMenu(event));
         this.addEventListener('keydown', (event) => this._onKeyDown(event));
         this._wireGestures();
-        if (this._model.length === 0) this._model = this._parseMenuAttr();
-        if (this._model.length > 0) this._adoptPopover(this._buildPopover());
+        if (this._slot.model === null) this._slot.writeMarkup(this.getAttribute('menu-model'));
+        this._adoptPopover(this._buildPopover());
     }
 
     disconnectedCallback() {
@@ -176,8 +178,8 @@ export class GtkPopoverBin extends WidgetElement {
             return;
         }
         if (name === 'menu-model') {
-            this._model = this._parseMenuAttr();
-            this._adoptPopover(this._model.length > 0 ? this._buildPopover() : null);
+            this._slot.writeMarkup(this.getAttribute('menu-model'));
+            this._adoptPopover(this._buildPopover());
             this._notifyModel();
         }
     }
@@ -265,14 +267,20 @@ export class GtkPopoverBin extends WidgetElement {
         this.popup();
     }
 
+    /**
+     * The popover follows the PRESENCE of a model, not its length: an empty non-null
+     * `Gio.Menu` at `menu-model` still builds a `GtkPopoverMenu` in GTK and still
+     * dissociates an application-set popover (measured, `MENU_MODEL_DOOR_VECTORS`), and
+     * `null` is the one spelling of "no menu".
+     */
     private _buildPopover(): GtkPopoverMenu | null {
-        if (this._model.length === 0) return null;
+        if (this._slot.model === null) return null;
         const popover = document.createElement('gtk-popover-menu') as GtkPopoverMenu;
         // `gtk_popover_set_position (popover, GTK_POS_BOTTOM)` in the same function
         // (gtkpopoverbin.c:493), on a popover `gtk_popover_menu_new_from_model` made.
         popover.setAttribute('position', 'bottom');
         popover.setAttribute('align', 'start');
-        popover.menuModel = this._model;
+        popover.menuModel = this._slot.model;
         popover.actions = this._actions;
         popover.anchor = this;
         return popover;
@@ -313,24 +321,10 @@ export class GtkPopoverBin extends WidgetElement {
         this.dispatchEvent(
             new CustomEvent('notify::menu-model', {
                 bubbles: true,
-                detail: { menuModel: this._model, popover: this._popover },
+                detail: { menuModel: this._slot.model, popover: this._popover },
             }),
         );
     }
-
-    /**
-     * The `menu-model` ATTRIBUTE through the core parser, refusing a `custom` item the way
-     * every menu-bearing surface here does: markup is parsed by the browser, so a throw from
-     * `connectedCallback` would reach nobody and the menu would be silently empty.
-     */
-    private _parseMenuAttr(): AdwMenuModel {
-        const model = normalizeMenuModel(parseMenuModel(this.getAttribute('menu-model')));
-        const refusals = menuRefusals(model, ADW_MENU_SURFACE_WEB);
-        if (refusals.length === 0) return model;
-        console.error(`${ADW_MENU_SURFACE_WEB.name} cannot render this menu, so it has none:`);
-        for (const refusal of refusals) console.error(`  [${refusal.path.join('.')}] ${refusal.message}`);
-        return [];
-    }
 }
 
 customElements.define('gtk-popover-bin', GtkPopoverBin);

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

@@ -37,7 +37,8 @@
 //   menu-model — the portable menu model as JSON (ADR 0042), whose TOPLEVEL entries must
 //               all be submenus.
 // Properties:
-//   menuModel  — the model, normalised (get/set; a `custom` item throws here).
+//   menuModel  — the real `Gio.MenuModel`, or `null` (get/set; ADR 0128 — a `custom` item
+//               throws here).
 //   actions    — what the action group publishes about the actions the menus name.
 //   activeItem — the focused/selected item's button, or `null`. GTK's `active_item`.
 // Methods:
@@ -57,16 +58,10 @@
 // Copyright (c) GNOME contributors (GTK, libadwaita). LGPLv2.1+
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
-import {
-    ADW_MENU_SURFACE_WEB,
-    assertMenuRenderable,
-    menuItemAt,
-    menuLabelText,
-    menuRefusals,
-    normalizeMenuModel,
-    parseMenuModel,
-} from '@gjsify/adwaita-core';
-import type { AdwMenuActions, AdwMenuInput, AdwMenuModel, AdwMenuPath, AdwMenuSubmenu } from '@gjsify/adwaita-core';
+import { buildMenu, menuItemAt, menuLabelText } from '@gjsify/adwaita-core';
+import type { AdwMenuActions, AdwMenuModel, AdwMenuPath, AdwMenuSubmenu } from '@gjsify/adwaita-core';
+
+import { MenuSlot } from './menu-slot.js';
 
 // The definition has to be there before this module's own can build one in
 // `connectedCallback`; a combined `import { GtkPopoverMenu }` would be elided, because the
@@ -88,7 +83,8 @@ interface MenuBarItem {
 }
 
 export class GtkPopoverMenuBar extends WidgetElement {
-    private _model: AdwMenuModel = [];
+    /** The model, its tree snapshot and its `items-changed` subscription (ADR 0128). */
+    private readonly _slot = new MenuSlot(() => this._menuChanged());
     private _actions: AdwMenuActions | null = null;
     private _items: MenuBarItem[] = [];
     private _active: MenuBarItem | null = null;
@@ -98,14 +94,29 @@ export class GtkPopoverMenuBar extends WidgetElement {
         return ['menu-model'];
     }
 
-    /** The menu model, normalised (ADR 0042). */
-    get menuModel(): AdwMenuModel {
-        return this._model;
+    /** The menu this bar draws, by identity, or `null` (ADR 0128). */
+    get menuModel(): AdwMenuModel | null {
+        return this._slot.model;
+    }
+
+    set menuModel(value: AdwMenuModel | string | null) {
+        this._slot.write(value);
+        this._menuChanged();
     }
 
-    set menuModel(value: AdwMenuInput) {
-        this._model = normalizeMenuModel(value);
-        assertMenuRenderable(this._model, ADW_MENU_SURFACE_WEB);
+    /**
+     * The one place a changed menu is answered — from either door AND from a mutation of
+     * the menu the bar is holding, which is why the `console.warn` below is here rather
+     * than beside the attribute parse it used to live in: a toplevel entry that is not a
+     * submenu can arrive by `append_item` just as easily as by markup.
+     */
+    private _menuChanged(): void {
+        for (const [index, node] of this._slot.tree.entries()) {
+            if (node.kind === 'submenu') continue;
+            // A WARNING and not an error, and the distinction is GTK's: `g_warning` is
+            // recoverable, and the submenus beside the offending entry still work.
+            console.warn(`Don't know how to handle this item: top-level entry ${index} is a ${node.kind}.`);
+        }
         if (this._initialized) this._rebuild();
     }
 
@@ -136,14 +147,14 @@ export class GtkPopoverMenuBar extends WidgetElement {
         this.addEventListener('pointerleave', () => {
             if (this._active !== null && !this._active.popover.open) this._setActive(null, false);
         });
-        if (this._model.length === 0) this._model = this._parseMenuAttr();
-        this._rebuild();
+        if (this._slot.model === null) this._slot.writeMarkup(this.getAttribute('menu-model'));
+        this._menuChanged();
     }
 
     attributeChangedCallback(name?: string) {
         if (!this._initialized || name !== 'menu-model') return;
-        this._model = this._parseMenuAttr();
-        this._rebuild();
+        this._slot.writeMarkup(this.getAttribute('menu-model'));
+        this._menuChanged();
     }
 
     /** `gtk_popover_menu_bar_select_first` — activate and OPEN the first item. */
@@ -213,7 +224,7 @@ export class GtkPopoverMenuBar extends WidgetElement {
         this._items = [];
         this._active = null;
         const built: MenuBarItem[] = [];
-        this._model.forEach((node, index) => {
+        this._slot.tree.forEach((node, index) => {
             if (node.kind !== 'submenu') return;
             built.push(this._buildItem(node, [index]));
         });
@@ -237,8 +248,8 @@ export class GtkPopoverMenuBar extends WidgetElement {
     /**
      * One `menubar > item > popover` (the node tree in gtkpopovermenubar.c:38-46).
      *
-     * A toplevel node that is not a submenu is refused by `_parseMenuAttr` with GTK's own
-     * wording rather than drawn: `tracker_insert` builds nothing for it
+     * A toplevel node that is not a submenu is WARNED about by {@link _menuChanged} with
+     * GTK's own wording rather than drawn: `tracker_insert` builds nothing for it
      * (gtkpopovermenubar.c:466), and a row that opens nothing is the same lie in another
      * shape.
      */
@@ -269,9 +280,10 @@ export class GtkPopoverMenuBar extends WidgetElement {
         // (gtkpopovermenubar.c:435-436).
         popover.setAttribute('position', 'bottom');
         popover.setAttribute('align', 'start');
-        // The submenu's OWN items, handed back as they are: `normalizeMenuModel` is
-        // idempotent and explicitly takes an already-normalised node (ADR 0042).
-        popover.menuModel = node.items;
+        // The submenu's OWN items, as a menu OF THEIR OWN: since ADR 0128 the popover takes
+        // a real `Gio.MenuModel`, and `buildMenu` is how a tree becomes one. Handing over
+        // the bar's own model instead would give the popover the whole bar.
+        popover.menuModel = buildMenu(node.items);
         popover.actions = this._actions;
         popover.anchor = button;
         // `gtk_accessible_update_relation (…, LABELLED_BY, item->label, CONTROLS,
@@ -324,7 +336,7 @@ export class GtkPopoverMenuBar extends WidgetElement {
      * row is not the row that opened a submenu (gtkpopovermenu.c:257-259).
      */
     private _activate(item: MenuBarItem, path: AdwMenuPath): void {
-        const target = menuItemAt(this._model, path);
+        const target = menuItemAt(this._slot.tree, path);
         item.popover.popdown();
         item.button.focus();
         if (target === null) return;
@@ -335,23 +347,6 @@ export class GtkPopoverMenuBar extends WidgetElement {
             }),
         );
     }
-
-    private _parseMenuAttr(): AdwMenuModel {
-        const model = normalizeMenuModel(parseMenuModel(this.getAttribute('menu-model')));
-        const refusals = menuRefusals(model, ADW_MENU_SURFACE_WEB);
-        if (refusals.length > 0) {
-            console.error(`${ADW_MENU_SURFACE_WEB.name} cannot render this menu, so it has none:`);
-            for (const refusal of refusals) console.error(`  [${refusal.path.join('.')}] ${refusal.message}`);
-            return [];
-        }
-        for (const [index, node] of model.entries()) {
-            if (node.kind === 'submenu') continue;
-            // A WARNING and not an error, and the distinction is GTK's: `g_warning` is
-            // recoverable, and the submenus beside the offending entry still work.
-            console.warn(`Don't know how to handle this item: top-level entry ${index} is a ${node.kind}.`);
-        }
-        return model;
-    }
 }
 
 customElements.define('gtk-popover-menu-bar', GtkPopoverMenuBar);

package/src/elements/gtk-popover-menu.ts

@@ -40,9 +40,9 @@
 //                      is its name. `gtk_popover_menu_open_submenu(popover, "main")` is
 //                      the way back, so this is writeable and readable.
 // Properties:
-//   menuModel        — the model, normalised (get/set; a `custom` item throws here). Takes
-//                      an already-normalised `AdwMenuModel` too, which is what a menu bar
-//                      hands over for one of its submenus.
+//   menuModel        — the real `Gio.MenuModel` (ADR 0128), or `null` (get/set; a `custom`
+//                      item throws here). A menu bar hands one of these over for a submenu
+//                      of its own; a JSON string is the authored spelling.
 //   actions          — what the action group publishes about the actions the model names
 //                      (ADR 0042), the source of every row's enabled/checked state.
 //   visibleSubmenu   — the open page's name (get/set).
@@ -72,26 +72,22 @@
 // Copyright (c) GNOME contributors (GTK, libadwaita). LGPLv2.1+
 // Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
 
-import {
-    ADW_MENU_SURFACE_WEB,
-    assertMenuRenderable,
-    menuItemAt,
-    menuNodeAt,
-    menuRefusals,
-    normalizeMenuModel,
-    parseMenuModel,
-} from '@gjsify/adwaita-core';
+import { menuItemAt, menuNodeAt } from '@gjsify/adwaita-core';
 import { activateElementMenuItem, menuActionsOfElement } from '../application.js';
-import type { AdwMenuActions, AdwMenuInput, AdwMenuModel, AdwMenuPath } from '@gjsify/adwaita-core';
+import type { AdwMenuActions, AdwMenuModel, AdwMenuPath, AdwMenuTree } from '@gjsify/adwaita-core';
 
 import { GtkPopover } from './gtk-popover.js';
+import { MenuSlot } from './menu-slot.js';
 import { PopoverMenuView } from './popover-menu.js';
 
 /** The name the ROOT page carries — `gtk_popover_menu_open_submenu`'s own "main". */
 const MAIN_PAGE = 'main';
 
 export class GtkPopoverMenu extends GtkPopover {
-    private _model: AdwMenuModel = [];
+    /** The model, its tree snapshot and its `items-changed` subscription (ADR 0128). */
+    private readonly _slot = new MenuSlot(() => {
+        if (this._menuInitialized) this._renderMenu();
+    });
     private _actions: AdwMenuActions | null = null;
     private _menuView!: PopoverMenuView;
     /** Named apart from `GtkPopover`'s own: two `private` fields of one name are two fields. */
@@ -101,26 +97,23 @@ export class GtkPopoverMenu extends GtkPopover {
         return [...GtkPopover.observedAttributes, 'menu-model', 'menu-title', 'visible-submenu'];
     }
 
-    /** The menu, normalised (ADR 0042). */
-    get menuModel(): AdwMenuModel {
-        return this._model;
+    /** The menu this popover draws, by identity, or `null` (ADR 0128). */
+    get menuModel(): AdwMenuModel | null {
+        return this._slot.model;
     }
 
     /**
-     * Set the menu from anything the portable model accepts, refusing a `custom` item
-     * HERE — at the assignment, where it is a call the caller can catch. An ATTRIBUTE is
-     * markup the browser parses, so the attribute path refuses the whole menu instead and
-     * says why on `console.error`, exactly as `<gtk-menu-button>` does.
+     * Take a real model, a JSON string in the portable spelling, or `null`, refusing a
+     * `custom` item HERE — at the assignment, where it is a call the caller can catch.
+     * An ATTRIBUTE is markup the browser parses, so that path refuses the whole menu and
+     * says why on `console.error`; {@link MenuSlot} owns both doors.
      *
-     * `AdwMenuModel` is in the union because a menu bar hands over a submenu's own `items`
-     * untouched, and `normalizeMenuModel` is documented to be IDEMPOTENT over an
-     * already-normalised node — that is what lets a renderer hand a model it is holding
-     * straight back. The one cast is where the core's parameter type (`AdwMenuInput`, whose
-     * entries are the AUTHORED shapes) is narrower than the behaviour it documents.
+     * A REAL MODEL IS WHAT A MENU BAR HANDS OVER for one of its submenus, and the model
+     * it hands over is `buildMenu(node.items)` — a menu of its own rather than this
+     * element's authored one, so the two cannot overwrite each other.
      */
-    set menuModel(value: AdwMenuInput | AdwMenuModel) {
-        this._model = normalizeMenuModel(value as AdwMenuInput);
-        assertMenuRenderable(this._model, ADW_MENU_SURFACE_WEB);
+    set menuModel(value: AdwMenuModel | string | null) {
+        this._slot.write(value);
         if (this._menuInitialized) this._renderMenu();
     }
 
@@ -183,10 +176,10 @@ export class GtkPopoverMenu extends GtkPopover {
         this._menuView = new PopoverMenuView(this, 'adw-popover-menu', (path) => this._activate(path));
         this._menuView.setActions(this._actions);
 
-        if (this._model.length === 0) this._model = this._parseMenuAttr();
-        // The VIEW is what draws, and it holds the model it walks — seeding `_model`
-        // directly and rendering without handing the view the same value would leave it
-        // drawing an EMPTY page over a model the element believes it has.
+        if (this._slot.model === null) this._slot.writeMarkup(this.getAttribute('menu-model'));
+        // The VIEW is what draws, and it holds the TREE it walks — seeding the slot
+        // without handing the view the same snapshot would leave it drawing an EMPTY
+        // page over a model the element believes it has.
         this._renderMenu();
 
         // The visible page RESETS when the popover closes, as `gtk_popover_menu_show` does
@@ -194,7 +187,7 @@ export class GtkPopoverMenu extends GtkPopover {
         // a menu that reopens three levels deep is one the reader cannot get out of.
         this.subscribe((open) => {
             if (open) {
-                this._menuView.setActions(this._actions ?? menuActionsOfElement(this, this._model));
+                this._menuView.setActions(this._actions ?? menuActionsOfElement(this, this._slot.tree));
                 this._menuView.render();
                 this._menuView.focusableRows[0]?.focus();
             } else this._menuView.reset();
@@ -205,7 +198,7 @@ export class GtkPopoverMenu extends GtkPopover {
         super.attributeChangedCallback(name, previous, value);
         if (!this._menuInitialized) return;
         if (name === 'menu-model') {
-            this._model = this._parseMenuAttr();
+            this._slot.writeMarkup(this.getAttribute('menu-model'));
             this._renderMenu();
             return;
         }
@@ -258,7 +251,7 @@ export class GtkPopoverMenu extends GtkPopover {
         } else {
             const path = this._findSubmenu(name);
             if (path === null) return false;
-            this._menuView.setMenuModel(this._model);
+            this._menuView.setMenuTree(this._slot.tree);
             this._menuView.showPage(path);
         }
         this._menuView.render();
@@ -276,12 +269,12 @@ export class GtkPopoverMenu extends GtkPopover {
     private _openPageLabel(): string | null {
         const path = this._menuView.page;
         if (path.length === 0) return null;
-        const node = menuNodeAt(this._model, path);
+        const node = menuNodeAt(this._slot.tree, path);
         return node !== null && node.kind !== 'item' ? node.label : null;
     }
 
     private _findSubmenu(label: string): AdwMenuPath | null {
-        const walk = (nodes: AdwMenuModel, path: AdwMenuPath): AdwMenuPath | null => {
+        const walk = (nodes: AdwMenuTree, path: AdwMenuPath): AdwMenuPath | null => {
             for (const [index, node] of nodes.entries()) {
                 if (node.kind === 'item') continue;
                 const here = [...path, index];
@@ -291,7 +284,7 @@ export class GtkPopoverMenu extends GtkPopover {
             }
             return null;
         };
-        return walk(this._model, []);
+        return walk(this._slot.tree, []);
     }
 
     /**
@@ -313,7 +306,7 @@ export class GtkPopoverMenu extends GtkPopover {
      * open by choosing from it.
      */
     private _activate(path: AdwMenuPath): void {
-        const target = menuItemAt(this._model, path);
+        const target = menuItemAt(this._slot.tree, path);
         this.popdown();
         this.anchor?.focus();
         if (target === null) return;
@@ -327,22 +320,10 @@ export class GtkPopoverMenu extends GtkPopover {
     }
 
     private _renderMenu(): void {
-        this._menuView.setMenuModel(this._model);
+        this._menuView.setMenuTree(this._slot.tree);
         this._menuView.setTitle(this.menuTitle);
         this._menuView.render();
-        if (this._model.length === 0) this.popdown();
-    }
-
-    private _parseMenuAttr(): AdwMenuModel {
-        const model = normalizeMenuModel(parseMenuModel(this.getAttribute('menu-model')));
-        const refusals = menuRefusals(model, ADW_MENU_SURFACE_WEB);
-        if (refusals.length === 0) return model;
-        // A throw from `connectedCallback` is reported as an uncaught PAGE error and
-        // reaches nobody, so markup refuses the menu and says why. See
-        // `<gtk-menu-button>`'s `_acceptMenu` for the same two doors.
-        console.error(`${ADW_MENU_SURFACE_WEB.name} cannot render this menu, so it has none:`);
-        for (const refusal of refusals) console.error(`  [${refusal.path.join('.')}] ${refusal.message}`);
-        return [];
+        if (this._slot.isEmpty) this.popdown();
     }
 }
 

package/src/elements/menu-slot.ts

@@ -0,0 +1,139 @@
+// The `menu-model` SLOT the menu-bearing elements of this package share.
+//
+// ADR 0128 made `menu-model` a real `Gio.MenuModel`, and that turned one assignment into
+// four steps that only work in one order:
+//
+//   1. read the write — `readMenuModelWrite` is the core's one door, and it is what tells a
+//      real model apart from the JSON string an attribute carries (ADR 0128 § 4);
+//   2. REFUSE what this surface cannot draw, before the element renders it;
+//   3. take a TREE SNAPSHOT, because every walker (`flattenMenu`, `menuNodeAt`,
+//      `menuItemAt`, `menuRefusals`) takes an `AdwMenuTree` and not a model — one snapshot
+//      per change rather than a chain of `get_item_link` calls per row;
+//   4. connect `items-changed` — on the root AND on every section and submenu it links,
+//      which is what `watchMenuModel` does, because a link's emission does NOT bubble.
+//
+// THE STEP THAT IS EASIEST TO GET WRONG IS THE LAST ONE: the watcher has to be RE-RUN after
+// every snapshot, since a mutation can add a section that was not there to connect to. Six
+// elements here need all four steps, so the arithmetic lives once and there is no sixth
+// place to forget it.
+//
+// THE TWO WRITES REFUSE DIFFERENTLY, and the difference is which side can hear it, exactly
+// as it was before the model became real. {@link MenuSlot.write} is a property assignment,
+// so it is a CALL and it THROWS; {@link MenuSlot.writeMarkup} is an attribute the browser
+// parsed, where a throw out of `connectedCallback` reaches nobody and is reported as an
+// uncaught page error (measured: it broke `adwaita-upgrade-order.spec.ts`, which counts
+// exactly those) — so markup refuses the MENU and says why on `console.error`.
+//
+// THE WATCHER'S LIFETIME IS THE ELEMENT'S, with no `release()` to call. GTK disconnects in
+// `dispose`, and a custom element has no dispose: it has `disconnectedCallback`, which also
+// fires when a node is MOVED, and an element re-inserted after dropping its watcher would
+// be deaf to the menu it still holds. A held model keeping its element alive is the same
+// shape GTK has, where the widget owns a reference to the model it reads.
+
+import {
+    ADW_MENU_SURFACE_WEB,
+    GjsifyMenu,
+    assertMenuRenderable,
+    menuRefusals,
+    menuTree,
+    readMenuModelWrite,
+    watchMenuModel,
+} from '@gjsify/adwaita-core';
+import type { AdwMenuTree, GioMenuModel } from '@gjsify/adwaita-core';
+
+export class MenuSlot {
+    /**
+     * The menu this element OWNS, so an edit to the same `menu-model="[…]"` attribute is a
+     * content change rather than a new menu — the popover already open follows it instead of
+     * being rebuilt (ADR 0128 § 5, the same rule `GjsifyOptionList` has for a list).
+     */
+    private readonly _authored = new GjsifyMenu();
+    private _model: GioMenuModel | null = null;
+    private _tree: AdwMenuTree = [];
+    private _unwatch: (() => void) | null = null;
+
+    /** @param onItemsChanged what to do when the HELD menu mutates under the element. */
+    constructor(private readonly onItemsChanged: () => void) {}
+
+    /** The model itself, by identity — what `menuModel` answers and what a child is handed. */
+    get model(): GioMenuModel | null {
+        return this._model;
+    }
+
+    /** The snapshot every walker reads. Re-taken on each `items-changed`, never aliased. */
+    get tree(): AdwMenuTree {
+        return this._tree;
+    }
+
+    /**
+     * Whether there is anything to show — NOT whether there is a menu.
+     *
+     * `null` and an empty `Gio.Menu` are different menus and GTK treats them differently: an
+     * empty non-null model still builds a `GtkPopoverMenu` and still dissociates an
+     * application-set popover (measured, `MENU_MODEL_DOOR_VECTORS`). This answers the
+     * question the ROWS ask — "is there a row to draw" — and the elements ask
+     * `model === null` where GTK asks about the model.
+     */
+    get isEmpty(): boolean {
+        return this._tree.length === 0;
+    }
+
+    /**
+     * A PROPERTY write: a real model by identity, a JSON string into the authored menu,
+     * `null` for no menu — and a `TypeError` for an array, which this door no longer takes
+     * (`buildMenu` is how an array becomes a model now).
+     *
+     * A REFUSAL PUTS THE AUTHORED MENU BACK, because the door has already reconciled it by
+     * the time the tree can be refused: without the restore a refused string would leave the
+     * element holding a menu it threw over, and the next render would draw it.
+     */
+    write(value: unknown): void {
+        const before = this._tree;
+        const next = readMenuModelWrite(value, this._authored);
+        try {
+            if (next !== null) assertMenuRenderable(menuTree(next), ADW_MENU_SURFACE_WEB);
+        } catch (error) {
+            if (next === this._authored) this._authored.reconcile(before);
+            throw error;
+        }
+        this._adopt(next);
+    }
+
+    /**
+     * The `menu-model` ATTRIBUTE, through the same door. A `null` attribute is no menu.
+     *
+     * A REFUSAL AND A TYPO ARE STILL DIFFERENT THINGS: `parseMenuModel` is total because
+     * malformed JSON is an author slip that must not stop the element upgrading, while a
+     * `custom` item is well-formed, deliberate, and unhonourable on this surface.
+     */
+    writeMarkup(value: string | null): void {
+        const next = readMenuModelWrite(value, this._authored);
+        const refusals = next === null ? [] : menuRefusals(menuTree(next), ADW_MENU_SURFACE_WEB);
+        if (refusals.length === 0) {
+            this._adopt(next);
+            return;
+        }
+        // `console.error` is the browser's own channel for "this is wrong, the page
+        // continues" — and the alternative here is a row that lies.
+        console.error(`${ADW_MENU_SURFACE_WEB.name} cannot render this menu, so it has none:`);
+        for (const refusal of refusals) console.error(`  [${refusal.path.join('.')}] ${refusal.message}`);
+        this._adopt(null);
+    }
+
+    /** Hold `next`, snapshot it, and listen to it — the three that always happen together. */
+    private _adopt(next: GioMenuModel | null): void {
+        this._unwatch?.();
+        this._unwatch = null;
+        this._model = next;
+        this._tree = next === null ? [] : menuTree(next);
+        if (next === null) return;
+        // Re-adopting from inside the handler re-snapshots AND re-watches, which is what
+        // makes a section added by the mutation audible. The port's `emit` copies its
+        // handler list and skips ones disconnected mid-emission, so disconnecting here is
+        // safe (`gobject.ts`, `emit`).
+        this._unwatch = watchMenuModel(next, () => {
+            this._adopt(this._model);
+            this.onItemsChanged();
+        });
+    }
+}