@formicoidea/labre-core 0.41.0 → 0.42.0

package/dist/_pkgs/affine-widget-edgeless-toolbar/catalogue/artefact-catalogue-widget.js

@@ -37,9 +37,11 @@ import { TOUCH_TARGET_MIN_PX } from '../../affine-shared/consts/index.js';
 import { CATALOGUE_OTHER, translateKey } from '../../affine-shared/services/index.js';
 import { IS_MAC } from '../../global/env/index.js';
 import { getCommandIcon, CommandUsageIdentifier, getCommandsForSurface, isCommandAvailable, normalizeLegacyCombo, rankCommandsByUsage, runCommand, ShortcutOverrideIdentifier, WidgetComponent, WidgetViewExtension, } from '../../std/index.js';
+import { GfxControllerIdentifier } from '../../std/gfx/index.js';
 import { css, html, nothing, unsafeCSS } from 'lit';
 import { state } from 'lit/decorators.js';
 import { literal, unsafeStatic } from 'lit/static-html.js';
+import { armArtefact, armedArtefact, } from '../placement/artefact-placement-tool.js';
 import { CATALOGUE_CATEGORY_KEY_PREFIX, groupCommandsByCategory, humanizeCategory, } from './catalogue-groups.js';
 import { formatChord } from './chord-format.js';
 export const EDGELESS_ARTEFACT_CATALOGUE_WIDGET = 'edgeless-artefact-catalogue-widget';
@@ -122,6 +124,15 @@ let EdgelessArtefactCatalogueWidget = (() => {
                 // it is in another tree, and its own click already landed.
                 if (event.composedPath().includes(this))
                     return;
+                // So does the click that PLACES the artefact this panel just armed. A row
+                // taps to arm since 2026-09-16, and the gesture that finishes it is a click
+                // on the canvas — which is also the click-away. Read literally, the panel
+                // would dismiss itself halfway through its own interaction, and furnishing
+                // a diagram would cost a re-open per artefact: exactly the open-click-reopen
+                // the PO reversed on 27/08/2026. The placement returns to the default tool,
+                // so the NEXT click outside puts the panel away as it always has.
+                if (armedArtefact(this.std.get(GfxControllerIdentifier)))
+                    return;
                 this.closePanel();
             };
             /**
@@ -437,11 +448,19 @@ let EdgelessArtefactCatalogueWidget = (() => {
             return keys.length ? formatChord(keys, IS_MAC) : null;
         }
         /**
-         * Run the command. The panel STAYS OPEN.
+         * Arm an artefact, run anything else. The panel STAYS OPEN either way.
+         *
+         * An artefact row arms the placement tool exactly as the senior menu's does
+         * (PO decision, 2026-09-16): the ghost goes under the cursor and the click on
+         * the canvas says where. The panel is one gesture away from the board, so it
+         * can stay open behind the ghost.
          *
-         * `runCommand` is the one bottleneck (ADR 0008): the telemetry and the usage
-         * measure are emitted there, and `surface: 'catalogue'` is what makes this
-         * panel distinguishable from the sub-menu in the numbers.
+         * For everything else `runCommand` is the one bottleneck (ADR 0008): the
+         * telemetry and the usage measure are emitted there, and `surface:
+         * 'catalogue'` is what makes this panel distinguishable from the sub-menu in
+         * the numbers. An armed artefact reports at PLACEMENT instead, through the
+         * tool, so its `surface` reads `'senior-menu'` — the row it belongs to,
+         * whichever surface offered it.
          *
          * Staying open is the PO's call (recette, 27/08/2026), reversing the first
          * default: a catalogue is where a user furnishes a diagram, and furnishing is
@@ -450,6 +469,10 @@ let EdgelessArtefactCatalogueWidget = (() => {
          * or a click on the canvas.
          */
         _invoke(command) {
+            if (command.kind === 'artefact') {
+                armArtefact(this.std.get(GfxControllerIdentifier), command.owner, command);
+                return;
+            }
             runCommand(this.std, command, {
                 surface: 'catalogue',
                 source: 'toolbar:general',

package/dist/_pkgs/affine-widget-edgeless-toolbar/create-popper.js

@@ -19,6 +19,19 @@ export function createPopper(tagName, reference, options) {
         const popper = elMap.get(tagName);
         if (popper) {
             popper.cancel?.();
+            // The cached element is handed back with the DOM it rendered the LAST
+            // time it opened, and a menu whose content depends on anything but its
+            // own properties never recomputes it. The senior rows do: an
+            // `EdgelessCommandMenu` ranks its buttons by command usage, read per
+            // render precisely so the row reflects what the user did this morning —
+            // and the PO's recette of 2026-09-15 found that a command that had just
+            // earned its seat (`uml.importXmi`, one import in) only appeared after a
+            // reload, because reopening the row re-showed yesterday's DOM.
+            //
+            // One update per reopen, requested from the toggle and not from a render,
+            // so there is no loop: Lit coalesces it into the next microtask and the
+            // menu's own `render()` is what reads the measure again.
+            popper.element.requestUpdate?.();
             requestAnimationFrame(() => animateEnter(popper.element));
             return popper;
         }

package/dist/_pkgs/affine-widget-edgeless-toolbar/index.d.ts

@@ -9,4 +9,6 @@ export * from './draggable/index.js';
 export * from './edgeless-toolbar.js';
 export * from './extension/index.js';
 export * from './menu/command-menu.js';
+export * from './menu/senior-menu-selection.js';
 export * from './mixins/index.js';
+export * from './placement/index.js';

package/dist/_pkgs/affine-widget-edgeless-toolbar/index.js

@@ -9,4 +9,6 @@ export * from './draggable/index.js';
 export * from './edgeless-toolbar.js';
 export * from './extension/index.js';
 export * from './menu/command-menu.js';
+export * from './menu/senior-menu-selection.js';
 export * from './mixins/index.js';
+export * from './placement/index.js';

package/dist/_pkgs/affine-widget-edgeless-toolbar/menu/command-menu.d.ts

@@ -11,6 +11,12 @@ declare const EdgelessCommandMenu_base: typeof LitElement & import("../../global
  * There is now exactly one renderer, and it enumerates
  * `getCommandsForSurface(std, owner, 'senior-menu')`. A framework subclass
  * declares its owner and its tool type, nothing else. See `docs/adr/0008`.
+ *
+ * `SignalWatcher` and not the mixin's own effect: the mixin registers that
+ * effect in `connectedCallback`, and bails out when `edgeless` is still unset —
+ * which it always is here, because the senior button assigns it AFTER appending
+ * the popover. So the row is re-rendered by reading the tool signal in
+ * {@link _armed} during render, the way the senior buttons do it.
  */
 export declare abstract class EdgelessCommandMenu extends EdgelessCommandMenu_base {
     /**
@@ -27,9 +33,73 @@ export declare abstract class EdgelessCommandMenu extends EdgelessCommandMenu_ba
      * frame, and the usage measure it reads is the whole point — a list cached
      * across openings would show the user yesterday's ranking of what they did
      * this morning.
+     *
+     * "Per render" is only worth anything if reopening the row IS a render, and
+     * for a while it was not: `createPopper` hands a cached element back rather
+     * than building a new one, so the row re-showed the DOM of its last opening
+     * and a command that had just earned its seat waited for a reload. The reopen
+     * path now requests an update; this getter is what it exists to re-ask.
      */
     private get _selection();
     get commands(): CommandDescriptor[];
+    /** Whoever shows an owner's whole catalogue, when anything does. */
+    private get _catalogue();
+    /**
+     * How many buttons a keypress can land on: the commands, plus the overflow
+     * button on the rows that render one. Read from the same `_selection` the
+     * render does, so the highlight can never point past what is on screen.
+     */
+    private get _slots();
+    /**
+     * Which button the armed artefact sits on, `-1` when this owner has none
+     * armed. Read off the tool option signal the mixin already subscribes to, so
+     * arming from anywhere — this menu, a keystroke, the catalogue — lights the
+     * same button.
+     */
+    private get _armed();
+    /**
+     * What the row shows as highlighted: the armed artefact when there is one,
+     * otherwise wherever the keyboard walked. The armed command WINS, so the
+     * menu can never point at one artefact while the ghost under the cursor is
+     * another.
+     */
+    private get _highlight();
+    /**
+     * Move the highlight by one button, wrapping at both ends.
+     *
+     * Shift+S over an open senior menu is the analogue of Shift+S over the shape
+     * tool: the same keystroke walks the row backwards.
+     *
+     * With an artefact ARMED it walks the tool instead — same row, same
+     * direction, and the ghost under the cursor changes with the highlight. The
+     * row it walks then is the row's artefacts alone: an entry of kind `'tool'`
+     * arms a gesture of its own and has no ghost to offer.
+     *
+     * With nothing armed it moves a HIGHLIGHT and nothing else, because these
+     * commands each drop an artefact on the canvas and "run the next one on every
+     * press" would litter the board.
+     */
+    cycle(dir: 1 | -1): void;
+    /**
+     * Do whatever the keyboard points at, and say whether it did.
+     *
+     * It goes through the same {@link _invoke} the click goes through, so an
+     * artefact reached from the keyboard is armed exactly like a clicked one, and
+     * a command run from it is measured and reported exactly like a clicked one.
+     * With nothing highlighted it consumes nothing and the caller's own Enter
+     * stands.
+     */
+    activate(): boolean;
+    /**
+     * An artefact is ARMED, not created (PO decision, 2026-09-16): the ghost goes
+     * under the cursor and the click on the canvas says where. Everything else —
+     * a link tool, a toggle, an export — runs on the spot, as it always has.
+     *
+     * Arming deliberately emits nothing and measures nothing. The ONE emission
+     * point is still `runCommand`, which the placement tool calls when the
+     * artefact actually lands; a user who arms one and changes their mind has not
+     * used it.
+     */
     private _invoke;
     /**
      * What the button says on hover: its label, plus — when the command declares
@@ -53,5 +123,15 @@ export declare abstract class EdgelessCommandMenu extends EdgelessCommandMenu_ba
      */
     private _renderCatalogueButton;
     render(): import("lit-html").TemplateResult<1>;
+    /**
+     * Which button the keyboard points at, `-1` while it points at none.
+     *
+     * It starts empty and stays empty until a cycling key is pressed: a menu that
+     * opened with its first artefact already lit would read as a choice the user
+     * did not make. Nothing resets it on close because each opening builds a new
+     * menu element — the only case the popover hands the same one back is a
+     * re-open during the leave transition, where the row never left the screen.
+     */
+    private accessor _active;
 }
 export {};

package/dist/_pkgs/affine-widget-edgeless-toolbar/menu/command-menu.js

@@ -1,8 +1,46 @@
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
 import { ArtefactCatalogueProvider, translateKey, } from '../../affine-shared/services/index.js';
-import { CommandUsageIdentifier, getCommandIcon, getCommandsForSurface, runCommand, selectSeniorMenuCommands, } from '../../std/index.js';
+import { getCommandIcon, runCommand, } from '../../std/index.js';
 import { MoreHorizontalIcon } from '@blocksuite/icons/lit';
+import { SignalWatcher } from '../../global/lit/index.js';
 import { css, html, LitElement, nothing } from 'lit';
+import { state } from 'lit/decorators.js';
 import { EdgelessToolbarToolMixin } from '../mixins/tool.mixin.js';
+import { armArtefact, armedArtefact, cycleArmedArtefact, } from '../placement/artefact-placement-tool.js';
+import { seniorMenuSelection } from './senior-menu-selection.js';
 /**
  * The senior button sub-menu, rendered FROM the command registry.
  *
@@ -13,13 +51,30 @@ import { EdgelessToolbarToolMixin } from '../mixins/tool.mixin.js';
  * There is now exactly one renderer, and it enumerates
  * `getCommandsForSurface(std, owner, 'senior-menu')`. A framework subclass
  * declares its owner and its tool type, nothing else. See `docs/adr/0008`.
+ *
+ * `SignalWatcher` and not the mixin's own effect: the mixin registers that
+ * effect in `connectedCallback`, and bails out when `edgeless` is still unset —
+ * which it always is here, because the senior button assigns it AFTER appending
+ * the popover. So the row is re-rendered by reading the tool signal in
+ * {@link _armed} during render, the way the senior buttons do it.
  */
-export class EdgelessCommandMenu extends EdgelessToolbarToolMixin(LitElement) {
-    /**
-     * Typed as a group so a subclass can extend rather than replace it — the DDD
-     * palettes narrow `--labre-command-menu-gap`.
-     */
-    static { this.styles = css `
+let EdgelessCommandMenu = (() => {
+    let _classSuper = EdgelessToolbarToolMixin(SignalWatcher(LitElement));
+    let __active_decorators;
+    let __active_initializers = [];
+    let __active_extraInitializers = [];
+    return class EdgelessCommandMenu extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            __active_decorators = [state()];
+            __esDecorate(this, null, __active_decorators, { kind: "accessor", name: "_active", static: false, private: false, access: { has: obj => "_active" in obj, get: obj => obj._active, set: (obj, value) => { obj._active = value; } }, metadata: _metadata }, __active_initializers, __active_extraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        /**
+         * Typed as a group so a subclass can extend rather than replace it — the DDD
+         * palettes narrow `--labre-command-menu-gap`.
+         */
+        static { this.styles = css `
     :host {
       display: flex;
       z-index: -1;
@@ -41,100 +96,234 @@ export class EdgelessCommandMenu extends EdgelessToolbarToolMixin(LitElement) {
       height: 24px;
     }
   `; }
-    /**
-     * The buttons, and whether the owner outgrew the fourteen slots.
-     *
-     * Recomputed per render on purpose: it opens with the popover, not with a
-     * frame, and the usage measure it reads is the whole point — a list cached
-     * across openings would show the user yesterday's ranking of what they did
-     * this morning.
-     */
-    get _selection() {
-        const std = this.edgeless.std;
-        const usage = std.getOptional(CommandUsageIdentifier);
-        return selectSeniorMenuCommands(getCommandsForSurface(std, this.owner, 'senior-menu'), getCommandsForSurface(std, this.owner, 'catalogue'), id => usage?.statsOf(id));
-    }
-    get commands() {
-        return this._selection.commands;
-    }
-    _invoke(command) {
-        // The ONE emission point: no `_track()` helper anywhere in the menus.
-        runCommand(this.edgeless.std, command, {
-            surface: 'senior-menu',
-            source: 'toolbar:general',
-        });
-    }
-    /**
-     * What the button says on hover: its label, plus — when the command declares
-     * one — the sentence that tells the user what its GESTURE means.
-     *
-     * That second line is M1 of `docs/adr/0010`: a link tool whose drag decides
-     * the orientation of a persisted relation has to SAY so, or the direction it
-     * writes is a by-product rather than a statement. The library still puts no
-     * words in a framework's mouth — both halves are the framework's own keys and
-     * fallbacks, resolved through the host's catalogue.
-     */
-    _tooltip(command) {
-        const label = translateKey(this.edgeless.std, command.labelKey, command.labelFallback);
-        const { descriptionKey, descriptionFallback } = command;
-        if (!descriptionKey && !descriptionFallback)
-            return label;
-        const hint = descriptionKey
-            ? translateKey(this.edgeless.std, descriptionKey, descriptionFallback)
-            : descriptionFallback;
-        // A key with no catalogue entry and no fallback resolves to itself — show
-        // the label alone rather than a raw i18n key under it.
-        if (!hint || hint === descriptionKey)
-            return label;
-        // Inline, not a class: the template is rendered inside the icon button's
-        // own shadow root, where this component's stylesheet does not reach.
-        return html `${label}<span
+        /**
+         * The buttons, and whether the owner outgrew the fourteen slots.
+         *
+         * Recomputed per render on purpose: it opens with the popover, not with a
+         * frame, and the usage measure it reads is the whole point — a list cached
+         * across openings would show the user yesterday's ranking of what they did
+         * this morning.
+         *
+         * "Per render" is only worth anything if reopening the row IS a render, and
+         * for a while it was not: `createPopper` hands a cached element back rather
+         * than building a new one, so the row re-showed the DOM of its last opening
+         * and a command that had just earned its seat waited for a reload. The reopen
+         * path now requests an update; this getter is what it exists to re-ask.
+         */
+        get _selection() {
+            return seniorMenuSelection(this.edgeless.std, this.owner);
+        }
+        get commands() {
+            return this._selection.commands;
+        }
+        /** Whoever shows an owner's whole catalogue, when anything does. */
+        get _catalogue() {
+            return this.edgeless.std.getOptional(ArtefactCatalogueProvider);
+        }
+        /**
+         * How many buttons a keypress can land on: the commands, plus the overflow
+         * button on the rows that render one. Read from the same `_selection` the
+         * render does, so the highlight can never point past what is on screen.
+         */
+        get _slots() {
+            const { commands, overflow } = this._selection;
+            return commands.length + (overflow && this._catalogue ? 1 : 0);
+        }
+        /**
+         * Which button the armed artefact sits on, `-1` when this owner has none
+         * armed. Read off the tool option signal the mixin already subscribes to, so
+         * arming from anywhere — this menu, a keystroke, the catalogue — lights the
+         * same button.
+         */
+        get _armed() {
+            const armed = armedArtefact(this.gfx);
+            if (!armed || armed.owner !== this.owner)
+                return -1;
+            return this._selection.commands.findIndex(command => command.id === armed.command.id);
+        }
+        /**
+         * What the row shows as highlighted: the armed artefact when there is one,
+         * otherwise wherever the keyboard walked. The armed command WINS, so the
+         * menu can never point at one artefact while the ghost under the cursor is
+         * another.
+         */
+        get _highlight() {
+            const armed = this._armed;
+            return armed >= 0 ? armed : this._active;
+        }
+        /**
+         * Move the highlight by one button, wrapping at both ends.
+         *
+         * Shift+S over an open senior menu is the analogue of Shift+S over the shape
+         * tool: the same keystroke walks the row backwards.
+         *
+         * With an artefact ARMED it walks the tool instead — same row, same
+         * direction, and the ghost under the cursor changes with the highlight. The
+         * row it walks then is the row's artefacts alone: an entry of kind `'tool'`
+         * arms a gesture of its own and has no ghost to offer.
+         *
+         * With nothing armed it moves a HIGHLIGHT and nothing else, because these
+         * commands each drop an artefact on the canvas and "run the next one on every
+         * press" would litter the board.
+         */
+        cycle(dir) {
+            if (this._armed >= 0) {
+                cycleArmedArtefact(this.gfx, dir);
+                return;
+            }
+            const slots = this._slots;
+            if (slots === 0)
+                return;
+            if (this._active < 0) {
+                // Nothing highlighted yet: forwards enters on the first button,
+                // backwards on the last — the "previous" the shape tool gives too.
+                this._active = dir === 1 ? 0 : slots - 1;
+                return;
+            }
+            this._active = (this._active + dir + slots) % slots;
+        }
+        /**
+         * Do whatever the keyboard points at, and say whether it did.
+         *
+         * It goes through the same {@link _invoke} the click goes through, so an
+         * artefact reached from the keyboard is armed exactly like a clicked one, and
+         * a command run from it is measured and reported exactly like a clicked one.
+         * With nothing highlighted it consumes nothing and the caller's own Enter
+         * stands.
+         */
+        activate() {
+            const highlight = this._highlight;
+            if (highlight < 0)
+                return false;
+            const { commands, overflow } = this._selection;
+            const command = commands[highlight];
+            if (command) {
+                this._invoke(command);
+                return true;
+            }
+            const catalogue = this._catalogue;
+            if (overflow && catalogue) {
+                catalogue.open(this.owner);
+                return true;
+            }
+            return false;
+        }
+        /**
+         * An artefact is ARMED, not created (PO decision, 2026-09-16): the ghost goes
+         * under the cursor and the click on the canvas says where. Everything else —
+         * a link tool, a toggle, an export — runs on the spot, as it always has.
+         *
+         * Arming deliberately emits nothing and measures nothing. The ONE emission
+         * point is still `runCommand`, which the placement tool calls when the
+         * artefact actually lands; a user who arms one and changes their mind has not
+         * used it.
+         */
+        _invoke(command) {
+            if (command.kind === 'artefact') {
+                armArtefact(this.gfx, this.owner, command);
+                return;
+            }
+            // The ONE emission point: no `_track()` helper anywhere in the menus.
+            runCommand(this.edgeless.std, command, {
+                surface: 'senior-menu',
+                source: 'toolbar:general',
+            });
+        }
+        /**
+         * What the button says on hover: its label, plus — when the command declares
+         * one — the sentence that tells the user what its GESTURE means.
+         *
+         * That second line is M1 of `docs/adr/0010`: a link tool whose drag decides
+         * the orientation of a persisted relation has to SAY so, or the direction it
+         * writes is a by-product rather than a statement. The library still puts no
+         * words in a framework's mouth — both halves are the framework's own keys and
+         * fallbacks, resolved through the host's catalogue.
+         */
+        _tooltip(command) {
+            const label = translateKey(this.edgeless.std, command.labelKey, command.labelFallback);
+            const { descriptionKey, descriptionFallback } = command;
+            if (!descriptionKey && !descriptionFallback)
+                return label;
+            const hint = descriptionKey
+                ? translateKey(this.edgeless.std, descriptionKey, descriptionFallback)
+                : descriptionFallback;
+            // A key with no catalogue entry and no fallback resolves to itself — show
+            // the label alone rather than a raw i18n key under it.
+            if (!hint || hint === descriptionKey)
+                return label;
+            // Inline, not a class: the template is rendered inside the icon button's
+            // own shadow root, where this component's stylesheet does not reach.
+            return html `${label}<span
         style="display:block;max-width:220px;margin-top:2px;opacity:0.75;font-size:11px;line-height:1.35;white-space:normal"
         >${hint}</span
       >`;
-    }
-    /**
-     * The way out of a menu that no longer shows everything.
-     *
-     * It appears only past the cap, and only when something answers
-     * {@link ArtefactCatalogueProvider}: a button that opens nothing is a dead
-     * control, and the thirteen ranked slots are only defensible as a *shortcut*
-     * to a catalogue the user can still reach in full. Thirteen plus this one is
-     * fourteen — the overflowed row is exactly as wide as the cap.
-     */
-    _renderCatalogueButton() {
-        const std = this.edgeless.std;
-        const catalogue = std.getOptional(ArtefactCatalogueProvider);
-        if (!catalogue)
-            return nothing;
-        const label = translateKey(std, 'com.labre.catalogue.open', 'More artefacts…');
-        return html `<edgeless-tool-icon-button
+        }
+        /**
+         * The way out of a menu that no longer shows everything.
+         *
+         * It appears only past the cap, and only when something answers
+         * {@link ArtefactCatalogueProvider}: a button that opens nothing is a dead
+         * control, and the thirteen ranked slots are only defensible as a *shortcut*
+         * to a catalogue the user can still reach in full. Thirteen plus this one is
+         * fourteen — the overflowed row is exactly as wide as the cap.
+         */
+        _renderCatalogueButton(index) {
+            const std = this.edgeless.std;
+            const catalogue = this._catalogue;
+            if (!catalogue)
+                return nothing;
+            const label = translateKey(std, 'com.labre.catalogue.open', 'More artefacts…');
+            return html `<edgeless-tool-icon-button
       .tooltip=${html `${label}<span
           style="display:block;max-width:220px;margin-top:2px;opacity:0.75;font-size:11px;line-height:1.35;white-space:normal"
           >${translateKey(std, 'com.labre.catalogue.open.description', 'This framework offers more than the menu can show.')}</span
         >`}
+      .active=${index === this._highlight}
+      .hoverState=${index === this._highlight}
       @click=${() => catalogue.open(this.owner)}
     >
       ${MoreHorizontalIcon()}
     </edgeless-tool-icon-button>`;
-    }
-    render() {
-        const std = this.edgeless.std;
-        const { commands, overflow } = this._selection;
-        return html `
+        }
+        render() {
+            const std = this.edgeless.std;
+            const { commands, overflow } = this._selection;
+            const highlight = this._highlight;
+            return html `
       <edgeless-slide-menu>
         <div class="menu-content">
           <div class="button-group-container">
-            ${commands.map(command => html `<edgeless-tool-icon-button
+            ${commands.map((command, index) => html `<edgeless-tool-icon-button
+                  data-command-id=${command.id}
                   .tooltip=${this._tooltip(command)}
+                  .active=${index === highlight}
+                  .hoverState=${index === highlight}
                   @click=${() => this._invoke(command)}
                 >
                   ${getCommandIcon(std, command.iconKey)}
                 </edgeless-tool-icon-button>`)}
-            ${overflow ? this._renderCatalogueButton() : nothing}
+            ${overflow ? this._renderCatalogueButton(commands.length) : nothing}
           </div>
         </div>
       </edgeless-slide-menu>
     `;
-    }
-}
+        }
+        #_active_accessor_storage = __runInitializers(this, __active_initializers, -1);
+        /**
+         * Which button the keyboard points at, `-1` while it points at none.
+         *
+         * It starts empty and stays empty until a cycling key is pressed: a menu that
+         * opened with its first artefact already lit would read as a choice the user
+         * did not make. Nothing resets it on close because each opening builds a new
+         * menu element — the only case the popover hands the same one back is a
+         * re-open during the leave transition, where the row never left the screen.
+         */
+        get _active() { return this.#_active_accessor_storage; }
+        set _active(value) { this.#_active_accessor_storage = value; }
+        constructor() {
+            super(...arguments);
+            __runInitializers(this, __active_extraInitializers);
+        }
+    };
+})();
+export { EdgelessCommandMenu };

package/dist/_pkgs/affine-widget-edgeless-toolbar/menu/senior-menu-selection.d.ts

@@ -0,0 +1,15 @@
+import { type AnyCommandDescriptor, type BlockStdScope, type CommandOwner } from '../../std/index.js';
+/**
+ * The row one framework's senior sub-menu shows, and whether the owner outgrew
+ * its slots — `selectSeniorMenuCommands` fed from the registry and the user's
+ * own usage measure.
+ *
+ * It lives beside the menu rather than inside it because the ROW is now read by
+ * two things: the popover that draws it, and the placement tool that cycles
+ * along it on Shift+S. One reading, so the ghost can never step onto a button
+ * the menu does not show.
+ */
+export declare function seniorMenuSelection(std: BlockStdScope, owner: CommandOwner): {
+    commands: AnyCommandDescriptor[];
+    overflow: boolean;
+};

package/dist/_pkgs/affine-widget-edgeless-toolbar/menu/senior-menu-selection.js

@@ -0,0 +1,15 @@
+import { CommandUsageIdentifier, getCommandsForSurface, selectSeniorMenuCommands, } from '../../std/index.js';
+/**
+ * The row one framework's senior sub-menu shows, and whether the owner outgrew
+ * its slots — `selectSeniorMenuCommands` fed from the registry and the user's
+ * own usage measure.
+ *
+ * It lives beside the menu rather than inside it because the ROW is now read by
+ * two things: the popover that draws it, and the placement tool that cycles
+ * along it on Shift+S. One reading, so the ghost can never step onto a button
+ * the menu does not show.
+ */
+export function seniorMenuSelection(std, owner) {
+    const usage = std.getOptional(CommandUsageIdentifier);
+    return selectSeniorMenuCommands(getCommandsForSurface(std, owner, 'senior-menu'), getCommandsForSurface(std, owner, 'catalogue'), id => usage?.statsOf(id));
+}