@celestia-island/hikari 0.55.268 → 0.55.269

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.268",
+  "version": "0.55.269",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",

package/src/components/HkAuthMethodList.test.tsx

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, h, nextTick } from "vue";
 
 import HkAuthMethodList from "./HkAuthMethodList";
@@ -15,6 +15,7 @@ function mount(node: ReturnType<typeof h>) {
 }
 
 afterEach(() => {
+  vi.useRealTimers();
   for (const { app, container } of mounts.splice(0)) {
     app.unmount();
     container.remove();
@@ -61,17 +62,19 @@ describe("HkAuthMethodList", () => {
   });
 
   it("wraps every tile in a tooltip carrying the provider label", async () => {
+    vi.useFakeTimers();
     const c = mount(
       h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, { methods })),
     );
     const wrappers = c.querySelectorAll(".hk-tooltip-wrapper");
     expect(wrappers.length).toBe(2);
-    // Popups mount lazily on first engage — a touch tap mounts each one
-    // immediately — and then carry the label text.
+    // Popups mount lazily on first engage — hover each tile through the
+    // 300ms show delay (a touch press no longer mounts the popup: the
+    // touch half is the long-press hint bar, never the anchored popup).
     for (const w of wrappers) {
-      w.dispatchEvent(new PointerEvent("pointerdown", { pointerType: "touch", bubbles: true }));
+      w.dispatchEvent(new MouseEvent("mouseenter"));
     }
-    await Promise.resolve();
+    await vi.advanceTimersByTimeAsync(300);
     const popups = [...document.querySelectorAll(".hk-tooltip-popup .hk-tooltip-content")]
       .map((el) => el.textContent);
     expect(popups).toContain("GitHub");

package/src/components/HkColorSchemeDialog.test.ts

@@ -52,8 +52,8 @@ const SECTIONED_GROUP: TokenGroupDefinition = {
       label: { en: "Process media", "zh-Hans": "工艺介质" },
       slots: [
         {
-          key: "h2",
-          label: { en: "Hydrogen", "zh-Hans": "氢气" },
+          key: "buffer",
+          label: { en: "Buffer", "zh-Hans": "缓冲" },
           defaults: { dark: { r: 20, g: 184, b: 166 }, light: { r: 15, g: 118, b: 110 } },
         },
       ],
@@ -151,7 +151,7 @@ describe("HkColorSchemeDialog extension groups", () => {
     );
     expect(labels).toContain("L1 相（黄）");
     expect(labels).toContain("L2 相（绿）");
-    expect(labels).toContain("氢气");
+    expect(labels).toContain("缓冲");
 
     await setLocale("en");
   });

package/src/components/HkColorSchemeEditor.test.ts

@@ -50,8 +50,8 @@ const SECTIONED_GROUP: TokenGroupDefinition = {
       label: { en: "Process media", "zh-Hans": "工艺介质" },
       slots: [
         {
-          key: "h2",
-          label: { en: "Hydrogen", "zh-Hans": "氢气" },
+          key: "buffer",
+          label: { en: "Buffer", "zh-Hans": "缓冲" },
           defaults: { dark: { r: 20, g: 184, b: 166 }, light: { r: 15, g: 118, b: 110 } },
         },
       ],

package/src/components/HkCopyBadge.test.tsx

@@ -21,6 +21,7 @@ function mount(renderNode: () => ReturnType<typeof h>) {
 }
 
 afterEach(() => {
+  vi.useRealTimers();
   for (const { app, container } of mounts.splice(0)) {
     app.unmount();
     container.remove();
@@ -128,33 +129,36 @@ describe("HkCopyBadge", () => {
     expect(writeText).not.toHaveBeenCalled();
   });
 
-  /** Engage the lazy tooltip without hovering: a touch tap mounts the
-   *  popup immediately (showNow), no fake timers needed. */
-  function engageTooltip(c: HTMLElement) {
-    c.querySelector(".hk-tooltip-wrapper")!.dispatchEvent(
-      new PointerEvent("pointerdown", { pointerType: "touch", bubbles: true }),
-    );
+  /** Engage the lazy tooltip the way a mouse user does: hover the
+   *  wrapper through the 300ms show delay. (A touch press no longer
+   *  mounts the popup — the touch half is the long-press hint bar, so
+   *  the tap vehicle this helper replaced is gone for good.) */
+  async function engageTooltip(c: HTMLElement) {
+    c.querySelector(".hk-tooltip-wrapper")!.dispatchEvent(new MouseEvent("mouseenter"));
+    await vi.advanceTimersByTimeAsync(300);
+    await nextTick();
   }
 
   it("renders the custom tooltip text", async () => {
+    vi.useFakeTimers();
     const c = mount(() => h(HkCopyBadge, { tooltip: "Open details" }, () => "#d.132"));
     // The popup mounts lazily on first engage (dense-list contract).
     expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
-    engageTooltip(c);
-    await nextTick();
+    await engageTooltip(c);
     const content = document.body.querySelector(".hk-tooltip-popup .hk-tooltip-content");
     expect(content?.textContent).toBe("Open details");
   });
 
   it("shows the localized click-to-copy tooltip by default", async () => {
+    vi.useFakeTimers();
     const c = mount(() => h(HkCopyBadge, null, () => "#d.132"));
-    engageTooltip(c);
-    await nextTick();
+    await engageTooltip(c);
     const content = document.body.querySelector(".hk-tooltip-popup .hk-tooltip-content");
     expect(content?.textContent).toBe("Click to copy");
   });
 
   it("links the badge to the popup via aria-describedby across the whole lifecycle", async () => {
+    vi.useFakeTimers();
     const c = mount(() => h(HkCopyBadge, { tooltip: "Open details" }, () => "#d.132"));
     const badge = c.querySelector(".hk-badge")!;
 
@@ -163,8 +167,7 @@ describe("HkCopyBadge", () => {
     expect(document.body.querySelector(".hk-tooltip-popup")).toBeNull();
 
     // Engage: describedby == the popup id.
-    engageTooltip(c);
-    await nextTick();
+    await engageTooltip(c);
     const popup = document.body.querySelector(".hk-tooltip-popup")!;
     expect(badge.getAttribute("aria-describedby")).toBe(popup.getAttribute("id"));
     expect(popup.querySelector(".hk-tooltip-content")!.textContent).toBe("Open details");
@@ -175,8 +178,7 @@ describe("HkCopyBadge", () => {
     expect(badge.getAttribute("aria-describedby")).toBeNull();
 
     // Re-engage: returns, reusing the same popup element.
-    engageTooltip(c);
-    await nextTick();
+    await engageTooltip(c);
     expect(badge.getAttribute("aria-describedby")).toBe(
       document.body.querySelector(".hk-tooltip-popup")!.getAttribute("id"),
     );

package/src/components/HkInput.password.test.tsx

@@ -34,7 +34,8 @@ const fakeCreateImageData = fakeFn<CanvasRenderingContext2D["createImageData"]>(
  *   click-to-toggle with auto-hide (revealAutoHideMs)
  * - the strength dot classifies through the shared passwordLevel util
  *   unless strengthEvaluator overrides it, and carries a localized
- *   tooltip that opens on hover AND on touch tap
+ *   tooltip that opens on hover (desktop) / via the touch long-press
+ *   hint bar (the touch half is the top bar, never the anchored popup)
  * - the native input stays type="password" at all times — the reveal
  *   pass draws on the canvas, so the value is never DOM text
  */
@@ -108,10 +109,14 @@ function fireBeforeinput(input: HTMLInputElement, inputType: string) {
 }
 
 afterEach(() => {
+  vi.useRealTimers();
   for (const { app, container } of mounts.splice(0)) {
     app.unmount();
     container.remove();
   }
+  // The touch hint bar is presenter-owned module state (runtime/
+  // touchHint.ts) — tear the node out so a case remounts it fresh.
+  document.querySelectorAll(".hk-touch-hint-bar").forEach((el) => el.remove());
 });
 
 describe("HkInput password surface identity", () => {
@@ -566,32 +571,42 @@ describe("HkInput password strength traffic light", () => {
     ).toBe(false);
   });
 
-  it("opens the tooltip immediately on a touch tap and closes on an outside tap", async () => {
+  it("hints the strength on touch through the long-press bar, never the anchored popup", async () => {
+    vi.useFakeTimers();
     const { container } = mountPasswordInput("Password1", {
       passwordTrailing: "strength",
     });
     const wrapper = container.querySelector<HTMLElement>(".hk-tooltip-wrapper")!;
 
+    // A quick tap shows NOTHING: neither the anchored popup (hover/focus
+    // only) nor the top hint bar (the hold never elapsed).
     wrapper.dispatchEvent(
-      new PointerEvent("pointerdown", { pointerType: "touch", bubbles: true }),
+      new PointerEvent("pointerdown", { pointerType: "touch", pointerId: 1, bubbles: true }),
     );
-    await nextTick();
-
-    let popup = document.querySelector<HTMLElement>(".hk-tooltip-popup");
-    expect(popup?.classList.contains("hk-tooltip-visible")).toBe(true);
-    expect(popup?.textContent).toContain("Fair");
-
-    // Tap somewhere else: the capture-phase document listener hides it.
-    const outside = document.createElement("div");
-    document.body.appendChild(outside);
-    outside.dispatchEvent(
-      new PointerEvent("pointerdown", { pointerType: "touch", bubbles: true }),
+    await vi.advanceTimersByTimeAsync(100);
+    document.dispatchEvent(
+      new PointerEvent("pointerup", { pointerType: "touch", pointerId: 1, bubbles: true }),
     );
-    await nextTick();
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
+    expect(document.querySelector(".hk-touch-hint-bar")).toBeNull();
 
-    popup = document.querySelector<HTMLElement>(".hk-tooltip-popup");
-    expect(popup?.classList.contains("hk-tooltip-visible")).toBe(false);
-    outside.remove();
+    // The long-press fires the top-docked bar with the strength text…
+    wrapper.dispatchEvent(
+      new PointerEvent("pointerdown", { pointerType: "touch", pointerId: 1, bubbles: true }),
+    );
+    await vi.advanceTimersByTimeAsync(450);
+    const bar = document.querySelector<HTMLElement>(".hk-touch-hint-bar");
+    expect(bar?.classList.contains("is-on")).toBe(true);
+    expect(bar?.textContent).toContain("Fair");
+    expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
+
+    // …the lift starts the linger window, and the bar retires after it.
+    document.dispatchEvent(
+      new PointerEvent("pointerup", { pointerType: "touch", pointerId: 1, bubbles: true }),
+    );
+    await vi.advanceTimersByTimeAsync(2200);
+    expect(bar?.classList.contains("is-on")).toBe(false);
   });
 });
 

package/src/components/HkModalBreadcrumb.test.tsx

@@ -109,7 +109,7 @@ function menuRows(): HTMLElement[] {
   return [...document.body.querySelectorAll<HTMLElement>(".hk-menu-action-item")];
 }
 
-const LONG = "【e2e-w0-002310】自动化测试流水线冒烟：请巡检当前氢站电解槽压力与温度状态";
+const LONG = "【e2e-w0-002310】自动化测试流水线冒烟：请确认当前会话缓冲区与缓存状态正常";
 const LONG_TAIL = "【e2e-w0-002310】…";
 
 /** A stack that outgrows any viewport this suite uses: every label is cut to

package/src/components/HkTooltip.test.tsx

@@ -15,6 +15,11 @@ import { POPUP_Z_BANDS, POPUP_Z_STEP, usePopupManager } from "../runtime/usePopu
  * - show/hide: anchor mouseenter shows after the delay (default 300ms),
  *   mouseleave hides and cancels a pending show; focusin/focusout ride
  *   the same path
+ * - the touch half: a touch/pen press ARMS the long-press recognizer of
+ *   runtime/touchHint.ts — the hint surfaces in the top-docked touch
+ *   hint bar, never in the anchored popup (which stays hover/focus
+ *   only); a quick tap shows nothing at all, and the tap's synthetic
+ *   mouseenter cannot flash the popup
  * - anchoring: placement drives the popup class, the wrapper
  *   data-position and the measured offset style (happy-dom reports a
  *   zero rect, so the numbers pin the 8px gap and per-placement
@@ -83,6 +88,9 @@ afterEach(() => {
     manager.unregister(entry.id);
   }
   document.querySelectorAll(".hk-tooltip-popup").forEach((el) => el.remove());
+  // The touch hint bar is presenter-owned module state — tear the node
+  // out so the next case remounts it fresh (it self-heals on show).
+  document.querySelectorAll(".hk-touch-hint-bar").forEach((el) => el.remove());
 });
 
 describe("HkTooltip popup-manager registration", () => {
@@ -255,62 +263,58 @@ describe("HkTooltip show/hide", () => {
   });
 });
 
-describe("HkTooltip touch taps", () => {
-  function tap(el: Element) {
-    el.dispatchEvent(
-      new PointerEvent("pointerdown", { pointerType: "touch", bubbles: true }),
-    );
+describe("HkTooltip touch hint bar", () => {
+  // The touch half is the top-docked hint bar (runtime/touchHint.ts):
+  // a touch press ARMS a long-press recognizer against the wrapper, and
+  // the anchored popup stays a hover/focus (and pen-hover) surface.
+  function touchDown(el: Element) {
+    el.dispatchEvent(new PointerEvent("pointerdown", {
+      pointerType: "touch", pointerId: 1, clientX: 40, clientY: 40, bubbles: true,
+    }));
   }
 
-  it("shows immediately (no hover delay) on a touch tap", async () => {
-    const { container } = mount({ text: "tapped", delay: 3000 });
-    tap(wrapper(container));
-    await nextTick();
-    // The 3000ms hover delay must NOT gate the touch path.
-    expect(popup().className).toContain("hk-tooltip-visible");
-  });
+  function touchUp() {
+    document.dispatchEvent(new PointerEvent("pointerup", {
+      pointerType: "touch", pointerId: 1, bubbles: true,
+    }));
+  }
 
-  it("follows a moving anchor on the touch-opened path too", async () => {
-    const { container } = mount({ text: "touch moving", delay: 3000, placement: "bottom" });
-    let top = 100;
-    wrapper(container).getBoundingClientRect = () => ({
-      x: 200, y: top, left: 200, top, right: 280, bottom: top + 40,
-      width: 80, height: 40, toJSON: () => ({}),
-    }) as DOMRect;
-    tap(wrapper(container));
-    await settle();
-    expect(popup().style.top).toBe("148px");
-    top = 120;
-    await settle();
-    expect(popup().style.top).toBe("168px");
-    tap(wrapper(container)); // close also stops the tracking loop
-    await nextTick();
-    expect(popup().className).not.toContain("hk-tooltip-visible");
-  });
+  function hintBar(): HTMLElement | null {
+    return document.querySelector<HTMLElement>(".hk-touch-hint-bar");
+  }
 
-  it("toggles closed when the trigger is tapped again", async () => {
-    const { container } = mount({ text: "toggle", delay: 3000 });
-    tap(wrapper(container));
-    await nextTick();
-    expect(popup().className).toContain("hk-tooltip-visible");
+  it("long-press shows the top hint bar with the text, not the anchored popup", async () => {
+    vi.useFakeTimers();
+    const { container } = mount({ text: "hold me", delay: 3000 });
+    touchDown(wrapper(container));
+    await vi.advanceTimersByTimeAsync(449);
+    expect(hintBar()?.classList.contains("is-on")).toBeFalsy();
+    await vi.advanceTimersByTimeAsync(1);
+    expect(hintBar()?.classList.contains("is-on")).toBe(true);
+    expect(hintBar()?.textContent).toBe("hold me");
+    // The anchored popup never enters the touch path: no teleported
+    // node at all — the lazy engage never ran.
+    expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
+    touchUp(); // end the fired hold (restores the wrapper guards)
+  });
 
-    tap(wrapper(container));
-    await nextTick();
-    expect(popup().className).not.toContain("hk-tooltip-visible");
+  it("a quick tap shows neither the anchored popup nor the bar", async () => {
+    vi.useFakeTimers();
+    const { container } = mount({ text: "tap", delay: 3000 });
+    touchDown(wrapper(container));
+    await vi.advanceTimersByTimeAsync(100);
+    touchUp();
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
+    expect(hintBar()?.classList.contains("is-on")).toBeFalsy();
   });
 
-  it("closes on a tap anywhere else (capture-phase document listener)", async () => {
-    const { container } = mount({ text: "outside", delay: 0 });
-    tap(wrapper(container));
-    await nextTick();
+  it("mouse hover still shows the anchored popup (desktop unchanged)", async () => {
+    const { container } = mount({ text: "mouse only", delay: 0 });
+    enter(container);
+    await settle();
     expect(popup().className).toContain("hk-tooltip-visible");
-
-    const elsewhere = document.createElement("div");
-    document.body.appendChild(elsewhere);
-    tap(elsewhere);
-    await nextTick();
-    expect(popup().className).not.toContain("hk-tooltip-visible");
-    elsewhere.remove();
+    expect(hintBar()?.classList.contains("is-on")).toBeFalsy();
   });
 
   it("ignores mouse pointerdown (the hover path owns mice)", async () => {
@@ -320,25 +324,21 @@ describe("HkTooltip touch taps", () => {
     );
     await nextTick();
     // A mouse press never engages the lazy tooltip at all — no popup
-    // node, no visible class.
+    // node, no touch hint bar.
     expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
+    expect(hintBar()).toBeNull();
   });
 
-  it("does not re-open from the synthetic mouseenter right after a closing tap", async () => {
+  it("does not flash the anchored popup from the synthetic mouseenter after a tap", async () => {
     const { container } = mount({ text: "synthetic", delay: 0 });
-    tap(wrapper(container));
-    await nextTick();
-    expect(popup().className).toContain("hk-tooltip-visible");
-
-    tap(wrapper(container)); // close via toggle
+    touchDown(wrapper(container));
+    touchUp();
     await nextTick();
-    expect(popup().className).not.toContain("hk-tooltip-visible");
-
-    // The tap's synthetic mouseenter arrives synchronously after the
-    // pointerdown — it must not resurrect the bubble.
+    // The tap's synthetic mouseenter arrives right after the pointer
+    // events — it must not open the hover-only anchored popup.
     enter(container);
     await settle();
-    expect(popup().className).not.toContain("hk-tooltip-visible");
+    expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
   });
 });
 

package/src/components/HkTooltip.tsx

@@ -1,6 +1,7 @@
 import { computed, defineComponent, onBeforeUnmount, ref, Teleport, type CSSProperties, type PropType, type SlotsType } from "vue";
 import { usePopupManager, type PopupHandle } from "../runtime/usePopupManager";
 import { applyTooltipPosition, type TooltipPlacement } from "../runtime/tooltipPosition";
+import { armTouchHint } from "../runtime/touchHint";
 import "./HkTooltip.scss";
 import { ensureOverlayRoot } from "../overlay/overlayRoot";
 
@@ -103,18 +104,13 @@ export default defineComponent({
       }, props.delay);
     }
 
-    function showNow() {
-      clearShowTimer();
-      ensureEngaged();
-      visible.value = true;
-      trackPositionWhileVisible();
-    }
-
     function hide() {
       clearShowTimer();
       visible.value = false;
       stopPositionTracking();
-      dismissTouchListener();
+      // A hide means the hover/focus gesture is over — a touch hint
+      // armed in parallel (pen press while hovering) retires with it.
+      cancelTouchHint();
     }
 
     function clearShowTimer() {
@@ -124,49 +120,51 @@ export default defineComponent({
       }
     }
 
-    // ── touch taps ──────────────────────────────────────────────────
-    // Touch has no hover: a finger tap must open the bubble immediately
-    // (no delay) and the NEXT tap — anywhere else — must close it.
+    // ── touch long-press ────────────────────────────────────────────
+    // Touch has no hover, and the "what is this?" gesture on a phone is
+    // the LONG-PRESS — owned by the touch hint bar docked at the top of
+    // the viewport (runtime/touchHint.ts), never by this anchored popup
+    // (the finger would occlude the very element being inspected). A
+    // quick tap shows nothing at all: neither the popup nor the bar.
+    // Pen joins touch for the press (a stylus hold is the same
+    // deliberate ask) while KEEPING hover — stylus users float this
+    // popup, and a pen long-press may surface the bar beside it.
     // Tap-derived synthetic mouseenter/mouseleave events are ignored for
-    // a short window after a touch so they cannot re-open what the tap
-    // just closed.
+    // a short window after a touch so they cannot flash the anchored
+    // popup the touch mode never shows.
     // -Infinity sentinel: a plain 0 would suppress hover during the
     // first 600ms of page life (performance.now() starts near 0) and
     // under test fake timers (frozen at 0).
     let lastTouchAt = -Infinity;
-    let touchDismiss: ((e: PointerEvent) => void) | null = null;
+    let touchHintCancel: (() => void) | null = null;
 
-    function dismissTouchListener() {
-      if (touchDismiss) {
-        document.removeEventListener("pointerdown", touchDismiss, true);
-        touchDismiss = null;
+    function cancelTouchHint() {
+      if (touchHintCancel) {
+        touchHintCancel();
+        touchHintCancel = null;
       }
     }
 
     function onPointerdown(e: PointerEvent) {
-      if (e.pointerType !== "touch") return;
+      if (e.pointerType !== "touch" && e.pointerType !== "pen") return;
+      if (!props.text.trim()) return; // nothing to hint
       lastTouchAt = performance.now();
-      if (visible.value) {
-        hide();
-        return;
-      }
-      showNow();
-      touchDismiss = (ev: PointerEvent) => {
-        const node = wrapperRef.value;
-        if (node && ev.target instanceof Node && node.contains(ev.target)) {
-          // A re-tap on the trigger itself is the toggle case — handled
-          // by the branch above on its own pointerdown.
-          return;
-        }
-        hide();
-      };
-      document.addEventListener("pointerdown", touchDismiss, true);
+      // One hold at a time: a fresh press re-arms from scratch.
+      cancelTouchHint();
+      const node = wrapperRef.value;
+      if (!node) return;
+      touchHintCancel = armTouchHint(node, props.text, {
+        pointerId: e.pointerId,
+        // The exact contact point keeps the recognizer's slop math
+        // honest (the arm hook cannot see this event itself).
+        origin: { x: e.clientX, y: e.clientY },
+      });
     }
 
     onBeforeUnmount(() => {
       clearShowTimer();
       stopPositionTracking();
-      dismissTouchListener();
+      cancelTouchHint();
       if (popupHandle) {
         manager.unregister(popupHandle.id);
         popupHandle = null;
@@ -194,8 +192,9 @@ export default defineComponent({
         aria-describedby={visible.value ? popupId : undefined}
         onPointerdown={onPointerdown}
         onMouseenter={() => {
-          // Synthetic mouseenter right after a touch tap must not
-          // re-open the bubble the tap just toggled closed.
+          // Synthetic mouseenter right after a touch press must not
+          // flash the anchored popup the touch mode never shows — the
+          // top hint bar owns touch.
           if (performance.now() - lastTouchAt < 600) return;
           show();
         }}

package/src/composables/useRailIconFlight.test.ts

@@ -185,7 +185,13 @@ beforeEach(() => {
   ) {
     const listeners = new Map<string, EventListener>();
     let cancels = 0;
-    const handle = {
+    // Typed as a PARTIAL Animation (plus this suite's own fire()
+    // harness method, which the recorded animations read back) so the
+    // return below is a SINGLE cast — the type-escape gate rejects the
+    // double-cast this literal used to carry.
+    const handle: Partial<Animation> & {
+      fire(type: "finish" | "cancel"): void;
+    } = {
       addEventListener: (type: string, listener: EventListener) => {
         listeners.set(type, listener);
       },
@@ -204,7 +210,7 @@ beforeEach(() => {
       fire: handle.fire,
       cancelCount: () => cancels,
     });
-    return handle as unknown as Animation;
+    return handle as Animation;
   } as typeof animatable.animate;
 });
 
@@ -484,7 +490,7 @@ describe("useRailIconFlight", () => {
     // Minimal MediaQueryList fake — spread of a live list loses the
     // accessor. `matches: true` must be readable at SETUP time: the
     // composable subscribes once and reads its ref in flightCapable().
-    const fakeList = {
+    const fakeList: Partial<MediaQueryList> = {
       matches: true,
       media: "(prefers-reduced-motion: reduce)",
       onchange: null,
@@ -493,8 +499,10 @@ describe("useRailIconFlight", () => {
       addListener: () => {},
       removeListener: () => {},
       dispatchEvent: () => false,
-    } as unknown as MediaQueryList;
-    vi.spyOn(window, "matchMedia").mockReturnValue(fakeList);
+    };
+    // Single cast from the Partial (see the animate fake above): the
+    // gate owns the double-cast this file used to carry.
+    vi.spyOn(window, "matchMedia").mockReturnValue(fakeList as MediaQueryList);
     const h = mountSwap();
     await h.set(true);
     const { leaving, entering } = dissolvePair(h, true);

package/src/index.ts

@@ -424,6 +424,11 @@ export {
   installHkTapHighlight,
   type HkTapHighlightOptions,
   type HkTapHighlightColor,
+  installHkTouchHintBridge,
+  showHkTouchHintBar,
+  armTouchHint,
+  type HkTouchHintOptions,
+  type HkTouchHintArmOptions,
   reportHkRuntime,
   getHkRuntimeEntry,
   listHkRuntime,

package/src/runtime/index.ts

@@ -8,6 +8,15 @@ export {
   installHkTooltipBridge,
   type HkTooltipBridgeOptions,
 } from "./tooltipBridge";
+// The touch half of the tooltip story: the top-docked long-press
+// hint bar (bridge installer, bare presenter, component arm hook).
+export {
+  installHkTouchHintBridge,
+  showHkTouchHintBar,
+  armTouchHint,
+  type HkTouchHintOptions,
+  type HkTouchHintArmOptions,
+} from "./touchHint";
 export {
   installHkImageFallback,
   type HkImageFallbackOptions,
@@ -21,6 +30,7 @@ export {
   tooltipPositionStyle,
   applyTooltipPosition,
   resolveTooltipFlip,
+  snapToPixelGrid,
   TOOLTIP_GAP_PX,
   type TooltipPlacement,
 } from "./tooltipPosition";

package/src/runtime/tooltipBridge.test.ts

@@ -13,7 +13,9 @@ import { usePopupManager } from "./usePopupManager";
  *   it; fresher writers (host re-set, HkPopover's `title=""` blanking,
  *   Vue undefined-removal) always win
  * - escape hatches: empty titles, [data-hk-tooltip-native], elements
- *   inside an HkTooltip wrapper — never engage
+ *   inside an HkTooltip wrapper — never engage; a pointerover with
+ *   pointerType "touch" never engages either (the touch hint bar in
+ *   runtime/touchHint.ts owns touch pointers)
  * - pointerdown hides but stays engaged; scroll/resize and Esc disengage
  * - the popup mounts inside #hk-overlay-root (same home as the component
  *   tooltip's teleported popup) — at body level its in-root ordinal z
@@ -137,6 +139,21 @@ describe("installHkTooltipBridge", () => {
     expect(bridgePopup()?.classList.contains("hk-tooltip-visible")).toBe(false);
   });
 
+  it("never engages a touch pointerover (the touch hint bar owns touch)", () => {
+    vi.useFakeTimers();
+    install();
+    const el = trigger("Touch owned");
+    el.dispatchEvent(
+      new PointerEvent("pointerover", { pointerType: "touch", bubbles: true }),
+    );
+    // Title untouched: engaging here would strip the attribute for an
+    // anchored popup the touch mode never shows, and break the touch
+    // bar's own title/data-hk-title fallback chain.
+    expect(el.hasAttribute("title")).toBe(true);
+    vi.advanceTimersByTime(1000);
+    expect(bridgePopup()?.classList.contains("hk-tooltip-visible")).toBe(false);
+  });
+
   it("honors the exclude option", () => {
     vi.useFakeTimers();
     install({ exclude: ".quiet" });