@celestia-island/hikari 0.4.4 → 0.30.0

package/src/components/HkPlaceholderMarquee.tsx

@@ -0,0 +1,170 @@
+import { defineComponent, ref, computed, onMounted, onBeforeUnmount, watch, type PropType } from "vue";
+
+/**
+ * Overflow strategy for a placeholder that does not fit its input.
+ *
+ * - `marquee` (default): while the text fits, the overlay stays in the DOM
+ *   only as an invisible measuring probe and the host input shows its NATIVE
+ *   placeholder (crisp, accessible, zero animation). When the text overflows
+ *   the input line, the overlay becomes visible, renders the text three
+ *   times side by side inside a clipping window, and translates the strip
+ *   leftward in a loop — the classic scrolling storefront sign. The strip
+ *   content is identical in all three copies so the wrap-around is seamless.
+ *
+ *   The motion is PURE CSS: one registered infinite keyframes animation
+ *   (`hk-placeholder-marquee-scroll`, see animation/registerAnimations.ts)
+ *   whose loop distance and duration live on inline custom properties
+ *   (`--hk-marquee-shift` / `--hk-marquee-duration`), measured once per
+ *   geometry change — never per frame. There is no JS/rAF animation and no
+ *   reactive per-frame transform write, so scrolling the page (or a mobile
+ *   bottom sheet) never competes with the strip for the main thread; the
+ *   animation runs on the compositor. The animation-context switch
+ *   (`setReducedMotion` / performance suspension via
+ *   `html[data-css-animations="0"]`) parks the strip, and the strip also
+ *   parks while the host input is focused (`data-parked`).
+ *
+ *   The `overflowChange` event tells the host when to swap its native
+ *   placeholder for the scrolling overlay.
+ * - `truncate`: hard-cut the text at the container edge with an ellipsis.
+ */
+export type PlaceholderVariant = "marquee" | "truncate";
+
+/** Horizontal spacing between repeated copies — mirrors the scss copy
+ * padding-right; kept in sync so overflow detection measures reality. */
+const COPY_SPACING = 24;
+
+export const HkPlaceholderMarquee = defineComponent({
+  name: "HkPlaceholderMarquee",
+  props: {
+    text: { type: String, default: "" },
+    variant: { type: String as PropType<PlaceholderVariant>, default: "marquee" },
+    /** Pixels per second of strip travel. Negative scrolls rightward. */
+    speed: { type: Number, default: 24 },
+  },
+  emits: {
+    overflowChange: (_overflowing: boolean) => true,
+  },
+  setup(props, { emit, expose }) {
+    const hostEl = ref<HTMLElement | null>(null);
+    const firstCopyEl = ref<HTMLElement | null>(null);
+    const overflowing = ref(false);
+    const parked = ref(false);
+    /** One copy's laid-out width (incl. trailing spacing) — reactive so
+     *  the loop geometry republishes when it changes even if the
+     *  overflow state does not (zoom, font swap, text edit mid-overflow). */
+    const loopWidth = ref(0);
+
+    let ro: ResizeObserver | null = null;
+
+    const measure = () => {
+      const host = hostEl.value;
+      const copy = firstCopyEl.value;
+      if (!host || !copy) return;
+      // Measure ONE copy's laid-out width directly (it includes the 24px
+      // copy spacing as trailing padding). Reading the first copy element —
+      // instead of stripWidth / 3 — stays correct in the fitting case,
+      // where the strip holds a single copy, and through overflow flips,
+      // where the copy count changes under the same strip. The fractional
+      // bounding-rect width keeps the CSS loop shift bit-exact with the
+      // laid-out advance — an integer-rounded width would show a ≤0.5px
+      // seam at every wrap (the copy rides the animated strip, so the
+      // width itself is never affected by the strip's transform).
+      const copyWidth = copy.getBoundingClientRect().width;
+      loopWidth.value = copyWidth;
+      overflowing.value = copyWidth - COPY_SPACING > host.clientWidth;
+      emit("overflowChange", overflowing.value);
+    };
+
+    onMounted(() => {
+      measure();
+      if (typeof ResizeObserver !== "undefined" && hostEl.value) {
+        ro = new ResizeObserver(() => measure());
+        ro.observe(hostEl.value);
+      }
+    });
+
+    watch(() => props.text, () => {
+      // Re-measure after the DOM paints the new strip.
+      requestAnimationFrame(() => measure());
+    });
+
+    onBeforeUnmount(() => {
+      ro?.disconnect();
+    });
+
+    expose({
+      /** Called by the host input: focus parks the strip, blur resumes. */
+      setActive(active: boolean) {
+        parked.value = active;
+      },
+      measure,
+    });
+
+    /** Loop geometry, published as custom properties + a direction flag
+     *  on the strip: the keyframes animate
+     *  `translateX(0 → var(--hk-marquee-shift))` over
+     *  `var(--hk-marquee-duration)` — both measured, never recomputed per
+     *  frame. Duration = one copy width at the configured px/s speed;
+     *  the sign of the speed flips the direction (reverse plays the
+     *  keyframes backwards, which wraps seamlessly on the three copies).
+     *  A zero speed parks the strip (no scroll class) — matching the
+     *  pre-CSS behavior, where the JS loop simply never advanced
+     *  (non-finite speeds fall back to the default rate). */
+    const stripVars = computed(() => {
+      if (!overflowing.value || loopWidth.value <= 0) return undefined;
+      const speed = Number.isFinite(props.speed) ? Math.abs(props.speed) : 24;
+      if (speed === 0) return undefined;
+      return {
+        "--hk-marquee-shift": `${-loopWidth.value}px`,
+        "--hk-marquee-duration": `${(loopWidth.value / speed).toFixed(3)}s`,
+        "--hk-marquee-direction": (props.speed ?? 24) < 0 ? "reverse" : "normal",
+      } as Record<string, string>;
+    });
+
+    return () => {
+      if (!props.text) return null;
+      if (props.variant === "truncate") {
+        return (
+          <span ref={hostEl} class="hk-placeholder-marquee hk-placeholder-marquee--truncate">
+            <span class="hk-placeholder-marquee__text">{props.text}</span>
+          </span>
+        );
+      }
+      return (
+        <span
+          ref={hostEl}
+          class={[
+            "hk-placeholder-marquee",
+            // While the text fits the overlay stays hidden (but laid out,
+            // so the probe keeps measuring) and the input's NATIVE
+            // placeholder does the showing.
+            overflowing.value ? "" : "hk-placeholder-marquee--hidden",
+          ].filter(Boolean).join(" ")}
+          data-parked={parked.value || undefined}
+          aria-hidden="true"
+        >
+          <span
+            class={[
+              "hk-placeholder-marquee__strip",
+              // The sweep only starts once the loop geometry is known —
+              // overflowing text with a parked speed (0/non-finite) stays
+              // a static strip, matching the old JS behavior.
+              overflowing.value && stripVars.value ? "hk-placeholder-marquee__strip--scroll" : "",
+            ].filter(Boolean).join(" ")}
+            style={stripVars.value}
+          >
+            <span ref={firstCopyEl} class="hk-placeholder-marquee__copy">{props.text}</span>
+            {overflowing.value && (
+              <>
+                <span class="hk-placeholder-marquee__copy">{props.text}</span>
+                <span class="hk-placeholder-marquee__copy">{props.text}</span>
+              </>
+            )}
+          </span>
+        </span>
+      );
+    };
+  },
+});
+
+export default HkPlaceholderMarquee;

package/src/components/HkPopover.scss

@@ -9,33 +9,45 @@
   max-height: min(70vh, calc(100vh - 2 * 8px));
 }
 
+/* Pop motion family tokens (--hk-pop-* in theme.scss) — the reference
+ * consumer. HkSelectPanel's desktop popout and HkTooltip use the same
+ * set so every anchored surface pops with one curve. */
 .hk-popover-enter-active {
   transition:
-    opacity 0.2s cubic-bezier(0.16, 1, 0.3, 1),
-    transform 0.2s cubic-bezier(0.34, 1.56, 0.64, 1);
+    opacity var(--hk-pop-in-duration, 0.2s)
+      var(--hk-pop-in-opacity-ease, cubic-bezier(0.16, 1, 0.3, 1)),
+    transform var(--hk-pop-in-duration, 0.2s)
+      var(--hk-pop-in-transform-ease, cubic-bezier(0.34, 1.56, 0.64, 1));
 }
 
 .hk-popover-leave-active {
   transition:
-    opacity 0.15s cubic-bezier(0.4, 0, 1, 1),
-    transform 0.15s cubic-bezier(0.4, 0, 1, 1);
+    opacity var(--hk-pop-out-duration, 0.15s)
+      var(--hk-pop-out-ease, cubic-bezier(0.4, 0, 1, 1)),
+    transform var(--hk-pop-out-duration, 0.15s)
+      var(--hk-pop-out-ease, cubic-bezier(0.4, 0, 1, 1));
 }
 
 .hk-popover-enter-from {
   opacity: 0;
-  transform: translateY(-4px) scale(0.97);
+  transform: translateY(calc(-1 * var(--hk-pop-offset, 4px)))
+    scale(var(--hk-pop-scale, 0.97));
 }
 
 .hk-popover-leave-to {
   opacity: 0;
-  transform: translateY(4px) scale(0.97);
+  transform: translateY(var(--hk-pop-offset, 4px))
+    scale(var(--hk-pop-scale, 0.97));
 }
 
-/* Glass dropdown content — used when `glass` prop is true */
+/* Glass dropdown content — used when `glass` prop is true.
+   --hk-popover-bg/--hk-popover-blur let a host app's surface-finish
+   preference (chest html[data-surface]) re-skin this layer; the defaults
+   keep the historical look. */
 .hii-dropdown-content,
 .hk-popover-panel.hii-dropdown-content {
-  background: rgb(var(--color-surface));
-  backdrop-filter: blur(var(--blur-lg)) saturate(1.2);
+  background: var(--hk-popover-bg, rgb(var(--color-surface)));
+  backdrop-filter: var(--hk-popover-blur, blur(var(--blur-lg)) saturate(1.2));
   border: 1px solid rgb(var(--color-border) / 20%);
   border-radius: var(--radius-sm);
   box-shadow: var(--shadow-dropdown);
@@ -62,7 +74,9 @@
   border-radius: var(--radius-sm);
 }
 
-.hk-popup-menu-item:hover {
+/* Hover = background wash only, never on the active item (active >
+   hover precedence — see HkNavItem.scss for the spec). */
+.hk-popup-menu-item:hover:not([data-active]) {
   background: var(--c-primary-subtle);
 }
 
@@ -80,3 +94,113 @@
   font-size: var(--text-base);
   line-height: 1;
 }
+
+// ------
+// Mobile bottom-sheet mode (`sheetOnMobile`) — the panel docks to the
+// bottom edge on <768px viewports instead of anchoring: a real scrim
+// (click closes), rounded top corners only, slide-up reveal. Same visual
+// contract as the modal mobile docking (top inset keeps the secondary-
+// window breadcrumb strip visible).
+// ------
+.hk-popover-scrim {
+  position: fixed;
+  inset: 0;
+  pointer-events: auto;
+  background: rgb(0 0 0 / 40%);
+}
+
+.hk-popover-panel.hk-is-sheet {
+  border-radius: var(--hk-modal-radius, var(--hi-radius-lg, 12px))
+                 var(--hk-modal-radius, var(--hi-radius-lg, 12px))
+                 0 0;
+  border-left: 0;
+  border-right: 0;
+  border-bottom: 0;
+  max-height: min(
+    72vh,
+    calc(
+      100vh - var(--hk-sheet-top-inset, 4.25rem) -
+        var(--hk-sheet-bottom-gap, 0.375rem)
+    )
+  );
+  display: flex;
+  flex-direction: column;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  padding-top: 0;
+  /* The sheet's bottom-edge distance itself comes from the shared
+   * --hk-sheet-bottom-gap (inline in HkPopover's sheet style); here the
+   * content keeps the last row clear of the home bar: the safe-area
+   * inset stacked on a 12px family base, which also restores a bottom
+   * cushion over the glass dropdown chrome (equal specificity, earlier
+   * in source, whose own bottom padding the sheet rule would otherwise
+   * zero out). The modal sheet footer goes further (it adds
+   * --hk-sheet-footer-gap for its action buttons); this sheet has no
+   * footer, so this is the family baseline. */
+  padding-bottom: calc(var(--space-12, 0.75rem) + env(safe-area-inset-bottom, 0px));
+
+  /* Overlay scrollbar (useOverlayScrollbar, sheet mode only) — the
+     native chrome is hidden, never styled. */
+  scrollbar-width: none;
+
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}
+
+.hk-popover-sheet-grabber {
+  flex-shrink: 0;
+  // Grabber zone: tap target tall enough for a thumb, bar visually small.
+  padding: 14px 0 20px;
+  margin: 0 auto;
+  width: 100%;
+  cursor: pointer;
+  display: flex;
+  justify-content: center;
+
+  &::before {
+    content: "";
+    width: 2.25rem;
+    height: 4px;
+    border-radius: 999px;
+    background: rgb(var(--color-border, 100 100 100) / 40%);
+  }
+}
+
+.hk-popover-sheet-title {
+  flex-shrink: 0;
+  // Same heading grammar as the select sheet title: small, semibold,
+  // slightly letterspaced, inset to the content edge. Hosts tune the
+  // leading inset via --hk-sheet-title-inset.
+  padding: 0 var(--space-16, 1rem) var(--space-8, 0.5rem)
+    var(--hk-sheet-title-inset, var(--space-16, 1rem));
+  font-size: var(--text-xs, 0.75rem);
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  color: rgb(var(--color-muted, 140 140 140));
+}
+
+.hk-popover-sheet-enter-active {
+  transition:
+    opacity 0.25s ease-out,
+    transform 0.3s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.hk-popover-sheet-leave-active {
+  transition:
+    opacity 0.2s ease-in,
+    transform 0.25s cubic-bezier(0.4, 0, 1, 1);
+}
+
+.hk-popover-sheet-enter-from,
+.hk-popover-sheet-leave-to {
+  opacity: 0;
+  transform: translateY(100%);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hk-popover-sheet-enter-active,
+  .hk-popover-sheet-leave-active {
+    transition: none;
+  }
+}

package/src/components/HkPopover.sheetdock.test.ts

@@ -0,0 +1,34 @@
+/**
+ * Source contract for the popover sheet docking (2026-08-30 user
+ * report: the theme toggle's bottom-up sheet didn't read as part of
+ * the standard sheet family). HkPopover's sheetOnMobile mode must dock
+ * with the SAME host-tunable --hk-sheet-bottom-gap as the HkModal and
+ * HkSelectPanel dockings, and keep its content clear of the home bar
+ * via the safe-area inset. The inline style used to pin hard
+ * `bottom: "0"`.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const tsx = readFileSync(join(here, "HkPopover.tsx"), "utf-8");
+const scss = readFileSync(join(here, "HkPopover.scss"), "utf-8");
+
+describe("HkPopover mobile sheet docking contract", () => {
+  it("docks the sheet above the shared bottom gap (inline sheet style)", () => {
+    const block = tsx.slice(tsx.indexOf("panelStyle"));
+    expect(block).toContain("var(--hk-sheet-bottom-gap");
+    // Same default as the HkModal sheet contract.
+    expect(block).toMatch(/--hk-sheet-bottom-gap,\s*0\.375rem/);
+  });
+
+  it("keeps sheet content clear of the home bar via the safe-area inset", () => {
+    const block = scss.match(/\.hk-popover-panel\.hk-is-sheet\s*{[^}]*}/)?.[0] ?? "";
+    // Stacked on the family 12px base so the glass dropdown chrome's
+    // bottom padding survives on non-notched phones too.
+    expect(block).toContain("calc(var(--space-12");
+    expect(block).toContain("env(safe-area-inset-bottom");
+  });
+});

package/src/components/HkPopover.surfacevars.test.ts

@@ -0,0 +1,20 @@
+/**
+ * Source contract: popover glass content reads --hk-popover-bg/--hk-popover-blur
+ * so a host surface-finish preference (chest html[data-surface]) can re-skin
+ * floating dropdown layers without forking the component.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const src = readFileSync(join(here, "HkPopover.scss"), "utf-8");
+
+describe("HkPopover glass layer surface hooks", () => {
+  it("keeps the glass background host-tunable with the historical default", () => {
+    const block = src.slice(src.indexOf(".hii-dropdown-content"));
+    expect(block).toContain("var(--hk-popover-bg, rgb(var(--color-surface)))");
+    expect(block).toContain("var(--hk-popover-blur,");
+  });
+});

package/src/components/HkPopover.titleSuppress.test.tsx

@@ -0,0 +1,265 @@
+/**
+ * Source contract: while an HkPopover is open, no native browser tooltip
+ * may fire over the custom popup — the anchor's `title` AND every
+ * descendant `title` are blanked and restored exactly (the model pill of
+ * hikari #338 was a descendant-title case). Restore must be lossless:
+ * elements without a title never gain one, `title=""` stays `title=""`,
+ * and unmounting while open must not leak a blanked title.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkPopover from "./HkPopover";
+
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+afterEach(() => {
+  for (const app of mounts.splice(0)) app.unmount();
+  for (const el of containers.splice(0)) el.remove();
+  // happy-dom never fires transitionend, so leave transitions never
+  // finish and teleported panels linger on <body> — strip them or the
+  // next test's querySelector sees this test's panel.
+  document.body
+    .querySelectorAll(".hk-popover-panel, .hk-popover-scrim")
+    .forEach((el) => el.remove());
+  vi.restoreAllMocks();
+});
+
+function setViewport(width: number) {
+  window.innerWidth = width;
+  window.dispatchEvent(new Event("resize"));
+}
+
+/**
+ * Mounts an HkPopover whose anchor is a plain DOM node (NOT rendered by
+ * Vue) so tests can decorate it with arbitrary `title` attributes and
+ * observe attribute mutations without Vue's patching interfering.
+ */
+function mountPopover(opts: { open?: boolean; anchor?: HTMLElement } = {}) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+
+  const anchor = opts.anchor ?? document.createElement("button");
+  // Only seed text on a fresh anchor — a caller-provided one may already
+  // carry the decorated descendants under test (textContent would wipe them).
+  if (!opts.anchor) anchor.textContent = "anchor";
+  container.appendChild(anchor);
+
+  const open = ref(opts.open ?? false);
+  const Wrapper = defineComponent({
+    setup() {
+      return () =>
+        h(HkPopover, {
+          modelValue: open.value,
+          "onUpdate:modelValue": (v: boolean) => { open.value = v; },
+          anchorRef: anchor,
+        }, { default: () => h("div", { class: "pop-content" }, "content") });
+    },
+  });
+  const app = createApp(Wrapper);
+  mounts.push(app);
+  app.mount(container);
+  return { open, app, anchor };
+}
+
+describe("HkPopover native title suppression", () => {
+  it("blanks the anchor's and descendants' titles while open and restores both exactly on close", async () => {
+    setViewport(1200);
+    const anchor = document.createElement("button");
+    anchor.setAttribute("title", "anchor tip");
+    const inner = document.createElement("span");
+    inner.setAttribute("title", "inner tip");
+    const nested = document.createElement("em");
+    nested.setAttribute("title", "nested tip");
+    inner.appendChild(nested);
+    anchor.appendChild(inner);
+
+    const { open } = mountPopover({ anchor });
+    await nextTick();
+    expect(anchor.getAttribute("title")).toBe("anchor tip");
+
+    open.value = true;
+    await nextTick();
+    expect(anchor.getAttribute("title")).toBe("");
+    expect(inner.getAttribute("title")).toBe("");
+    expect(nested.getAttribute("title")).toBe("");
+
+    open.value = false;
+    await nextTick();
+    expect(anchor.getAttribute("title")).toBe("anchor tip");
+    expect(inner.getAttribute("title")).toBe("inner tip");
+    expect(nested.getAttribute("title")).toBe("nested tip");
+  });
+
+  it("does not grant a title to an element that never had one", async () => {
+    setViewport(1200);
+    const anchor = document.createElement("button");
+    anchor.setAttribute("title", "anchor tip");
+    const plain = document.createElement("span");
+    anchor.appendChild(plain);
+
+    const { open } = mountPopover({ anchor });
+    open.value = true;
+    await nextTick();
+    open.value = false;
+    await nextTick();
+
+    expect(plain.hasAttribute("title")).toBe(false);
+    expect(plain.getAttribute("title")).toBeNull();
+  });
+
+  it("leaves an existing title=\"\" as title=\"\" (not removed, not filled)", async () => {
+    setViewport(1200);
+    const anchor = document.createElement("button");
+    const empty = document.createElement("span");
+    empty.setAttribute("title", "");
+    anchor.appendChild(empty);
+
+    const { open } = mountPopover({ anchor });
+    open.value = true;
+    await nextTick();
+    expect(empty.hasAttribute("title")).toBe(true);
+    expect(empty.getAttribute("title")).toBe("");
+
+    open.value = false;
+    await nextTick();
+    expect(empty.hasAttribute("title")).toBe(true);
+    expect(empty.getAttribute("title")).toBe("");
+  });
+
+  it("restores the anchor's title when unmounted while open", async () => {
+    setViewport(1200);
+    const anchor = document.createElement("button");
+    anchor.setAttribute("title", "unmount tip");
+
+    const { open, app } = mountPopover({ anchor });
+    open.value = true;
+    await nextTick();
+    expect(anchor.getAttribute("title")).toBe("");
+
+    app.unmount();
+    expect(anchor.getAttribute("title")).toBe("unmount tip");
+  });
+
+  it("performs no title-related DOM mutations when the anchor has no titles anywhere", async () => {
+    setViewport(1200);
+    const anchor = document.createElement("button");
+    const plain = document.createElement("span");
+    anchor.appendChild(plain);
+    const setSpy = vi.spyOn(anchor, "setAttribute");
+    const removeSpy = vi.spyOn(anchor, "removeAttribute");
+
+    const { open } = mountPopover({ anchor });
+    open.value = true;
+    await nextTick();
+    open.value = false;
+    await nextTick();
+
+    expect(setSpy).not.toHaveBeenCalled();
+    expect(removeSpy).not.toHaveBeenCalled();
+    expect(anchor.hasAttribute("title")).toBe(false);
+    expect(anchor.querySelector("[title]")).toBeNull();
+  });
+
+  it("restores the retired anchor and suppresses the new one on a mid-open anchorRef swap", async () => {
+    setViewport(1200);
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+
+    const oldAnchor = document.createElement("button");
+    oldAnchor.setAttribute("title", "old tip");
+    const oldInner = document.createElement("span");
+    oldInner.setAttribute("title", "old inner tip");
+    oldAnchor.appendChild(oldInner);
+    const newAnchor = document.createElement("button");
+    newAnchor.setAttribute("title", "new tip");
+    container.append(oldAnchor, newAnchor);
+
+    const open = ref(false);
+    const anchorRef = ref<HTMLElement | null>(oldAnchor);
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkPopover, {
+            modelValue: open.value,
+            "onUpdate:modelValue": (v: boolean) => { open.value = v; },
+            anchorRef: anchorRef.value,
+          }, { default: () => h("div", { class: "pop-content" }, "content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+
+    open.value = true;
+    await nextTick();
+    expect(oldAnchor.getAttribute("title")).toBe("");
+    expect(oldInner.getAttribute("title")).toBe("");
+
+    anchorRef.value = newAnchor;
+    await nextTick();
+    expect(oldAnchor.getAttribute("title")).toBe("old tip");
+    expect(oldInner.getAttribute("title")).toBe("old inner tip");
+    expect(newAnchor.getAttribute("title")).toBe("");
+
+    open.value = false;
+    await nextTick();
+    expect(newAnchor.getAttribute("title")).toBe("new tip");
+    expect(oldAnchor.getAttribute("title")).toBe("old tip");
+  });
+
+  it("restores the retired subtree when opening and an anchor swap land in the same flush", async () => {
+    setViewport(1200);
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+
+    const anchorA = document.createElement("button");
+    anchorA.setAttribute("title", "A tip");
+    const childA = document.createElement("span");
+    childA.setAttribute("title", "A child tip");
+    anchorA.appendChild(childA);
+    const anchorB = document.createElement("button");
+    anchorB.setAttribute("title", "B tip");
+    const childB = document.createElement("span");
+    childB.setAttribute("title", "B child tip");
+    anchorB.appendChild(childB);
+    container.append(anchorA, anchorB);
+
+    const open = ref(false);
+    const anchorRef = ref<HTMLElement | null>(anchorA);
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkPopover, {
+            modelValue: open.value,
+            "onUpdate:modelValue": (v: boolean) => { open.value = v; },
+            anchorRef: anchorRef.value,
+          }, { default: () => h("div", { class: "pop-content" }, "content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+
+    // Same tick: the popover never observes "open while anchored to A" —
+    // open and the swap to B land in one flush together.
+    open.value = true;
+    anchorRef.value = anchorB;
+    await nextTick();
+    expect(anchorA.getAttribute("title")).toBe("A tip");
+    expect(childA.getAttribute("title")).toBe("A child tip");
+    expect(anchorB.getAttribute("title")).toBe("");
+    expect(childB.getAttribute("title")).toBe("");
+
+    open.value = false;
+    await nextTick();
+    expect(anchorA.getAttribute("title")).toBe("A tip");
+    expect(childA.getAttribute("title")).toBe("A child tip");
+    expect(anchorB.getAttribute("title")).toBe("B tip");
+    expect(childB.getAttribute("title")).toBe("B child tip");
+  });
+});