@jxsuite/studio 4.1.0 → 5.0.0

package/src/panels/settings-menu.ts

@@ -17,41 +17,38 @@
  * own definition site — which is state the command already validates, not a second vocabulary
  * (§12.5).
  *
- * **A parent row runs its own command AND owns a submenu**, which the APG menu pattern does not
- * describe and Spectrum's stock `slot="submenu"` forbids outright:
- * `Menu.handlePointerBasedSelection` bails on `hasSubmenu`, so a parent emits no `change`, and
- * `MenuItem.handleSubmenuChange` reports the PARENT's value to the outer menu, which would break
- * the deep link as well. So the submenu is a second `renderPopover` and the parent keeps its own
- * `@click`. The deviation is recorded in `specs/studio-ui-guidelines.md` §8.4 and §14; nothing is
- * unreachable by keyboard because Enter runs the row, ArrowRight reaches every child, and every
- * child is also in the settings document's own inner nav.
+ * **A parent row runs its own command AND owns a submenu.** The APG menu pattern does not describe
+ * that and Spectrum's stock submenu forbade it outright; the kit's `jx-menu-item` makes it the rule
+ * (`ui.md` §5.1), so the deviation `specs/studio-ui-guidelines.md` §8.4 records is now what the
+ * element does rather than what this file hand-rolls around it. Nothing is unreachable by keyboard:
+ * Enter runs the row, ArrowRight reaches every child, and every child is also in the settings
+ * document's own inner nav.
  *
- * **There is no hover-intent timer, deliberately.** A timer is this suite's largest flake source
- * and buys a nicety rather than a capability; a submenu closes when the pointer enters a SIBLING
- * row, so diagonal travel into an open submenu crosses nothing that would shut it. Do not "fix"
- * this by adding one.
- *
- * The machinery is `editor/context-menu.ts:828-1094`'s, with its function names kept, so folding
- * both onto a shared `ui/menu.ts` is a move rather than a rewrite.
+ * The menu is the `menu` surface (`surfaces/menu.json`, through `surfaces/menu.ts`). What is left
+ * here is the projection — which records, which sections, what each row runs — and where the panel
+ * hangs: off the gear's right edge, its bottom flush with the rail's, which is also the floor every
+ * submenu keeps above the status bar. The section subscription lives for as long as the menu is up:
+ * six of Project Settings' sections are contributed by extensions and register a tick after the
+ * built-ins (`settings/extension-sections.ts`), so a menu opened in that window would otherwise be
+ * permanently short. It deliberately does NOT call the sync itself: opening a menu must not do IO.
  *
  * @docs studio/interface/preferences
  * @docs studio/projects/settings
  */
 
-import { html, nothing } from "lit-html";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { activeRegistry } from "../commands/active-registry";
 import { LEVELS } from "../commands/levels";
 import { notify } from "../services/notify";
 import { onSettingsDocumentChanged, sortedSettingsSections } from "../settings/section-registry";
 import { PREFERENCES_SECTIONS } from "../settings/preferences-sections";
-import { renderPopover } from "../ui/layers";
+import { openMenu } from "../surfaces/menu";
 import { REGION_ATTR } from "../ui/regions";
 import { rectOf } from "../utils/geometry";
 
-import type { TemplateResult } from "lit-html";
-import type { AnyCommand, CommandRegistry } from "../commands/registry";
+import type { CommandRegistry } from "../commands/registry";
 import type { Level } from "../commands/levels";
+import type { MenuHandle, MenuRowProjection } from "../surfaces/menu";
 
 /** The placement the rail's gear renders. One definition site for the string. */
 export const SETTINGS_MENU_PLACEMENT = "settings/menu" as const;
@@ -62,36 +59,9 @@ interface MenuSection {
   label: string;
 }
 
-/** One row of the root menu. Everything it prints comes off the record. */
-interface MenuRow {
-  command: AnyCommand;
-  enabled: boolean;
-  reason: string | undefined;
-  chord: string | undefined;
-  /** Whether a divider opens this row's LEVEL group. */
-  dividerAbove: boolean;
-  /** The values this command's own `section` argument accepts. Empty ⇒ no submenu. */
-  sections: readonly MenuSection[];
-}
-
-type PopoverHandle = ReturnType<typeof renderPopover>;
-
-let _root: PopoverHandle | null = null;
-let _sub: PopoverHandle | null = null;
-let _rows: MenuRow[] = [];
-let _activeIdx = 0;
-/** Which root row owns the open submenu; -1 = none. */
-let _subIdx = -1;
-let _subActiveIdx = 0;
-let _focus: "root" | "sub" = "root";
-let _opener: HTMLElement | null = null;
-let _rerender: (() => void) | null = null;
+let _menu: MenuHandle | null = null;
 let _unsubscribe: (() => void) | null = null;
-let _outside: ((e: MouseEvent) => void) | null = null;
-let _x = 0;
-let _y = 0;
-let _sx = 0;
-let _sy = 0;
+let _rerender: (() => void) | null = null;
 
 // ─── Where a submenu's rows come from ─────────────────────────────────────────
 
@@ -116,39 +86,6 @@ function menuSectionsFor(id: string): readonly MenuSection[] {
   return SECTION_SOURCES[id]?.() ?? [];
 }
 
-// ─── Rows ─────────────────────────────────────────────────────────────────────
-
-/**
- * Ask the registry what belongs in the gear right now, ordered level-first.
- *
- * `forPlacement` already filters by `when` and sorts by `group` then title; `toSorted` is stable,
- * so that order survives inside each level group. The divider falls where the LEVEL changes, which
- * is the same boundary the rail's own panel groups draw — and the reason a menu may hold two levels
- * where a pinned slot may not.
- */
-function buildSettingsMenuRows(registry: CommandRegistry): MenuRow[] {
-  const commands = [...registry.forPlacement(SETTINGS_MENU_PLACEMENT)].toSorted(
-    (a, b) => LEVELS.indexOf(a.level) - LEVELS.indexOf(b.level),
-  );
-  let level: Level | undefined;
-  return commands.map((command, index) => {
-    const dividerAbove = index > 0 && command.level !== level;
-    ({ level } = command);
-    const enabled = registry.isEnabled(command.id);
-    const chord = registry.keymap.formatBinding(command.id);
-    return {
-      // A chord that just restates the row's own name teaches nothing and reads as a stutter.
-      chord: chord?.toLowerCase() === command.title.toLowerCase() ? undefined : chord,
-      command,
-      dividerAbove,
-      enabled,
-      reason: enabled ? undefined : registry.disabledReason(command.id),
-      // A row whose command cannot run offers no sections: every one of them runs that same refusal.
-      sections: enabled ? menuSectionsFor(command.id) : [],
-    };
-  });
-}
-
 // ─── Running ──────────────────────────────────────────────────────────────────
 
 /**
@@ -176,567 +113,91 @@ function runRow(id: string, args?: Record<string, unknown>): void {
   });
 }
 
-// ─── Focus ────────────────────────────────────────────────────────────────────
-
-/** The rendered root rows, in order. */
-function rootItems(): HTMLElement[] {
-  return _root
-    ? [..._root.host.querySelectorAll<HTMLElement>("sp-menu-item[data-command-id]")]
-    : [];
-}
-
-/** The rendered submenu rows, in order. */
-function subItems(): HTMLElement[] {
-  return _sub ? [..._sub.host.querySelectorAll<HTMLElement>("sp-menu-item[data-section-key]")] : [];
-}
-
-/**
- * Move the roving tabindex (and the caret) to `index`, wrapping at both ends.
- *
- * `tabIndex` is written BEFORE `.focus()`: an `sp-menu-item` is an undefined custom element until
- * `ui/spectrum.ts` loads, and a plain unknown element is only focusable once it has one.
- */
-function focusItem(items: HTMLElement[], index: number): number {
-  if (items.length === 0) {
-    return 0;
-  }
-  const next = ((index % items.length) + items.length) % items.length;
-  for (const [at, item] of items.entries()) {
-    item.tabIndex = at === next ? 0 : -1;
-    item.toggleAttribute("focused", at === next);
-  }
-  items[next]?.focus();
-  return next;
-}
-
-function focusRoot(index: number): void {
-  _activeIdx = focusItem(rootItems(), index);
-}
-
-function focusSub(index: number): void {
-  _subActiveIdx = focusItem(subItems(), index);
-}
-
-/** How many frames to keep re-applying a freshly opened submenu's caret before giving up. */
-const FOCUS_SETTLE_FRAMES = 8;
+// ─── Rows ─────────────────────────────────────────────────────────────────────
 
 /**
- * Move a freshly opened submenu's caret, and keep asking until it lands.
+ * Ask the registry what belongs in the gear right now, ordered level-first, and project each record
+ * for the surface.
  *
- * `sp-menu-item.focus()` is a no-op until Spectrum has finished setting the item up, and `sp-menu`
- * runs its own roving-tabindex pass over its items after they connect — so applying once, even a
- * frame later, is still too early. The symptom is precise and bad: the logical caret is right
- * (Enter runs the correct section) while the focus RING stays on the parent row, so the keyboard
- * and the screen disagree about where you are. `panels/tab-strip.ts` records meeting the same
- * component behaviour from the other side.
- *
- * Rather than guess the settle point, this re-applies on each of the next few frames and stops the
- * moment the browser agrees. The first pass is synchronous so a test in happy-dom — where the
- * element is inert and focus is immediate — sees it on the same tick and never schedules a second.
- * Every pass is guarded, so a pointer that has since moved to another row is not yanked back.
- *
- * @param owner Which root row's submenu this is — the guard against a stale deferral.
+ * `forPlacement` already filters by `when` and sorts by `group` then title; `toSorted` is stable,
+ * so that order survives inside each level group. The divider falls where the LEVEL changes, which
+ * is the same boundary the rail's own panel groups draw — and the reason a menu may hold two levels
+ * where a pinned slot may not.
  */
-function focusSubSettled(index: number, owner: number): void {
-  focusSub(index);
-  let attempts = 0;
-  const settle = () => {
-    if (_focus !== "sub" || _subIdx !== owner || !_sub) {
-      return;
-    }
-    const wanted = subItems()[_subActiveIdx];
-    if (!wanted || document.activeElement === wanted) {
-      return;
+function buildSettingsMenuRows(registry: CommandRegistry): MenuRowProjection[] {
+  const commands = [...registry.forPlacement(SETTINGS_MENU_PLACEMENT)].toSorted(
+    (a, b) => LEVELS.indexOf(a.level) - LEVELS.indexOf(b.level),
+  );
+  let level: Level | undefined;
+  return commands.map((command, index) => {
+    const dividerAbove = index > 0 && command.level !== level;
+    ({ level } = command);
+    const enabled = registry.isEnabled(command.id);
+    const chord = registry.keymap.formatBinding(command.id);
+    // A chord that just restates the row's own name teaches nothing and reads as a stutter.
+    const taught = chord && chord.toLowerCase() !== command.title.toLowerCase() ? chord : undefined;
+    const reason = enabled ? undefined : registry.disabledReason(command.id);
+    const { id } = command;
+    const row: MenuRowProjection = {
+      // A row whose command cannot run offers no sections: every one of them runs that same refusal.
+      children: enabled
+        ? menuSectionsFor(id).map((section) => ({
+            destructive: false,
+            disabled: false,
+            dividerAbove: false,
+            id: `${id}:${section.key}`,
+            // Named by the argument value it passes, never by a reworded command title.
+            run: () => runRow(id, { section: section.key }),
+            title: section.label,
+          }))
+        : [],
+      destructive: command.destructive === true,
+      disabled: !enabled,
+      dividerAbove,
+      id,
+      // A row that owns sections still ACTIVATES, with no arguments: "Open Project Settings" opens
+      // Project Settings on its default section, and the submenu is a second way in.
+      run: () => runRow(id),
+      submenuLabel: `Sections of ${command.title}`,
+      title: command.title,
+    };
+    if (taught) {
+      row.chord = taught;
     }
-    focusSub(_subActiveIdx);
-    attempts += 1;
-    if (attempts < FOCUS_SETTLE_FRAMES) {
-      requestAnimationFrame(settle);
+    if (reason) {
+      row.requires = reason;
     }
-  };
-  requestAnimationFrame(settle);
+    return row;
+  });
 }
 
 // ─── Geometry ─────────────────────────────────────────────────────────────────
 
-/**
- * Clamp a rendered popover into the viewport, writing the result back into module state.
- *
- * The predecessor mutated the `x`/`y` its own render had closed over, which is why
- * `editor/context-menu.ts:851-861` says re-rendering to move focus would re-run the placement from
- * stale coordinates. Writing into `_x`/`_y` makes `renderRoot()` idempotent instead, which is what
- * lets the section subscription repaint an open submenu freely.
- *
- * **Both axes are floored**, not just capped. Project Settings has ~16 sections once extensions
- * have contributed, and a submenu taller than the viewport would otherwise be pushed to a negative
- * `top` — its first rows off the top of the window, unreachable. The floor plus the
- * `.settings-submenu` height cap is what keeps the whole list reachable.
- */
 /**
  * The lowest edge any menu in this stack may reach.
  *
  * The trigger's REGION, not the viewport. The gear sits in the rail, whose bottom is the status
- * bar's top — so clamping to the viewport lets a tall submenu run down over the status bar while
- * the root menu sits neatly above it. One floor for both levels is what keeps the stack looking
- * like one surface.
+ * bar's top — so clamping to the viewport would let a tall submenu run down over the status bar
+ * while the root menu sits neatly above it. One floor for both levels is what keeps the stack
+ * looking like one surface, and it is expressed through the shell's own addressing grammar rather
+ * than a selector into markup — so a menu button in another region would align to that one without
+ * this function learning about it.
  */
-function menuFloor(): number {
-  const host = _opener?.closest<HTMLElement>(`[${REGION_ATTR}]`);
+function menuFloor(anchor: HTMLElement): number {
+  const host = anchor.closest<HTMLElement>(`[${REGION_ATTR}]`);
   return host ? rectOf(host).bottom : window.innerHeight;
 }
 
-/** Keep a popover inside the menu area — floored as well as capped, on both axes. */
-function clampIntoMenuArea(
-  box: DOMRect,
-  origin: { x: number; y: number },
-): { x: number; y: number } {
-  return {
-    x: Math.max(4, Math.min(origin.x, window.innerWidth - box.width - 4)),
-    y: Math.max(4, Math.min(origin.y, menuFloor() - box.height)),
-  };
-}
-
-/**
- * Where the root menu wants to sit: hanging off the trigger's right edge, with its BOTTOM flush
- * with the bottom of the region the trigger lives in.
- *
- * Not the trigger's own bottom, and not "below the trigger". The gear is the last control in a
- * full-height rail whose foot abuts the status bar, so a menu dropped below it would be off-screen
- * and one aligned to the button would float six pixels of `.rail-footer` padding clear of the
- * status bar. Aligning to the REGION is what puts it flush, and it is expressed through the shell's
- * own addressing grammar rather than a selector into markup — so a menu button in another region
- * would align to that one without this function learning about it.
- */
-function rootOrigin(box: DOMRect): { x: number; y: number } {
-  if (!_opener) {
-    return { x: _x, y: _y };
-  }
-  const anchor = rectOf(_opener);
-  return { x: anchor.right + 4, y: menuFloor() - box.height };
-}
-
-/**
- * Place a popover, now and again after the browser has laid it out.
- *
- * **The second pass is the one that works.** A popover measures 0×0 until layout runs, and layout
- * does not run inside the call that rendered it — so the synchronous pass clamps against a
- * zero-height box and parks the menu at the bottom edge of the window, which is precisely where a
- * control at the foot of a full-height rail puts it. `editor/context-menu.ts` does its clamp inside
- * a `requestAnimationFrame` for this reason; keeping the first pass as well costs nothing and means
- * a caller that CAN measure (a repaint of an already-open menu) is right immediately.
- *
- * Running twice is safe because the clamp is idempotent and reads its own output: a first pass that
- * parked the origin too low is pulled back up by the second pass's `Math.min`.
- *
- * @param apply Receives the clamped origin — it writes module state and the element's style.
- */
-function placePopover(
-  el: HTMLElement,
-  desired: (box: DOMRect) => { x: number; y: number },
-  apply: (at: { x: number; y: number }) => void,
-): void {
-  const pass = () => {
-    const box = rectOf(el);
-    apply(clampIntoMenuArea(box, desired(box)));
-  };
-  pass();
-  requestAnimationFrame(() => {
-    if (el.isConnected) {
-      pass();
-    }
-  });
-}
-
-// ─── Templates ────────────────────────────────────────────────────────────────
-
-/**
- * The row's trailing cell: its chord, its chevron, or both.
- *
- * ONE slotted node, not two. Spectrum's menu-item grid gives `[slot=value]` a single cell with
- * `justify-self: end`, and that applies to each assigned node independently — so a `<kbd>` and a
- * chevron both slotted directly land on top of each other. Wrapping them makes the cell one flex
- * row, which is also where the gap between the title and the chord comes from.
- */
-function valueTpl(chord: string | undefined, hasSections: boolean) {
-  if (!chord && !hasSections) {
-    return nothing;
-  }
-  return html`<span slot="value" class="settings-menu-value"
-    >${chord ? html`<kbd class="cmd-chord">${chord}</kbd>` : nothing}${
-      hasSections
-        ? html`<sp-icon-chevron-right size="s" aria-hidden="true"></sp-icon-chevron-right>`
-        : nothing
-    }</span
-  >`;
-}
-
-/**
- * One root row.
- *
- * A row that owns sections still ACTIVATES — `@click` runs its own command with no arguments, so
- * "Open Project Settings" opens Project Settings on its default section and the submenu is a second
- * way in rather than a replacement for the first. `aria-haspopup`/`aria-expanded` bind to `nothing`
- * on a row without sections so lit removes the attributes rather than emitting
- * `aria-haspopup="false"`.
- */
-function rowTemplate(row: MenuRow, index: number): TemplateResult {
-  const hasSections = row.sections.length > 0;
-  const expanded = hasSections ? (_subIdx === index ? "true" : "false") : nothing;
-  return html`${row.dividerAbove ? html`<sp-menu-divider role="separator"></sp-menu-divider>` : nothing}<sp-menu-item
-      role="menuitem"
-      data-command-id=${row.command.id}
-      tabindex=${index === _activeIdx ? 0 : -1}
-      ?focused=${index === _activeIdx}
-      ?disabled=${!row.enabled}
-      aria-disabled=${row.enabled ? "false" : "true"}
-      aria-haspopup=${hasSections ? "menu" : nothing}
-      aria-expanded=${expanded}
-      @mouseenter=${() => {
-        if (hasSections) {
-          openSubmenu(index);
-        } else {
-          closeSubmenu({ restoreFocus: false });
-        }
-      }}
-      @click=${() => activateRow(index)}
-      >${row.command.title}${valueTpl(row.chord, hasSections)}${
-        row.reason ? html`<span slot="description">Needs ${row.reason}</span>` : nothing
-      }</sp-menu-item
-    >`;
-}
-
-/** One submenu row — named by the argument value it passes, never by a reworded command title. */
-function sectionTemplate(parent: MenuRow, section: MenuSection, index: number): TemplateResult {
-  return html`<sp-menu-item
-    role="menuitem"
-    data-section-key=${section.key}
-    tabindex=${index === _subActiveIdx ? 0 : -1}
-    ?focused=${index === _subActiveIdx}
-    @click=${() => activateSection(parent, section)}
-    >${section.label}</sp-menu-item
-  >`;
-}
-
-// ─── Rendering ────────────────────────────────────────────────────────────────
-
-/** Draw (or redraw) the root menu at `_x`/`_y`, clamping once the nodes exist. */
-function renderRoot(): void {
-  if (!_root) {
-    return;
-  }
-  _root.update(html`<sp-popover open style="position:fixed;z-index:10000;left:${_x}px;top:${_y}px">
-    <sp-menu class="settings-menu" role="menu" aria-label="Settings"
-      >${_rows.map((row, index) => rowTemplate(row, index))}</sp-menu
-    >
-  </sp-popover>`);
-  const popover = _root.host.querySelector<HTMLElement>("sp-popover");
-  if (popover) {
-    placePopover(popover, rootOrigin, (at) => {
-      ({ x: _x, y: _y } = at);
-      popover.style.left = `${_x}px`;
-      popover.style.top = `${_y}px`;
-    });
-  }
-}
-
-/** Draw (or redraw) the open submenu. Re-applies the roving focus at a clamped index. */
-function renderSub(): void {
-  const parent = _rows[_subIdx];
-  if (!_sub || !parent) {
-    return;
-  }
-  const { sections } = parent;
-  _subActiveIdx = Math.min(_subActiveIdx, Math.max(0, sections.length - 1));
-  _sub.update(html`<sp-popover
-    open
-    class="settings-submenu"
-    style="position:fixed;z-index:10001;left:${_sx}px;top:${_sy}px"
-  >
-    <sp-menu role="menu" aria-label=${`Sections of ${parent.command.title}`}
-      >${sections.map((section, index) => sectionTemplate(parent, section, index))}</sp-menu
-    >
-  </sp-popover>`);
-  const popover = _sub.host.querySelector<HTMLElement>("sp-popover");
-  if (popover) {
-    placePopover(
-      popover,
-      () => ({ x: _sx, y: _sy }),
-      (at) => {
-        ({ x: _sx, y: _sy } = at);
-        popover.style.left = `${_sx}px`;
-        popover.style.top = `${_sy}px`;
-      },
-    );
-  }
-}
-
-// ─── Activation ───────────────────────────────────────────────────────────────
-
-/** Run the row's own command, with no arguments, then dismiss. Disabled rows do nothing. */
-function activateRow(index: number): void {
-  const row = _rows[index];
-  if (!row?.enabled) {
-    return;
-  }
-  const { id } = row.command;
-  dismissSettingsMenu();
-  runRow(id);
-}
-
-/** Run the PARENT's command with the section this row names, then dismiss both levels. */
-function activateSection(parent: MenuRow, section: MenuSection): void {
-  const { id } = parent.command;
-  dismissSettingsMenu();
-  runRow(id, { section: section.key });
-}
-
-// ─── The submenu level ────────────────────────────────────────────────────────
-
-/**
- * Open the submenu for root row `index`, replacing whichever one was open.
- *
- * It subscribes to the section registry for as long as it is up. Six of Project Settings' sections
- * are contributed by extensions and register a tick after the built-ins
- * (`settings/extension-sections.ts`, fired by `format/format-host.ts`'s `refreshExtensionUi` on
- * project activation and after every `project.json` write), so a submenu opened in that window
- * would otherwise be permanently short. It deliberately does NOT call the sync itself: opening a
- * menu must not do IO.
- */
-function openSubmenu(index: number): void {
-  if (_subIdx === index) {
-    return;
-  }
-  const row = _rows[index];
-  if (!_root || !row || row.sections.length === 0) {
-    return;
-  }
-  closeSubmenu({ restoreFocus: false });
-  _subIdx = index;
-  _subActiveIdx = 0;
-  /* The root repaints FIRST, before the submenu exists.
-     `aria-expanded` on the parent row is a binding, so the root has to be redrawn either way — but
-     doing it afterwards let `sp-menu` re-assert focus on its own focused item and take it straight
-     back off the submenu we had just handed it to. The caret and the focus ring then disagreed:
-     ArrowRight ran the right section on Enter while the ring stayed on the parent row. */
-  renderRoot();
-
-  const rootRect = rectOf(_root.host.querySelector<HTMLElement>("sp-popover") ?? _root.host);
-  const parentRow = rootItems()[index];
-  _sx = rootRect.right - 2;
-  _sy = parentRow ? rectOf(parentRow).top : rootRect.top;
-
-  _sub = renderPopover(html`${nothing}`, {
-    // One handler for two popovers — see `onOutsideMousedown`.
-    dismissOnOutsideClick: false,
-    region: "settings-sections",
-  });
-  renderSub();
-  /* Flip to the menu's left when the submenu would leave the viewport on the right — after layout,
-     for the same reason `placePopover` runs twice: an unlaid-out popover is 0 wide and would never
-     appear to overflow anything. */
-  const popover = _sub.host.querySelector<HTMLElement>("sp-popover");
-  requestAnimationFrame(() => {
-    if (!popover?.isConnected) {
-      return;
-    }
-    const box = rectOf(popover);
-    if (_sx + box.width > window.innerWidth - 4) {
-      ({ x: _sx, y: _sy } = clampIntoMenuArea(box, {
-        x: rootRect.left - box.width + 2,
-        y: _sy,
-      }));
-      popover.style.left = `${_sx}px`;
-      popover.style.top = `${_sy}px`;
-    }
-  });
-
-  _unsubscribe = onSettingsDocumentChanged(() => {
-    const registry = activeRegistry();
-    if (!registry) {
-      return;
-    }
-    _rows = buildSettingsMenuRows(registry);
-    renderRoot();
-    renderSub();
-  });
-}
-
-/** Close the submenu level, optionally handing focus back to the row that owns it. */
-function closeSubmenu(opts: { restoreFocus: boolean }): void {
-  _unsubscribe?.();
-  _unsubscribe = null;
-  const owner = _subIdx;
-  _sub?.dismiss();
-  _sub = null;
-  _subIdx = -1;
-  _subActiveIdx = 0;
-  if (owner !== -1) {
-    _focus = "root";
-    renderRoot();
-    if (opts.restoreFocus) {
-      focusRoot(owner);
-    }
-  }
-}
-
-// ─── Keyboard ─────────────────────────────────────────────────────────────────
-
-/**
- * The menu keyboard contract, acting on the deepest open level.
- *
- * Bound on `document` in the CAPTURE phase, the shape `editor/slash-menu.ts` and
- * `editor/context-menu.ts` both use, and for the two reasons the latter states: the app's own
- * Escape walks the selection ladder and the canvas nudges on arrows, so neither must also fire; and
- * a bubble-phase handler on the popover would race Spectrum's own menu key handling.
- *
- * An unhandled key returns BEFORE `preventDefault`, so nothing else is swallowed.
- */
-function onMenuKeydown(e: KeyboardEvent): void {
-  if (!_root) {
-    return;
-  }
-  const inSub = _focus === "sub" && _sub !== null;
-  const count = inSub ? subItems().length : _rows.length;
-  const move = (index: number) => (inSub ? focusSub(index) : focusRoot(index));
-  const active = inSub ? _subActiveIdx : _activeIdx;
-
-  switch (e.key) {
-    case "ArrowDown": {
-      move(active + 1);
-      break;
-    }
-    case "ArrowUp": {
-      move(active - 1);
-      break;
-    }
-    case "Home": {
-      move(0);
-      break;
-    }
-    case "End": {
-      move(count - 1);
-      break;
-    }
-    case "ArrowRight": {
-      if (inSub || !(_rows[_activeIdx]?.sections.length ?? 0)) {
-        return;
-      }
-      const owner = _activeIdx;
-      openSubmenu(owner);
-      _focus = "sub";
-      focusSubSettled(0, owner);
-      break;
-    }
-    case "ArrowLeft": {
-      if (!inSub) {
-        return;
-      }
-      closeSubmenu({ restoreFocus: true });
-      break;
-    }
-    case "Enter":
-    case " ": {
-      if (inSub) {
-        const parent = _rows[_subIdx];
-        const section = parent?.sections[_subActiveIdx];
-        if (parent && section) {
-          activateSection(parent, section);
-        }
-      } else {
-        activateRow(_activeIdx);
-      }
-      break;
-    }
-    case "Escape": {
-      // One level at a time: the submenu first, the whole menu second.
-      if (inSub) {
-        closeSubmenu({ restoreFocus: true });
-      } else {
-        dismissSettingsMenu();
-      }
-      break;
-    }
-    case "Tab": {
-      dismissSettingsMenu();
-      break;
-    }
-    default: {
-      return;
-    }
-  }
-  e.preventDefault();
-  e.stopPropagation();
-}
-
-// ─── Dismissal ────────────────────────────────────────────────────────────────
-
-/**
- * One outside-click handler for BOTH popovers, which is why neither uses `renderPopover`'s.
- *
- * `dismissOnOutsideClick` tests `slot.contains(e.target)` for ONE slot, so with two popovers a
- * mousedown in the submenu is "outside" the root — and `dismiss()` removes the node, so the submenu
- * row's own `click` would never arrive. The opener is inside too: the gear's `@click` owns the
- * toggle, and dismissing here first would make every second click re-open.
- */
-function onOutsideMousedown(e: MouseEvent): void {
-  const target = e.target as Node;
-  if (_root?.host.contains(target) || _sub?.host.contains(target) || _opener?.contains(target)) {
-    return;
-  }
-  dismissSettingsMenu();
-}
-
-/** Drop the menu's global state and hand the keyboard back to whatever opened it. */
-function teardown(): void {
-  document.removeEventListener("keydown", onMenuKeydown, true);
-  /* Disarm the PENDING arm as well as the armed listener. The arm is deferred a frame so the click
-     that opened the menu cannot immediately close it, so a menu dismissed inside that frame would
-     otherwise arm AFTER its own death: a document-wide capture listener on a detached slot that
-     answers the next mousedown by dismissing the LIVE menu. `ui/layers.ts` documents the same
-     hazard at length; this is the same fix. */
-  if (_outside) {
-    document.removeEventListener("mousedown", _outside, true);
-    _outside = null;
-  }
-  _unsubscribe?.();
-  _unsubscribe = null;
-  const opener = _opener;
-  const rerender = _rerender;
-  _rows = [];
-  _activeIdx = 0;
-  _subIdx = -1;
-  _subActiveIdx = 0;
-  _focus = "root";
-  _opener = null;
-  _rerender = null;
-  // Only when the menu still held the keyboard: an outside CLICK has already moved focus somewhere
-  // The author chose, and yanking it back to the gear would fight them.
-  const active = document.activeElement;
-  if (opener?.isConnected && (!active || active === document.body)) {
-    opener.focus();
-  }
-  // Last, so `aria-expanded` repaints against the cleared state.
-  rerender?.();
-}
-
 // ─── Public surface ───────────────────────────────────────────────────────────
 
 /** Whether the gear menu is on screen. The rail reads it for `aria-expanded`. */
 export function isSettingsMenuOpen(): boolean {
-  return _root !== null;
+  return _menu !== null;
 }
 
 /** Dismiss the menu and any open submenu. Idempotent. */
 export function dismissSettingsMenu(): void {
-  if (!_root) {
-    return;
-  }
-  _sub?.dismiss();
-  _sub = null;
-  const root = _root;
-  _root = null;
-  root.dismiss();
-  teardown();
+  _menu?.close();
 }
 
 /**
@@ -749,7 +210,7 @@ export function dismissSettingsMenu(): void {
  * @param anchor The control the menu hangs off — the rail's gear.
  */
 export function openSettingsMenu(anchor: HTMLElement, opts: { rerender?: () => void } = {}): void {
-  if (_root) {
+  if (_menu) {
     dismissSettingsMenu();
     return;
   }
@@ -761,39 +222,41 @@ export function openSettingsMenu(anchor: HTMLElement, opts: { rerender?: () => v
   if (rows.length === 0) {
     return;
   }
-  _rows = rows;
-  _activeIdx = 0;
-  _subIdx = -1;
-  _focus = "root";
-  _opener = anchor;
   _rerender = opts.rerender ?? null;
-
-  // A seed only: `rootOrigin` recomputes both axes from the measured box on every placement pass.
-  const rect = rectOf(anchor);
-  _x = rect.right + 4;
-  _y = rect.top;
-
-  _root = renderPopover(html`${nothing}`, {
-    dismissOnOutsideClick: false,
+  const floor = (): number => menuFloor(anchor);
+  const handle = openMenu({
+    floor,
+    label: "Settings",
+    onClosed: (closedHandle) => {
+      if (_menu !== closedHandle) {
+        return;
+      }
+      _menu = null;
+      _unsubscribe?.();
+      _unsubscribe = null;
+      const rerender = _rerender;
+      _rerender = null;
+      // Last, so `aria-expanded` repaints against the cleared state.
+      rerender?.();
+    },
+    opener: anchor,
+    /* Hanging off the trigger's right edge, with its BOTTOM flush with the bottom of the region the
+       trigger lives in. Not "below the trigger": the gear is the last control in a full-height rail
+       whose foot abuts the status bar, so a menu dropped below it would be off-screen, and one
+       aligned to the button would float six pixels of `.rail-footer` padding clear of the status
+       bar. Floored at 4, because Project Settings has ~16 sections once extensions have contributed
+       and a menu taller than the area must keep its FIRST rows on screen. */
+    place: (box) => ({ x: rectOf(anchor).right + 4, y: Math.max(4, floor() - box.height) }),
     region: "settings",
+    rows,
   });
-  renderRoot();
-
-  document.addEventListener("keydown", onMenuKeydown, true);
-  _outside = onOutsideMousedown;
-  requestAnimationFrame(() => {
-    if (_outside) {
-      document.addEventListener("mousedown", _outside, true);
-    }
-  });
-  /* A frame later: lit has committed the items, and focusing the first row is what makes the whole
-     keyboard contract reachable at all. Guarded, because it is a DEFERRED write of an INITIAL
-     value — an arrow pressed inside that frame has already moved the caret, and re-applying row 0
-     on top of it would undo the first keystroke after opening. */
-  requestAnimationFrame(() => {
-    if (_root && _focus === "root" && _subIdx === -1 && _activeIdx === 0) {
-      focusRoot(0);
+  _menu = handle;
+  _unsubscribe = onSettingsDocumentChanged(() => {
+    const live = activeRegistry();
+    if (!live || _menu !== handle) {
+      return;
     }
+    handle.setRows(buildSettingsMenuRows(live));
   });
   _rerender?.();
 }