@celestia-island/hikari 0.55.216 → 0.55.217

package/package.json

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

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

@@ -0,0 +1,42 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h, nextTick } from "vue";
+
+import HkPopover from "./HkPopover";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+  document.body.querySelectorAll(".hk-popover-panel").forEach((el) => el.remove());
+});
+
+describe("HkPopover panel hover intent", () => {
+  it("emits from the whole panel, including padding outside the slot content", async () => {
+    const events: string[] = [];
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () => h(
+        HkPopover as never,
+        {
+          modelValue: true,
+          title: "hover probe",
+          onMouseenter: () => events.push("enter"),
+          onMouseleave: () => events.push("leave"),
+        },
+        () => h("div", { class: "probe-body" }, "content"),
+      ),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+    await nextTick();
+    const panel = document.body.querySelector<HTMLElement>(".hk-popover-panel")!;
+    expect(panel).not.toBeNull();
+    panel.dispatchEvent(new MouseEvent("mouseenter"));
+    panel.dispatchEvent(new MouseEvent("mouseleave"));
+    expect(events).toEqual(["enter", "leave"]);
+  });
+});

package/src/components/HkPopover.tsx

@@ -103,6 +103,12 @@ export default defineComponent({
      *  emits on unmounted instances) — a host that itself is going away
      *  has nothing to reclaim anyway. */
     closed: () => true,
+    /** Hover intent for anchor↔popover safe travel. These fire on the WHOLE
+     *  panel (padding and chrome included), not only its slot content; a
+     *  consumer can track anchor/panel hover independently without the
+     *  overlap open→leave→close→enter loop. */
+    mouseenter: (_event: MouseEvent) => true,
+    mouseleave: (_event: MouseEvent) => true,
   },
   setup(props, { emit, slots }) {
     const attrs = useAttrs();
@@ -732,6 +738,8 @@ export default defineComponent({
                 aria-label={props.title || undefined}
                 tabindex={sheetBranch ? "-1" : undefined}
                 onKeydown={onPanelKeydown}
+                onMouseenter={(event: MouseEvent) => emit("mouseenter", event)}
+                onMouseleave={(event: MouseEvent) => emit("mouseleave", event)}
               >
                 {sheetBranch && (
                   <div class="hk-popover-sheet-grabber" aria-hidden="true" onClick={() => close()} />

package/src/components/HkTooltip.test.tsx

@@ -57,6 +57,10 @@ function wrapper(c: HTMLElement): HTMLElement {
 async function settle() {
   await new Promise((r) => setTimeout(r, 20));
   await nextTick();
+  // Wait for the show-time rAF position pass itself; a wall-clock sleep is
+  // not a frame barrier under a loaded test host.
+  await new Promise<void>((resolve) => { requestAnimationFrame(() => resolve()); });
+  await nextTick();
 }
 
 function enter(c: HTMLElement) {
@@ -266,6 +270,24 @@ describe("HkTooltip touch taps", () => {
     expect(popup().className).toContain("hk-tooltip-visible");
   });
 
+  it("follows a moving anchor on the touch-opened path too", async () => {
+    const { container } = mount({ text: "touch moving", delay: 3000, placement: "bottom" });
+    let top = 100;
+    wrapper(container).getBoundingClientRect = () => ({
+      x: 200, y: top, left: 200, top, right: 280, bottom: top + 40,
+      width: 80, height: 40, toJSON: () => ({}),
+    }) as DOMRect;
+    tap(wrapper(container));
+    await settle();
+    expect(popup().style.top).toBe("148px");
+    top = 120;
+    await settle();
+    expect(popup().style.top).toBe("168px");
+    tap(wrapper(container)); // close also stops the tracking loop
+    await nextTick();
+    expect(popup().className).not.toContain("hk-tooltip-visible");
+  });
+
   it("toggles closed when the trigger is tapped again", async () => {
     const { container } = mount({ text: "toggle", delay: 3000 });
     tap(wrapper(container));
@@ -321,6 +343,44 @@ describe("HkTooltip touch taps", () => {
 });
 
 describe("HkTooltip anchoring", () => {
+  it("uses an explicitly-sized absolute wrapper as the visible cell anchor", async () => {
+    const { container } = mount({
+      text: "cell", delay: 0, placement: "bottom",
+      style: { position: "absolute", left: "200px", top: "100px", width: "400px", height: "240px" },
+    });
+    const anchor = wrapper(container);
+    expect(anchor.style.position).toBe("absolute");
+    expect(anchor.style.width).toBe("400px");
+    anchor.getBoundingClientRect = () => ({
+      x: 200, y: 100, left: 200, top: 100, right: 600, bottom: 340,
+      width: 400, height: 240, toJSON: () => ({}),
+    }) as DOMRect;
+    enter(container);
+    await settle();
+    expect(popup().style.top).toBe("348px"); // cell.bottom 340 + 8px gap
+    expect(popup().style.left).toBe("400px"); // visible frame's centre
+    expect(popup().style.transform).toBe("translate(-50%, 0)");
+  });
+
+  it("follows a moving anchor while visible (wheel zoom / minimap pan)", async () => {
+    const { container } = mount({ text: "moving", delay: 0, placement: "bottom" });
+    let top = 100;
+    wrapper(container).getBoundingClientRect = () => ({
+      x: 200, y: top, left: 200, top, right: 280, bottom: top + 40,
+      width: 80, height: 40, toJSON: () => ({}),
+    }) as DOMRect;
+    enter(container);
+    await settle();
+    expect(popup().style.top).toBe("148px");
+
+    top = 120; // the same hovered cell moves with the camera; no new enter
+    await settle();
+    expect(popup().style.top).toBe("168px");
+    leave(container);
+    await nextTick();
+    expect(popup().className).not.toContain("hk-tooltip-visible");
+  });
+
   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);

package/src/components/HkTooltip.tsx

@@ -38,6 +38,7 @@ export default defineComponent({
     const wrapperRef = ref<HTMLElement | null>(null);
     const popupRef = ref<HTMLElement | null>(null);
     let showTimer: ReturnType<typeof setTimeout> | null = null;
+    let positionFrame: number | null = null;
 
     // The band handle and the popup DOM are both LAZY (dense-list contract,
     // 2026-10-05): a tooltip that is never engaged — the overwhelming
@@ -74,12 +75,31 @@ export default defineComponent({
       applyTooltipPosition(popupRef.value, rect, props.placement, props.maxWidth);
     }
 
+    function stopPositionTracking() {
+      if (positionFrame !== null) cancelAnimationFrame(positionFrame);
+      positionFrame = null;
+    }
+
+    function trackPositionWhileVisible() {
+      if (positionFrame !== null) return;
+      const tick = () => {
+        positionFrame = null;
+        if (!visible.value) return;
+        // A visible trigger can move without a pointer event (treemap wheel
+        // zoom, minimap pan, layout animation). Re-read its rect per frame
+        // until hide/unmount; each visible tooltip owns one such loop.
+        updatePosition();
+        positionFrame = requestAnimationFrame(tick);
+      };
+      positionFrame = requestAnimationFrame(tick);
+    }
+
     function show() {
       clearShowTimer();
       ensureEngaged();
       showTimer = setTimeout(() => {
         visible.value = true;
-        requestAnimationFrame(updatePosition);
+        trackPositionWhileVisible();
       }, props.delay);
     }
 
@@ -87,12 +107,13 @@ export default defineComponent({
       clearShowTimer();
       ensureEngaged();
       visible.value = true;
-      requestAnimationFrame(updatePosition);
+      trackPositionWhileVisible();
     }
 
     function hide() {
       clearShowTimer();
       visible.value = false;
+      stopPositionTracking();
       dismissTouchListener();
     }
 
@@ -144,6 +165,7 @@ export default defineComponent({
 
     onBeforeUnmount(() => {
       clearShowTimer();
+      stopPositionTracking();
       dismissTouchListener();
       if (popupHandle) {
         manager.unregister(popupHandle.id);

package/src/components/HkTreemap.test.tsx

@@ -11,9 +11,15 @@ import { createApp, defineComponent, h, nextTick, reactive } from "vue";
 vi.mock("./HkTooltip", () => ({
   default: {
     name: "HkTooltipStub",
-    props: { text: { type: String, required: true } },
-    setup(props: { text: string }, { slots }: { slots: { default?: (p: unknown) => unknown } }) {
-      return () => h("span", { "data-hk-tooltip-text": props.text }, slots.default?.({}) as never);
+    props: {
+      text: { type: String, required: true },
+      placement: { type: String, default: "top" },
+    },
+    setup(props: { text: string; placement: string }, { slots }: { slots: { default?: (p: unknown) => unknown } }) {
+      return () => h("span", {
+        "data-hk-tooltip-text": props.text,
+        "data-hk-tooltip-placement": props.placement,
+      }, slots.default?.({}) as never);
     },
   },
 }));
@@ -316,8 +322,35 @@ describe("HkTreemap component", () => {
     // 400×240 LOCAL space (the old gBCR-based measure painted 2× cells).
     await setSize(mounted, 400, 240, 2);
     const cell = mounted.container.querySelector<HTMLElement>(".hk-treemap__cell")!;
-    expect(cell.style.width).toBe("400px");
-    expect(cell.style.height).toBe("240px");
+    const frame = cell.closest<HTMLElement>("[data-hk-tooltip-text]")!;
+    expect(frame.style.width).toBe("400px");
+    expect(frame.style.height).toBe("240px");
+    expect(cell.style.inset).toBe("0px");
+  });
+
+  it("keeps every small-canvas cell frame inside the chart at 1×/2×/3× DPI", async () => {
+    const mounted = mountTreemap({ nodes: NODES });
+    for (const zoom of [1, 2, 3]) {
+      await setSize(mounted, 220, 120, zoom);
+      const cells = [...mounted.container.querySelectorAll<HTMLElement>(".hk-treemap__cell")];
+      expect(cells.length).toBeGreaterThanOrEqual(4);
+      for (const cell of cells) {
+        const frame = cell.classList.contains("hk-treemap__cell--plate")
+          ? cell
+          : cell.closest<HTMLElement>("[data-hk-tooltip-text]")!;
+        if (frame !== cell) expect(frame.style.position).toBe("absolute");
+        const x = Number.parseFloat(frame.style.left);
+        const y = Number.parseFloat(frame.style.top);
+        const w = Number.parseFloat(frame.style.width);
+        const h = Number.parseFloat(frame.style.height);
+        expect([x, y, w, h].every(Number.isFinite)).toBe(true);
+        expect(x).toBeGreaterThanOrEqual(0);
+        expect(y).toBeGreaterThanOrEqual(0);
+        expect(x + w).toBeLessThanOrEqual(220.001);
+        expect(y + h).toBeLessThanOrEqual(120.001);
+        if (frame !== cell) expect(cell.style.inset).toBe("0px");
+      }
+    }
   });
 
   it("every cell carries the standard HkTooltip with label, value and share", async () => {
@@ -332,6 +365,10 @@ describe("HkTreemap component", () => {
     expect(tooltips).toContain("Group: 6u · 60%");
     expect(tooltips).toContain("Alpha: 2u · 20%");
     expect(tooltips).toContain("Other: 4u · 40%");
+    const placements = [...mounted.container.querySelectorAll("[data-hk-tooltip-placement]")]
+      .map((node) => node.getAttribute("data-hk-tooltip-placement"));
+    expect(placements).toHaveLength(tooltips.length);
+    expect(new Set(placements)).toEqual(new Set(["bottom"]));
   });
 
   it("re-renders cells when data changes on a same-size container", async () => {

package/src/components/HkTreemap.tsx

@@ -488,36 +488,36 @@ export default defineComponent({
       }
       const head = entry.kind === "head";
       const bandH = Math.min(22, Math.max(0, h));
-      const style = head
-        ? {
-            left: `${x}px`,
-            top: `${y}px`,
-            width: `${w}px`,
-            height: `${bandH}px`,
-            background: node.color,
-            "--hk-treemap-fg": contrastTextColor(node.color),
-          }
-        : {
-            left: `${x}px`,
-            top: `${y}px`,
-            width: `${w}px`,
-            height: `${h}px`,
-            background: node.color,
-            "--hk-treemap-fg": contrastTextColor(node.color),
-          };
+      // The tooltip wrapper IS the absolute cell frame. Its trigger fills
+      // that frame, so the wrapper both establishes the correct containing
+      // block and reports the visible cell's rect to tooltipPosition. The
+      // old shape positioned the trigger inside a zero-sized inline wrapper
+      // (wrong origin + chart-edge clipping + every tooltip at the top-left).
+      const frameStyle = {
+        position: "absolute" as const,
+        left: `${x}px`,
+        top: `${y}px`,
+        width: `${w}px`,
+        height: `${head ? bandH : h}px`,
+      };
+      const cellStyle = {
+        inset: "0px",
+        background: node.color,
+        "--hk-treemap-fg": contrastTextColor(node.color),
+      };
       const label = showLabel || head ? node.label : null;
       const meta = showValue
         ? `${formatValue(node.value)} · ${formatHkTreemapPercent(node.percent)}`
         : null;
       return (
-        <HkTooltip key={entry.key} text={cellText(node)} placement="top">
+        <HkTooltip key={entry.key} text={cellText(node)} placement="bottom" style={frameStyle}>
           {() => (
             <div
               class={{
                 "hk-treemap__cell": true,
                 "hk-treemap__cell--group": head,
               }}
-              style={style}
+              style={cellStyle}
               role="img"
               aria-label={cellText(node)}
             >

package/src/components/HkTreemapStage.test.tsx

@@ -6,9 +6,15 @@ import { createApp, defineComponent, h, nextTick, reactive } from "vue";
 vi.mock("./HkTooltip", () => ({
   default: {
     name: "HkTooltipStub",
-    props: { text: { type: String, required: true } },
-    setup(props: { text: string }, { slots }: { slots: { default?: (p: unknown) => unknown } }) {
-      return () => h("span", { "data-hk-tooltip-text": props.text }, slots.default?.({}) as never);
+    props: {
+      text: { type: String, required: true },
+      placement: { type: String, default: "top" },
+    },
+    setup(props: { text: string; placement: string }, { slots }: { slots: { default?: (p: unknown) => unknown } }) {
+      return () => h("span", {
+        "data-hk-tooltip-text": props.text,
+        "data-hk-tooltip-placement": props.placement,
+      }, slots.default?.({}) as never);
     },
   },
 }));
@@ -76,11 +82,13 @@ function mountStage(initialProps: Record<string, unknown> = { nodes: NODES }) {
   };
 }
 
-async function setSize(mounted: { container: HTMLElement }, width = 400, height = 240) {
+async function setSize(mounted: { container: HTMLElement }, width = 400, height = 240, zoom = 1) {
   const el = mounted.container.querySelector<HTMLElement>(".hk-treemap-stage__canvas")!;
-  el.getBoundingClientRect = () => fakeRect(width, height);
+  el.getBoundingClientRect = () => fakeRect(width * zoom, height * zoom);
   Object.defineProperty(el, "clientWidth", { value: width, configurable: true });
   Object.defineProperty(el, "clientHeight", { value: height, configurable: true });
+  Object.defineProperty(el, "offsetWidth", { value: width, configurable: true });
+  Object.defineProperty(el, "offsetHeight", { value: height, configurable: true });
   FakeResizeObserver.instances[0]?.callback();
   await nextTick();
 }
@@ -112,9 +120,34 @@ describe("HkTreemapStage — the drill path", () => {
       (n) => n.getAttribute("data-hk-tooltip-text"),
     );
     expect(tooltips.some((t) => t!.startsWith("Group:"))).toBe(true);
+    const placements = [...mounted.container.querySelectorAll("[data-hk-tooltip-placement]")]
+      .map((node) => node.getAttribute("data-hk-tooltip-placement"));
+    expect(new Set(placements)).toEqual(new Set(["bottom"]));
     expect(mounted.container.textContent).toContain("Usage"); // the root crumb
   });
 
+  it("keeps the tooltip-owned cell frames inside a small canvas at 2×/3× DPI", async () => {
+    const mounted = mountStage({ nodes: NODES });
+    for (const zoom of [2, 3]) {
+      await setSize(mounted, 220, 120, zoom);
+      const cells = [...mounted.container.querySelectorAll<HTMLElement>(".hk-treemap-stage__cell")];
+      expect(cells).toHaveLength(2);
+      for (const cell of cells) {
+        const frame = cell.closest<HTMLElement>("[data-hk-tooltip-text]")!;
+        expect(frame.style.position).toBe("absolute");
+        const x = Number.parseFloat(frame.style.left);
+        const y = Number.parseFloat(frame.style.top);
+        const w = Number.parseFloat(frame.style.width);
+        const h = Number.parseFloat(frame.style.height);
+        expect(x).toBeGreaterThanOrEqual(0);
+        expect(y).toBeGreaterThanOrEqual(0);
+        expect(x + w).toBeLessThanOrEqual(220.001);
+        expect(y + h).toBeLessThanOrEqual(120.001);
+        expect(cell.style.inset).toBe("0px");
+      }
+    }
+  });
+
   it("clicking a GROUP cell drills in: children fill the canvas, back button appears", async () => {
     const mounted = mountStage({ nodes: NODES });
     await setSize(mounted);
@@ -223,6 +256,106 @@ describe("HkTreemapStage — the camera + minimap", () => {
     expect(mounted.container.querySelector(".hk-mm-zoom-label")!.textContent).toContain("110");
   });
 
+  it("wheel gestures zoom the canvas and never scroll the host page", async () => {
+    const mounted = mountStage({ nodes: NODES });
+    await setSize(mounted);
+    const canvas = mounted.container.querySelector<HTMLElement>(".hk-treemap-stage__canvas")!;
+    const surface = mounted.container.querySelector<HTMLElement>(".hk-treemap-stage__surface")!;
+    const inEvent = new WheelEvent("wheel", { deltaY: -100, bubbles: true, cancelable: true });
+    canvas.dispatchEvent(inEvent);
+    await nextTick();
+    expect(inEvent.defaultPrevented).toBe(true);
+    expect(surface.style.transform).toContain("scale(1.1)");
+    canvas.dispatchEvent(new WheelEvent("wheel", { deltaY: 100, bubbles: true, cancelable: true }));
+    await nextTick();
+    expect(surface.style.transform).toContain("scale(1)");
+  });
+
+  it("clamps wheel zoom at 50–200% and ignores zero-delta motion", async () => {
+    const mounted = mountStage({ nodes: NODES });
+    await setSize(mounted);
+    const canvas = mounted.container.querySelector<HTMLElement>(".hk-treemap-stage__canvas")!;
+    const surface = mounted.container.querySelector<HTMLElement>(".hk-treemap-stage__surface")!;
+    const zero = new WheelEvent("wheel", { deltaY: 0, bubbles: true, cancelable: true });
+    canvas.dispatchEvent(zero);
+    await nextTick();
+    expect(zero.defaultPrevented).toBe(true);
+    expect(surface.style.transform).toContain("scale(1)");
+    for (let i = 0; i < 8; i += 1) {
+      canvas.dispatchEvent(new WheelEvent("wheel", { deltaY: 100, bubbles: true, cancelable: true }));
+    }
+    await nextTick();
+    expect(surface.style.transform).toContain("scale(0.5)");
+    for (let i = 0; i < 20; i += 1) {
+      canvas.dispatchEvent(new WheelEvent("wheel", { deltaY: -100, bubbles: true, cancelable: true }));
+    }
+    await nextTick();
+    expect(surface.style.transform).toContain("scale(2)");
+  });
+
+  it("keeps wheel zoom anchored under the pointer at 2× root DPI", async () => {
+    const mounted = mountStage({ nodes: [{ id: "leaf", label: "Leaf", value: 1 }] });
+    await setSize(mounted, 400, 240, 2);
+    const canvas = mounted.container.querySelector<HTMLElement>(".hk-treemap-stage__canvas")!;
+    canvas.getBoundingClientRect = () => ({
+      x: 100, y: 50, left: 100, top: 50, right: 900, bottom: 530,
+      width: 800, height: 480, toJSON: () => ({}),
+    }) as DOMRect;
+    const surface = mounted.container.querySelector<HTMLElement>(".hk-treemap-stage__surface")!;
+    const wheel = new WheelEvent("wheel", {
+      deltaY: -100, bubbles: true, cancelable: true,
+    });
+    // happy-dom does not apply MouseEventInit's client coords to WheelEvent;
+    // pin them explicitly (same convention as HkBoard.scale.test.ts).
+    Object.defineProperty(wheel, "clientX", { value: 500 });
+    Object.defineProperty(wheel, "clientY", { value: 290 });
+    // (500,290) drawn = (200,120) local. At 100→110%, pan must become
+    // (-20,-12) so -20 + 200×1.1 = 200 (and likewise on y).
+    canvas.dispatchEvent(wheel);
+    await nextTick();
+    const match = /translate\(([-\d.]+)px, ([-\d.]+)px\) scale\(([\d.]+)\)/.exec(
+      surface.style.transform,
+    );
+    expect(match).not.toBeNull();
+    expect(Number(match![1])).toBeCloseTo(-20, 8);
+    expect(Number(match![2])).toBeCloseTo(-12, 8);
+    expect(Number(match![3])).toBeCloseTo(1.1, 8);
+    // The world point under the pointer is invariant, not merely "zoomed".
+    expect(Number(match![1]) + 200 * Number(match![3])).toBeCloseTo(200, 8);
+    expect(Number(match![2]) + 120 * Number(match![3])).toBeCloseTo(120, 8);
+  });
+
+  it("controlled zoom changes pan only when the parent actually applies the request", async () => {
+    const mounted = mountStage({
+      nodes: [{ id: "leaf", label: "Leaf", value: 1 }],
+      zoomPercent: 100,
+    });
+    await setSize(mounted, 400, 240, 2);
+    const canvas = mounted.container.querySelector<HTMLElement>(".hk-treemap-stage__canvas")!;
+    canvas.getBoundingClientRect = () => ({
+      x: 100, y: 50, left: 100, top: 50, right: 900, bottom: 530,
+      width: 800, height: 480, toJSON: () => ({}),
+    }) as DOMRect;
+    const surface = mounted.container.querySelector<HTMLElement>(".hk-treemap-stage__surface")!;
+    const wheel = new WheelEvent("wheel", { deltaY: -100, bubbles: true, cancelable: true });
+    Object.defineProperty(wheel, "clientX", { value: 500 });
+    Object.defineProperty(wheel, "clientY", { value: 290 });
+    canvas.dispatchEvent(wheel);
+    await nextTick();
+    // Parent rejected/omitted the update: neither scale nor pan may move.
+    expect(surface.style.transform).toBe("translate(0px, 0px) scale(1)");
+
+    mounted.update({ zoomPercent: 110 });
+    await nextTick();
+    const match = /translate\(([-\d.]+)px, ([-\d.]+)px\) scale\(([\d.]+)\)/.exec(
+      surface.style.transform,
+    );
+    expect(match).not.toBeNull();
+    expect(Number(match![1])).toBeCloseTo(-20, 8);
+    expect(Number(match![2])).toBeCloseTo(-12, 8);
+    expect(Number(match![3])).toBeCloseTo(1.1, 8);
+  });
+
   it("zoom reveals detail: a small cell's label appears at a higher rung", async () => {
     // One dominant leaf + crumbs: at 100% the crumbs sit under the label
     // floor; zoom in and the effective size crosses it.

package/src/components/HkTreemapStage.tsx

@@ -5,6 +5,7 @@ import { ChevronLeft } from "lucide-vue-next";
 import HkIconButton from "./HkIconButton";
 import HkMinimap, { type MinimapBox } from "./HkMinimap";
 import HkTooltip from "./HkTooltip";
+import { drawnScale } from "../composables/layoutGeometry";
 import {
   buildHkTreemapLayout,
   contrastTextColor,
@@ -86,30 +87,73 @@ export default defineComponent({
     const panX = ref(0);
     const panY = ref(0);
 
-    function applyZoom(target: number): void {
+    interface ZoomAnchor { x: number; y: number }
+    let pendingControlledZoom: { percent: number; anchor: ZoomAnchor } | null = null;
+
+    function rescalePan(prev: number, next: number, anchor: ZoomAnchor): void {
+      // transform = translate(pan) scale(k): keep the WORLD point under
+      // `anchor` stationary. Minimap buttons keep the historical origin
+      // anchor; wheel passes the pointer's LOCAL canvas point (DPI-safe).
+      if (prev <= 0 || next === prev) return;
+      const ratio = next / prev;
+      panX.value = anchor.x - (anchor.x - panX.value) * ratio;
+      panY.value = anchor.y - (anchor.y - panY.value) * ratio;
+    }
+
+    function applyZoom(target: number, anchor = { x: 0, y: 0 }): void {
       const next = Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, Math.round(target)));
-      // Capture the PREVIOUS rung before writing the new one — reading
-      // zoomPct after the write always yields `next` and turns the pan
-      // rescale below into a silent no-op (R2 finding).
       const prev = zoomPct.value;
-      internalZoom.value = next;
-      emit("update:zoomPercent", next);
-      // The camera anchors the ORIGIN (transform-origin: 0 0), so a rung
-      // change rescales any accumulated pan by the same ratio to keep the
-      // content under the cursor tracking — an origin-anchored re-scale,
-      // not a centre-anchored one.
-      if (prev > 0 && next !== prev) {
-        const ratio = next / prev;
-        panX.value *= ratio;
-        panY.value *= ratio;
+      if (props.zoomPercent === undefined) {
+        internalZoom.value = next;
+        rescalePan(prev, next, anchor);
+      } else {
+        // Controlled mode is a REQUEST until the parent applies it. If the
+        // parent rejects/omits the update, scale AND pan must both stay put.
+        pendingControlledZoom = { percent: next, anchor };
       }
+      emit("update:zoomPercent", next);
     }
 
+    watch(() => props.zoomPercent, (next, prev) => {
+      if (next == null || prev == null || next === prev) return;
+      const pending = pendingControlledZoom;
+      pendingControlledZoom = null;
+      rescalePan(prev, next, pending?.percent === next ? pending.anchor : { x: 0, y: 0 });
+    });
+
     function applyPanDelta(dx: number, dy: number): void {
       panX.value += dx;
       panY.value += dy;
     }
 
+    function localPoint(event: WheelEvent): { x: number; y: number } {
+      const el = hostRef.value;
+      const rect = el?.getBoundingClientRect();
+      if (!el) return { x: 0, y: 0 };
+      // Pointer coordinates and gBCR are DRAWN px; the camera lives in the
+      // canvas's LOCAL CSS px. Follow HkBoard's root-zoom conversion rather
+      // than letting a 200%/300% root move the zoom anchor off the pointer.
+      const scale = drawnScale(el);
+      const factor = el.offsetWidth > 0 ? scale.x : el.offsetHeight > 0 ? scale.y : 1;
+      const k = factor > 0 ? factor : 1;
+      return {
+        x: (event.clientX - (rect?.left ?? 0)) / k,
+        y: (event.clientY - (rect?.top ?? 0)) / k,
+      };
+    }
+
+    function onWheel(event: WheelEvent): void {
+      // The stage is a map canvas: wheel gestures belong to its camera, not
+      // to the popover/page behind it. Prevent the scroll even at a zoom
+      // limit so reaching 50%/200% never unexpectedly scrolls the host.
+      event.preventDefault();
+      if (event.deltaY === 0) return;
+      applyZoom(
+        zoomPct.value + (event.deltaY < 0 ? STEP_ZOOM : -STEP_ZOOM),
+        localPoint(event),
+      );
+    }
+
     function resetCamera(): void {
       internalZoom.value = 100;
       emit("update:zoomPercent", 100);
@@ -276,7 +320,13 @@ export default defineComponent({
           </header>
         )}
         <div class="hk-treemap-stage__body">
-          <div ref={hostRef} class="hk-treemap-stage__canvas" role="application" aria-label={props.ariaLabel}>
+          <div
+            ref={hostRef}
+            class="hk-treemap-stage__canvas"
+            role="application"
+            aria-label={props.ariaLabel}
+            onWheel={onWheel}
+          >
             {hasData.value && (
               <div class="hk-treemap-stage__surface" style={surfaceStyle.value}>
                 {cells.value.map((cell) => {
@@ -289,8 +339,15 @@ export default defineComponent({
                   const zh = h * (zoomPct.value / 100);
                   const showValue = zh >= 40 && zw >= 56;
                   const showLabel = zh >= 18 && zw >= 24;
+                  const frameStyle = {
+                    position: "absolute" as const,
+                    left: `${x}px`,
+                    top: `${y}px`,
+                    width: `${w}px`,
+                    height: `${h}px`,
+                  };
                   return (
-                    <HkTooltip key={node.id} text={cellText(node)} placement="top">
+                    <HkTooltip key={node.id} text={cellText(node)} placement="bottom" style={frameStyle}>
                       {() => (
                         <div
                           class={{
@@ -300,10 +357,7 @@ export default defineComponent({
                             "hk-treemap-stage__cell--drillable": isGroup,
                           }}
                           style={{
-                            left: `${x}px`,
-                            top: `${y}px`,
-                            width: `${w}px`,
-                            height: `${h}px`,
+                            inset: "0px",
                             background: node.color,
                             "--hk-treemap-fg": contrastTextColor(node.color),
                           }}

package/src/index.ts

@@ -730,6 +730,7 @@ export {
 export { default as HkMinimap3D } from "./components/HkMinimap3D";
 export { default as HkTrendChart } from "./components/HkTrendChart";
 export { default as HkTreemap } from "./components/HkTreemap";
+export { default as HkTreemapStage } from "./components/HkTreemapStage";
 export { default as HkErrorBoundary } from "./components/HkErrorBoundary";
 export { default as HkDraggableList } from "./components/HkDraggableList";
 export { default as HkDraggableGrid } from "./components/HkDraggableGrid";