@pindoba/astro-menu 0.0.0-alpha-20260829223243

package/src/__test__/boot-menu.test.ts

@@ -0,0 +1,917 @@
+// @vitest-environment happy-dom
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { bootMenu, bootAllMenus } from "../boot-menu.js";
+import type { MenuConfig, MenuRootElement } from "../runtime.js";
+
+// --- Fake popover -----------------------------------------------------------
+// The boot drives every level through `$open` and reads it back in `reconcile`,
+// so the atom must be real-behaving. Floating UI itself is out of scope here.
+interface FakeAtom {
+  _value: boolean;
+  _listeners: Array<(v: boolean) => void>;
+  get(): boolean;
+  set(v: boolean): void;
+  listen(fn: (v: boolean) => void): () => void;
+}
+
+function makeAtom(): FakeAtom {
+  return {
+    _value: false,
+    _listeners: [],
+    get() {
+      return this._value;
+    },
+    set(v: boolean) {
+      if (this._value === v) return;
+      this._value = v;
+      for (const fn of [...this._listeners]) fn(v);
+    },
+    listen(fn: (v: boolean) => void) {
+      this._listeners.push(fn);
+      return () => {
+        const i = this._listeners.indexOf(fn);
+        if (i >= 0) this._listeners.splice(i, 1);
+      };
+    },
+  };
+}
+
+interface FakePopover {
+  options: Record<string, unknown>;
+  $open: FakeAtom;
+  setDialogElement: ReturnType<typeof vi.fn>;
+  setTriggerElement: ReturnType<typeof vi.fn>;
+  setAnchorElement: ReturnType<typeof vi.fn>;
+  setInsideElements: ReturnType<typeof vi.fn>;
+  setDialog: ReturnType<typeof vi.fn>;
+  destroy: ReturnType<typeof vi.fn>;
+}
+
+let createdPopovers: FakePopover[] = [];
+
+const { mockCreatePopover } = vi.hoisted(() => ({
+  mockCreatePopover: vi.fn(),
+}));
+
+// Only `createPopover` is faked — the safe-triangle helpers are re-exported
+// through this package, so replacing the whole module would strip them and the
+// pointer gating would throw instead of running.
+vi.mock("@pindoba/core-popover", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@pindoba/core-popover")>();
+  return { ...actual, createPopover: mockCreatePopover };
+});
+
+function popoverFor(id: string): FakePopover {
+  const found = createdPopovers.find((p) => p.options.id === id);
+  if (!found) throw new Error(`no popover created for ${id}`);
+  return found;
+}
+
+// --- requestAnimationFrame control -----------------------------------------
+let rafQueue: FrameRequestCallback[] = [];
+function drainRaf(maxRounds = 40) {
+  let rounds = 0;
+  while (rafQueue.length && rounds++ < maxRounds) {
+    const q = rafQueue;
+    rafQueue = [];
+    for (const cb of q) cb(0);
+  }
+}
+
+// --- Dialog manager ---------------------------------------------------------
+function installManager(getInstance = vi.fn((id: string) => ({ id }))) {
+  // @ts-expect-error -- partial dialog instance is all `setDialog` receives here
+  window.__PindobaDialogManager = { getInstance };
+  return getInstance;
+}
+
+// --- Fixture ----------------------------------------------------------------
+const ROOT_POPOVER = "menu-popover";
+const ROOT_MENU = "menu-list";
+const SUB_QUALIFIED = `${ROOT_MENU}-sub-more`;
+const SUB_POPOVER = `${SUB_QUALIFIED}-popover`;
+const SUB_MENU = `${SUB_QUALIFIED}-menu`;
+const SUB_TRIGGER_ITEM = `${ROOT_MENU}-option-more`;
+
+function makeConfig(overrides: Partial<MenuConfig> = {}): MenuConfig {
+  return {
+    rootId: "menu",
+    triggerId: "menu-trigger",
+    popoverId: ROOT_POPOVER,
+    menuId: ROOT_MENU,
+    side: "right",
+    placement: "bottom-start",
+    levels: [
+      {
+        id: null,
+        popoverId: ROOT_POPOVER,
+        menuId: ROOT_MENU,
+        depth: 0,
+        parentTriggerItemId: null,
+        submenus: [
+          {
+            id: "more",
+            qualifiedId: SUB_QUALIFIED,
+            triggerItemId: SUB_TRIGGER_ITEM,
+            popoverId: SUB_POPOVER,
+            menuId: SUB_MENU,
+          },
+        ],
+      },
+      {
+        id: "more",
+        popoverId: SUB_POPOVER,
+        menuId: SUB_MENU,
+        depth: 1,
+        parentTriggerItemId: SUB_TRIGGER_ITEM,
+        submenus: [],
+      },
+    ],
+    nodeIndex: {
+      save: { type: "action", closeOnSelect: true },
+      stay: { type: "action", closeOnSelect: false },
+      docs: { type: "link" },
+      wrap: { type: "checkbox", checked: false, closeOnSelect: false },
+      close: { type: "checkbox", checked: true, closeOnSelect: true },
+      more: { type: "submenu", subId: "more" },
+      red: { type: "radio", groupId: "color", value: "red" },
+      blue: { type: "radio", groupId: "color", value: "blue" },
+    },
+    radioInitial: { color: "red" },
+    ...overrides,
+  };
+}
+
+interface ListboxHandle {
+  setItems: ReturnType<typeof vi.fn>;
+}
+type ListboxUl = HTMLElement & { listbox?: ListboxHandle };
+
+interface MountOpts {
+  config?: MenuConfig;
+  /** Replace the serialized payload wholesale (parse-fail / non-array levels). */
+  rawConfig?: string;
+  /** Drop the `[data-pindoba-menu]` wrapper. */
+  orphanTrigger?: boolean;
+  /** Skip attaching fake ListBox handles (exercises the un-booted path). */
+  withListboxHandles?: boolean;
+  /** Mark the dialogs non-modal so the boot relocates them. */
+  isModalFalse?: boolean;
+}
+
+function makeList(
+  id: string,
+  keys: string[],
+  withHandle: boolean,
+): { ul: ListboxUl; handle: ListboxHandle | null } {
+  const ul: ListboxUl = document.createElement("ul");
+  ul.id = id;
+  ul.setAttribute(
+    "data-listbox-config",
+    JSON.stringify({
+      items: [
+        { id: "wrap", label: "Wrap", checked: false },
+        {
+          id: "colors",
+          type: "section",
+          items: [
+            { id: "red", label: "Red", checked: true },
+            { id: "blue", label: "Blue", checked: false },
+          ],
+        },
+      ],
+    }),
+  );
+  for (const key of keys) {
+    const li = document.createElement("li");
+    li.setAttribute("data-key", key);
+    li.id = `${id}-option-${key}`;
+    li.tabIndex = -1;
+    ul.appendChild(li);
+  }
+  const handle = withHandle ? { setItems: vi.fn() } : null;
+  if (handle) ul.listbox = handle;
+  return { ul, handle };
+}
+
+interface Fixture {
+  root: MenuRootElement;
+  trigger: HTMLElement;
+  rootDialog: HTMLDialogElement;
+  subDialog: HTMLDialogElement;
+  rootUl: ListboxUl;
+  subUl: ListboxUl;
+  rootHandle: ListboxHandle | null;
+  subHandle: ListboxHandle | null;
+  config: MenuConfig;
+}
+
+function mount(opts: MountOpts = {}): Fixture {
+  const config = opts.config ?? makeConfig();
+  const withHandles = opts.withListboxHandles ?? true;
+
+  const trigger = document.createElement("button");
+  trigger.id = config.triggerId;
+  trigger.setAttribute("data-menu-trigger", "");
+  trigger.setAttribute(
+    "data-menu-config",
+    opts.rawConfig ?? JSON.stringify(config),
+  );
+
+  let root: HTMLElement;
+  if (opts.orphanTrigger) {
+    root = document.createElement("div");
+    root.appendChild(trigger);
+  } else {
+    root = document.createElement("div");
+    root.setAttribute("data-pindoba-menu", "");
+    root.appendChild(trigger);
+  }
+  document.body.appendChild(root);
+
+  const rootDialog = document.createElement("dialog");
+  rootDialog.id = ROOT_POPOVER;
+  const subDialog = document.createElement("dialog");
+  subDialog.id = SUB_POPOVER;
+  if (opts.isModalFalse) {
+    rootDialog.dataset.isModal = "false";
+    subDialog.dataset.isModal = "false";
+  }
+
+  const rootList = makeList(
+    ROOT_MENU,
+    ["save", "stay", "docs", "wrap", "close", "more"],
+    withHandles,
+  );
+  const subList = makeList(SUB_MENU, ["red", "blue"], withHandles);
+  rootDialog.appendChild(rootList.ul);
+  subDialog.appendChild(subList.ul);
+  document.body.append(rootDialog, subDialog);
+
+  return {
+    root,
+    trigger,
+    rootDialog,
+    subDialog,
+    rootUl: rootList.ul,
+    subUl: subList.ul,
+    rootHandle: rootList.handle,
+    subHandle: subList.handle,
+    config,
+  };
+}
+
+const keyOn = (el: HTMLElement, key: string) => {
+  const event = new KeyboardEvent("keydown", {
+    key,
+    bubbles: true,
+    cancelable: true,
+  });
+  el.dispatchEvent(event);
+  return event;
+};
+
+const action = (ul: HTMLElement, key: string) =>
+  ul.dispatchEvent(
+    new CustomEvent("listbox:action", { detail: { key }, bubbles: true }),
+  );
+
+const pointerAt = (el: HTMLElement, target: HTMLElement, x = 0, y = 0) => {
+  const event = new Event("pointermove", { bubbles: true });
+  Object.defineProperties(event, {
+    clientX: { value: x },
+    clientY: { value: y },
+    target: { value: target },
+  });
+  el.dispatchEvent(event);
+};
+
+function capture(root: HTMLElement, type: string) {
+  const seen: unknown[] = [];
+  root.addEventListener(type, (e) => seen.push((e as CustomEvent).detail));
+  return seen;
+}
+
+let teardowns: Array<() => void> = [];
+
+beforeEach(() => {
+  createdPopovers = [];
+  rafQueue = [];
+  teardowns = [];
+  mockCreatePopover.mockImplementation((options: Record<string, unknown>) => {
+    const popover: FakePopover = {
+      options,
+      $open: makeAtom(),
+      setDialogElement: vi.fn(),
+      setTriggerElement: vi.fn(),
+      setAnchorElement: vi.fn(),
+      setInsideElements: vi.fn(),
+      setDialog: vi.fn(),
+      destroy: vi.fn(),
+    };
+    createdPopovers.push(popover);
+    return popover;
+  });
+  vi.stubGlobal("requestAnimationFrame", (cb: FrameRequestCallback) => {
+    rafQueue.push(cb);
+    return rafQueue.length;
+  });
+  installManager();
+});
+
+afterEach(() => {
+  for (const t of teardowns) t();
+  document.body.innerHTML = "";
+  delete window.__PindobaDialogManager;
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+function boot(fixture: Fixture) {
+  const result = bootMenu(fixture.trigger);
+  if (result) teardowns.push(result.destroy);
+  return result;
+}
+
+describe("bootMenu — payload + ownership guards", () => {
+  it("bails on a malformed config without marking the trigger", () => {
+    const f = mount({ rawConfig: "{not json" });
+    expect(bootMenu(f.trigger)).toBeNull();
+    expect(f.trigger.hasAttribute("data-menu-initialized")).toBe(false);
+  });
+
+  it("bails when `levels` is not an array", () => {
+    const f = mount({ rawConfig: JSON.stringify({ levels: "nope" }) });
+    expect(bootMenu(f.trigger)).toBeNull();
+    expect(f.trigger.hasAttribute("data-menu-initialized")).toBe(false);
+  });
+
+  it("bails on a trigger outside any `[data-pindoba-menu]` root", () => {
+    const f = mount({ orphanTrigger: true });
+    expect(bootMenu(f.trigger)).toBeNull();
+    expect(f.trigger.hasAttribute("data-menu-initialized")).toBe(false);
+  });
+
+  it("bails (once) on a second boot of the same trigger", () => {
+    const f = mount();
+    expect(boot(f)).not.toBeNull();
+    expect(f.trigger.getAttribute("data-menu-initialized")).toBe("true");
+    expect(bootMenu(f.trigger)).toBeNull();
+  });
+
+  it("bails when no root level is described, leaving nothing behind", () => {
+    const config = makeConfig();
+    config.levels = config.levels.filter((l) => l.id !== null);
+    const f = mount({ config });
+
+    expect(bootMenu(f.trigger)).toBeNull();
+    // This bail happens after the per-level popovers were created, so they must
+    // be torn down — and the trigger must stay unmarked so a corrected render
+    // can still boot.
+    for (const popover of createdPopovers) {
+      expect(popover.destroy).toHaveBeenCalled();
+    }
+    expect(f.trigger.hasAttribute("data-menu-initialized")).toBe(false);
+  });
+});
+
+describe("bootMenu — popover wiring", () => {
+  it("creates one popover per level, root anchored to the trigger", () => {
+    const f = mount();
+    boot(f);
+    expect(createdPopovers).toHaveLength(2);
+
+    const rootPopover = popoverFor(ROOT_POPOVER);
+    expect(rootPopover.options).toMatchObject({
+      placement: "bottom-start",
+      triggerStrategy: "click",
+      anchorElement: f.trigger,
+      autoFocus: false,
+    });
+    expect(rootPopover.setTriggerElement).toHaveBeenCalledWith(f.trigger);
+    expect(rootPopover.setDialogElement).toHaveBeenCalledWith(f.rootDialog);
+  });
+
+  it("gives each submenu a manual-trigger popover stacked by depth", () => {
+    const f = mount();
+    boot(f);
+    expect(popoverFor(SUB_POPOVER).options).toMatchObject({
+      placement: "right-start",
+      triggerStrategy: "manual",
+      zIndex: 10001,
+    });
+  });
+
+  it("registers the submenu dialogs as inside-elements of the root", () => {
+    const f = mount();
+    boot(f);
+    expect(popoverFor(ROOT_POPOVER).setInsideElements).toHaveBeenCalledWith([
+      f.subDialog,
+    ]);
+  });
+
+  it("relocates non-modal dialogs to <body>", () => {
+    const f = mount({ isModalFalse: true });
+    const wrapper = document.createElement("div");
+    document.body.appendChild(wrapper);
+    wrapper.appendChild(f.subDialog);
+
+    boot(f);
+    expect(f.subDialog.parentElement).toBe(document.body);
+  });
+
+  it("keeps a non-modal dialog nested inside a MODAL <dialog> ancestor", () => {
+    const f = mount({ isModalFalse: true });
+    const modal = document.createElement("dialog");
+    modal.setAttribute("data-is-modal", "true");
+    document.body.appendChild(modal);
+    modal.appendChild(f.subDialog);
+
+    boot(f);
+    expect(f.subDialog.parentElement).toBe(modal);
+  });
+
+  it("hands each popover its dialog instance once the manager is ready", async () => {
+    const getInstance = installManager();
+    const f = mount();
+    boot(f);
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(getInstance).toHaveBeenCalledWith(ROOT_POPOVER);
+    expect(popoverFor(ROOT_POPOVER).setDialog).toHaveBeenCalled();
+  });
+
+  it("waits for the manager-ready event when it boots first", async () => {
+    delete window.__PindobaDialogManager;
+    const f = mount();
+    boot(f);
+    await Promise.resolve();
+    expect(popoverFor(ROOT_POPOVER).setDialog).not.toHaveBeenCalled();
+
+    const getInstance = installManager();
+    document.dispatchEvent(new Event("pindoba:dialog-manager-ready"));
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(getInstance).toHaveBeenCalledWith(ROOT_POPOVER);
+  });
+});
+
+describe("bootMenu — root open state", () => {
+  it("mirrors open state onto the trigger and emits openchange", () => {
+    const f = mount();
+    boot(f);
+    const events = capture(f.root, "pindoba:menu:openchange");
+
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    expect(f.trigger.getAttribute("aria-expanded")).toBe("true");
+    expect(f.trigger.getAttribute("data-state")).toBe("open");
+
+    popoverFor(ROOT_POPOVER).$open.set(false);
+    expect(f.trigger.getAttribute("aria-expanded")).toBe("false");
+    expect(f.trigger.getAttribute("data-state")).toBe("closed");
+    expect(events).toEqual([
+      { id: "menu", open: true },
+      { id: "menu", open: false },
+    ]);
+  });
+
+  it("focuses the first row when the root opens", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    expect(document.activeElement).toBe(
+      f.rootUl.querySelector('[data-key="save"]'),
+    );
+  });
+
+  it("collapses every open submenu when the root closes", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    action(f.rootUl, "more");
+    expect(popoverFor(SUB_POPOVER).$open.get()).toBe(true);
+
+    popoverFor(ROOT_POPOVER).$open.set(false);
+    expect(popoverFor(SUB_POPOVER).$open.get()).toBe(false);
+  });
+
+  it("opens on boot when the config asked for it", async () => {
+    const f = mount({ config: { ...makeConfig(), open: true } as MenuConfig });
+    boot(f);
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(popoverFor(ROOT_POPOVER).$open.get()).toBe(true);
+  });
+});
+
+describe("bootMenu — activation", () => {
+  it("emits an action and closes when `closeOnSelect`", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    const actions = capture(f.root, "pindoba:menu:action");
+
+    action(f.rootUl, "save");
+    expect(actions).toEqual([{ id: "save" }]);
+    expect(popoverFor(ROOT_POPOVER).$open.get()).toBe(false);
+  });
+
+  it("keeps the menu open for a non-closing action", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    action(f.rootUl, "stay");
+    expect(popoverFor(ROOT_POPOVER).$open.get()).toBe(true);
+  });
+
+  it("closes the root after a link activation", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    action(f.rootUl, "docs");
+    expect(popoverFor(ROOT_POPOVER).$open.get()).toBe(false);
+  });
+
+  it("ignores keys with no entry in the node index", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    const actions = capture(f.root, "pindoba:menu:action");
+    action(f.rootUl, "ghost");
+    expect(actions).toEqual([]);
+    expect(popoverFor(ROOT_POPOVER).$open.get()).toBe(true);
+  });
+
+  it("toggles a checkbox, repaints the list and reports the change", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    const changes = capture(f.root, "pindoba:menu:checkedchange");
+
+    action(f.rootUl, "wrap");
+    expect(changes).toEqual([{ id: "wrap", checked: true }]);
+    const painted = f.rootHandle!.setItems.mock.lastCall![0];
+    expect(painted[0]).toMatchObject({ id: "wrap", checked: true });
+
+    action(f.rootUl, "wrap");
+    expect(changes[1]).toEqual({ id: "wrap", checked: false });
+  });
+
+  it("seeds checkbox state from the server-rendered payload", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    const changes = capture(f.root, "pindoba:menu:checkedchange");
+    // `close` was SSR'd checked, so its first toggle must go to false.
+    action(f.rootUl, "close");
+    expect(changes).toEqual([{ id: "close", checked: false }]);
+  });
+
+  it("selects a radio value and repaints without closing", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    const changes = capture(f.root, "pindoba:menu:valuechange");
+
+    action(f.rootUl, "blue");
+    expect(changes).toEqual([{ groupId: "color", value: "blue" }]);
+    expect(popoverFor(ROOT_POPOVER).$open.get()).toBe(true);
+
+    const painted = f.rootHandle!.setItems.mock.lastCall![0];
+    expect(painted[1].items).toEqual([
+      expect.objectContaining({ id: "red", checked: false }),
+      expect.objectContaining({ id: "blue", checked: true }),
+    ]);
+  });
+
+  it("opens the submenu and focuses its first row from an activation", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+
+    action(f.rootUl, "more");
+    expect(popoverFor(SUB_POPOVER).$open.get()).toBe(true);
+    expect(popoverFor(SUB_POPOVER).setAnchorElement).toHaveBeenCalledWith(
+      document.getElementById(SUB_TRIGGER_ITEM),
+    );
+    expect(document.activeElement).toBe(
+      f.subUl.querySelector('[data-key="red"]'),
+    );
+  });
+});
+
+describe("bootMenu — keyboard", () => {
+  it("opens a submenu with ArrowRight on its trigger row", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    f.rootUl.querySelector<HTMLElement>('[data-key="more"]')!.focus();
+
+    const event = keyOn(f.rootDialog, "ArrowRight");
+    expect(event.defaultPrevented).toBe(true);
+    expect(popoverFor(SUB_POPOVER).$open.get()).toBe(true);
+  });
+
+  it("ignores ArrowRight on a row with no submenu", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    f.rootUl.querySelector<HTMLElement>('[data-key="save"]')!.focus();
+
+    const event = keyOn(f.rootDialog, "ArrowRight");
+    expect(event.defaultPrevented).toBe(false);
+    expect(popoverFor(SUB_POPOVER).$open.get()).toBe(false);
+  });
+
+  it("closes a submenu with ArrowLeft and restores focus to its trigger row", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    action(f.rootUl, "more");
+
+    keyOn(f.subDialog, "ArrowLeft");
+    expect(popoverFor(SUB_POPOVER).$open.get()).toBe(false);
+    expect(document.activeElement).toBe(
+      document.getElementById(SUB_TRIGGER_ITEM),
+    );
+  });
+
+  it("leaves ArrowLeft alone at the root level", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    const event = keyOn(f.rootDialog, "ArrowLeft");
+    expect(event.defaultPrevented).toBe(false);
+    expect(popoverFor(ROOT_POPOVER).$open.get()).toBe(true);
+  });
+
+  it("Escape closes only the topmost level", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    action(f.rootUl, "more");
+
+    keyOn(f.subDialog, "Escape");
+    expect(popoverFor(SUB_POPOVER).$open.get()).toBe(false);
+    expect(popoverFor(ROOT_POPOVER).$open.get()).toBe(true);
+
+    keyOn(f.rootDialog, "Escape");
+    expect(popoverFor(ROOT_POPOVER).$open.get()).toBe(false);
+  });
+
+  it("swallows Escape so the native dialog cancel cannot desync state", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    expect(keyOn(f.rootDialog, "Escape").defaultPrevented).toBe(true);
+  });
+});
+
+describe("bootMenu — pointer", () => {
+  it("opens a submenu on hover without stealing focus", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    const saveRow = f.rootUl.querySelector<HTMLElement>('[data-key="save"]')!;
+    saveRow.focus();
+
+    pointerAt(
+      f.rootDialog,
+      f.rootUl.querySelector<HTMLElement>('[data-key="more"]')!,
+    );
+    drainRaf();
+
+    expect(popoverFor(SUB_POPOVER).$open.get()).toBe(true);
+    expect(document.activeElement).toBe(saveRow);
+  });
+
+  it("closes the open submenu when a sibling row is hovered", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    action(f.rootUl, "more");
+
+    pointerAt(
+      f.rootDialog,
+      f.rootUl.querySelector<HTMLElement>('[data-key="save"]')!,
+    );
+    expect(popoverFor(SUB_POPOVER).$open.get()).toBe(false);
+  });
+
+  it("ignores pointer moves that land outside any row", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    action(f.rootUl, "more");
+
+    pointerAt(f.rootDialog, f.rootUl);
+    expect(popoverFor(SUB_POPOVER).$open.get()).toBe(true);
+  });
+
+  it("closes the open submenu when the parent level scrolls", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    action(f.rootUl, "more");
+
+    f.rootUl.dispatchEvent(new Event("scroll", { bubbles: true }));
+    expect(popoverFor(SUB_POPOVER).$open.get()).toBe(false);
+  });
+});
+
+describe("bootMenu — imperative handle", () => {
+  const handleOf = (f: Fixture) => (f.root as MenuRootElement).menu!;
+
+  it("exposes open / close / toggle / isOpen", () => {
+    const f = mount();
+    boot(f);
+    const menu = handleOf(f);
+
+    expect(menu.isOpen()).toBe(false);
+    menu.open();
+    expect(menu.isOpen()).toBe(true);
+    menu.toggle();
+    expect(menu.isOpen()).toBe(false);
+    menu.toggle();
+    expect(menu.isOpen()).toBe(true);
+    menu.close();
+    expect(menu.isOpen()).toBe(false);
+  });
+
+  it("reads the server-seeded radio value and sets a new one without emitting", () => {
+    const f = mount();
+    boot(f);
+    const menu = handleOf(f);
+    const changes = capture(f.root, "pindoba:menu:valuechange");
+
+    expect(menu.getRadioValue("color")).toBe("red");
+    menu.setRadioValue("color", "blue");
+    expect(menu.getRadioValue("color")).toBe("blue");
+    expect(changes).toEqual([]);
+
+    const painted = f.rootHandle!.setItems.mock.lastCall![0];
+    expect(painted[1].items[1]).toMatchObject({ id: "blue", checked: true });
+  });
+
+  it("retries the repaint until every level's ListBox has booted", () => {
+    const f = mount({ withListboxHandles: false });
+    boot(f);
+    handleOf(f).setRadioValue("color", "blue");
+
+    const handle = { setItems: vi.fn() };
+    f.rootUl.listbox = handle;
+    f.subUl.listbox = { setItems: vi.fn() };
+    drainRaf();
+
+    expect(handle.setItems).toHaveBeenCalled();
+  });
+
+  it("gives up retrying after a bounded number of frames", () => {
+    const f = mount({ withListboxHandles: false });
+    boot(f);
+    handleOf(f).setRadioValue("color", "blue");
+    drainRaf();
+    expect(rafQueue).toHaveLength(0);
+  });
+});
+
+describe("bootMenu — teardown", () => {
+  it("destroys every popover, drops the handle and allows a re-boot", () => {
+    const f = mount();
+    const result = boot(f)!;
+    result.destroy();
+
+    for (const popover of createdPopovers) {
+      expect(popover.destroy).toHaveBeenCalled();
+    }
+    expect((f.root as MenuRootElement).menu).toBeUndefined();
+    expect(f.trigger.hasAttribute("data-menu-initialized")).toBe(false);
+    expect(bootMenu(f.trigger)).not.toBeNull();
+  });
+
+  it("stops responding to level events", () => {
+    const f = mount();
+    const result = boot(f)!;
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    result.destroy();
+
+    const actions = capture(f.root, "pindoba:menu:action");
+    action(f.rootUl, "save");
+    expect(actions).toEqual([]);
+  });
+});
+
+describe("bootAllMenus", () => {
+  it("boots every astro-owned trigger and skips foreign ones", () => {
+    const f = mount();
+    const foreign = document.createElement("button");
+    foreign.setAttribute("data-menu-trigger", "");
+    document.body.appendChild(foreign);
+
+    const results = bootAllMenus();
+    for (const r of results) teardowns.push(r.destroy);
+
+    expect(results).toHaveLength(1);
+    expect(f.trigger.getAttribute("data-menu-initialized")).toBe("true");
+    expect(foreign.hasAttribute("data-menu-initialized")).toBe(false);
+  });
+
+  it("is safe to run twice (astro:page-load re-fires on the initial load)", () => {
+    mount();
+    const first = bootAllMenus();
+    for (const r of first) teardowns.push(r.destroy);
+    expect(bootAllMenus()).toEqual([]);
+  });
+});
+
+describe("bootMenu — safe-triangle deferral", () => {
+  /** Give the submenu dialog a real box so the aim maths has something to hit. */
+  function sizeSubmenu(f: Fixture) {
+    f.subDialog.getBoundingClientRect = () =>
+      ({
+        left: 250,
+        top: 100,
+        right: 400,
+        bottom: 300,
+        width: 150,
+        height: 200,
+        x: 250,
+        y: 100,
+        toJSON: () => ({}),
+      }) as DOMRect;
+  }
+
+  it("keeps the submenu open while the pointer travels toward it", () => {
+    // The whole point of the safe triangle: moving diagonally across a sibling
+    // row on the way to the open panel must not slam it shut.
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    action(f.rootUl, "more");
+    sizeSubmenu(f);
+
+    const more = f.rootUl.querySelector<HTMLElement>('[data-key="more"]')!;
+    const save = f.rootUl.querySelector<HTMLElement>('[data-key="save"]')!;
+
+    // Two samples heading right, toward the panel at x >= 200.
+    pointerAt(f.rootDialog, more, 120, 150);
+    // Right+down diagonal toward the panel face, crossing a sibling row.
+    pointerAt(f.rootDialog, save, 200, 200);
+
+    expect(popoverFor(SUB_POPOVER).$open.get()).toBe(true);
+  });
+
+  it("closes the submenu when the pointer is not heading for it", () => {
+    const f = mount();
+    boot(f);
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    action(f.rootUl, "more");
+    sizeSubmenu(f);
+
+    const more = f.rootUl.querySelector<HTMLElement>('[data-key="more"]')!;
+    const save = f.rootUl.querySelector<HTMLElement>('[data-key="save"]')!;
+
+    // Straight down onto a sibling: no horizontal progress toward the panel,
+    // so the deferral must not engage.
+    pointerAt(f.rootDialog, more, 120, 150);
+    pointerAt(f.rootDialog, save, 120, 220);
+
+    expect(popoverFor(SUB_POPOVER).$open.get()).toBe(false);
+  });
+});
+
+describe("bootMenu — first-row focus retry", () => {
+  it("retries across frames until a row can take focus", () => {
+    // The rows are `tabindex -1` and the dialog may not be focusable yet on the
+    // first frame, so the boot retries rather than giving up silently.
+    const f = mount();
+    boot(f);
+
+    const first = f.rootUl.querySelector<HTMLElement>('[data-key="save"]')!;
+    let allowed = false;
+    const realFocus = first.focus.bind(first);
+    first.focus = (opts?: FocusOptions) => {
+      if (allowed) realFocus(opts);
+    };
+
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    expect(document.activeElement).not.toBe(first);
+
+    allowed = true;
+    drainRaf();
+    expect(document.activeElement).toBe(first);
+  });
+
+  it("gives up after a bounded number of frames", () => {
+    const f = mount();
+    boot(f);
+    const first = f.rootUl.querySelector<HTMLElement>('[data-key="save"]')!;
+    first.focus = () => {};
+
+    popoverFor(ROOT_POPOVER).$open.set(true);
+    drainRaf();
+
+    // Bounded: the queue drains rather than rescheduling forever.
+    expect(rafQueue).toHaveLength(0);
+  });
+});