@celestia-island/hikari 0.55.132 → 0.55.133

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.132",
+  "version": "0.55.133",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/animation/registerAnimations.ts

@@ -119,6 +119,12 @@ registerCssAnimation("hk-placeholder-marquee-scroll", { infinite: true });
 registerCssAnimation("s-admin-header-emergency-pulse", { infinite: true });
 registerCssAnimation("hk-loading-veil-in");
 registerCssAnimation("hk-loading-veil-spin", { infinite: true });
+// components/HkPersistentToast.scss — chrome-bar chip spinner (loops
+// forever while the loading tone shows).
+registerCssAnimation("hk-persistent-toast-spin", { infinite: true });
+// components/HkPersistentToast.scss — hover detail card entrance (plays
+// once; hides instantly on close, so no leave keyframe).
+registerCssAnimation("hk-persistent-toast-card-in");
 // The styles/theme/mixins.scss ambient/glow/entrance keyframes were
 // retired with the legacy Gen-1 sheet vendoring (hikari #476) — their
 // registrar entries went with them.

package/src/components/HkPersistentToast.scss

@@ -0,0 +1,143 @@
+// Chrome-bar persistent status chip — proportions match a title-bar
+// loading pill (HkStatusPill's compactness at toast-family semantics).
+// All colors ride the RGB-channel theme tokens so light/dark and the
+// glass/opacity pipelines apply without component-side branching.
+
+.hk-persistent-toast-wrap {
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  min-width: 0;
+  // The wrap owns the live-region semantics; the chip inside may be a
+  // button (chrome no-drag regions only exempt buttons from window
+  // dragging — see the wowsp title bar's interactive() gate).
+  font-size: var(--text-2xs, 0.6875rem);
+  line-height: 1.4;
+}
+
+.hk-persistent-toast {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-6, 0.375rem);
+  padding: 2px var(--space-8, 0.5rem);
+  border-radius: var(--radius-full, 999px);
+  border: 1px solid var(--border-faint, rgb(var(--color-border) / 10%));
+  background: rgb(var(--color-surface) / 60%);
+  color: rgb(var(--color-text) / 72%);
+  font: inherit;
+  max-width: 220px;
+  min-width: 0;
+}
+
+// Interactive variant (detail slot provided): a real button — reset the
+// browser chrome, tighten the start padding so the icon optically
+// balances, and give the hover a faint lift like HkTag's interactive
+// cousins.
+button.hk-persistent-toast {
+  cursor: pointer;
+  appearance: none;
+  padding-inline-start: var(--space-6, 0.375rem);
+
+  &:hover {
+    background: rgb(var(--color-surface) / 85%);
+    color: rgb(var(--color-text) / 90%);
+  }
+
+  &:focus-visible {
+    outline: 1px solid rgb(var(--color-primary) / 70%);
+    outline-offset: 1px;
+  }
+}
+
+.hk-persistent-toast__icon {
+  flex-shrink: 0;
+}
+
+.hk-persistent-toast--warning .hk-persistent-toast__icon {
+  color: rgb(var(--color-warning));
+}
+
+.hk-persistent-toast--error .hk-persistent-toast__icon {
+  color: rgb(var(--color-error));
+}
+
+.hk-persistent-toast--info .hk-persistent-toast__icon {
+  color: rgb(var(--color-muted));
+}
+
+.hk-persistent-toast__label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+// Same grammar as HkToast's spinner, sized for the chip and themed via
+// currentColor so the tone classes stay in one place.
+.hk-persistent-toast__spinner {
+  width: 11px;
+  height: 11px;
+  flex-shrink: 0;
+  border: 2px solid rgb(var(--color-text) / 25%);
+  border-top-color: rgb(var(--color-text) / 80%);
+  border-radius: 50%;
+  box-sizing: border-box;
+  animation: hk-persistent-toast-spin 0.7s linear infinite;
+}
+
+@keyframes hk-persistent-toast-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.hk-persistent-toast__dismiss {
+  appearance: none;
+  border: none;
+  background: transparent;
+  color: rgb(var(--color-text) / 45%);
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  padding: 2px;
+  border-radius: var(--radius-full, 999px);
+
+  &:hover {
+    color: rgb(var(--color-text));
+    background: rgb(var(--color-text) / 8%);
+  }
+
+  &:focus-visible {
+    outline: 1px solid rgb(var(--color-primary) / 70%);
+  }
+}
+
+// The detail card: a fixed-position rich surface teleported to body,
+// positioned by the component (below the chip, end-aligned, viewport-
+// clamped). Glass surface rides the shared hii-dropdown-content class;
+// only geometry and motion live here.
+.hk-persistent-toast-card {
+  position: fixed;
+  min-width: 200px;
+  max-width: 340px;
+  padding: var(--space-8, 0.5rem) var(--space-10, 0.75rem);
+  border-radius: var(--radius-lg, 0.5rem);
+  font-size: var(--text-2xs, 0.6875rem);
+  line-height: 1.5;
+  color: rgb(var(--color-text));
+  font-family: inherit;
+  animation: hk-persistent-toast-card-in 120ms ease-out;
+}
+
+@keyframes hk-persistent-toast-card-in {
+  from {
+    opacity: 0;
+    transform: translateY(-4px);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .hk-persistent-toast__spinner,
+  .hk-persistent-toast-card {
+    animation: none;
+  }
+}

package/src/components/HkPersistentToast.test.tsx

@@ -0,0 +1,263 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick } from "vue";
+
+import HkPersistentToast from "./HkPersistentToast";
+import { POPUP_Z_BANDS, usePopupManager } from "../runtime/usePopupManager";
+
+/**
+ * HkPersistentToast contract tests:
+ * - inert default: a chip without a detail slot renders a plain span,
+ *   engages no popup-manager entry and exposes no aria-expanded
+ * - hover open/close: detail slot + chip mouseenter opens the rich card
+ *   after the open delay (one tooltip-kind band entry, z stamped
+ *   inline); chip mouseleave closes it after the grace; moving onto the
+ *   card cancels the close (hover continuity is the whole point of the
+ *   rich card — the host list must survive the trip across the gap)
+ * - click pinning: a click pins the card against the grace timer until
+ *   an outside pointerdown / Escape / another click closes it
+ * - dismiss: the ✕ sibling button emits `dismiss` (never nested inside
+ *   the chip button)
+ * - the wrap carries the live-region semantics (role=status +
+ *   aria-live=polite) so label changes announce
+ *
+ * House style: raw createApp mounts on a shared container list torn
+ * down after each case; the popup-manager singleton is REAL state,
+ * swept afterEach the way HkTooltip.test.tsx does.
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+interface MountOptions {
+  props?: Record<string, unknown>;
+  detail?: string;
+  onDismiss?: () => void;
+}
+
+function mount({ props = {}, detail, onDismiss }: MountOptions = {}) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const host = defineComponent({
+    setup() {
+      return () =>
+        h(
+          HkPersistentToast,
+          { ...props, onDismiss } as never,
+          detail ? { detail: () => h("p", { class: "card-probe" }, detail) } : undefined,
+        );
+    },
+  });
+  const app = createApp(host);
+  app.mount(container);
+  mounts.push({ app, container });
+  return { app, container };
+}
+
+const manager = usePopupManager();
+
+function tooltipEntries() {
+  return [...manager.registry.value.values()].filter((e) => e.kind === "tooltip");
+}
+
+function chip(c: HTMLElement): HTMLElement {
+  return c.querySelector<HTMLElement>(".hk-persistent-toast")!;
+}
+
+function wrap(c: HTMLElement): HTMLElement {
+  return c.querySelector<HTMLElement>(".hk-persistent-toast-wrap")!;
+}
+
+function card(): HTMLElement {
+  return document.querySelector<HTMLElement>(".hk-persistent-toast-card")!;
+}
+
+/** real-timer settle: covers the open/close setTimeout + the rAF position pass */
+async function settle() {
+  await new Promise((r) => setTimeout(r, 20));
+  await nextTick();
+}
+
+function fire(el: Element, type: string, Ctor: typeof MouseEvent = MouseEvent) {
+  el.dispatchEvent(new Ctor(type, { bubbles: true }));
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+  for (const entry of [...manager.registry.value.values()]) {
+    manager.unregister(entry.id);
+  }
+  document.querySelectorAll(".hk-persistent-toast-card").forEach((el) => el.remove());
+});
+
+describe("HkPersistentToast inert default", () => {
+  it("renders label, tone class and live-region semantics as a plain span", () => {
+    const { container } = mount({ props: { tone: "error", label: "Upstream fault" } });
+    const c = chip(container);
+    expect(c.tagName).toBe("SPAN");
+    expect(c.classList.contains("hk-persistent-toast--error")).toBe(true);
+    expect(c.textContent).toContain("Upstream fault");
+    expect(wrap(container).getAttribute("role")).toBe("status");
+    expect(wrap(container).getAttribute("aria-live")).toBe("polite");
+    expect(c.getAttribute("aria-expanded")).toBeNull();
+    expect(tooltipEntries().length).toBe(0);
+    expect(document.querySelector(".hk-persistent-toast-card")).toBeNull();
+  });
+
+  it("renders the spinner for the loading tone", () => {
+    const { container } = mount({ props: { tone: "loading", label: "Loading" } });
+    expect(container.querySelector(".hk-persistent-toast__spinner")).not.toBeNull();
+  });
+
+  it("renders the ✕ sibling button only when dismissible", () => {
+    const onDismiss = vi.fn();
+    const { container } = mount({ props: { label: "x", dismissible: true }, onDismiss });
+    const dismiss = container.querySelector<HTMLElement>(".hk-persistent-toast__dismiss")!;
+    expect(dismiss).not.toBeNull();
+    // The ✕ must never nest inside the chip (a button in a button is
+    // invalid markup).
+    expect(chip(container).contains(dismiss)).toBe(false);
+    dismiss.click();
+    expect(onDismiss).toHaveBeenCalledTimes(1);
+  });
+
+  it("renders no ✕ when not dismissible", () => {
+    const { container } = mount({ props: { label: "x" } });
+    expect(container.querySelector(".hk-persistent-toast__dismiss")).toBeNull();
+  });
+});
+
+describe("HkPersistentToast detail card", () => {
+  it("opens on hover after the delay and closes after the grace", async () => {
+    const { container } = mount({
+      props: { label: "fault", openDelay: 0, closeGrace: 0, detailLabel: "Failing hosts" },
+      detail: "vortex.wowsgame.cn",
+    });
+    fire(chip(container), "mouseenter");
+    await settle();
+    const c = card();
+    expect(c).not.toBeNull();
+    expect(c.textContent).toContain("vortex.wowsgame.cn");
+    expect(chip(container).getAttribute("aria-expanded")).toBe("true");
+    const entries = tooltipEntries();
+    expect(entries.length).toBe(1);
+    expect(entries[0]!.kind).toBe("tooltip");
+    expect(c.style.zIndex).toBe(String(POPUP_Z_BANDS.tooltip));
+
+    fire(chip(container), "mouseleave");
+    await settle();
+    expect(card()).toBeNull();
+    expect(tooltipEntries().length).toBe(0);
+  });
+
+  it("delays the hover open by openDelay", async () => {
+    const { container } = mount({
+      props: { label: "fault", openDelay: 80, closeGrace: 0 },
+      detail: "hosts",
+    });
+    fire(chip(container), "mouseenter");
+    await nextTick();
+    expect(card()).toBeNull();
+    await new Promise((r) => setTimeout(r, 120));
+    await nextTick();
+    expect(card()).not.toBeNull();
+  });
+
+  it("keeps the card open while the pointer moves onto it", async () => {
+    const { container } = mount({
+      props: { label: "fault", openDelay: 0, closeGrace: 0 },
+      detail: "hosts",
+    });
+    fire(chip(container), "mouseenter");
+    await settle();
+    // Chip → card crossing: the close grace must be cancelled by the
+    // card's own mouseenter, or the host list dies mid-read.
+    fire(chip(container), "mouseleave");
+    fire(card(), "mouseenter");
+    await settle();
+    expect(card()).not.toBeNull();
+    // Leaving the card closes (nothing pinned).
+    fire(card(), "mouseleave");
+    await settle();
+    expect(card()).toBeNull();
+  });
+
+  it("pins on click: grace timer and chip leave cannot close it", async () => {
+    const { container } = mount({
+      props: { label: "fault", openDelay: 0, closeGrace: 0 },
+      detail: "hosts",
+    });
+    fire(chip(container), "mouseenter");
+    await settle();
+    chip(container).click();
+    fire(chip(container), "mouseleave");
+    await settle();
+    expect(card()).not.toBeNull();
+    expect(chip(container).getAttribute("aria-expanded")).toBe("true");
+  });
+
+  it("an outside pointerdown closes a pinned card", async () => {
+    const { container } = mount({
+      props: { label: "fault", openDelay: 0, closeGrace: 0 },
+      detail: "hosts",
+    });
+    chip(container).click();
+    await settle();
+    expect(card()).not.toBeNull();
+    document.body.dispatchEvent(
+      new MouseEvent("pointerdown", { bubbles: true }),
+    );
+    await settle();
+    expect(card()).toBeNull();
+  });
+
+  it("a click inside the card does not close a pinned card", async () => {
+    const { container } = mount({
+      props: { label: "fault", openDelay: 0, closeGrace: 0 },
+      detail: "hosts",
+    });
+    chip(container).click();
+    await settle();
+    card().dispatchEvent(new MouseEvent("pointerdown", { bubbles: true }));
+    await settle();
+    expect(card()).not.toBeNull();
+  });
+
+  it("Escape closes a pinned card", async () => {
+    const { container } = mount({
+      props: { label: "fault", openDelay: 0, closeGrace: 0 },
+      detail: "hosts",
+    });
+    chip(container).click();
+    await settle();
+    chip(container).dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" }));
+    await settle();
+    expect(card()).toBeNull();
+  });
+
+  it("a second click toggles a pinned card closed", async () => {
+    const { container } = mount({
+      props: { label: "fault", openDelay: 0, closeGrace: 0 },
+      detail: "hosts",
+    });
+    chip(container).click();
+    await settle();
+    chip(container).click();
+    await settle();
+    expect(card()).toBeNull();
+  });
+
+  it("releases the band entry on unmount while open", async () => {
+    const { app, container } = mount({
+      props: { label: "fault", openDelay: 0, closeGrace: 0 },
+      detail: "hosts",
+    });
+    fire(chip(container), "mouseenter");
+    await settle();
+    expect(tooltipEntries().length).toBe(1);
+    app.unmount();
+    expect(tooltipEntries().length).toBe(0);
+  });
+});

package/src/components/HkPersistentToast.tsx

@@ -0,0 +1,290 @@
+import { AlertTriangle, Info, X } from "lucide-vue-next";
+import {
+  computed,
+  defineComponent,
+  nextTick,
+  onBeforeUnmount,
+  ref,
+  Teleport,
+  type PropType,
+  type SlotsType,
+} from "vue";
+
+import { usePopupManager, type PopupHandle } from "../runtime/usePopupManager";
+import { useI18n } from "../i18n/context";
+import "./HkPersistentToast.scss";
+
+export type PersistentToastTone = "loading" | "info" | "warning" | "error";
+
+/** Viewport gutter the detail card clamps into (mirror of
+ *  --viewport-gutter's desktop value; the card is chrome-adjacent and
+ *  small, so the mobile/desktop split is not worth a runtime read). */
+const GUTTER_PX = 8;
+/** Vertical gap between the chip's bottom edge and the detail card. */
+const CARD_GAP_PX = 6;
+
+let popupSeq = 0;
+
+/**
+ * HkPersistentToast — a persistent status chip for chrome bars (title
+ * bars, status strips): the third member of the toast family after
+ * HkToast (transient corner stack) and HkBlockingToast (window-modal).
+ * It never auto-dismisses; the host renders it while a condition holds
+ * (a load in flight, an upstream outage) and unmounts it when the
+ * condition clears.
+ *
+ * ```tsx
+ * <HPersistentToast tone="loading" label="Loading stats…" />
+ * <HPersistentToast tone="error" label="Upstream fault" onDismiss={silence}>
+ *   <template #detail>…rich card…</template>
+ * </HPersistentToast>
+ * ```
+ *
+ * Behavior contract:
+ * - `tone="loading"` renders a spinner, the other tones a static icon;
+ *   the label truncates, the chip never wraps.
+ * - With a `detail` slot the chip becomes a button: hover (after
+ *   `openDelay`) or focus opens the rich card anchored below the chip;
+ *   moving the pointer onto the card keeps it open (`closeGrace`), and
+ *   a click PINNS it — a pinned card only closes on its own Escape /
+ *   outside click / another chip click, so touch users get parity.
+ * - `onDismiss` (a dismiss emit) renders the ✕ affordance beside the
+ *   chip; the chip itself stays a single interactive surface (the ✕ is
+ *   a sibling button, never nested — a button inside a button is dead
+ *   markup).
+ * - The wrap carries role="status" + aria-live="polite", so label
+ *   changes announce without stealing focus — the property the wowsp
+ *   title-bar loading chip relies on.
+ */
+export default defineComponent({
+  name: "HkPersistentToast",
+  props: {
+    tone: { type: String as PropType<PersistentToastTone>, default: "info" },
+    /** Text beside the icon; truncates rather than wraps. */
+    label: { type: String, default: "" },
+    /** Hover/focus card content; providing the slot makes the chip interactive. */
+    detailLabel: { type: String, default: "" },
+    /** Renders the ✕ affordance beside the chip; clicking it emits `dismiss`.
+     *  A sibling button, never a child of the chip — a button inside a
+     *  button is invalid markup and would break the chip's click toggle. */
+    dismissible: { type: Boolean, default: false },
+    openDelay: { type: Number, default: 150 },
+    closeGrace: { type: Number, default: 250 },
+  },
+  emits: {
+    dismiss: () => true,
+  },
+  slots: Object as SlotsType<{
+    detail?: () => unknown;
+  }>,
+  setup(props, { slots, emit }) {
+    const { t } = useI18n();
+    const manager = usePopupManager();
+    const wrapRef = ref<HTMLElement | null>(null);
+    const cardRef = ref<HTMLElement | null>(null);
+    const open = ref(false);
+    const pinned = ref(false);
+    const zIndex = ref<number | null>(null);
+    const popupId = `hk-persistent-toast-${++popupSeq}`;
+    let handle: PopupHandle | null = null;
+    let openTimer: ReturnType<typeof setTimeout> | null = null;
+    let closeTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const interactive = computed(() => !!slots.detail);
+
+    // The card is LAZY (tooltip-bridge contract): a chip nobody hovers
+    // costs no teleported node and no band registration. The handle is
+    // held for the whole open window — hover-out only closes, unmount
+    // releases.
+    function ensureHandle() {
+      if (!handle) {
+        handle = manager.register("tooltip", false);
+        zIndex.value = handle.zIndex;
+      }
+    }
+
+    function releaseHandle() {
+      if (handle) {
+        manager.unregister(handle.id);
+        handle = null;
+      }
+      zIndex.value = null;
+    }
+
+    function clearTimers() {
+      if (openTimer !== null) {
+        clearTimeout(openTimer);
+        openTimer = null;
+      }
+      if (closeTimer !== null) {
+        clearTimeout(closeTimer);
+        closeTimer = null;
+      }
+    }
+
+    /** Anchor the card below the chip, right-aligned to it (chrome bars
+     *  hug the window's trailing corner, so an end-aligned card grows
+     *  leftward into the roomier side), clamped into the viewport. */
+    function positionCard() {
+      const chip = wrapRef.value;
+      const card = cardRef.value;
+      if (!chip || !card) return;
+      const rect = chip.getBoundingClientRect();
+      const vw = window.innerWidth;
+      const vh = window.innerHeight;
+      let left = rect.right - card.offsetWidth;
+      left = Math.max(GUTTER_PX, Math.min(left, vw - GUTTER_PX - card.offsetWidth));
+      let top = rect.bottom + CARD_GAP_PX;
+      top = Math.max(GUTTER_PX, Math.min(top, vh - GUTTER_PX - card.offsetHeight));
+      card.style.left = `${left}px`;
+      card.style.top = `${top}px`;
+    }
+
+    function openCard(pin: boolean) {
+      clearTimers();
+      ensureHandle();
+      if (pin) pinned.value = true;
+      open.value = true;
+      nextTick(() => requestAnimationFrame(positionCard));
+    }
+
+    function closeCard(force = false) {
+      if (pinned.value && !force) return;
+      pinned.value = false;
+      open.value = false;
+      releaseHandle();
+    }
+
+    function scheduleOpen() {
+      if (openTimer !== null) clearTimeout(openTimer);
+      openTimer = setTimeout(() => {
+        openTimer = null;
+        openCard(false);
+      }, props.openDelay);
+    }
+
+    function scheduleClose() {
+      if (closeTimer !== null) clearTimeout(closeTimer);
+      closeTimer = setTimeout(() => {
+        closeTimer = null;
+        closeCard(false);
+      }, props.closeGrace);
+    }
+
+    function cancelClose() {
+      if (closeTimer !== null) {
+        clearTimeout(closeTimer);
+        closeTimer = null;
+      }
+    }
+
+    function onChipClick() {
+      if (pinned.value) {
+        closeCard(true);
+      } else {
+        // A click during the hover-open window promotes to pinned in
+        // place — the card must not flicker closed and reopen.
+        openCard(true);
+      }
+    }
+
+    function onChipKeydown(e: KeyboardEvent) {
+      if (e.key === "Escape" && open.value) {
+        e.preventDefault();
+        e.stopPropagation();
+        closeCard(true);
+      }
+    }
+
+    // Outside clicks close a PINNED card (a hover-open card closes on
+    // its own grace timer; listening always would fight the chip's own
+    // click toggle — hence the contains check).
+    function onDocumentPointerdown(e: PointerEvent) {
+      if (!open.value || !pinned.value) return;
+      const target = e.target as Node;
+      if (wrapRef.value?.contains(target)) return;
+      if (cardRef.value?.contains(target)) return;
+      closeCard(true);
+    }
+
+    function onWindowResize() {
+      if (open.value) positionCard();
+    }
+
+    document.addEventListener("pointerdown", onDocumentPointerdown, true);
+    window.addEventListener("resize", onWindowResize);
+
+    onBeforeUnmount(() => {
+      clearTimers();
+      releaseHandle();
+      document.removeEventListener("pointerdown", onDocumentPointerdown, true);
+      window.removeEventListener("resize", onWindowResize);
+    });
+
+    const cardStyle = computed(() => (zIndex.value != null ? { zIndex: zIndex.value } : {}));
+
+    return () => {
+      const Tag = (interactive.value ? "button" : "span") as "button";
+      return (
+        <span ref={wrapRef} class="hk-persistent-toast-wrap" role="status" aria-live="polite">
+          <Tag
+            type={interactive.value ? "button" : undefined}
+            class={["hk-persistent-toast", `hk-persistent-toast--${props.tone}`]}
+            aria-expanded={interactive.value ? open.value : undefined}
+            aria-haspopup={interactive.value ? "true" : undefined}
+            aria-controls={open.value ? popupId : undefined}
+            onMouseenter={interactive.value ? scheduleOpen : undefined}
+            onMouseleave={interactive.value ? scheduleClose : undefined}
+            onFocusin={interactive.value ? () => openCard(false) : undefined}
+            onFocusout={
+              interactive.value
+                ? () => {
+                    if (!pinned.value) closeCard(false);
+                  }
+                : undefined
+            }
+            onClick={interactive.value ? onChipClick : undefined}
+            onKeydown={interactive.value ? onChipKeydown : undefined}
+          >
+            {props.tone === "loading" ? (
+              <span class="hk-persistent-toast__spinner" aria-hidden="true" />
+            ) : props.tone === "error" || props.tone === "warning" ? (
+              <AlertTriangle size={12} class="hk-persistent-toast__icon" aria-hidden="true" />
+            ) : (
+              <Info size={12} class="hk-persistent-toast__icon" aria-hidden="true" />
+            )}
+            <span class="hk-persistent-toast__label">{props.label}</span>
+          </Tag>
+          {props.dismissible && (
+            <button
+              type="button"
+              class="hk-persistent-toast__dismiss"
+              aria-label={t("hikari::persistentToast.dismiss", "Dismiss")}
+              onClick={() => emit("dismiss")}
+            >
+              <X size={12} aria-hidden="true" />
+            </button>
+          )}
+          {slots.detail && open.value && (
+            <Teleport to="body">
+              <div
+                ref={cardRef}
+                id={popupId}
+                class="hk-persistent-toast-card hii-dropdown-content"
+                role="group"
+                aria-label={props.detailLabel || undefined}
+                style={cardStyle.value}
+                onMouseenter={cancelClose}
+                onMouseleave={() => {
+                  if (!pinned.value) scheduleClose();
+                }}
+              >
+                {slots.detail()}
+              </div>
+            </Teleport>
+          )}
+        </span>
+      );
+    };
+  },
+});

package/src/components/HkPersistentToastGroup.scss

@@ -0,0 +1,22 @@
+// Chrome-bar chip row: chips + the "+N" overflow counter, one compact
+// line. Token palette mirrors HkPersistentToast.scss so the pair reads
+// as one family inside a title bar.
+.hk-persistent-toast-group {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  min-width: 0;
+}
+
+.hk-persistent-toast-group__extra {
+  flex-shrink: 0;
+  display: inline-flex;
+  align-items: center;
+  padding: 1px 6px;
+  border-radius: var(--radius-full, 999px);
+  background: rgb(var(--color-text) / 8%);
+  color: rgb(var(--color-text) / 72%);
+  font-size: var(--text-2xs, 0.6875rem);
+  line-height: 1.4;
+  font-variant-numeric: tabular-nums;
+}

package/src/components/HkPersistentToastGroup.test.tsx

@@ -0,0 +1,82 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h } from "vue";
+
+import HkPersistentToast from "./HkPersistentToast";
+import HkPersistentToastGroup from "./HkPersistentToastGroup";
+
+/**
+ * HkPersistentToastGroup contract tests:
+ * - renders the first maxVisible children and collapses the rest into
+ *   the "+N" counter
+ * - comment placeholders (v-if=false children) do not count
+ * - hidden children are unmounted, so their own DOM never reaches the
+ *   document
+ *
+ * House style: raw createApp mounts torn down afterEach.
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mountRow(count: number, maxVisible: number) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const host = defineComponent({
+    setup() {
+      return () =>
+        h(
+          HkPersistentToastGroup,
+          { maxVisible } as never,
+          {
+            default: () =>
+              Array.from({ length: count }, (_, i) =>
+                h(HkPersistentToast, { key: i, tone: "loading", label: `task ${i}` }),
+              ),
+          },
+        );
+    },
+  });
+  const app = createApp(host);
+  app.mount(container);
+  mounts.push({ app, container });
+  return { app, container };
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+function chips(c: HTMLElement) {
+  return c.querySelectorAll(".hk-persistent-toast");
+}
+
+describe("HkPersistentToastGroup", () => {
+  it("renders up to maxVisible chips and collapses the rest into +N", () => {
+    const { container } = mountRow(4, 1);
+    expect(chips(container).length).toBe(1);
+    expect(chips(container)[0]!.textContent).toContain("task 0");
+    const extra = container.querySelector<HTMLElement>(".hk-persistent-toast-group__extra")!;
+    expect(extra.textContent).toBe("+3");
+  });
+
+  it("renders everything when count fits and skips the counter", () => {
+    const { container } = mountRow(2, 3);
+    expect(chips(container).length).toBe(2);
+    expect(container.querySelector(".hk-persistent-toast-group__extra")).toBeNull();
+  });
+
+  it("unmounts hidden chips entirely (no stray DOM)", () => {
+    const { container } = mountRow(3, 1);
+    expect(document.body.textContent).not.toContain("task 1");
+    expect(document.body.textContent).not.toContain("task 2");
+    expect(chips(container).length).toBe(1);
+  });
+
+  it("renders an empty group without noise", () => {
+    const { container } = mountRow(0, 1);
+    expect(chips(container).length).toBe(0);
+    expect(container.querySelector(".hk-persistent-toast-group__extra")).toBeNull();
+  });
+});

package/src/components/HkPersistentToastGroup.tsx

@@ -0,0 +1,45 @@
+import { Comment, defineComponent, type PropType, type SlotsType, type VNode } from "vue";
+
+import "./HkPersistentToastGroup.scss";
+
+/**
+ * HkPersistentToastGroup — a chrome-bar row of HkPersistentToast chips
+ * with a "+N" overflow: renders the first `maxVisible` children and
+ * collapses the rest into a passive counter. The wowsp title bar's
+ * loading chip ("newest label + +N") is the reference consumer.
+ *
+ * ```tsx
+ * <HPersistentToastGroup maxVisible={1}>
+ *   {tasks.map((t) => (
+ *     <HPersistentToast key={t.id} tone="loading" label={t.label} />
+ *   ))}
+ * </HPersistentToastGroup>
+ * ```
+ *
+ * Hidden children are UNMOUNTED, not merely hidden — their hover cards
+ * and timers are their own state and die with the vnode; a chip that
+ * re-enters the visible window starts fresh (a persistent toast has no
+ * meaningful state to preserve across an overflow eviction).
+ */
+export default defineComponent({
+  name: "HkPersistentToastGroup",
+  props: {
+    maxVisible: { type: Number as PropType<number>, default: 3 },
+  },
+  slots: Object as SlotsType<{
+    default?: () => unknown;
+  }>,
+  setup(props, { slots }) {
+    return () => {
+      const children = ((slots.default?.() ?? []) as VNode[]).filter((v) => v.type !== Comment);
+      const visible = children.slice(0, Math.max(0, props.maxVisible));
+      const extra = children.length - visible.length;
+      return (
+        <span class="hk-persistent-toast-group">
+          {visible}
+          {extra > 0 && <span class="hk-persistent-toast-group__extra">+{extra}</span>}
+        </span>
+      );
+    };
+  },
+});

package/src/i18n/locales/ar/components.json

@@ -128,6 +128,7 @@
     "hikari::passwordInput.strengthLabel": "قوة كلمة المرور",
     "hikari::passwordInput.strengthStrong": "قوية",
     "hikari::passwordInput.strengthWeak": "ضعيفة",
+    "hikari::persistentToast.dismiss": "تجاهل",
     "hikari::phoneInput.chooseCountry": "اختر رمز الدولة",
     "hikari::phoneInput.dialCode": "الرمز",
     "hikari::phoneInput.noMatches": "لا توجد دولة مطابقة",

package/src/i18n/locales/de/components.json

@@ -128,6 +128,7 @@
     "hikari::passwordInput.strengthLabel": "Passwortstärke",
     "hikari::passwordInput.strengthStrong": "Stark",
     "hikari::passwordInput.strengthWeak": "Schwach",
+    "hikari::persistentToast.dismiss": "Ausblenden",
     "hikari::phoneInput.chooseCountry": "Ländercode wählen",
     "hikari::phoneInput.dialCode": "Code",
     "hikari::phoneInput.noMatches": "Kein passendes Land",

package/src/i18n/locales/en/components.json

@@ -128,6 +128,7 @@
     "hikari::passwordInput.strengthLabel": "Password strength",
     "hikari::passwordInput.strengthStrong": "Strong",
     "hikari::passwordInput.strengthWeak": "Weak",
+    "hikari::persistentToast.dismiss": "Dismiss",
     "hikari::phoneInput.chooseCountry": "Choose country code",
     "hikari::phoneInput.dialCode": "Code",
     "hikari::phoneInput.noMatches": "No matching country",

package/src/i18n/locales/es/components.json

@@ -128,6 +128,7 @@
     "hikari::passwordInput.strengthLabel": "Fuerza de la contraseña",
     "hikari::passwordInput.strengthStrong": "Fuerte",
     "hikari::passwordInput.strengthWeak": "Débil",
+    "hikari::persistentToast.dismiss": "Descartar",
     "hikari::phoneInput.chooseCountry": "Elegir prefijo país",
     "hikari::phoneInput.dialCode": "Código",
     "hikari::phoneInput.noMatches": "Sin coincidencias de país",

package/src/i18n/locales/fr/components.json

@@ -128,6 +128,7 @@
     "hikari::passwordInput.strengthLabel": "Robustesse du mot de passe",
     "hikari::passwordInput.strengthStrong": "Fort",
     "hikari::passwordInput.strengthWeak": "Faible",
+    "hikari::persistentToast.dismiss": "Ignorer",
     "hikari::phoneInput.chooseCountry": "Choisir l'indicatif pays",
     "hikari::phoneInput.dialCode": "Code",
     "hikari::phoneInput.noMatches": "Aucun pays correspondant",

package/src/i18n/locales/ja/components.json

@@ -128,6 +128,7 @@
     "hikari::passwordInput.strengthLabel": "パスワード強度",
     "hikari::passwordInput.strengthStrong": "強い",
     "hikari::passwordInput.strengthWeak": "弱い",
+    "hikari::persistentToast.dismiss": "閉じる",
     "hikari::phoneInput.chooseCountry": "国コードを選択",
     "hikari::phoneInput.dialCode": "コード",
     "hikari::phoneInput.noMatches": "一致する国がありません",

package/src/i18n/locales/ko/components.json

@@ -128,6 +128,7 @@
     "hikari::passwordInput.strengthLabel": "비밀번호 강도",
     "hikari::passwordInput.strengthStrong": "강함",
     "hikari::passwordInput.strengthWeak": "약함",
+    "hikari::persistentToast.dismiss": "닫기",
     "hikari::phoneInput.chooseCountry": "국가 코드 선택",
     "hikari::phoneInput.dialCode": "코드",
     "hikari::phoneInput.noMatches": "일치하는 국가가 없습니다",

package/src/i18n/locales/pt/components.json

@@ -128,6 +128,7 @@
     "hikari::passwordInput.strengthLabel": "Força da senha",
     "hikari::passwordInput.strengthStrong": "Forte",
     "hikari::passwordInput.strengthWeak": "Fraca",
+    "hikari::persistentToast.dismiss": "Dispensar",
     "hikari::phoneInput.chooseCountry": "Escolher código do país",
     "hikari::phoneInput.dialCode": "Código",
     "hikari::phoneInput.noMatches": "Nenhum país correspondente",

package/src/i18n/locales/ru/components.json

@@ -128,6 +128,7 @@
     "hikari::passwordInput.strengthLabel": "Надёжность пароля",
     "hikari::passwordInput.strengthStrong": "Сильный",
     "hikari::passwordInput.strengthWeak": "Слабый",
+    "hikari::persistentToast.dismiss": "Скрыть",
     "hikari::phoneInput.chooseCountry": "Выберите код страны",
     "hikari::phoneInput.dialCode": "Код",
     "hikari::phoneInput.noMatches": "Подходящей страны не найдено",

package/src/i18n/locales/zh-Hans/components.json

@@ -128,6 +128,7 @@
     "hikari::passwordInput.strengthLabel": "密码强度",
     "hikari::passwordInput.strengthStrong": "强",
     "hikari::passwordInput.strengthWeak": "弱",
+    "hikari::persistentToast.dismiss": "关闭",
     "hikari::phoneInput.chooseCountry": "选择国家区号",
     "hikari::phoneInput.dialCode": "区号",
     "hikari::phoneInput.noMatches": "没有匹配的国家",

package/src/i18n/locales/zh-Hant/components.json

@@ -128,6 +128,7 @@
     "hikari::passwordInput.strengthLabel": "密碼強度",
     "hikari::passwordInput.strengthStrong": "強",
     "hikari::passwordInput.strengthWeak": "弱",
+    "hikari::persistentToast.dismiss": "關閉",
     "hikari::phoneInput.chooseCountry": "選擇國家區碼",
     "hikari::phoneInput.dialCode": "區碼",
     "hikari::phoneInput.noMatches": "沒有符合的國家",

package/src/index.ts

@@ -114,6 +114,8 @@ export {
   acceptExtensions,
 } from "./components/filePicker";
 export { default as HToast } from "./components/HkToast";
+export { default as HPersistentToast } from "./components/HkPersistentToast";
+export { default as HPersistentToastGroup } from "./components/HkPersistentToastGroup";
 export { default as HTooltip } from "./components/HkTooltip";
 export { default as HTree } from "./components/HkTree";
 export { default as HWindowedItem } from "./components/HkWindowedItem";
@@ -754,6 +756,8 @@ export { default as HkFileField } from "./components/HkFileField";
 export { default as HkFileBrowserDialog } from "./components/HkFileBrowserDialog";
 export { default as HkFilePickerField } from "./components/HkFilePickerField";
 export { default as HkToast } from "./components/HkToast";
+export { default as HkPersistentToast, type PersistentToastTone } from "./components/HkPersistentToast";
+export { default as HkPersistentToastGroup } from "./components/HkPersistentToastGroup";
 export { default as HkTooltip } from "./components/HkTooltip";
 export { type HkTooltipSlotProps } from "./components/HkTooltip";
 export { default as HkTree } from "./components/HkTree";