@celestia-island/hikari 0.40.33 → 0.40.35

package/package.json

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

package/src/components/HkButton.test.tsx

@@ -0,0 +1,159 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h } from "vue";
+
+import HkButton from "./HkButton";
+
+/**
+ * HkButton contract tests:
+ * - variant / size / block / loading class mapping on the root <button>
+ * - the native disabled attribute is the click guard (disabled OR loading)
+ * - loading renders the spinner INSTEAD of the icon and flags aria-busy
+ * - default-slot text, aria-label (icon-only usage), suffix, shortcut kbd
+ * - attr fallthrough: inheritAttrs is false, the component MUST spread
+ *   $attrs itself (type / data-* / class merging)
+ *
+ * House style: raw createApp mounts on a shared container list torn down
+ * after each case; DOM assertions via document queries.
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(node: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => node });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+function button(c: HTMLElement): HTMLButtonElement {
+  return c.querySelector("button")!;
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+describe("HkButton class mapping", () => {
+  it("renders the default primary/md classes with default-slot text and type=button", () => {
+    const c = mount(h(HkButton, () => "Deploy"));
+    const btn = button(c);
+    expect(btn).not.toBeNull();
+    expect(btn.className).toBe("hk-btn hk-btn-primary hk-btn-md");
+    expect(btn.getAttribute("type")).toBe("button");
+    expect(btn.textContent).toContain("Deploy");
+  });
+
+  it("maps variant and size props to modifier classes", () => {
+    const c = mount(h(HkButton, { variant: "danger", size: "sm" }, () => "Delete"));
+    const cls = button(c).className;
+    expect(cls).toContain("hk-btn-danger");
+    expect(cls).toContain("hk-btn-sm");
+    expect(cls).not.toContain("hk-btn-primary");
+    expect(cls).not.toContain("hk-btn-md");
+  });
+
+  it("adds the block modifier only when block is set", () => {
+    const blocked = mount(h(HkButton, { block: true }, () => "wide"));
+    expect(button(blocked).className).toContain("hk-btn-block");
+    const plain = mount(h(HkButton, () => "narrow"));
+    expect(button(plain).className).not.toContain("hk-btn-block");
+  });
+});
+
+describe("HkButton click guard", () => {
+  it("emits the declared click event on activation", async () => {
+    let clicks = 0;
+    const c = mount(h(HkButton, { onClick: () => { clicks += 1; } }, () => "go"));
+    button(c).click();
+    await Promise.resolve();
+    expect(clicks).toBe(1);
+  });
+
+  it("suppresses the click emit while disabled", async () => {
+    let clicks = 0;
+    const c = mount(h(HkButton, { disabled: true, onClick: () => { clicks += 1; } }, () => "no"));
+    // The guard is the NATIVE disabled attribute: the platform (and
+    // happy-dom) fires no click listeners on a disabled button.
+    expect(button(c).disabled).toBe(true);
+    button(c).click();
+    await Promise.resolve();
+    expect(clicks).toBe(0);
+  });
+
+  it("disables the button and suppresses clicks while loading", async () => {
+    let clicks = 0;
+    const c = mount(h(HkButton, { loading: true, onClick: () => { clicks += 1; } }, () => "busy"));
+    const btn = button(c);
+    expect(btn.disabled).toBe(true); // loading implies disabled
+    expect(btn.className).toContain("hk-btn-loading");
+    expect(btn.getAttribute("aria-busy")).toBe("true");
+    btn.click();
+    await Promise.resolve();
+    expect(clicks).toBe(0);
+  });
+
+  it("clears the loading state back to a clickable button (aria-busy drops off)", () => {
+    const busy = mount(h(HkButton, { loading: true }, () => "x"));
+    expect(busy.querySelector(".hk-spinner")).not.toBeNull();
+    const idle = mount(h(HkButton, () => "x"));
+    const btn = button(idle);
+    expect(idle.querySelector(".hk-spinner")).toBeNull();
+    expect(btn.disabled).toBe(false);
+    expect(btn.getAttribute("aria-busy")).toBeNull();
+    expect(btn.className).not.toContain("hk-btn-loading");
+  });
+});
+
+describe("HkButton content slots", () => {
+  it("renders the leading icon only when NOT loading", () => {
+    const idle = mount(h(HkButton, { icon: "close" }, () => "x"));
+    expect(idle.querySelector(".hk-btn-icon")).not.toBeNull();
+    expect(idle.querySelector(".hk-spinner")).toBeNull();
+
+    // Loading swaps the icon out for the spinner — never both.
+    const busy = mount(h(HkButton, { icon: "close", loading: true }, () => "x"));
+    expect(busy.querySelector(".hk-btn-icon")).toBeNull();
+    expect(busy.querySelector(".hk-spinner")).not.toBeNull();
+  });
+
+  it("renders the suffix icon slot", () => {
+    const c = mount(h(HkButton, { suffix: "close" }, () => "Open"));
+    expect(c.querySelector(".hk-btn-suffix")).not.toBeNull();
+  });
+
+  it("renders the shortcut kbd and its marker class", () => {
+    const c = mount(h(HkButton, { shortcut: "Ctrl+Enter" }, () => "Send"));
+    const btn = button(c);
+    expect(btn.className).toContain("hk-btn-has-shortcut");
+    const kbd = c.querySelector("kbd.hk-kbd")!;
+    expect(kbd).not.toBeNull();
+    expect(kbd.textContent).toContain("Ctrl");
+    expect(kbd.textContent).toContain("Enter");
+  });
+
+  it("exposes aria-label for icon-only usage", () => {
+    const c = mount(h(HkButton, { icon: "close", ariaLabel: "Close inspector" }));
+    expect(button(c).getAttribute("aria-label")).toBe("Close inspector");
+  });
+});
+
+describe("HkButton attr fallthrough (inheritAttrs: false)", () => {
+  it("spreads extra attrs and honors an explicit type", () => {
+    const c = mount(h(HkButton, { type: "submit", "data-test": "probe" }, () => "Save"));
+    const btn = button(c);
+    expect(btn.getAttribute("type")).toBe("submit");
+    expect(btn.getAttribute("data-test")).toBe("probe");
+  });
+
+  it("merges a fallthrough class onto its own class list", () => {
+    const c = mount(h(HkButton, { class: "extra-class" }, () => "x"));
+    const cls = button(c).className;
+    expect(cls).toContain("hk-btn");
+    expect(cls).toContain("extra-class");
+  });
+});

package/src/components/HkCheckbox.test.tsx

@@ -0,0 +1,202 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkCheckbox from "./HkCheckbox";
+
+/**
+ * HkCheckbox contract tests:
+ * - tri-state model wiring: false → unlit box, true → check icon (or dot
+ *   in radio mode), null → indeterminate dash (checkbox mode only)
+ * - the label shell is a real <label> wrapping the native input, so
+ *   clicking the TEXT forwards to the input and toggles (label association)
+ * - change events carry the input's NEW checked value; disabled drops them
+ * - the data-animating pulse is set on change and cleared by the 300ms
+ *   cron one-shot
+ *
+ * House style: raw createApp mounts on a shared container list torn down
+ * after each case; DOM assertions via document queries.
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(node: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => node });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+/** v-model harness: mirrors consumer usage, records every emitted value. */
+function mountVModel(initial: boolean | null, props: Record<string, unknown> = {}) {
+  const model = ref<boolean | null>(initial);
+  const emitted: Array<boolean> = [];
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp(defineComponent({
+    setup: () => () =>
+      h(HkCheckbox, {
+        ...props,
+        modelValue: model.value as boolean,
+        "onUpdate:modelValue": (v: boolean) => {
+          model.value = v;
+          emitted.push(v);
+        },
+      }),
+  }));
+  app.mount(container);
+  mounts.push({ app, container });
+  const input = () => container.querySelector<HTMLInputElement>("input")!;
+  const box = () => container.querySelector<HTMLElement>(".hk-checkbox-box")!;
+  const root = () => container.querySelector<HTMLElement>("label")!;
+  return { container, model, emitted, input, box, root };
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+describe("HkCheckbox model states", () => {
+  it("renders an unlit box and an unchecked native checkbox by default", () => {
+    const c = mount(h(HkCheckbox));
+    const root = c.querySelector<HTMLElement>("label")!;
+    expect(root.className).toBe("hk-checkbox hk-checkbox-md");
+    expect(root.getAttribute("data-type")).toBe("checkbox");
+    const input = c.querySelector<HTMLInputElement>("input")!;
+    expect(input.type).toBe("checkbox");
+    expect(input.checked).toBe(false);
+    const box = c.querySelector<HTMLElement>(".hk-checkbox-box")!;
+    expect(box.hasAttribute("data-checked")).toBe(false);
+    expect(box.hasAttribute("data-indeterminate")).toBe(false);
+    expect(c.querySelector(".hk-checkbox-icon")).toBeNull();
+    expect(c.querySelector(".hk-checkbox-indeterminate")).toBeNull();
+  });
+
+  it("maps modelValue=true to the checked box with the check icon", () => {
+    const c = mount(h(HkCheckbox, { modelValue: true }));
+    const box = c.querySelector<HTMLElement>(".hk-checkbox-box")!;
+    expect(box.getAttribute("data-checked")).toBe("");
+    expect(c.querySelector<HTMLInputElement>("input")!.checked).toBe(true);
+    // The glyph is the lucide Check svg itself (lucide puts the class on
+    // its root <svg>), not the radio dot.
+    expect(c.querySelector("svg.hk-checkbox-icon")).not.toBeNull();
+    expect(c.querySelector(".hk-checkbox-dot")).toBeNull();
+  });
+
+  it("maps modelValue=null to the indeterminate dash without checking the input", () => {
+    const c = mount(h(HkCheckbox, { modelValue: null as unknown as boolean }));
+    const box = c.querySelector<HTMLElement>(".hk-checkbox-box")!;
+    expect(box.getAttribute("data-indeterminate")).toBe("");
+    expect(box.hasAttribute("data-checked")).toBe(false);
+    // null is NOT true: the native input stays unchecked.
+    expect(c.querySelector<HTMLInputElement>("input")!.checked).toBe(false);
+    expect(c.querySelector(".hk-checkbox-indeterminate")).not.toBeNull();
+    expect(c.querySelector(".hk-checkbox-icon")).toBeNull();
+  });
+
+  it("radio mode swaps the check icon for the dot and drops the indeterminate dash", () => {
+    const checked = mount(h(HkCheckbox, { modelValue: true, type: "radio" }));
+    expect(checked.querySelector("label")!.getAttribute("data-type")).toBe("radio");
+    expect(checked.querySelector<HTMLInputElement>("input")!.type).toBe("radio");
+    expect(checked.querySelector(".hk-checkbox-dot")).not.toBeNull();
+    expect(checked.querySelector(".hk-checkbox-icon")).toBeNull();
+
+    // null in radio mode: no dash — indeterminate is checkbox-only.
+    const unset = mount(h(HkCheckbox, { modelValue: null as unknown as boolean, type: "radio" }));
+    expect(unset.querySelector(".hk-checkbox-indeterminate")).toBeNull();
+    expect(unset.querySelector(".hk-checkbox-dot")).toBeNull();
+  });
+
+  it("maps the size prop to the shell modifier", () => {
+    const c = mount(h(HkCheckbox, { size: "sm" }));
+    expect(c.querySelector("label")!.className).toContain("hk-checkbox-sm");
+  });
+});
+
+describe("HkCheckbox label", () => {
+  it("renders the label prop through the HkLabel shell", () => {
+    const c = mount(h(HkCheckbox, { label: "Remember login" }));
+    const label = c.querySelector<HTMLElement>(".hk-label")!;
+    expect(label).not.toBeNull();
+    expect(label.textContent).toBe("Remember login");
+  });
+
+  it("prefers default-slot content over the label prop", () => {
+    const c = mount(
+      h(HkCheckbox, { label: "plain" }, () => ["rich ", h("b", "text")]),
+    );
+    expect(c.querySelector(".hk-label")!.textContent).toBe("rich text");
+  });
+
+  it("renders no label shell without label prop or slot", () => {
+    const c = mount(h(HkCheckbox));
+    expect(c.querySelector(".hk-label")).toBeNull();
+  });
+});
+
+describe("HkCheckbox change wiring", () => {
+  it("round-trips v-model through native input activation", async () => {
+    const t = mountVModel(false);
+    t.input().click();
+    await nextTick();
+    expect(t.emitted).toEqual([true]);
+    expect(t.model.value).toBe(true);
+    expect(t.input().checked).toBe(true);
+    expect(t.box().getAttribute("data-checked")).toBe("");
+
+    t.input().click();
+    await nextTick();
+    expect(t.emitted).toEqual([true, false]);
+    expect(t.box().hasAttribute("data-checked")).toBe(false);
+  });
+
+  it("toggles through the label text — the shell is a real <label>", async () => {
+    const t = mountVModel(false, { label: "Remember login" });
+    // Clicking the TEXT (not the input): the platform forwards the click
+    // to the first labelable descendant — the checkbox input — which
+    // toggles and fires the change the component listens to.
+    (t.container.querySelector(".hk-label") as HTMLElement).click();
+    await nextTick();
+    expect(t.emitted).toEqual([true]);
+    expect(t.input().checked).toBe(true);
+  });
+
+  it("emits the post-click indeterminate resolution as a plain boolean", async () => {
+    // null (indeterminate) + click → the input lands checked → emits true.
+    const t = mountVModel(null);
+    t.input().click();
+    await nextTick();
+    expect(t.emitted).toEqual([true]);
+    expect(t.box().getAttribute("data-checked")).toBe("");
+    expect(t.box().hasAttribute("data-indeterminate")).toBe(false);
+  });
+
+  it("pulses data-animating on change and clears it after the 300ms cron", async () => {
+    vi.useFakeTimers();
+    const t = mountVModel(false);
+    t.input().click();
+    await nextTick();
+    expect(t.root().getAttribute("data-animating")).toBe("");
+
+    vi.advanceTimersByTime(300);
+    await nextTick();
+    expect(t.root().hasAttribute("data-animating")).toBe(false);
+  });
+
+  it("drops change events entirely while disabled", async () => {
+    const t = mountVModel(false, { disabled: true });
+    expect(t.input().disabled).toBe(true);
+    expect(t.root().getAttribute("data-disabled")).toBe("");
+    // The platform fires no activation on a disabled input.
+    t.input().click();
+    t.container.querySelector<HTMLElement>(".hk-checkbox-box")!.click();
+    await nextTick();
+    expect(t.emitted).toEqual([]);
+    expect(t.input().checked).toBe(false);
+  });
+});

package/src/components/HkJsonTree.scss

@@ -29,6 +29,21 @@
   }
 }
 
+/* ONE SCROLLBAR PER WINDOW (2026-09-08 audit): inside a window surface's
+ * own scroller the bounded tree cap lit a second scrollbar under the
+ * window's — the window's scrollbar is the only one there and the tree
+ * grows with its content. Pages and standalone cards (the error landing,
+ * chat tool blocks outside windows) keep the bounded viewport above.
+ * The host's deferred overlay pass self-hides its rails once the
+ * content fits, so no attach-side change is needed. */
+.hk-modal-body-scroll .s-tool-json-tree,
+.hk-select-sheet-list .s-tool-json-tree,
+.hk-select-popout .s-tool-json-tree,
+.hk-popover-panel .s-tool-json-tree,
+.hk-drawer-body .s-tool-json-tree {
+  max-height: none;
+}
+
 .s-jt-row {
   /* Baseline alignment keeps the small type hints (boolean/number/string)
      on the value's text baseline instead of floating above it. */

package/src/components/HkProtocolModal.scss

@@ -1,15 +1,7 @@
+/* ONE SCROLLBAR PER WINDOW (2026-09-08 audit): the body grows with its
+ * content and the HkModal body scroller is THE scrollbar. The old
+ * `bodyHeight`-driven nested scroll region (with its own overlay chrome)
+ * was removed as dead API — no consumer in the family ever passed it. */
 .s-protocol-modal {
   position: relative;
 }
-
-
-/* With `bodyHeight` set the body becomes its own scroll region (nested
- * inside HkModal's body scroller) — overlay chrome only. */
-.s-protocol-modal {
-  overflow-y: auto;
-  scrollbar-width: none;
-
-  &::-webkit-scrollbar {
-    display: none;
-  }
-}

package/src/components/HkProtocolModal.tsx

@@ -1,4 +1,4 @@
-import { computed, defineComponent, onBeforeUnmount, ref, watch, type PropType } from "vue";
+import { computed, defineComponent, type PropType } from "vue";
 import {
   HMarkdownRenderer,
   HModal,
@@ -9,7 +9,6 @@ import {
 } from "@celestia-island/hikari";
 
 import { useI18n } from "../i18n/context";
-import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 
 import "./HkProtocolModal.scss";
 
@@ -21,6 +20,12 @@ import "./HkProtocolModal.scss";
  * a Decline/Accept footer. `accept`/`decline` are the caller's commit
  * actions; closing (overlay click / ESC / X) only emits `update:modelValue`
  * so the caller can decide whether close === decline.
+ *
+ * ONE SCROLLBAR PER WINDOW: the body grows with its content and the
+ * HkModal body scroller is THE scrollbar. The old `bodyHeight` prop
+ * (a height-capped scroll region nested inside the modal's own scroller —
+ * the exact double-scroll this library eliminates) was removed as dead
+ * API: no consumer in the family ever passed it.
  */
 export const HkProtocolModal = defineComponent({
   name: "HkProtocolModal",
@@ -37,8 +42,6 @@ export const HkProtocolModal = defineComponent({
     /** Allow dismissing without a decision (overlay/ESC/X). Default true. */
     closable: { type: Boolean, default: true },
     width: { type: String as PropType<ModalWidth>, default: "48rem" },
-    /** Cap the scroll body height (e.g. "60vh"). */
-    bodyHeight: { type: String, default: undefined },
   },
   emits: {
     "update:modelValue": (_v: boolean) => true,
@@ -69,32 +72,6 @@ export const HkProtocolModal = defineComponent({
       },
     ]);
 
-    // ── overlay scrollbar (shared chrome) ─────────────────────────
-    // With `bodyHeight` set the body becomes a height-capped scroll
-    // region NESTED inside HkModal's overlay-equipped body scroller —
-    // without the overlay it would be a surviving native bar (the exact
-    // double-scroll this library eliminates). Attach on mount, re-sync
-    // when the cap flips, detach on unmount.
-    const bodyRef = ref<HTMLElement | null>(null);
-    let bodyScrollbar: OverlayScrollbarHandle | null = null;
-    function syncBodyScrollbar(): void {
-      if (props.bodyHeight && bodyRef.value) {
-        if (!bodyScrollbar) bodyScrollbar = attachOverlayScrollbars(bodyRef.value);
-      } else {
-        bodyScrollbar?.detach();
-        bodyScrollbar = null;
-      }
-    }
-    function bindBodyRef(el: unknown): void {
-      bodyRef.value = (el as HTMLElement) ?? null;
-      syncBodyScrollbar();
-    }
-    watch(() => props.bodyHeight, () => syncBodyScrollbar());
-    onBeforeUnmount(() => {
-      bodyScrollbar?.detach();
-      bodyScrollbar = null;
-    });
-
     return () => (
       <HModal
         modelValue={props.modelValue}
@@ -104,11 +81,7 @@ export const HkProtocolModal = defineComponent({
         closable={props.closable}
         footerActions={footerActions.value}
       >
-        <div
-          ref={bindBodyRef}
-          class="s-protocol-modal"
-          style={props.bodyHeight ? { maxHeight: props.bodyHeight } : undefined}
-        >
+        <div class="s-protocol-modal">
           <HMarkdownRenderer content={props.content} />
         </div>
       </HModal>

package/src/components/HkRadio.test.tsx

@@ -0,0 +1,206 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkRadio, { type HkRadioOption } from "./HkRadio";
+
+/**
+ * HkRadio contract tests:
+ * - option selection semantics: the model value matches option VALUES
+ *   (strict, type-preserving — a numeric option emits a number), and the
+ *   checked markers (box data-checked, dot, native radio checked) follow
+ *   the matching option only
+ * - direction / size group modifiers
+ * - each option is a real <label> wrapping its native radio input, so
+ *   clicking an option's TEXT selects it; re-activating the already
+ *   selected option fires no platform change (and thus no emit)
+ * - disabled: whole group or per option; disabled inputs swallow clicks
+ *
+ * The component wires no custom keyboard handlers (no roving tabindex /
+ * arrow-key code exists) — keyboard behavior is whatever the native
+ * inputs provide, so no keyboard case is asserted here.
+ *
+ * House style: raw createApp mounts on a shared container list torn
+ * down after each case; DOM assertions via document queries.
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(node: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => node });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+const OPTS = [
+  { value: "a", label: "Alpha" },
+  { value: "b", label: "Beta" },
+];
+
+const NUM_OPTS = [
+  { value: 1, label: "One" },
+  { value: 2, label: "Two" },
+];
+
+/** v-model harness: mirrors consumer usage, records every emitted value. */
+function mountVModel(initial: string | number | null, props: Record<string, unknown> = {}) {
+  const model = ref<string | number | null>(initial);
+  const emitted: Array<string | number> = [];
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp(defineComponent({
+    setup: () => () =>
+      h(HkRadio, {
+        ...props,
+        modelValue: model.value as string | number,
+        "onUpdate:modelValue": (v: string | number) => {
+          model.value = v;
+          emitted.push(v);
+        },
+      } as never),
+  }));
+  app.mount(container);
+  mounts.push({ app, container });
+  const group = () => container.querySelector<HTMLElement>(".hk-radio-group")!;
+  const items = () => Array.from(container.querySelectorAll<HTMLElement>("label.hk-radio"));
+  const inputs = () => Array.from(container.querySelectorAll<HTMLInputElement>("input"));
+  return { container, model, emitted, group, items, inputs };
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+describe("HkRadio group shell", () => {
+  it("renders the horizontal/md group by default with one option per label", () => {
+    const c = mount(h(HkRadio, { options: OPTS }));
+    const group = c.querySelector<HTMLElement>(".hk-radio-group")!;
+    expect(group).not.toBeNull();
+    expect(group.className).toBe("hk-radio-group hk-radio-group-horizontal hk-radio-group-md");
+    const items = c.querySelectorAll("label.hk-radio");
+    expect(items.length).toBe(2);
+    // Option labels render through the HkLabel shell.
+    const labels = Array.from(c.querySelectorAll<HTMLElement>(".hk-label"));
+    expect(labels.map((l) => l.textContent)).toEqual(["Alpha", "Beta"]);
+    const inputs = c.querySelectorAll("input");
+    expect(inputs.length).toBe(2);
+    expect(Array.from(inputs).every((i) => i.type === "radio")).toBe(true);
+  });
+
+  it("maps direction and size props to group modifiers", () => {
+    const c = mount(h(HkRadio, { options: OPTS, direction: "vertical", size: "lg" }));
+    const cls = c.querySelector(".hk-radio-group")!.className;
+    expect(cls).toContain("hk-radio-group-vertical");
+    expect(cls).toContain("hk-radio-group-lg");
+    expect(cls).not.toContain("hk-radio-group-horizontal");
+    expect(c.querySelector("label.hk-radio")!.getAttribute("data-size")).toBe("lg");
+  });
+
+  it("lets the label slot override the option text", () => {
+    const c = mount(h(HkRadio, {
+      options: OPTS,
+    }, {
+      label: ({ option }: { option: HkRadioOption }) => h("span", { class: "custom-opt" }, `#${option.label}`),
+    }));
+    const customs = Array.from(c.querySelectorAll<HTMLElement>(".custom-opt"));
+    expect(customs.map((el) => el.textContent)).toEqual(["#Alpha", "#Beta"]);
+  });
+});
+
+describe("HkRadio selection semantics", () => {
+  it("marks only the option whose value matches the model", () => {
+    const c = mount(h(HkRadio, { options: OPTS, modelValue: "b" }));
+    const boxes = Array.from(c.querySelectorAll<HTMLElement>(".hk-radio-box"));
+    expect(boxes[0]!.hasAttribute("data-checked")).toBe(false);
+    expect(boxes[1]!.getAttribute("data-checked")).toBe("");
+    // The dot renders in the selected option only.
+    expect(c.querySelectorAll(".hk-radio-dot").length).toBe(1);
+    expect(boxes[1]!.querySelector(".hk-radio-dot")).not.toBeNull();
+    const inputs = Array.from(c.querySelectorAll<HTMLInputElement>("input"));
+    expect(inputs[0]!.checked).toBe(false);
+    expect(inputs[1]!.checked).toBe(true);
+  });
+
+  it("emits the clicked option's value and moves the selection", async () => {
+    const t = mountVModel("a", { options: OPTS });
+    t.inputs()[1]!.click();
+    await nextTick();
+    expect(t.emitted).toEqual(["b"]);
+    expect(t.model.value).toBe("b");
+    // Selection moved: dot and data-checked follow the new option.
+    const boxes = Array.from(t.container.querySelectorAll<HTMLElement>(".hk-radio-box"));
+    expect(boxes[0]!.hasAttribute("data-checked")).toBe(false);
+    expect(boxes[1]!.getAttribute("data-checked")).toBe("");
+  });
+
+  it("emits the option value type-preserving (number stays number)", async () => {
+    const t = mountVModel(1, { options: NUM_OPTS });
+    t.inputs()[1]!.click();
+    await nextTick();
+    expect(t.emitted).toEqual([2]);
+    expect(t.emitted[0]).toBe(2);
+    expect(typeof t.emitted[0]).toBe("number");
+    // Strict matching against the numeric model still selects.
+    expect(
+      Array.from(t.container.querySelectorAll<HTMLInputElement>("input"))[1]!.checked,
+    ).toBe(true);
+  });
+
+  it("selects through the option label text (native label→input forwarding)", async () => {
+    const t = mountVModel("a", { options: OPTS });
+    (t.container.querySelectorAll(".hk-label")[1] as HTMLElement).click();
+    await nextTick();
+    expect(t.emitted).toEqual(["b"]);
+    expect(t.inputs()[1]!.checked).toBe(true);
+  });
+
+  it("fires no emit when re-activating the already selected option", async () => {
+    const t = mountVModel("a", { options: OPTS });
+    t.inputs()[0]!.click(); // already checked: the platform fires no change
+    await nextTick();
+    expect(t.emitted).toEqual([]);
+    expect(t.model.value).toBe("a");
+  });
+
+  it("leaves every option unselected with a null model", () => {
+    const c = mount(h(HkRadio, { options: OPTS }));
+    expect(c.querySelector(".hk-radio-dot")).toBeNull();
+    expect(Array.from(c.querySelectorAll(".hk-radio-box")).every((b) => !b.hasAttribute("data-checked"))).toBe(true);
+  });
+});
+
+describe("HkRadio disabled", () => {
+  it("disables every option from the group prop", () => {
+    const c = mount(h(HkRadio, { options: OPTS, disabled: true }));
+    const items = Array.from(c.querySelectorAll<HTMLElement>("label.hk-radio"));
+    expect(items.every((el) => el.getAttribute("data-disabled") === "")).toBe(true);
+    expect(Array.from(c.querySelectorAll<HTMLInputElement>("input")).every((i) => i.disabled)).toBe(true);
+  });
+
+  it("disables a single option without touching its siblings", () => {
+    const c = mount(h(HkRadio, {
+      options: [{ value: "a", label: "Alpha" }, { value: "b", label: "Beta", disabled: true }],
+    }));
+    const items = Array.from(c.querySelectorAll<HTMLElement>("label.hk-radio"));
+    expect(items[0]!.hasAttribute("data-disabled")).toBe(false);
+    expect(items[1]!.getAttribute("data-disabled")).toBe("");
+    const inputs = Array.from(c.querySelectorAll<HTMLInputElement>("input"));
+    expect(inputs[0]!.disabled).toBe(false);
+    expect(inputs[1]!.disabled).toBe(true);
+  });
+
+  it("swallows clicks on a disabled option", async () => {
+    const t = mountVModel("a", {
+      options: [{ value: "a", label: "Alpha" }, { value: "b", label: "Beta", disabled: true }],
+    });
+    t.inputs()[1]!.click();
+    await nextTick();
+    expect(t.emitted).toEqual([]);
+    expect(t.model.value).toBe("a");
+  });
+});

package/src/components/HkSwitch.test.tsx

@@ -0,0 +1,174 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkSwitch from "./HkSwitch";
+
+/**
+ * HkSwitch contract tests:
+ * - role: the interactive control is a NATIVE <input type="checkbox">
+ *   inside a real <label> — keyboard interaction (Space) rides the
+ *   platform checkbox for free, so the tests exercise the input's
+ *   activation, which is exactly what a Space keypress produces
+ *   (happy-dom does not synthesize Space → click, so dispatching a raw
+ *   KeyboardEvent would assert nothing real)
+ * - model flip on activation emits !modelValue exactly once — the track
+ *   handler calls preventDefault() so the label's native click-forwarding
+ *   cannot produce a second toggle; that dedup is pinned here
+ * - data-checked / data-disabled state markers, size/color modifiers,
+ *   checked/unchecked track contents, label shell
+ *
+ * House style: raw createApp mounts on a shared container list torn down
+ * after each case; DOM assertions via document queries.
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(node: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => node });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+/** v-model harness: mirrors consumer usage, records every emitted value. */
+function mountVModel(initial: boolean, props: Record<string, unknown> = {}) {
+  const model = ref<boolean>(initial);
+  const emitted: Array<boolean> = [];
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp(defineComponent({
+    setup: () => () =>
+      h(HkSwitch, {
+        ...props,
+        modelValue: model.value,
+        "onUpdate:modelValue": (v: boolean) => {
+          model.value = v;
+          emitted.push(v);
+        },
+      }),
+  }));
+  app.mount(container);
+  mounts.push({ app, container });
+  const input = () => container.querySelector<HTMLInputElement>("input")!;
+  const root = () => container.querySelector<HTMLElement>("label")!;
+  const track = () => container.querySelector<HTMLElement>(".hk-switch-track")!;
+  return { container, model, emitted, input, root, track };
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+describe("HkSwitch rendering", () => {
+  it("exposes a native checkbox inside the label with md/primary defaults", () => {
+    const c = mount(h(HkSwitch));
+    const root = c.querySelector<HTMLElement>("label")!;
+    expect(root).not.toBeNull();
+    expect(root.className).toBe("hk-switch hk-switch-md hk-switch-primary");
+    expect(root.hasAttribute("data-checked")).toBe(false);
+    const input = c.querySelector<HTMLInputElement>("input")!;
+    expect(input.type).toBe("checkbox");
+    expect(input.checked).toBe(false);
+    expect(c.querySelector(".hk-switch-track")).not.toBeNull();
+    expect(c.querySelector(".hk-switch-thumb")).not.toBeNull();
+  });
+
+  it("maps modelValue=true to the checked markers on root and input", () => {
+    const c = mount(h(HkSwitch, { modelValue: true }));
+    expect(c.querySelector<HTMLElement>("label")!.getAttribute("data-checked")).toBe("");
+    expect(c.querySelector<HTMLInputElement>("input")!.checked).toBe(true);
+  });
+
+  it("maps size and color props to modifiers", () => {
+    const c = mount(h(HkSwitch, { size: "sm", color: "danger" }));
+    const cls = c.querySelector("label")!.className;
+    expect(cls).toContain("hk-switch-sm");
+    expect(cls).toContain("hk-switch-danger");
+    expect(cls).not.toContain("hk-switch-md");
+    expect(cls).not.toContain("hk-switch-primary");
+  });
+
+  it("swaps the track contents with the checked state", () => {
+    const off = mount(h(HkSwitch, {
+      checkedContent: "on-text",
+      uncheckedContent: "off-text",
+    }));
+    const offContent = off.querySelector<HTMLElement>(".hk-switch-content")!;
+    expect(offContent.className).toContain("hk-switch-content-off");
+    expect(offContent.textContent).toBe("off-text");
+    expect(off.querySelector(".hk-switch-content-on")).toBeNull();
+
+    const on = mount(h(HkSwitch, {
+      modelValue: true,
+      checkedContent: "on-text",
+      uncheckedContent: "off-text",
+    }));
+    const onContent = on.querySelector<HTMLElement>(".hk-switch-content")!;
+    expect(onContent.className).toContain("hk-switch-content-on");
+    expect(onContent.textContent).toBe("on-text");
+    expect(on.querySelector(".hk-switch-content-off")).toBeNull();
+  });
+
+  it("renders the label prop through the HkLabel shell", () => {
+    const c = mount(h(HkSwitch, { label: "Dark mode" }));
+    expect(c.querySelector(".hk-label")!.textContent).toBe("Dark mode");
+  });
+});
+
+describe("HkSwitch toggling", () => {
+  it("flips the model exactly once per track click (preventDefault dedup)", async () => {
+    const t = mountVModel(false);
+    t.track().click();
+    await nextTick();
+    // The track handler toggles AND calls preventDefault so the wrapping
+    // label cannot forward a second click to the native input — without
+    // that guard one tap would emit twice and net-zero the flip.
+    expect(t.emitted).toEqual([true]);
+    expect(t.model.value).toBe(true);
+    expect(t.root().getAttribute("data-checked")).toBe("");
+
+    t.track().click();
+    await nextTick();
+    expect(t.emitted).toEqual([true, false]);
+  });
+
+  it("toggles through the label text via native label→input forwarding", async () => {
+    const t = mountVModel(false, { label: "Dark mode" });
+    (t.container.querySelector(".hk-label") as HTMLElement).click();
+    await nextTick();
+    expect(t.emitted).toEqual([true]);
+    // The forwarded click natively flipped the input's checkedness.
+    expect(t.input().checked).toBe(true);
+  });
+
+  it("flips via the native checkbox activation (the Space-key path)", async () => {
+    const t = mountVModel(true);
+    // A real Space keypress on a focused checkbox produces exactly this
+    // input activation (checked flip + change event); the component owns
+    // no custom key handlers, so the platform control IS the keyboard
+    // story. Enter is not a checkbox activation key — nothing to assert.
+    t.input().click();
+    await nextTick();
+    expect(t.emitted).toEqual([false]);
+    expect(t.input().checked).toBe(false);
+  });
+
+  it("drops every toggle path while disabled", async () => {
+    const t = mountVModel(false, { disabled: true });
+    expect(t.root().getAttribute("data-disabled")).toBe("");
+    expect(t.input().disabled).toBe(true);
+    t.track().click();
+    t.input().click();
+    // Also the label-forwarding path: the platform drops clicks on a
+    // disabled input, so the forwarded activation dies too.
+    (t.container.querySelector(".hk-switch-thumb") as HTMLElement).click();
+    await nextTick();
+    expect(t.emitted).toEqual([]);
+    expect(t.model.value).toBe(false);
+  });
+});

package/src/components/HkToolBlock.scss

@@ -114,6 +114,22 @@
   }
 }
 
+/* ONE SCROLLBAR PER WINDOW (2026-09-08 audit, HkJsonTree tool blocks and
+   code panes): inside a window surface's own scroller the bounded pane
+   cap lit a SECOND scrollbar under the window's — one per pane in pane
+   lists like the chest todo-log modal. There the window's scrollbar is
+   the only one and the pane grows with its content. Chat message cards
+   and pages are NOT window surfaces: the bounded viewport above stays.
+   (The panes' overlay rails self-hide once the content fits, so the
+   deferred attach pass needs no changes.) */
+.hk-modal-body-scroll .s-tool-code,
+.hk-select-sheet-list .s-tool-code,
+.hk-select-popout .s-tool-code,
+.hk-popover-panel .s-tool-code,
+.hk-drawer-body .s-tool-code {
+  max-height: none;
+}
+
 .s-tool-result {
   border-left: 2px solid rgb(var(--color-success) / 40%);
   padding-left: var(--space-8, 0.5rem);
@@ -167,6 +183,15 @@
   }
 }
 
+/* Window-surface twin of the .s-tool-code rule above. */
+.hk-modal-body-scroll .s-tool-code-block,
+.hk-select-sheet-list .s-tool-code-block,
+.hk-select-popout .s-tool-code-block,
+.hk-popover-panel .s-tool-code-block,
+.hk-drawer-body .s-tool-code-block {
+  max-height: none;
+}
+
 .s-tool-code-table {
   border-collapse: collapse;
   width: 100%;

package/src/components/HkToolBlock.windowScroll.contract.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Source contract: ONE SCROLLBAR PER WINDOW — tool panes (2026-09-08
+ * audit follow-up). The tool block's code panes and the shared JSON tree
+ * keep a bounded widget viewport in chat cards and on pages (the exempt
+ * content-widget class, like markdown code blocks), but INSIDE a window
+ * surface's own scroller (modal body, select sheet, popout, popover
+ * sheet/panel, drawer body) that cap lit a second scrollbar under the
+ * window's — one per pane in pane lists like the chest todo-log modal.
+ * There the window's scrollbar is the only one and the pane grows with
+ * its content.
+ */
+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 toolScss = readFileSync(join(here, "HkToolBlock.scss"), "utf-8");
+const treeScss = readFileSync(join(here, "HkJsonTree.scss"), "utf-8");
+const toolTsx = readFileSync(join(here, "HkToolBlock.tsx"), "utf-8");
+
+/** Window-surface scrollers — the ONE-scrollbar owners. */
+const SCROLLERS = [
+  ".hk-modal-body-scroll",
+  ".hk-select-sheet-list",
+  ".hk-select-popout",
+  ".hk-popover-panel",
+  ".hk-drawer-body",
+] as const;
+
+const PANES = [".s-tool-code", ".s-tool-code-block", ".s-tool-json-tree"] as const;
+
+/** Extract ONE balanced `{...}` declaration block following `selector`
+ *  (a naive `[^}]*` would stop at the first nested `}` — see the
+ *  HkAffixPicker single-scroll contract for the established pattern). */
+function cssBlock(src: string, selector: string): string {
+  const at = src.indexOf(selector);
+  if (at < 0) return "";
+  const open = src.indexOf("{", at);
+  if (open < 0) return "";
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    if (src[i] === "{") depth++;
+    else if (src[i] === "}") {
+      depth--;
+      if (depth === 0) return src.slice(open, i + 1);
+    }
+  }
+  return "";
+}
+
+describe("tool pane single-scrollbar-per-window contract", () => {
+  it("keeps the bounded widget viewport outside windows", () => {
+    expect(cssBlock(toolScss, ".s-tool-code ")).toContain("max-height: 240px");
+    expect(cssBlock(toolScss, ".s-tool-code-block ")).toContain("max-height: 240px");
+    expect(cssBlock(treeScss, ".s-tool-json-tree ")).toContain("max-height: 320px");
+  });
+
+  it("drops the cap inside every window surface scroller", () => {
+    for (const pane of PANES) {
+      for (const scroller of SCROLLERS) {
+        // The uncap rule lives next to the pane's own file: tool panes in
+        // HkToolBlock.scss, the tree in HkJsonTree.scss. Search BOTH — a
+        // rule moved between the files must not fail the pin, a rule
+        // deleted anywhere must fail it.
+        const body =
+          cssBlock(toolScss, `${scroller} ${pane}`) ||
+          cssBlock(treeScss, `${scroller} ${pane}`);
+        expect(body, `${scroller} ${pane} uncap rule exists`).toBeTruthy();
+        expect(body, `${scroller} ${pane} uncaps via max-height: none`).toContain(
+          "max-height: none",
+        );
+      }
+    }
+  });
+
+  it("no window-scroller context ever re-caps a pane with a length", () => {
+    for (const scss of [toolScss, treeScss]) {
+      for (const scroller of SCROLLERS) {
+        // Any scroller-descendant rule for a pane carrying a px/vh/rem
+        // max-height would reintroduce the nested scrollbar.
+        const re = new RegExp(
+          `${scroller.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")} [^{]*\\{[^}]*max-height:\\s*(?!none)[\\d.]`,
+        );
+        expect(scss.match(re), `${scroller} descendant px cap`).toBeNull();
+      }
+    }
+  });
+
+  it("the deferred overlay pass still targets the three panes (rails self-hide when uncapped)", () => {
+    expect(toolTsx).toContain('".s-tool-code, .s-tool-code-block, .s-tool-json-tree"');
+  });
+});

package/src/components/HkTooltip.test.tsx

@@ -0,0 +1,226 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, h, nextTick } from "vue";
+
+import HkTooltip from "./HkTooltip";
+import { POPUP_Z_BANDS, POPUP_Z_STEP, usePopupManager } from "../runtime/usePopupManager";
+
+/**
+ * HkTooltip contract tests:
+ * - popup-manager registration: every mounted tooltip registers ONE
+ *   entry of kind "tooltip" in the real singleton registry (read back
+ *   through usePopupManager), stacked in the tooltip z band (above the
+ *   window/dropdown bands, below toasts), never scroll-locking; the
+ *   entry leaves the registry on unmount
+ * - the band z lands INLINE on the teleported popup element
+ * - show/hide: anchor mouseenter shows after the delay (default 300ms),
+ *   mouseleave hides and cancels a pending show; focusin/focusout ride
+ *   the same path
+ * - 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
+ *   transform)
+ *
+ * House style: raw createApp mounts on a shared container list torn
+ * down after each case; the popup-manager singleton is REAL state, so
+ * afterEach sweeps it the way usePopupManager.test.ts does.
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(props: Record<string, unknown> = {}) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({
+    render: () =>
+      h(HkTooltip, props as never, () => h("span", { class: "anchor-probe" }, "anchor")),
+  });
+  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 popup(): HTMLElement {
+  return document.querySelector<HTMLElement>(".hk-tooltip-popup")!;
+}
+
+function wrapper(c: HTMLElement): HTMLElement {
+  return c.querySelector<HTMLElement>(".hk-tooltip-wrapper")!;
+}
+
+/** real-timer settle: covers the show setTimeout(0) + the rAF position pass */
+async function settle() {
+  await new Promise((r) => setTimeout(r, 20));
+  await nextTick();
+}
+
+function enter(c: HTMLElement) {
+  wrapper(c).dispatchEvent(new MouseEvent("mouseenter"));
+}
+
+function leave(c: HTMLElement) {
+  wrapper(c).dispatchEvent(new MouseEvent("mouseleave"));
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+  // The registry is a module singleton — sweep leftovers so tests do not
+  // leak z state (same discipline as usePopupManager.test.ts).
+  for (const entry of [...manager.registry.value.values()]) {
+    manager.unregister(entry.id);
+  }
+  document.querySelectorAll(".hk-tooltip-popup").forEach((el) => el.remove());
+});
+
+describe("HkTooltip popup-manager registration", () => {
+  it("registers one tooltip-kind entry at the tooltip band and stamps its z inline", async () => {
+    mount({ text: "hello" });
+    const entries = tooltipEntries();
+    expect(entries.length).toBe(1);
+    expect(entries[0]!.kind).toBe("tooltip");
+    expect(entries[0]!.zIndex).toBe(POPUP_Z_BANDS.tooltip);
+    // 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
+    // --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" });
+    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);
+    expect(zs[0]).toBeGreaterThanOrEqual(POPUP_Z_BANDS.tooltip);
+  });
+
+  it("removes its registry entry on unmount", () => {
+    const { app } = mount({ text: "bye" });
+    expect(tooltipEntries().length).toBe(1);
+    app.unmount();
+    expect(tooltipEntries().length).toBe(0);
+  });
+
+  it("keeps a single registration across show/hide cycles", async () => {
+    const { container } = mount({ text: "stable", delay: 0 });
+    enter(container);
+    await settle();
+    leave(container);
+    await nextTick();
+    enter(container);
+    await settle();
+    expect(tooltipEntries().length).toBe(1);
+  });
+});
+
+describe("HkTooltip show/hide", () => {
+  it("teleports the popup to body, hidden, with the text content", () => {
+    const { container } = mount({ text: "the tip" });
+    const el = popup();
+    expect(document.body.contains(el)).toBe(true);
+    expect(el.parentElement).toBe(document.body);
+    expect(el.className).not.toContain("hk-tooltip-visible");
+    expect(el.querySelector(".hk-tooltip-content")!.textContent).toBe("the tip");
+    // The anchor slot renders inside the wrapper's trigger span.
+    expect(wrapper(container).querySelector(".hk-tooltip-trigger .anchor-probe")).not.toBeNull();
+  });
+
+  it("waits out the default 300ms delay before showing", async () => {
+    vi.useFakeTimers();
+    const { container } = mount({ text: "delayed" });
+    enter(container);
+    await vi.advanceTimersByTimeAsync(299);
+    await nextTick();
+    expect(popup().className).not.toContain("hk-tooltip-visible");
+
+    await vi.advanceTimersByTimeAsync(1);
+    await nextTick();
+    expect(popup().className).toContain("hk-tooltip-visible");
+  });
+
+  it("shows on anchor enter and hides on leave (delay 0)", async () => {
+    const { container } = mount({ text: "quick", delay: 0 });
+    enter(container);
+    await settle();
+    expect(popup().className).toContain("hk-tooltip-visible");
+
+    leave(container);
+    await nextTick();
+    expect(popup().className).not.toContain("hk-tooltip-visible");
+  });
+
+  it("cancels a pending show when the anchor is left before the delay elapses", async () => {
+    vi.useFakeTimers();
+    const { container } = mount({ text: "cancelled", delay: 200 });
+    enter(container);
+    await vi.advanceTimersByTimeAsync(100);
+    leave(container);
+    await vi.advanceTimersByTimeAsync(1000);
+    await nextTick();
+    expect(popup().className).not.toContain("hk-tooltip-visible");
+  });
+
+  it("shows on focusin and hides on focusout like hover", async () => {
+    const { container } = mount({ text: "focused", delay: 0 });
+    container
+      .querySelector(".hk-tooltip-trigger")!
+      .dispatchEvent(new FocusEvent("focusin", { bubbles: true }));
+    await settle();
+    expect(popup().className).toContain("hk-tooltip-visible");
+
+    container
+      .querySelector(".hk-tooltip-trigger")!
+      .dispatchEvent(new FocusEvent("focusout", { bubbles: true }));
+    await nextTick();
+    expect(popup().className).not.toContain("hk-tooltip-visible");
+  });
+});
+
+describe("HkTooltip anchoring", () => {
+  it("places the popup above the anchor with the top placement (gap + transform)", async () => {
+    const { container } = mount({ text: "up", delay: 0, placement: "top" });
+    enter(container);
+    await settle();
+    const el = popup();
+    expect(el.className).toContain("hk-tooltip-top");
+    expect(wrapper(container).getAttribute("data-position")).toBe("top");
+    // happy-dom reports a zero anchor rect: top = 0 - 8 gap, left = the
+    // anchor center, transform flips the popup above that point.
+    expect(el.style.top).toBe("-8px");
+    expect(el.style.left).toBe("0px");
+    expect(el.style.transform).toBe("translate(-50%, -100%)");
+  });
+
+  it("places the popup beside the anchor with the right placement", async () => {
+    const { container } = mount({ text: "side", delay: 0, placement: "right" });
+    enter(container);
+    await settle();
+    const el = popup();
+    expect(el.className).toContain("hk-tooltip-right");
+    expect(wrapper(container).getAttribute("data-position")).toBe("right");
+    expect(el.style.top).toBe("0px");
+    expect(el.style.left).toBe("8px");
+    expect(el.style.transform).toBe("translate(0, -50%)");
+  });
+
+  it("carries the maxWidth prop onto the popup style", async () => {
+    const { container } = mount({ text: "wide", delay: 0, maxWidth: "220px" });
+    enter(container);
+    await settle();
+    expect(popup().style.maxWidth).toBe("220px");
+  });
+});