@celestia-island/hikari 0.55.116 → 0.55.118

package/package.json

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

package/src/components/HkAuthMethodList.test.tsx

@@ -60,13 +60,18 @@ describe("HkAuthMethodList", () => {
     expect(c.querySelector(".s-auth-methods [role='radiogroup']")).toBeNull();
   });
 
-  it("wraps every tile in a tooltip carrying the provider label", () => {
+  it("wraps every tile in a tooltip carrying the provider label", async () => {
     const c = mount(
       h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, { methods })),
     );
     const wrappers = c.querySelectorAll(".hk-tooltip-wrapper");
     expect(wrappers.length).toBe(2);
-    // The teleported popups exist with the label text (hidden until hover).
+    // Popups mount lazily on first engage — a touch tap mounts each one
+    // immediately — and then carry the label text.
+    for (const w of wrappers) {
+      w.dispatchEvent(new PointerEvent("pointerdown", { pointerType: "touch", bubbles: true }));
+    }
+    await Promise.resolve();
     const popups = [...document.querySelectorAll(".hk-tooltip-popup .hk-tooltip-content")]
       .map((el) => el.textContent);
     expect(popups).toContain("GitHub");

package/src/components/HkCopyBadge.test.tsx

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { createApp, h, defineComponent } from "vue";
+import { createApp, h, defineComponent, nextTick } from "vue";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -8,6 +8,7 @@ import HkCopyBadge from "./HkCopyBadge";
 import { useToast } from "../runtime/useToast";
 
 const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+const appUnmounts: Array<{ app: ReturnType<typeof createApp> }> = [];
 
 function mount(renderNode: () => ReturnType<typeof h>) {
   const container = document.createElement("div");
@@ -15,6 +16,7 @@ function mount(renderNode: () => ReturnType<typeof h>) {
   const app = createApp({ render: renderNode });
   app.mount(container);
   mounts.push({ app, container });
+  appUnmounts.push({ app });
   return container;
 }
 
@@ -126,18 +128,64 @@ describe("HkCopyBadge", () => {
     expect(writeText).not.toHaveBeenCalled();
   });
 
-  it("renders the custom tooltip text", () => {
+  /** 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 }),
+    );
+  }
+
+  it("renders the custom tooltip text", async () => {
     const c = mount(() => h(HkCopyBadge, { tooltip: "Open details" }, () => "#d.132"));
-    const content = c.parentElement!.querySelector(".hk-tooltip-popup .hk-tooltip-content");
+    // The popup mounts lazily on first engage (dense-list contract).
+    expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
+    engageTooltip(c);
+    await nextTick();
+    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", () => {
+  it("shows the localized click-to-copy tooltip by default", async () => {
     const c = mount(() => h(HkCopyBadge, null, () => "#d.132"));
-    const content = c.parentElement!.querySelector(".hk-tooltip-popup .hk-tooltip-content");
+    engageTooltip(c);
+    await nextTick();
+    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 () => {
+    const c = mount(() => h(HkCopyBadge, { tooltip: "Open details" }, () => "#d.132"));
+    const badge = c.querySelector(".hk-badge")!;
+
+    // Dormant: no popup, no describedby.
+    expect(badge.getAttribute("aria-describedby")).toBeNull();
+    expect(document.body.querySelector(".hk-tooltip-popup")).toBeNull();
+
+    // Engage: describedby == the popup id.
+    engageTooltip(c);
+    await nextTick();
+    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");
+
+    // Leave: the attribute flips BACK (slot re-invocation must not stick).
+    c.querySelector(".hk-tooltip-wrapper")!.dispatchEvent(new MouseEvent("mouseleave"));
+    await nextTick();
+    expect(badge.getAttribute("aria-describedby")).toBeNull();
+
+    // Re-engage: returns, reusing the same popup element.
+    engageTooltip(c);
+    await nextTick();
+    expect(badge.getAttribute("aria-describedby")).toBe(
+      document.body.querySelector(".hk-tooltip-popup")!.getAttribute("id"),
+    );
+
+    // Unmount while visible: the teleported popup goes away.
+    appUnmounts.splice(0).forEach(({ app }) => app.unmount());
+    expect(document.body.querySelector(".hk-tooltip-popup")).toBeNull();
+  });
+
   it("renders the inert badge face when disabled", () => {
     const c = mount(() => h(HkCopyBadge, { disabled: true }, () => "#d.132"));
     const badge = c.querySelector(".hk-badge")!;

package/src/components/HkCopyBadge.tsx

@@ -27,9 +27,12 @@ import "./HkCopyBadge.scss";
  *
  * A11y: the tag is a real button (role, tab order, Enter/Space), and the
  * click is stopped from reaching clickable ancestors — a tag inside a
- * selectable row copies without selecting the row. Consumer attrs
- * (class/style/data-*) land on the badge element itself, so a call site
- * skinning the pill keeps working; the tooltip wrapper stays clean.
+ * selectable row copies without selecting the row. The tooltip popup is
+ * linked to the badge via aria-describedby (HkTooltip hands the popup id
+ * down as a slot prop, so the describedby lands on the actual focus
+ * target). Consumer attrs (class/style/data-*) land on the badge element
+ * itself, so a call site skinning the pill keeps working; the tooltip
+ * wrapper stays clean.
  */
 export default defineComponent({
   name: "HkCopyBadge",
@@ -95,7 +98,7 @@ export default defineComponent({
       // itself; only the interactive contract below is ours to add.
       const { class: attrClass, style: attrStyle, ...restAttrs } = attrs;
 
-      const badge = (
+      const buildBadge = (describedBy?: string) => (
         <HBadge
           ref={badgeRef}
           {...restAttrs}
@@ -110,6 +113,7 @@ export default defineComponent({
           color={props.color}
           bgColor={props.bgColor}
           borderColor={props.borderColor}
+          aria-describedby={describedBy}
           {...(props.disabled
             ? {}
             : {
@@ -133,8 +137,13 @@ export default defineComponent({
         </HBadge>
       );
 
-      if (props.disabled) return badge;
-      return <HTooltip text={tooltipText.value}>{badge}</HTooltip>;
+      if (props.disabled) return buildBadge();
+      return (
+        <HTooltip text={tooltipText.value}>
+          {(tip: { popupId: string; visible: boolean }) =>
+            buildBadge(tip?.visible ? tip.popupId : undefined)}
+        </HTooltip>
+      );
     };
   },
 });

package/src/components/HkSectionCard.scss

@@ -0,0 +1,22 @@
+/* HkSectionCard — the standard titled section: heading + hint above one
+ * card. The ONLY spacing definition for that anatomy; consumers must not
+ * add their own margins/wrappers around it (2026-10-05 unification: two
+ * tabs of one page had drifted apart in hint position and body padding). */
+.hk-section-card {
+  display: flex;
+  flex-direction: column;
+  /* Heading block → body. One token, both axes of the rhythm (the header
+     carries its own 4px title→hint gap). */
+  gap: var(--space-12, 0.75rem);
+  min-width: 0;
+}
+
+/* Trailing notes under the card (the section's own footnote slot). No font
+   override: a footer may carry prose or a control — it only owns the
+   rhythm, so consumers stop inventing their own top margin. */
+.hk-section-card-footer {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4, 0.25rem);
+  min-width: 0;
+}

package/src/components/HkSectionCard.styles.test.ts

@@ -0,0 +1,42 @@
+/**
+ * Style contract (house pattern: HkAboutModal.styles.test.ts) — the
+ * section card's class↔rule wiring. `sheetCompile.test.ts` proves every
+ * sheet COMPILES; nothing else proves the classes the component emits are
+ * the ones the sheet styles, so a rename on either side would silently
+ * orphan the rule (the #493 failure mode).
+ */
+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, "HkSectionCard.tsx"), "utf-8");
+const scss = readFileSync(join(here, "HkSectionCard.scss"), "utf-8");
+
+/** Every `hk-section-card*` class the component emits. */
+function emittedClasses(): string[] {
+  const found = new Set<string>();
+  for (const m of tsx.matchAll(/"(hk-section-card[a-z-]*)"/g)) found.add(m[1]!);
+  for (const m of tsx.matchAll(/\bhk-section-card[a-z-]*\b/g)) found.add(m[0]);
+  return [...found].sort();
+}
+
+describe("HkSectionCard styles", () => {
+  it("emits at least the wrapper and the footer (the guard is not vacuous)", () => {
+    const classes = emittedClasses();
+    expect(classes).toContain("hk-section-card");
+    expect(classes).toContain("hk-section-card-footer");
+  });
+
+  it("styles every class the component emits", () => {
+    for (const cls of emittedClasses()) {
+      expect(scss, `${cls} must have a rule`).toMatch(new RegExp(`\\.${cls}\\s*\\{`));
+    }
+  });
+
+  it("keeps the intra-section rhythm token on the wrapper and the footer", () => {
+    expect(scss).toMatch(/\.hk-section-card\s*\{[^}]*gap:\s*var\(--space-12/);
+    expect(scss).toMatch(/\.hk-section-card-footer\s*\{[^}]*gap:\s*var\(--space-4/);
+  });
+});

package/src/components/HkSectionCard.test.tsx

@@ -0,0 +1,156 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h } from "vue";
+
+import { HkSectionCard } from "./HkSectionCard";
+
+/**
+ * HkSectionCard contract — the section-level chrome standard:
+ * - the heading block carries the title and the hint (its ONLY place: the
+ *   drift this component exists to end was one section printing its hint
+ *   above the table and another below it)
+ * - the body is ONE card: flush for tables (padded default false), padded
+ *   when the body is not a table
+ * - `error` replaces the body with an alert and `loading` with a spinner,
+ *   both inside a PADDED card — a state is content, not a table
+ * - the optional `actions` slot reaches the header (the heading row's
+ *   trailing affordances), not the card
+ *
+ * (Repo test convention: raw createApp + document queries, no
+ * @vue/test-utils.)
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+afterEach(() => {
+  while (mounts.length) {
+    const { app, container } = mounts.pop()!;
+    app.unmount();
+    container.remove();
+  }
+});
+
+function mountCard(props: Record<string, unknown>, slots: Record<string, () => unknown> = {}) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({
+    render: () => h(HkSectionCard, props as never, slots as never),
+  });
+  mounts.push({ app, container });
+  app.mount(container);
+  return container;
+}
+
+describe("HkSectionCard", () => {
+  it("renders the title and the hint in the heading block, above the card", () => {
+    const c = mountCard({ title: "Public domains", hint: "Where this instance is reachable." }, {
+      default: () => h("table", { class: "body-table" }, h("tbody")),
+    });
+    const header = c.querySelector(".hk-section-header")!;
+    expect(header.textContent).toContain("Public domains");
+    expect(header.textContent).toContain("Where this instance is reachable.");
+    // The hint belongs to the HEADER, never to the card body.
+    const card = c.querySelector(".hk-card")!;
+    expect(card.textContent).not.toContain("Where this instance is reachable.");
+    expect(card.querySelectorAll(".body-table")).toHaveLength(1);
+    // Header precedes the card in document order (the one rhythm).
+    expect(header.compareDocumentPosition(card) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+  });
+
+  it("keeps a table body flush in the card and pads a non-table body on request", () => {
+    const flush = mountCard({ title: "T" }, { default: () => h("span", "row") });
+    // HkCard spells "no padding" as a body modifier — the body carries the
+    // padding decision, not the card shell.
+    expect(flush.querySelector(".hk-card-body")!.className).toContain("hk-card-body-unpadded");
+    const padded = mountCard({ title: "T", padded: true }, { default: () => h("span", "row") });
+    // HkCard carries the padding itself — no caller wrapper.
+    expect(padded.querySelector(".hk-card-body")!.className).not.toContain("hk-card-body-unpadded");
+  });
+
+  it("replaces the body with an alert on error, inside a padded card", () => {
+    const c = mountCard({ title: "T", error: "boom" }, { default: () => h("span", "row") });
+    expect(c.querySelector(".hk-alert")).not.toBeNull();
+    expect(c.textContent).toContain("boom");
+    expect(c.querySelector(".hk-card-body")!.className).not.toContain("hk-card-body-unpadded");
+    expect(c.textContent).not.toContain("row");
+  });
+
+  it("replaces the body with a centred spinner while loading", () => {
+    const c = mountCard({ title: "T", loading: true }, { default: () => h("span", "row") });
+    expect(c.querySelector(".hk-spinner")).not.toBeNull();
+    expect(c.querySelector(".hk-card-body")!.className).not.toContain("hk-card-body-unpadded");
+    expect(c.textContent).not.toContain("row");
+  });
+
+  it("lets error win when both error and loading are set", () => {
+    const c = mountCard({ title: "T", error: "boom", loading: true }, {
+      default: () => h("span", "row"),
+    });
+    expect(c.querySelector(".hk-alert")).not.toBeNull();
+    expect(c.querySelector(".hk-spinner")).toBeNull();
+    expect(c.textContent).toContain("boom");
+  });
+
+  it("forwards the description slot into the hint position", () => {
+    const c = mountCard({ title: "T" }, { description: () => h("span", "own hint") });
+    const header = c.querySelector(".hk-section-header")!;
+    expect(header.querySelector(".hk-section-header-description")!.textContent).toContain("own hint");
+    expect(c.querySelector(".hk-card")!.textContent).not.toContain("own hint");
+  });
+
+  it("forwards icon, level and dense to the heading", () => {
+    const Icon = () => h("svg", { class: "own-icon" });
+    const c = mountCard({ title: "T", icon: Icon, level: "h2", dense: true });
+    const header = c.querySelector(".hk-section-header")!;
+    expect(header.classList.contains("hk-section-header-dense")).toBe(true);
+    expect(header.querySelector("h2")).not.toBeNull();
+    expect(header.querySelector(".own-icon")).not.toBeNull();
+    const plain = mountCard({ title: "T" });
+    expect(plain.querySelector(".hk-section-header h3")).not.toBeNull();
+  });
+
+  it("forwards the actions slot into the heading row", () => {
+    const c = mountCard({ title: "T" }, { actions: () => h("button", { class: "hdr-act" }, "x") });
+    expect(c.querySelector(".hk-section-header")!.querySelector(".hdr-act")).not.toBeNull();
+    expect(c.querySelector(".hk-card")!.querySelector(".hdr-act")).toBeNull();
+  });
+
+  it("renders the footer under the card — and nothing when no footer is given", () => {
+    const c = mountCard({ title: "T" }, {
+      default: () => h("span", "row"),
+      footer: () => h("p", { class: "note" }, "keep this"),
+    });
+    const footer = c.querySelector(".hk-section-card-footer")!;
+    expect(footer.querySelector(".note")!.textContent).toBe("keep this");
+    // Under the CARD, not inside it, and after it in document order.
+    const card = c.querySelector(".hk-card")!;
+    expect(card.querySelector(".note")).toBeNull();
+    expect(card.compareDocumentPosition(footer) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+
+    const bare = mountCard({ title: "T" });
+    expect(bare.querySelector(".hk-section-card-footer")).toBeNull();
+  });
+
+  it("renders no empty header wrapper when only one of the two slots is given", () => {
+    // R3 finding: forwarding an absent slot as a function returning
+    // undefined left an empty `.hk-section-header-actions` /
+    // `.hk-section-header-description` node behind — and in the column-flex
+    // heading a zero-height item still eats a gap slot.
+    const actionsOnly = mountCard({ title: "T" }, { actions: () => h("button", "x") });
+    expect(actionsOnly.querySelector(".hk-section-header-actions")).not.toBeNull();
+    expect(actionsOnly.querySelector(".hk-section-header-description")).toBeNull();
+
+    const descriptionOnly = mountCard({ title: "T" }, { description: () => h("span", "hint") });
+    expect(descriptionOnly.querySelector(".hk-section-header-description")).not.toBeNull();
+    expect(descriptionOnly.querySelector(".hk-section-header-actions")).toBeNull();
+
+    const neither = mountCard({ title: "T" });
+    expect(neither.querySelector(".hk-section-header-actions")).toBeNull();
+    expect(neither.querySelector(".hk-section-header-description")).toBeNull();
+  });
+
+  it("carries the count into the title and renders no hint paragraph when none is given", () => {
+    const c = mountCard({ title: "T", count: "3" });
+    expect(c.querySelector(".hk-section-header-count")!.textContent).toBe("3");
+    expect(c.querySelector(".hk-section-header-description")).toBeNull();
+  });
+});

package/src/components/HkSectionCard.tsx

@@ -0,0 +1,122 @@
+import { defineComponent, type Component, type PropType } from "vue";
+
+import HkAlert from "./HkAlert";
+import HkCard from "./HkCard";
+import { HkSectionHeader } from "./HkSectionHeader";
+import HkSpinner from "./HkSpinner";
+import "./HkSectionCard.scss";
+
+/**
+ * HkSectionCard — the standard titled SECTION: a heading (with an optional
+ * hint line) above ONE card that carries the body.
+ *
+ * This is the section-level twin of the page-level scaffold
+ * (`HkAdminTablePage`): a page whose content is several lists (settings
+ * categories, tab panels, dashboards) renders each as an HkSectionCard, so
+ * the heading→body rhythm, the hint typography and the body padding come
+ * from ONE definition instead of every caller hand-rolling `mt-3`,
+ * `p-4`/`padded={false}` wrappers and its own hint classes — the drift the
+ * 2026-10-05 audit found between two tabs of the same page (one table flush
+ * in the card with its hint above, the other wrapped in a padded div with
+ * its hint below).
+ *
+ * The body states follow `HkAdminTablePage`'s contract: `error` replaces
+ * the body with an alert, `loading` with a centred spinner — both inside a
+ * PADDED card (a state is content, not a table), while the normal body
+ * honours `padded` (default false: tables carry their own cell padding and
+ * sit flush in the card). `error` wins when both are set, as on the
+ * scaffold.
+ *
+ * The section owns the INTRA-section rhythm only (heading block → card). The
+ * page owns the gap BETWEEN sections: several siblings on one page need the
+ * parent's own `gap` (a flex/grid column), because this component adds no
+ * outer margin by design — otherwise a page that renders three sections
+ * would stack them flush.
+ *
+ * A `footer` slot renders trailing notes under the card (placeholder
+ * grammars, "what this list feeds" details) with the same rhythm, so those
+ * notes stop being a per-consumer margin.
+ *
+ * One deliberate difference from the scaffold: `loading` replaces the body
+ * whenever it is true, where `HkAdminTablePage` only replaces an EMPTY body
+ * (`loading && !rows.length`) and keeps populated rows on screen through a
+ * refresh. A section therefore passes `loading` for its FIRST load, not for
+ * every refetch — or it blanks a table the user is reading.
+ *
+ * ```tsx
+ * <HkSectionCard title={t("…")} hint={t("…")} loading={loading}>
+ *   <HkTable columns={columns} rows={rows} rowKey="id">{…}</HkTable>
+ * </HkSectionCard>
+ * ```
+ */
+export const HkSectionCard = defineComponent({
+  name: "HkSectionCard",
+  props: {
+    title: { type: String, required: true },
+    /** Explanatory line under the heading — the standard place for the
+     *  "what this list is for" copy every section used to spell its own. */
+    hint: { type: String, default: undefined },
+    icon: { type: [Object, Function] as PropType<Component>, default: undefined },
+    /** Heading level only; the visual size is fixed by the header styles. */
+    level: { type: String as PropType<"h2" | "h3" | "div">, default: "h3" },
+    /** Trailing count beside the title (e.g. "3"). */
+    count: { type: String, default: undefined },
+    /** Tighter header spacing for dense panels. */
+    dense: { type: Boolean, default: false },
+    /** Hard failure: replaces the body with an alert. */
+    error: { type: String, default: undefined },
+    /** In-flight: replaces the body with a centred spinner. */
+    loading: { type: Boolean, default: false },
+    /** Body padding for non-table content (tables stay flush). */
+    padded: { type: Boolean, default: false },
+  },
+  setup(props, { slots }) {
+    return () => {
+      const state = props.error ? "error" : props.loading ? "loading" : "body";
+      // Hoisted to an identifier: the CONDITIONAL inline form
+      // (`{slots.actions ? { actions: … } : undefined}` as children) lands in
+      // a child array, where the plain object is no longer normalized to
+      // slots and the button silently disappears. Hoisting fixes it; the
+      // bare inline literal happens to work, which is exactly why the
+      // conditional one is a trap.
+      // Each slot is spread CONDITIONALLY: forwarding an absent one as a
+      // function that returns undefined defeats HkSectionHeader's own
+      // empty-node guard, which renders an empty wrapper (and, in the
+      // column-flex heading, a phantom gap slot) — a whitespace-only
+      // regression the R3 review caught.
+      const headerSlots =
+        slots.actions || slots.description
+          ? {
+              ...(slots.actions ? { actions: () => slots.actions?.() } : {}),
+              ...(slots.description ? { description: () => slots.description?.() } : {}),
+            }
+          : undefined;
+      return (
+        <section class="hk-section-card">
+          <HkSectionHeader
+            title={props.title}
+            description={props.hint}
+            icon={props.icon}
+            level={props.level}
+            count={props.count}
+            dense={props.dense}
+          >
+            {headerSlots}
+          </HkSectionHeader>
+          <HkCard padded={state === "body" ? props.padded : true}>
+            {state === "error" ? (
+              <HkAlert message={props.error!} />
+            ) : state === "loading" ? (
+              <HkSpinner center />
+            ) : (
+              slots.default?.()
+            )}
+          </HkCard>
+          {slots.footer ? <div class="hk-section-card-footer">{slots.footer()}</div> : null}
+        </section>
+      );
+    };
+  },
+});
+
+export default HkSectionCard;

package/src/components/HkToast.test.tsx

@@ -235,3 +235,31 @@ describe("HkToast", () => {
     expect(items().length).toBe(0);
   });
 });
+
+describe("HkToast live-region semantics", () => {
+  it("announces errors as alert/assertive and everything else as status/polite", async () => {
+    mountHost();
+    const toast = useToast();
+    toast.error("boom");
+    toast.success("nice");
+    toast.warning("hmm");
+    toast.info("fyi");
+    toast.loading("working");
+    await settle();
+
+    // The toast surface teleports to body — the host container never
+    // contains the items.
+    const items = [...document.body.querySelectorAll(".hk-toast-item")];
+    expect(items.length).toBe(5);
+    const byType = (type: string) =>
+      items.find((el) => el.classList.contains(`hk-toast-${type}`))!;
+    const err = byType("error");
+    expect(err.getAttribute("role")).toBe("alert");
+    expect(err.getAttribute("aria-live")).toBe("assertive");
+    for (const type of ["success", "warning", "info", "loading"]) {
+      const el = byType(type);
+      expect(el.getAttribute("role"), type).toBe("status");
+      expect(el.getAttribute("aria-live"), type).toBe("polite");
+    }
+  });
+});

package/src/components/HkToast.tsx

@@ -105,8 +105,19 @@ const HkToastItem = defineComponent({
       const long = isLong(text);
       const count = props.toast.messages.length;
 
+      // Live-region semantics: errors interrupt (role=alert implies
+      // assertive), everything else announces politely (role=status).
+      const a11y: { role: string; "aria-live": "assertive" | "polite" } =
+        props.toast.type === "error"
+          ? { role: "alert", "aria-live": "assertive" }
+          : { role: "status", "aria-live": "polite" };
+
       return (
-        <div class={["hk-toast-item", `hk-toast-${props.toast.type}`]}>
+        <div
+          class={["hk-toast-item", `hk-toast-${props.toast.type}`]}
+          role={a11y.role}
+          aria-live={a11y["aria-live"]}
+        >
           <span class="hk-toast-icon">{renderIcon(props.toast.type)}</span>
           <div class="hk-toast-body">
             <Transition

package/src/components/HkTooltip.test.tsx

@@ -82,8 +82,18 @@ afterEach(() => {
 });
 
 describe("HkTooltip popup-manager registration", () => {
+  it("defers the band entry until the first engage (lazy contract)", () => {
+    mount({ text: "dormant" });
+    // A never-engaged tooltip — the dense-list majority — costs no
+    // teleported popup and no registry entry at all.
+    expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
+    expect(tooltipEntries().length).toBe(0);
+  });
+
   it("registers one tooltip-kind entry at the tooltip band and stamps its z inline", async () => {
-    mount({ text: "hello" });
+    const { container } = mount({ text: "hello" });
+    enter(container);
+    await settle();
     const entries = tooltipEntries();
     expect(entries.length).toBe(1);
     expect(entries[0]!.kind).toBe("tooltip");
@@ -91,25 +101,28 @@ describe("HkTooltip popup-manager registration", () => {
     // Tooltips are transient annotations — they never lock scroll.
     expect(entries[0]!.locksScroll).toBe(false);
     expect(document.body.style.overflow).not.toBe("hidden");
-    // The band z lands on the teleported popup element (set from
-    // onMounted, so the patch flushes on the next tick), overriding the
+    // The band z lands on the teleported popup element, overriding the
     // --hi-z-tooltip SCSS fallback.
-    await nextTick();
     expect(popup().style.zIndex).toBe(String(POPUP_Z_BANDS.tooltip));
   });
 
-  it("stacks a second tooltip one step above within the band", () => {
-    mount({ text: "one" });
-    mount({ text: "two" });
+  it("stacks a second tooltip one step above within the band", async () => {
+    const a = mount({ text: "one" });
+    const b = mount({ text: "two" });
+    enter(a.container);
+    enter(b.container);
+    await settle();
     const entries = tooltipEntries();
     expect(entries.length).toBe(2);
-    const zs = entries.map((e) => e.zIndex).sort((a, b) => a - b);
-    expect(zs[1]).toBe(zs[0] + POPUP_Z_STEP);
+    const zs = entries.map((e) => e.zIndex).sort((x, y) => x - y);
+    expect(zs[1]).toBe(zs[0]! + POPUP_Z_STEP);
     expect(zs[0]).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
   });
 
-  it("removes its registry entry on unmount", () => {
-    const { app } = mount({ text: "bye" });
+  it("removes its registry entry on unmount", async () => {
+    const { app, container } = mount({ text: "bye" });
+    enter(container);
+    await settle();
     expect(tooltipEntries().length).toBe(1);
     app.unmount();
     expect(tooltipEntries().length).toBe(0);
@@ -128,8 +141,15 @@ describe("HkTooltip popup-manager registration", () => {
 });
 
 describe("HkTooltip show/hide", () => {
-  it("teleports the popup to body, hidden, with the text content", () => {
+  it("mounts the popup on first engage and keeps it hidden after hide, with the text content", async () => {
     const { container } = mount({ text: "the tip" });
+    // Nothing before the first engage…
+    expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
+    // …then engage and hide: the popup persists, hidden, for reuse.
+    enter(container);
+    await settle();
+    leave(container);
+    await nextTick();
     const el = popup();
     expect(document.body.contains(el)).toBe(true);
     expect(el.parentElement).toBe(document.body);
@@ -139,6 +159,46 @@ describe("HkTooltip show/hide", () => {
     expect(wrapper(container).querySelector(".hk-tooltip-trigger .anchor-probe")).not.toBeNull();
   });
 
+  it("wires aria: role=tooltip + id on the popup, describedby on the wrapper while visible", async () => {
+    const { container } = mount({ text: "a11y tip", delay: 0 });
+    enter(container);
+    await settle();
+    const el = popup();
+    expect(el.getAttribute("role")).toBe("tooltip");
+    const id = el.getAttribute("id");
+    expect(id).toBeTruthy();
+    expect(wrapper(container).getAttribute("aria-describedby")).toBe(id);
+    leave(container);
+    await nextTick();
+    expect(wrapper(container).getAttribute("aria-describedby")).toBeNull();
+  });
+
+  it("hands { popupId, visible } to the default slot for focus-target wiring", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    let seen: { popupId?: string; visible?: boolean } = {};
+    const app = createApp({
+      render: () =>
+        h(
+          HkTooltip,
+          { text: "slot props", delay: 0 } as never,
+          // The scoped-slot child needs a cast: HkTooltip does not declare
+          // slot prop types, so h() types the default slot as no-arg.
+          ((slotProps: { popupId: string; visible: boolean }) => {
+            seen = slotProps;
+            return h("span", { class: "anchor-probe" }, "anchor");
+          }) as never,
+        ),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+    await nextTick();
+    wrapper(container).dispatchEvent(new MouseEvent("mouseenter"));
+    await settle();
+    expect(seen.visible).toBe(true);
+    expect(seen.popupId).toBe(popup().getAttribute("id"));
+  });
+
   it("waits out the default 300ms delay before showing", async () => {
     vi.useFakeTimers();
     const { container } = mount({ text: "delayed" });
@@ -236,7 +296,9 @@ describe("HkTooltip touch taps", () => {
       new PointerEvent("pointerdown", { pointerType: "mouse", bubbles: true }),
     );
     await nextTick();
-    expect(popup().className).not.toContain("hk-tooltip-visible");
+    // A mouse press never engages the lazy tooltip at all — no popup
+    // node, no visible class.
+    expect(document.querySelector(".hk-tooltip-popup")).toBeNull();
   });
 
   it("does not re-open from the synthetic mouseenter right after a closing tap", async () => {

package/src/components/HkTooltip.tsx

@@ -1,8 +1,10 @@
-import { computed, defineComponent, onBeforeUnmount, onMounted, ref, Teleport, type CSSProperties, type PropType } from "vue";
+import { computed, defineComponent, onBeforeUnmount, ref, Teleport, type CSSProperties, type PropType } from "vue";
 import { usePopupManager, type PopupHandle } from "../runtime/usePopupManager";
 import { applyTooltipPosition, type TooltipPlacement } from "../runtime/tooltipPosition";
 import "./HkTooltip.scss";
 
+let popupSeq = 0;
+
 export default defineComponent({
   name: "HkTooltip",
   props: {
@@ -13,22 +15,35 @@ export default defineComponent({
   },
   setup(props, { slots }) {
     const visible = ref(false);
+    // Stable id for the aria-describedby link from the trigger wrapper to
+    // the popup (set while the popup is visible, mirroring the tooltip
+    // bridge's contract).
+    const popupId = `hk-tooltip-${++popupSeq}`;
     const wrapperRef = ref<HTMLElement | null>(null);
     const popupRef = ref<HTMLElement | null>(null);
     let showTimer: ReturnType<typeof setTimeout> | null = null;
 
-    // Registers with the popup manager (kind "tooltip") so tooltips hold
-    // the tooltip band (above modal/drawer overlays, below toasts); the
-    // zIndex lands on the popup element and overrides the --hi-z-tooltip
-    // fallback in the SCSS.
+    // The band handle and the popup DOM are both LAZY (dense-list contract,
+    // 2026-10-05): a tooltip that is never engaged — the overwhelming
+    // majority in a list of tags — costs no teleported node, no band
+    // registration and no pointer wiring beyond the wrapper's own handlers.
+    // The first engage registers the popup-manager handle (kind "tooltip",
+    // above modal/drawer overlays, below toasts) and mounts the popup;
+    // both are held until unmount so re-shows never churn.
     const manager = usePopupManager();
     let popupHandle: PopupHandle | null = null;
     const zIndex = ref<number | null>(null);
+    const everShown = ref(false);
 
-    onMounted(() => {
-      popupHandle = manager.register("tooltip", false);
-      zIndex.value = popupHandle.zIndex;
-    });
+    function ensureEngaged() {
+      if (!everShown.value) {
+        everShown.value = true;
+        if (!popupHandle) {
+          popupHandle = manager.register("tooltip", false);
+        }
+        zIndex.value = popupHandle.zIndex;
+      }
+    }
 
     function updatePosition() {
       if (!wrapperRef.value || !popupRef.value) return;
@@ -45,6 +60,7 @@ export default defineComponent({
 
     function show() {
       clearShowTimer();
+      ensureEngaged();
       showTimer = setTimeout(() => {
         visible.value = true;
         requestAnimationFrame(updatePosition);
@@ -53,6 +69,7 @@ export default defineComponent({
 
     function showNow() {
       clearShowTimer();
+      ensureEngaged();
       visible.value = true;
       requestAnimationFrame(updatePosition);
     }
@@ -136,6 +153,7 @@ export default defineComponent({
         ref={wrapperRef}
         class="hk-tooltip-wrapper"
         data-position={props.placement}
+        aria-describedby={visible.value ? popupId : undefined}
         onPointerdown={onPointerdown}
         onMouseenter={() => {
           // Synthetic mouseenter right after a touch tap must not
@@ -148,16 +166,20 @@ export default defineComponent({
         onFocusout={hide}
       >
         <span class="hk-tooltip-trigger">
-          {slots.default?.()}
+          {slots.default?.({ popupId, visible: visible.value })}
         </span>
         <Teleport to="body">
-          <div
-            ref={popupRef}
-            class={tooltipCls.value}
-            style={popupStyle.value}
-          >
-            <div class="hk-tooltip-content">{props.text}</div>
-          </div>
+          {everShown.value && (
+            <div
+              ref={popupRef}
+              id={popupId}
+              role="tooltip"
+              class={tooltipCls.value}
+              style={popupStyle.value}
+            >
+              <div class="hk-tooltip-content">{props.text}</div>
+            </div>
+          )}
         </Teleport>
       </span>
     );

package/src/index.ts

@@ -818,6 +818,8 @@ export { HkCardList, HkListRow } from "./components/HkCardList";
 export { HkCardList as HCardList, HkListRow as HListRow } from "./components/HkCardList";
 export { HkSectionHeader, type SectionHeaderVariant } from "./components/HkSectionHeader";
 export { HkSectionHeader as HSectionHeader } from "./components/HkSectionHeader";
+export { HkSectionCard } from "./components/HkSectionCard";
+export { HkSectionCard as HSectionCard } from "./components/HkSectionCard";
 export { default as HFilterBar } from "./components/HkFilterBar";
 export { HkShareBar as HkShareBar } from "./components/HkShareBar";
 export { HkSecretRevealModal as HkSecretRevealModal } from "./components/HkSecretRevealModal";