@celestia-island/hikari 0.43.14 → 0.43.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.43.14",
+  "version": "0.43.15",
   "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

@@ -89,6 +89,30 @@ describe("HkAuthMethodList", () => {
     expect(wrapper.style.getPropertyValue("--auth-methods-label-width")).toBe("63px");
   });
 
+  it("publishes a width in the column's own units inside a scaled root", async () => {
+    // The labels are measured where they are DRAWN while the custom property
+    // is a CSS length the column is laid out with: in a scaled or zoomed root
+    // the published column would come out that many times too wide.
+    const c = mount(h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, { methods })));
+    await nextTick();
+    const wrapper = c.querySelector<HTMLElement>(".s-auth-methods-list")!;
+    const spans = [...wrapper.querySelectorAll<HTMLElement>(".s-auth-methods-label")];
+    Object.defineProperty(spans[0]!, "getBoundingClientRect", { configurable: true, value: () => ({ width: 58 }) });
+    Object.defineProperty(spans[1]!, "getBoundingClientRect", { configurable: true, value: () => ({ width: 61.4 }) });
+    // The list is drawn twice the size it is laid out at.
+    Object.defineProperty(wrapper, "getBoundingClientRect", {
+      configurable: true,
+      value: () => ({ left: 0, top: 0, right: 400, bottom: 200, width: 400, height: 200, x: 0, y: 0 }) as DOMRect,
+    });
+    Object.defineProperty(wrapper, "offsetWidth", { configurable: true, get: () => 200 });
+    Object.defineProperty(wrapper, "offsetHeight", { configurable: true, get: () => 100 });
+    const instance = (wrapper as unknown as { __vueParentComponent?: { exposed?: Record<string, unknown> } })
+      .__vueParentComponent?.exposed;
+    (instance!.measure as () => void)();
+    // 61.4 drawn are 30.7 of the column's own: ceil 31, plus the 1px headroom.
+    expect(wrapper.style.getPropertyValue("--auth-methods-label-width")).toBe("32px");
+  });
+
   it("leaves the column fallback intact when no text metrics are available", async () => {
     const c = mount(h("div", { class: "s-auth-methods" }, h(HkAuthMethodList, { methods })));
     await nextTick();

package/src/components/HkAuthMethodList.tsx

@@ -1,5 +1,6 @@
 import { defineComponent, nextTick, onBeforeUnmount, onMounted, ref, watch } from "vue";
 import HkButton from "./HkButton";
+import { drawnScale } from "../composables/layoutGeometry";
 import "./HkAuthMethodList.scss";
 
 /**
@@ -81,10 +82,16 @@ export default defineComponent({
       const root = listRef.value;
       if (!root) return;
       let widest = 0;
+      // The labels are measured where they are DRAWN, and the width is
+      // published as a CSS length the column is laid out with: in a scaled or
+      // zoomed root the two differ by the scale of the space, so the column
+      // would come out that many times too wide (see `layoutGeometry`).
+      const space = drawnScale(root);
+      const factor = root.offsetWidth > 0 ? space.x : root.offsetHeight > 0 ? space.y : 1;
       for (const label of root.querySelectorAll<HTMLElement>(".s-auth-methods-label")) {
         const previous = label.style.width;
         label.style.width = "max-content";
-        widest = Math.max(widest, label.getBoundingClientRect().width);
+        widest = Math.max(widest, label.getBoundingClientRect().width / (factor > 0 ? factor : 1));
         label.style.width = previous;
       }
       // Guard: only publish when real text metrics were observed, so a

package/src/components/HkBoard.scale.test.ts

@@ -0,0 +1,136 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick } from "vue";
+
+import HkBoard from "./HkBoard";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+const restores: Array<() => void> = [];
+
+afterEach(() => {
+  for (const restore of restores.splice(0)) restore();
+  for (const m of mounts.splice(0)) {
+    m.app.unmount();
+    m.container.remove();
+  }
+});
+
+/** The board's camera lives in the board's OWN pixels: the world transform is
+ *  written in them. */
+function worldTransform(container: HTMLElement): { x: number; y: number; k: number } {
+  const world = container.querySelector<HTMLElement>(".hk-board-world")!;
+  const m = /translate\((-?[\d.]+)px,\s*(-?[\d.]+)px\)\s*scale\(([\d.]+)\)/.exec(
+    world.style.transform,
+  );
+  if (!m) throw new Error(`unexpected world transform: ${world.style.transform}`);
+  return { x: parseFloat(m[1]), y: parseFloat(m[2]), k: parseFloat(m[3]) };
+}
+
+function pointer(type: string, id: number, x: number, y: number): PointerEvent {
+  return new PointerEvent(type, { bubbles: true, pointerId: id, pointerType: "touch", clientX: x, clientY: y });
+}
+
+async function mountBoard() {
+  // The board reads its viewport size at mount (clientWidth/Height, i.e. the
+  // layout box): pin it on the prototype for the duration so the camera's
+  // clamp has a real viewport to work with, the way a laid-out page would.
+  const proto = HTMLElement.prototype as unknown as {
+    clientWidth: number;
+    clientHeight: number;
+  };
+  const beforeW = Object.getOwnPropertyDescriptor(proto, "clientWidth");
+  const beforeH = Object.getOwnPropertyDescriptor(proto, "clientHeight");
+  Object.defineProperty(proto, "clientWidth", {
+    configurable: true,
+    get(this: HTMLElement) {
+      return this.classList?.contains("hk-board") ? 800 : 0;
+    },
+  });
+  Object.defineProperty(proto, "clientHeight", {
+    configurable: true,
+    get(this: HTMLElement) {
+      return this.classList?.contains("hk-board") ? 600 : 0;
+    },
+  });
+  restores.push(() => {
+    if (beforeW) Object.defineProperty(proto, "clientWidth", beforeW);
+    else delete (proto as { clientWidth?: number }).clientWidth;
+    if (beforeH) Object.defineProperty(proto, "clientHeight", beforeH);
+    else delete (proto as { clientHeight?: number }).clientHeight;
+  });
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp(
+    defineComponent({
+      setup: () => () =>
+        h(HkBoard, {
+          // Content far larger than the viewport, so the camera's clamp lets
+          // it pan instead of re-centring a board that already fits.
+          nodes: [
+            { id: "a", x: 0, y: 0, w: 200, h: 120, label: "A" },
+            { id: "b", x: 3000, y: 3000, w: 200, h: 120, label: "B" },
+          ],
+          fitOnMount: false,
+          // No tween: the assertions read the camera right after the event.
+          animated: false,
+          grid: false,
+          minimap: false,
+        }),
+    }),
+  );
+  app.mount(container);
+  mounts.push({ app, container });
+  await nextTick();
+  const viewport = container.querySelector<HTMLElement>(".hk-board")!;
+  // The board is drawn twice the size it is laid out at, and its own box
+  // reports the layout size — the shape a scaled or zoomed root produces.
+  Object.defineProperty(viewport, "getBoundingClientRect", {
+    configurable: true,
+    value: () => ({ left: 0, top: 0, right: 1600, bottom: 1200, width: 1600, height: 1200, x: 0, y: 0 }) as DOMRect,
+  });
+  Object.defineProperty(viewport, "offsetWidth", { configurable: true, get: () => 800 });
+  Object.defineProperty(viewport, "offsetHeight", { configurable: true, get: () => 600 });
+  Object.defineProperty(viewport, "clientWidth", { configurable: true, get: () => 800 });
+  Object.defineProperty(viewport, "clientHeight", { configurable: true, get: () => 600 });
+  // happy-dom has no pointer capture: the board captures every finger, and a
+  // throw there would end the gesture before it starts.
+  Object.defineProperty(viewport, "setPointerCapture", { configurable: true, value: () => {} });
+  Object.defineProperty(viewport, "releasePointerCapture", { configurable: true, value: () => {} });
+  Object.defineProperty(viewport, "hasPointerCapture", { configurable: true, value: () => true });
+  return { container, viewport };
+}
+
+describe("HkBoard scaled-space gestures", () => {
+  it("pans by the finger's own distance inside a scaled root", async () => {
+    const { container, viewport } = await mountBoard();
+    const before = worldTransform(container);
+
+    viewport.dispatchEvent(pointer("pointerdown", 1, 1600, 1600));
+    viewport.dispatchEvent(pointer("pointermove", 1, 1520, 1540));
+    await nextTick();
+
+    const after = worldTransform(container);
+    expect(after.x, "-80 drawn px are -40 of the board's own").toBeCloseTo(before.x - 40, 4);
+    expect(after.y, "-60 drawn px are -30 of the board's own").toBeCloseTo(before.y - 30, 4);
+    viewport.dispatchEvent(pointer("pointerup", 1, 1520, 1540));
+  });
+
+  it("keeps a zoom anchored under the pointer inside a scaled root", async () => {
+    const { container, viewport } = await mountBoard();
+    const wheel = new WheelEvent("wheel", { bubbles: true, cancelable: true, deltaY: -1 });
+    Object.defineProperty(wheel, "clientX", { value: 800 });
+    Object.defineProperty(wheel, "clientY", { value: 600 });
+    // The pointer sits at the board's own (400, 300) — half the layout box.
+    const anchor = { x: 400, y: 300 };
+    const before = worldTransform(container);
+    const world = {
+      x: (anchor.x - before.x) / before.k,
+      y: (anchor.y - before.y) / before.k,
+    };
+    viewport.dispatchEvent(wheel);
+    await nextTick();
+    const after = worldTransform(container);
+    expect(after.k).toBeGreaterThan(before.k);
+    expect(after.x + world.x * after.k, "the world point stays under the pointer").toBeCloseTo(anchor.x, 3);
+    expect(after.y + world.y * after.k).toBeCloseTo(anchor.y, 3);
+  });
+});

package/src/components/HkBoard.tsx

@@ -59,6 +59,7 @@ import {
   type BoardEdgeStyle,
 } from "../utils/boardEdges";
 import "./HkBoard.scss";
+import { drawnScale } from "../composables/layoutGeometry";
 
 /**
  * A node on the board. `hidden` nodes are junction-only (invisible).
@@ -211,9 +212,23 @@ export default defineComponent({
     // — SCADA scenes, mind maps — still get `nodeClick` on a short tap.
     let pressed: { id: string; pointerId: number; x: number; y: number } | null = null;
 
+    /** How many of the board's own pixels one DRAWN pixel is worth: the
+     *  camera and every anchor live in the board's local CSS pixels while the
+     *  pointer arrives in drawn ones, and a scaled or zoomed root separates
+     *  the two (see `layoutGeometry`). */
+    const pxScale = (): number => {
+      const el = viewportRef.value;
+      if (!el) return 1;
+      const scale = drawnScale(el);
+      const factor = el.offsetWidth > 0 ? scale.x : el.offsetHeight > 0 ? scale.y : 1;
+      return factor > 0 ? factor : 1;
+    };
+
     const localPoint = (e: PointerEvent | WheelEvent): BoardPoint => {
-      const rect = viewportRef.value?.getBoundingClientRect();
-      return { x: e.clientX - (rect?.left ?? 0), y: e.clientY - (rect?.top ?? 0) };
+      const el = viewportRef.value;
+      const rect = el?.getBoundingClientRect();
+      const k = pxScale();
+      return { x: (e.clientX - (rect?.left ?? 0)) / k, y: (e.clientY - (rect?.top ?? 0)) / k };
     };
 
     function onWheel(e: WheelEvent): void {
@@ -237,14 +252,10 @@ export default defineComponent({
     function rearmPinch(): void {
       const [a, b] = [...pointers.values()];
       if (!a || !b) return;
-      const rect = viewportRef.value?.getBoundingClientRect();
       pinchBase = {
         cam: { ...camera.value },
         dist: Math.hypot(a.x - b.x, a.y - b.y) || 1,
-        mid: {
-          x: (a.x + b.x) / 2 - (rect?.left ?? 0),
-          y: (a.y + b.y) / 2 - (rect?.top ?? 0),
-        },
+        mid: localPoint({ clientX: (a.x + b.x) / 2, clientY: (a.y + b.y) / 2 } as PointerEvent),
       };
     }
 
@@ -273,17 +284,18 @@ export default defineComponent({
       if (pinchBase && pointers.size >= 2) {
         const [a, b] = [...pointers.values()];
         const dist = Math.hypot(a.x - b.x, a.y - b.y) || 1;
-        const rect = viewportRef.value?.getBoundingClientRect();
-        const mid = {
-          x: (a.x + b.x) / 2 - (rect?.left ?? 0),
-          y: (a.y + b.y) / 2 - (rect?.top ?? 0),
-        };
+        const mid = localPoint({
+          clientX: (a.x + b.x) / 2,
+          clientY: (a.y + b.y) / 2,
+        } as PointerEvent);
         pinchBase.mid = mid;
         cam.pinchZoom(pinchBase.cam, dist / pinchBase.dist, mid);
         return;
       }
       if (dragState) {
-        const k = camera.value.k || 1;
+        // The node lives in WORLD units: the drawn delta comes down through
+        // the ancestor scale and then through the camera's own zoom.
+        const k = (camera.value.k || 1) * pxScale();
         const dx = (e.clientX - dragState.sx) / k;
         const dy = (e.clientY - dragState.sy) / k;
         if (Math.abs(e.clientX - dragState.sx) + Math.abs(e.clientY - dragState.sy) > 3) dragState.moved = true;
@@ -293,7 +305,8 @@ export default defineComponent({
         return;
       }
       if (panState) {
-        cam.panBy(e.clientX - panState.px, e.clientY - panState.py);
+        const k = pxScale();
+        cam.panBy((e.clientX - panState.px) / k, (e.clientY - panState.py) / k);
         panState = { px: e.clientX, py: e.clientY };
       }
     }

package/src/components/HkImageViewer.tsx

@@ -2,6 +2,7 @@ import { computed, defineComponent, onBeforeUnmount, onMounted, ref, watch } fro
 
 import HSpinner from "./HkSpinner";
 import HMinimap from "./HkMinimap";
+import { drawnScale } from "../composables/layoutGeometry";
 import "./HkImageViewer.scss";
 
 /**
@@ -57,6 +58,29 @@ export default defineComponent({
       return c ? { cw: c.clientWidth, ch: c.clientHeight } : { cw: 0, ch: 0 };
     }
 
+    /** How many of the container's own pixels one DRAWN pixel is worth.
+     *  The camera (`panX`/`panY`/`zoom`) lives in the container's local CSS
+     *  pixels while the pointer arrives in drawn ones, and a scaled or zoomed
+     *  root makes the two differ — feeding a drawn delta straight into the
+     *  camera moves the image `k` times as far as the finger went. */
+    function pxScale() {
+      const el = containerRef.value;
+      if (!el) return 1;
+      const scale = drawnScale(el);
+      const factor = el.offsetWidth > 0 ? scale.x : el.offsetHeight > 0 ? scale.y : 1;
+      return factor > 0 ? factor : 1;
+    }
+
+    /** A pointer position inside the container, in the container's own
+     *  pixels (the space every anchor and the camera are written in). */
+    function localPoint(e: { clientX: number; clientY: number }) {
+      const el = containerRef.value;
+      if (!el) return { x: 0, y: 0 };
+      const rect = el.getBoundingClientRect();
+      const factor = pxScale();
+      return { x: (e.clientX - rect.left) / factor, y: (e.clientY - rect.top) / factor };
+    }
+
     function recomputeFit() {
       const { cw, ch } = dims();
       if (!imgW.value || !imgH.value || !cw || !ch) return;
@@ -115,11 +139,9 @@ export default defineComponent({
       e.preventDefault();
       const el = containerRef.value;
       if (!el) return;
-      const rect = el.getBoundingClientRect();
-      const cx = e.clientX - rect.left;
-      const cy = e.clientY - rect.top;
+      const at = localPoint(e);
       const factor = e.deltaY < 0 ? 1.15 : 1 / 1.15;
-      setZoom(zoom.value * factor, cx, cy);
+      setZoom(zoom.value * factor, at.x, at.y);
     }
 
     /** Euclidean distance between two pointer positions. */
@@ -172,19 +194,19 @@ export default defineComponent({
         if (!pair || !el) return;
         // Anchor the zoom at the fingers' midpoint (container-local
         // coordinates, same space as the wheel/dblclick anchors).
-        const rect = el.getBoundingClientRect();
         const dist = Math.max(pointerDist(pair[0], pair[1]), 1);
-        setZoom(
-          pinchStartZoom * (dist / pinchStartDist),
-          (pair[0].x + pair[1].x) / 2 - rect.left,
-          (pair[0].y + pair[1].y) / 2 - rect.top,
-        );
+        const mid = localPoint({
+          clientX: (pair[0].x + pair[1].x) / 2,
+          clientY: (pair[0].y + pair[1].y) / 2,
+        });
+        setZoom(pinchStartZoom * (dist / pinchStartDist), mid.x, mid.y);
         return;
       }
 
       if (!dragging.value) return;
-      const dx = e.clientX - lastPt.value.x;
-      const dy = e.clientY - lastPt.value.y;
+      const factor = pxScale();
+      const dx = (e.clientX - lastPt.value.x) / factor;
+      const dy = (e.clientY - lastPt.value.y) / factor;
       lastPt.value = { x: e.clientX, y: e.clientY };
       panX.value += dx;
       panY.value += dy;
@@ -235,12 +257,11 @@ export default defineComponent({
       if (!loaded.value) return;
       const el = containerRef.value;
       if (!el) return;
-      const rect = el.getBoundingClientRect();
-      const cx = e.clientX - rect.left;
-      const cy = e.clientY - rect.top;
-      setZoom(isZoomed.value ? fit.value : Math.min(MAX_ZOOM, fit.value * 3), cx, cy);
+      const at = localPoint(e);
+      setZoom(isZoomed.value ? fit.value : Math.min(MAX_ZOOM, fit.value * 3), at.x, at.y);
     }
 
+    /** Panned by another surface (the minimap), in this camera's own units. */
     function onPanDelta(dx: number, dy: number) {
       panX.value += dx;
       panY.value += dy;

package/src/components/HkImageViewerTouch.test.tsx

@@ -100,6 +100,63 @@ describe("HkImageViewer touch gestures", () => {
     expect(after.scale).toBe(before.scale);
   });
 
+  it("pans by the finger's own distance inside a scaled root", async () => {
+    // The camera lives in the container's local pixels while the pointer
+    // arrives in drawn ones. Inside a scaled or zoomed root (chest's display
+    // scale reaches 300%) the image would otherwise travel k times as far as
+    // the finger — it slips out from under the pointer.
+    const s = await mountViewer();
+    const c = s.container();
+    // The container is drawn twice the size it is laid out at.
+    Object.defineProperty(c, "getBoundingClientRect", {
+      configurable: true,
+      value: () => ({ left: 0, top: 0, right: 800, bottom: 600, width: 800, height: 600, x: 0, y: 0 }) as DOMRect,
+    });
+    Object.defineProperty(c, "offsetWidth", { configurable: true, get: () => 400 });
+    Object.defineProperty(c, "offsetHeight", { configurable: true, get: () => 300 });
+
+    const before = s.transform();
+    c.dispatchEvent(pointer("pointerdown", 1, 100, 100));
+    c.dispatchEvent(pointer("pointermove", 1, 140, 160));
+    await nextTick();
+
+    const after = s.transform();
+    expect(after.tx, "40 drawn px are 20 of the container's own").toBeCloseTo(before.tx + 20, 5);
+    expect(after.ty, "60 drawn px are 30 of the container's own").toBeCloseTo(before.ty + 30, 5);
+  });
+
+  it("anchors a wheel zoom where the pointer is, inside a scaled root", async () => {
+    const s = await mountViewer();
+    const c = s.container();
+    Object.defineProperty(c, "getBoundingClientRect", {
+      configurable: true,
+      value: () => ({ left: 0, top: 0, right: 800, bottom: 600, width: 800, height: 600, x: 0, y: 0 }) as DOMRect,
+    });
+    Object.defineProperty(c, "offsetWidth", { configurable: true, get: () => 400 });
+    Object.defineProperty(c, "offsetHeight", { configurable: true, get: () => 300 });
+
+    // The point under the pointer must stay under it: the container-local
+    // coordinate of the pointer is (200, 150) — half of the layout box — and
+    // the anchor has to be that, not the drawn (400, 300).
+    const anchor = { x: 200, y: 150 };
+    const before = s.transform();
+    const worldBefore = {
+      x: (anchor.x - before.tx) / before.scale,
+      y: (anchor.y - before.ty) / before.scale,
+    };
+    // happy-dom's WheelEvent carries no pointer coordinates: pin them by hand
+    // so the anchor has a position to work from.
+    const wheel = new WheelEvent("wheel", { bubbles: true, cancelable: true, deltaY: -1 });
+    Object.defineProperty(wheel, "clientX", { value: 400 });
+    Object.defineProperty(wheel, "clientY", { value: 300 });
+    c.dispatchEvent(wheel);
+    await nextTick();
+    const after = s.transform();
+    expect(after.scale).toBeGreaterThan(before.scale);
+    expect(after.tx + worldBefore.x * after.scale, "the world point stays under the pointer").toBeCloseTo(anchor.x, 4);
+    expect(after.ty + worldBefore.y * after.scale).toBeCloseTo(anchor.y, 4);
+  });
+
   it("a stray move without an active pointer never pans", async () => {
     const s = await mountViewer();
     const c = s.container();

package/src/components/HkMinimap.scale.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h } from "vue";
+
+import HkMinimap from "./HkMinimap";
+
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+afterEach(() => {
+  for (const app of mounts.splice(0)) app.unmount();
+  for (const el of containers.splice(0)) el.remove();
+});
+
+/** Mount the overview map and drag it: the emitted pan says how far the scene
+ *  should move for a pointer that travelled `drawn` pixels. */
+function drag(drawnWidth: number): { dx: number; dy: number } {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+  const deltas: Array<[number, number]> = [];
+  const Host = defineComponent({
+    setup() {
+      return () =>
+        h(HkMinimap, {
+          zoom: 1,
+          zoomPercent: 100,
+          panX: 0,
+          panY: 0,
+          viewportWidth: 400,
+          viewportHeight: 300,
+          boxes: [{ id: "a", bounds: { x: 0, y: 0, w: 100, h: 100 }, color: "red" }],
+          onPanDelta: (dx: number, dy: number) => deltas.push([dx, dy]),
+        });
+    },
+  });
+  const app = createApp(Host);
+  mounts.push(app);
+  app.mount(container);
+
+  const root = container.querySelector<HTMLElement>(".hk-minimap")!;
+  const svg = root.querySelector<SVGSVGElement>("svg.hk-minimap-svg")!;
+  // The map's viewBox is 160 units wide; the card draws it at `drawnWidth`.
+  Object.defineProperty(svg, "getBoundingClientRect", {
+    configurable: true,
+    value: () =>
+      ({ left: 0, top: 0, right: drawnWidth, bottom: drawnWidth * (110 / 160), width: drawnWidth, height: drawnWidth * (110 / 160), x: 0, y: 0 }) as DOMRect,
+  });
+  Object.defineProperty(root, "setPointerCapture", { configurable: true, value: () => {} });
+  Object.defineProperty(root, "releasePointerCapture", { configurable: true, value: () => {} });
+
+  const at = (type: string, x: number, y: number) =>
+    root.dispatchEvent(
+      new PointerEvent(type, { bubbles: true, pointerId: 1, pointerType: "mouse", clientX: x, clientY: y }),
+    );
+  at("pointerdown", 100, 100);
+  at("pointermove", 140, 120);
+  at("pointerup", 140, 120);
+  expect(deltas, "the drag emitted a pan").toHaveLength(1);
+  return { dx: deltas[0][0], dy: deltas[0][1] };
+}
+
+describe("HkMinimap scaled-space pan", () => {
+  it("scales the pan by the map's own drawn size", () => {
+    // The map is drawn into a card that is not necessarily as wide as the
+    // SVG's viewBox — and, in a scaled or zoomed root, is drawn wider still.
+    // The pointer's drawn pixels have to come down through that factor, or a
+    // drag moves the scene further than the pointer went (and at k = 3 the
+    // scene runs away from the cursor entirely).
+    const normal = drag(160); // 1 drawn px = 1 user unit
+    const wide = drag(320); // 1 drawn px = half a unit
+    expect(Math.abs(wide.dx), "half the travel for the same pointer").toBeCloseTo(
+      Math.abs(normal.dx) / 2,
+      6,
+    );
+    expect(Math.abs(wide.dy)).toBeCloseTo(Math.abs(normal.dy) / 2, 6);
+    expect(normal.dx, "the scene follows the pointer the other way").toBeLessThan(0);
+  });
+});

package/src/components/HkMinimap.tsx

@@ -5,6 +5,7 @@ import { computed, defineComponent, onBeforeUnmount, onMounted, ref, type PropTy
 
 
 import { useI18n } from "../i18n/context";
+import { layoutOffset } from "../composables/layoutGeometry";
 import "./HkMinimap.scss";
 
 export interface MinimapBox {
@@ -158,7 +159,21 @@ export default defineComponent({
       const dy = e.clientY - dragStart.value.y;
       dragStart.value = { x: e.clientX, y: e.clientY };
       if (scale.value > 0) {
-        emit("panDelta", (-dx / scale.value) * props.zoom, (-dy / scale.value) * props.zoom);
+        // The pointer moves in DRAWN pixels while the map is drawn into a
+        // card that is not necessarily as wide as the SVG's viewBox (and, in
+        // a scaled or zoomed root, is drawn wider still). One drawn pixel is
+        // `viewBox / rect.width` user units, so the delta is converted before
+        // it is turned into a pan.
+        const host = rootRef.value;
+        const svg =
+          host instanceof SVGElement ? host : host?.querySelector("svg") ?? host ?? null;
+        const rect = svg?.getBoundingClientRect();
+        const units = rect && rect.width > 0 ? svgW / rect.width : 1;
+        emit(
+          "panDelta",
+          (-dx * units / scale.value) * props.zoom,
+          (-dy * units / scale.value) * props.zoom,
+        );
       }
     }
     function onUp(e: PointerEvent) {

package/src/components/HkPasswordInput.test.ts

@@ -278,4 +278,52 @@ describe("HkPasswordInput placeholder layers on Tab focus", () => {
     expect(staticText).toBeTruthy();
     expect(marqueeText).toBe(staticText);
   });
+
+/** happy-dom's own ResizeObserver never fires (no layout engine): this one
+ *  keeps the callbacks so a test can run the measurement deterministically. */
+class FakeResizeObserver {
+  static instances: FakeResizeObserver[] = [];
+  callback: () => void;
+  constructor(callback: () => void) {
+    this.callback = callback;
+    FakeResizeObserver.instances.push(this);
+  }
+  observe(): void {}
+  disconnect(): void {}
+}
+
+describe("HkPasswordInput strength dots in a scaled root", () => {
+  it("sizes the dot canvas in the box's own units", () => {
+    const original = globalThis.ResizeObserver;
+    FakeResizeObserver.instances = [];
+    globalThis.ResizeObserver = FakeResizeObserver as unknown as typeof ResizeObserver;
+    try {
+    // The canvas is CSS-sized to its box (`inset: 0`) while its backing store
+    // is drawn from the box's DRAWN size: in a scaled or zoomed root the grid
+    // came out k times denser and every dot k times smaller.
+    const m = mountPasswordInput("hunter2", { showStrengthDots: true });
+    const box = m.container.querySelector<HTMLElement>(".hk-pwd-box")!;
+    const canvas = m.container.querySelector<HTMLCanvasElement>(".hk-pwd-dots")!;
+    expect(box && canvas).toBeTruthy();
+    // The box is drawn twice the size it is laid out at.
+    Object.defineProperty(box, "getBoundingClientRect", {
+      configurable: true,
+      value: () => ({ left: 0, top: 0, right: 800, bottom: 200, width: 800, height: 200, x: 0, y: 0 }) as DOMRect,
+    });
+    Object.defineProperty(box, "offsetWidth", { configurable: true, get: () => 400 });
+    Object.defineProperty(box, "offsetHeight", { configurable: true, get: () => 100 });
+    const dpr = window.devicePixelRatio || 1;
+    // Re-run the measurement the box's observer would run.
+    const observers = FakeResizeObserver.instances.filter((o) => o.callback);
+    expect(observers.length, "the box is observed").toBeGreaterThan(0);
+    observers.forEach((o) => o.callback());
+    expect(canvas.width, "400 of the box's own pixels, not the drawn 800").toBe(
+      Math.round(400 * dpr),
+    );
+    } finally {
+      globalThis.ResizeObserver = original;
+    }
+  });
+});
+
 });

package/src/components/HkPasswordInput.tsx

@@ -17,6 +17,7 @@ import { scheduleInterval, type IntervalHandle } from "../runtime/intervalBus";
 import HListTransition from "./HkListTransition";
 import { HkPlaceholderMarquee, type PlaceholderVariant } from "./HkPlaceholderMarquee";
 import "./HkPasswordInput.scss";
+import { drawnScale } from "../composables/layoutGeometry";
 
 interface Ripple {
   radius: number;
@@ -232,7 +233,14 @@ export default defineComponent({
       const cv = dotCanvasRef.value;
       const bx = boxRef.value;
       if (!cv || !bx) return;
-      const { width, height } = bx.getBoundingClientRect();
+      // The canvas box is sized in the element's own units (`inset: 0`), so
+      // its backing store has to be too: taking the DRAWN box would make the
+      // dot grid k times denser inside a scaled or zoomed root (see
+      // `layoutGeometry`).
+      const drawn = bx.getBoundingClientRect();
+      const scale = drawnScale(bx);
+      const width = bx.offsetWidth > 0 ? drawn.width / (scale.x > 0 ? scale.x : 1) : drawn.width;
+      const height = bx.offsetHeight > 0 ? drawn.height / (scale.y > 0 ? scale.y : 1) : drawn.height;
       cv.width = width * dpr;
       cv.height = height * dpr;
       const usable = width * 0.8;

package/src/components/HkScrollContainer.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { createApp, defineComponent, h, nextTick, reactive, ref } from "vue";
 
 import HkScrollContainer from "./HkScrollContainer";
@@ -16,6 +16,7 @@ interface Mounted {
   } | null;
 }
 
+const scrolled: number[] = [];
 const mounts: Mounted["app"][] = [];
 const containers: HTMLElement[] = [];
 
@@ -63,6 +64,52 @@ afterEach(() => {
 });
 
 describe("HkScrollContainer alignment", () => {
+  it("scrolls to an element by its laid-out distance, inside a scaled root", () => {
+    // The target is compared against `scrollTop`, a layout number: measured
+    // from drawn boxes it overshoots by (scale - 1) of the element's distance
+    // from the visible top, and in a zoomed root that walks the element right
+    // out of view.
+    const m = mountScroller();
+    stubGeometry(m.viewport, {
+      scrollHeight: 2000, clientHeight: 400, scrollTop: 100,
+      scrollWidth: 300, clientWidth: 300, scrollLeft: 0,
+    });
+    Object.defineProperty(m.viewport, "scrollTo", {
+      configurable: true,
+      value: (opts: { top: number }) => {
+        scrolled.push(opts.top);
+      },
+    });
+    // The viewport is drawn twice the size it is laid out at.
+    const drawn = vi.spyOn(m.viewport, "getBoundingClientRect").mockReturnValue({
+      left: 0, top: 0, right: 800, bottom: 800, width: 800, height: 800, x: 0, y: 0,
+    } as DOMRect);
+    Object.defineProperty(m.viewport, "offsetWidth", { configurable: true, get: () => 400 });
+    Object.defineProperty(m.viewport, "offsetHeight", { configurable: true, get: () => 400 });
+    void drawn;
+
+    // The element sits 150 of the viewport's own pixels below its top edge...
+    const target = document.createElement("div");
+    m.viewport.appendChild(target);
+    Object.defineProperty(target, "offsetParent", { configurable: true, get: () => m.viewport });
+    Object.defineProperty(target, "offsetLeft", { configurable: true, get: () => 0 });
+    Object.defineProperty(target, "offsetTop", { configurable: true, get: () => 150 });
+    vi.spyOn(target, "getBoundingClientRect").mockReturnValue({
+      left: 0, top: 600, right: 100, bottom: 700, width: 100, height: 100, x: 0, y: 600,
+    } as DOMRect);
+    // ...while the VIEWPORT itself sits 310 of its own pixels down the page,
+    // which the scroll target must not carry: an offset sum walked all the way
+    // to the root would ask to scroll 460 and land the element past the top.
+    const above = document.createElement("div");
+    above.appendChild(m.viewport);
+    Object.defineProperty(m.viewport, "offsetParent", { configurable: true, get: () => above });
+    Object.defineProperty(m.viewport, "offsetTop", { configurable: true, get: () => 310 });
+    Object.defineProperty(above, "offsetParent", { configurable: true, get: () => null });
+    Object.defineProperty(above, "offsetTop", { configurable: true, get: () => 0 });
+
+    (m.instance as unknown as { scrollToElement: (el: HTMLElement) => void }).scrollToElement(target);
+    expect(scrolled.at(-1), "150 of the viewport's own pixels, not the drawn 300 nor the page offset 460").toBe(150);
+  });
   it("renders the slot bare without an align prop", () => {
     const m = mountScroller();
     expect(m.root.hasAttribute("data-align")).toBe(false);

package/src/components/HkScrollContainer.tsx

@@ -10,6 +10,7 @@ import {
 } from "vue";
 
 import { useI18n } from "../i18n/context";
+import { laidOffsetWithin } from "../composables/layoutGeometry";
 import "./HkScrollContainer.scss";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
 import { useApproachEnd, type ApproachEndHandle } from "../composables/useApproachEnd";
@@ -357,7 +358,17 @@ export default defineComponent({
         el.scrollIntoView({ behavior, block: "start" });
         return;
       }
-      const target = el.getBoundingClientRect().top - vp.getBoundingClientRect().top + vp.scrollTop;
+      // Both ends in the LAYOUT space the scroll offset lives in: the drawn
+      // boxes would carry the scale of whatever root this sits in, and the
+      // target would overshoot by (scale - 1) of the element's distance from
+      // the visible top. The offset is measured INSIDE the viewport — a raw
+      // `layoutOffset` sum runs on to the document root, which lands the scroll
+      // past the element by however far the viewport itself sits down the page
+      // (see `laidOffsetWithin`).
+      const inside = laidOffsetWithin(el, vp);
+      const target = Number.isFinite(inside.y)
+        ? inside.y
+        : el.getBoundingClientRect().top - vp.getBoundingClientRect().top + vp.scrollTop;
       vp.scrollTo({ top: target, behavior });
     }
 

package/src/components/HkWindowedItem.scale.test.ts

@@ -0,0 +1,107 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkWindowedItem from "./HkWindowedItem";
+import { provideScrollWindow } from "../composables/useScrollWindow";
+
+const SCREEN = 400; // laid-out size of the scroll root, in its own units
+const ITEM = 40;
+
+const apps: ReturnType<typeof createApp>[] = [];
+let originalRect: typeof HTMLElement.prototype.getBoundingClientRect;
+/** Drawn (client) geometry of the windowed item, in drawn pixels. */
+let itemDrawn = { top: 0, height: ITEM };
+
+function rectOf(left: number, top: number, width: number, height: number): DOMRect {
+  return {
+    x: left,
+    y: top,
+    left,
+    top,
+    right: left + width,
+    bottom: top + height,
+    width,
+    height,
+    toJSON: () => ({}),
+  } as DOMRect;
+}
+
+beforeEach(() => {
+  originalRect = HTMLElement.prototype.getBoundingClientRect;
+  // The component's own root is created inside the mount, so its drawn box is
+  // scripted per element class rather than per instance.
+  HTMLElement.prototype.getBoundingClientRect = function (this: HTMLElement) {
+    if (this.classList?.contains("hk-windowed-item")) {
+      return rectOf(0, itemDrawn.top, 200, itemDrawn.height);
+    }
+    return originalRect.call(this);
+  };
+  (globalThis as { IntersectionObserver?: unknown }).IntersectionObserver = class {
+    observe(): void {}
+    disconnect(): void {}
+  } as unknown as typeof IntersectionObserver;
+});
+
+afterEach(() => {
+  HTMLElement.prototype.getBoundingClientRect = originalRect;
+  for (const app of apps.splice(0)) app.unmount();
+  document.body.innerHTML = "";
+  delete (globalThis as { IntersectionObserver?: unknown }).IntersectionObserver;
+});
+
+/**
+ * Mount one windowed item against a scroll root whose drawn box is `scale`
+ * times its laid-out box (zoom on `documentElement`, a transformed ancestor, or
+ * a scoped `zoom` all produce this), with the item laid out `laidTop` units
+ * below the root's top. Returns whether the item mounted real content or the
+ * placeholder.
+ */
+async function dataState(laidTop: number, scale: number): Promise<string | null> {
+  const rootEl = document.createElement("div");
+  document.body.appendChild(rootEl);
+  Object.defineProperty(rootEl, "offsetWidth", { configurable: true, value: SCREEN });
+  Object.defineProperty(rootEl, "offsetHeight", { configurable: true, value: SCREEN });
+  Object.defineProperty(rootEl, "clientHeight", { configurable: true, value: SCREEN });
+  Object.defineProperty(rootEl, "getBoundingClientRect", {
+    configurable: true,
+    value: () => rectOf(0, 0, SCREEN * scale, SCREEN * scale),
+  });
+  itemDrawn = { top: laidTop * scale, height: ITEM * scale };
+
+  const scrollRoot = ref<HTMLElement | null>(rootEl);
+  const Host = defineComponent({
+    setup() {
+      provideScrollWindow(scrollRoot, 1);
+      return () => h(HkWindowedItem, { estimatedHeight: ITEM }, { default: () => h("span", { class: "real" }) });
+    },
+  });
+  const app = createApp(Host);
+  apps.push(app);
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  app.mount(container);
+  await nextTick();
+  const item = container.querySelector<HTMLElement>(".hk-windowed-item");
+  return item?.getAttribute("data-state") ?? null;
+}
+
+describe("HkWindowedItem scaled-space buffer", () => {
+  it("keeps an item inside the overscan band that a scaled root draws out of it", async () => {
+    // One laid-out screen of overscan = 400 of the root's own units. An item
+    // 350 units below the root's bottom is inside it - but it is *drawn* 700px
+    // below, so a buffer compared in drawn pixels without the scale reads as an
+    // empty slot and the row unmounts while still on (scaled) screen.
+    expect(await dataState(750, 2)).toBe("real");
+  });
+
+  it("still windows out an item beyond the overscan band when scaled", async () => {
+    // 500 laid-out units below the bottom > one screen of overscan: out either
+    // way, so the fix is not "always render".
+    expect(await dataState(900, 2)).toBe("placeholder");
+  });
+
+  it("is unchanged for an unscaled root", async () => {
+    expect(await dataState(750, 1)).toBe("real");
+    expect(await dataState(900, 1)).toBe("placeholder");
+  });
+});

package/src/components/HkWindowedItem.tsx

@@ -3,6 +3,7 @@ import { defineComponent, onBeforeUnmount, onMounted, ref, shallowRef, watch, ty
 import "./HkWindowedItem.scss";
 import { useScrollWindow } from "../composables/useScrollWindow";
 import { onceFrame } from "../runtime/animationBus";
+import { drawnScale } from "../composables/layoutGeometry";
 
 export default defineComponent({
   name: "HkWindowedItem",
@@ -24,9 +25,16 @@ export default defineComponent({
     }
 
     function withinBuffer(el: HTMLElement, scrollEl: HTMLElement, overscan: number): boolean {
+      // Both boxes and the buffer in the scroll root's own units: the rects
+      // are drawn (a scaled or zoomed root makes them k times bigger) while
+      // `clientHeight` is laid out, which shrank the effective overscan to
+      // overscan/k (see `layoutGeometry`).
+      const scale = drawnScale(scrollEl);
+      const factor = scrollEl.offsetHeight > 0 ? scale.y : scrollEl.offsetWidth > 0 ? scale.x : 1;
+      const k = factor > 0 ? factor : 1;
       const elRect = el.getBoundingClientRect();
       const rootRect = scrollEl.getBoundingClientRect();
-      const buf = scrollEl.clientHeight * overscan;
+      const buf = scrollEl.clientHeight * overscan * k;
       return elRect.bottom >= rootRect.top - buf && elRect.top <= rootRect.bottom + buf;
     }
 

package/src/composables/layoutGeometry.test.ts

@@ -4,6 +4,7 @@ import {
   drawnScale,
   frameMetrics,
   frameScale,
+  laidOffsetWithin,
   laidSize,
   layoutOffset,
   layoutRect,
@@ -107,6 +108,46 @@ describe("layoutGeometry", () => {
       .toEqual({ x: 140, y: 240 });
   });
 
+  it("measures an offset INSIDE its frame, not from the document root", () => {
+    // The trap this helper exists for: a raw offset sum runs on to the root,
+    // so the frame's own distance down the page is added to the answer. Used
+    // as a scroll target that overshoots by exactly that distance — measured
+    // in Chromium, a frame 310px down the page asked for 810 where 500 was
+    // right, and the drawn-box equivalent is a further zoom factor out.
+    const outer = document.createElement("div");
+    const frame = document.createElement("div");
+    const child = document.createElement("div");
+    frame.appendChild(child);
+    outer.appendChild(frame);
+    document.body.appendChild(outer);
+
+    laid(outer, { left: 0, top: 0, w: 400, h: 600 }, document.body);
+    laid(frame, { left: 10, top: 310, w: 300, h: 400 }, outer);
+    laid(child, { left: 0, top: 500, w: 200, h: 60 }, frame);
+    // The frame is drawn at 2x: the drawn-box answer for the same scroll.
+    drawn(frame, { left: 20, right: 620, top: 620, bottom: 1420 });
+    drawn(child, { left: 20, right: 420, top: 1620, bottom: 1740 });
+
+    expect(layoutOffset(child, frame).y, "the raw sum carries the frame's own 310").toBe(810);
+    expect(laidOffsetWithin(child, frame).y, "inside the frame, in its own units").toBe(500);
+    expect(laidOffsetWithin(child, frame).through).toBe(true);
+    // Same number however the frame is drawn: layout units are scale-free.
+    drawn(frame, { left: 30, right: 930, top: 930, bottom: 2130 });
+    expect(laidOffsetWithin(child, frame).y).toBe(500);
+  });
+
+  it("refuses an offset inside something that is not an ancestor", () => {
+    const frame = document.createElement("div");
+    const stranger = document.createElement("div");
+    document.body.appendChild(frame);
+    document.body.appendChild(stranger);
+    laid(frame, { left: 0, top: 0, w: 200, h: 200 }, document.body);
+    laid(stranger, { left: 0, top: 40, w: 100, h: 40 }, document.body);
+    laid(frame, { left: 0, top: 0, w: 200, h: 200 }, document.body);
+
+    expect(Number.isFinite(laidOffsetWithin(stranger, frame).y)).toBe(false);
+  });
+
   it("scales what it places by the scale the frame is drawn at", () => {
     const frame = document.createElement("div");
     const child = document.createElement("div");

package/src/composables/layoutGeometry.ts

@@ -97,6 +97,33 @@ export function layoutOffset(el: HTMLElement, frame?: HTMLElement | null): Layou
   return { x, y, through };
 }
 
+/** Where `el` sits inside `frame`'s content, in the frame's own layout units —
+ *  the number a scroll offset has to be set to in order to bring the element's
+ *  top/left edge to the frame's visible top/left (its padding edge).
+ *
+ *  `layoutOffset` sums a chain all the way to the document root, so using its
+ *  result directly as a scroll target is off by the frame's own distance from
+ *  that root: measured in Chromium, a frame sitting 310px down the page asked
+ *  for 810 where the correct scroll offset was 500. Subtracting the frame's own
+ *  sum cancels every offset convention along the way (see the file comment) and
+ *  the result is scale-free, so it is the same number at zoom 1 and zoom 3
+ *  while the drawn-box equivalent (`rect.top - frameRect.top + frame.scrollTop`)
+ *  is `k` times too large at zoom `k`.
+ *
+ *  `y` (and `x`) are `NaN` when the chain cannot be added up or when `frame` is
+ *  not an ancestor of `el` — the difference is meaningless then, and callers
+ *  check `Number.isFinite` before scrolling with it. */
+export function laidOffsetWithin(el: HTMLElement, frame: HTMLElement): LayoutOffset {
+  const at = layoutOffset(el, frame);
+  const of = layoutOffset(frame, null);
+  const through = at.through;
+  if (!Number.isFinite(at.x) || !Number.isFinite(at.y) || !Number.isFinite(of.x) || !Number.isFinite(of.y)) {
+    return { x: NaN, y: NaN, through };
+  }
+  if (el !== frame && !frame.contains(el)) return { x: NaN, y: NaN, through };
+  return { x: at.x - of.x, y: at.y - of.y, through };
+}
+
 /** An element's laid-out BORDER box, as finely as the engine will report it.
  *  `offsetWidth`/`offsetHeight` are integers — they round, and half a pixel is
  *  a third of the line filter's entire tolerance — while the computed

package/src/composables/useOverlayScrollbar.test.ts

@@ -156,6 +156,39 @@ describe("attachOverlayScrollbars", () => {
     document.dispatchEvent(new MouseEvent("mouseup"));
   });
 
+  it("rests the horizontal thumb at the track's right end in a right-to-left scroller", () => {
+    // An RTL scroller starts with `scrollLeft` at 0 — the content's right end
+    // — and counts down from there, so the thumb belongs at the right of the
+    // track and travels left. Rendering it at translateX(0) parked it at the
+    // wrong end of its own track.
+    const { viewport, wrapper, handle } = mountViewport("horizontal");
+    const track = wrapper.querySelector<HTMLElement>('.hk-scrollbar-track[data-axis="horizontal"]')!;
+    const thumb = track.querySelector<HTMLElement>(".hk-scrollbar-thumb")!;
+    // A 100px track with a 100-of-400 client box: thumb 25px, 75px of travel.
+    Object.defineProperty(track, "clientWidth", { configurable: true, get: () => 100 });
+    const at = (scrollLeft: number) => {
+      stubGeometry(viewport, {
+        scrollWidth: 400, clientWidth: 100, scrollLeft,
+        scrollHeight: 100, clientHeight: 100, scrollTop: 0,
+      });
+      handle.update();
+      return thumb.style.transform;
+    };
+    viewport.style.direction = "rtl";
+    // An RTL scroller starts with `scrollLeft` at 0 — the content's right end
+    // — and counts down from there, so the thumb belongs at the right of the
+    // track and travels left. Rendering it at translateX(0) parked it at the
+    // wrong end of its own track.
+    expect(at(0), "at the start, against the right end").toBe("translateX(75px)");
+    expect(at(-150), "half way").toBe("translateX(37.5px)");
+    expect(at(-300), "scrolled to the far end, at the left").toBe("translateX(0px)");
+
+    // …and the left-to-right bar keeps resting at the left.
+    viewport.style.direction = "ltr";
+    expect(at(0)).toBe("translateX(0px)");
+    expect(at(150)).toBe("translateX(37.5px)");
+  });
+
   it("pages when the track (not the thumb) is clicked", () => {
     const { viewport, wrapper, handle } = mountViewport("vertical");
     stubGeometry(viewport, {

package/src/composables/useOverlayScrollbar.ts

@@ -81,6 +81,14 @@ function axisMetrics(viewport: HTMLElement, horizontal: boolean) {
   };
 }
 
+/** Whether the axis runs right-to-left. Only the horizontal one can: a
+ *  vertical bar is RTL-agnostic, and `writing-mode` on the scroller is not
+ *  something this component supports. */
+function isRtlAxis(viewport: HTMLElement, horizontal: boolean): boolean {
+  if (!horizontal) return false;
+  return getComputedStyle(viewport).direction === "rtl";
+}
+
 function makeAxisState(horizontal: boolean): AxisState {
   const track = document.createElement("div");
   track.className = "hk-scrollbar-track";
@@ -161,7 +169,13 @@ export function attachOverlayScrollbars(
     const thumbSize = Math.max(ratio * trackSize, 20);
     const maxScroll = scrollSize - clientSize;
     const maxTrack = trackSize - thumbSize;
-    const offset = maxScroll > 0 ? (scrollPos / maxScroll) * maxTrack : 0;
+    // A right-to-left scroller starts with `scrollLeft` at 0 (showing the
+    // content's right end) and counts DOWN to -maxScroll, so its progress is
+    // the magnitude — and the thumb rests at the track's right end and
+    // travels left, mirrored against the left-to-right bar.
+    const rtl = isRtlAxis(viewport, horizontal);
+    const progress = maxScroll > 0 ? Math.abs(scrollPos) / maxScroll : 0;
+    const offset = (rtl ? 1 - progress : progress) * maxTrack;
     if (horizontal) {
       s.thumb.style.width = `${thumbSize}px`;
       s.thumb.style.transform = `translateX(${offset}px)`;

package/src/composables/useZoomPan.test.ts

@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import { useZoomPan } from "./useZoomPan";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+afterEach(() => {
+  for (const m of mounts.splice(0)) {
+    m.app.unmount();
+    m.container.remove();
+  }
+});
+
+/** Mount a host that binds the composable's container ref to a real element. */
+async function mountHost() {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const el = ref<HTMLElement | null>(null);
+  const content = ref<HTMLElement | null>(null);
+  let api!: ReturnType<typeof useZoomPan>;
+  const Host = defineComponent({
+    setup() {
+      api = useZoomPan({ containerRef: el, contentRef: content });
+      return () =>
+        h("div", { ref: (r: unknown) => (el.value = r as HTMLElement) }, [
+          h("div", { ref: (r: unknown) => (content.value = r as HTMLElement) }),
+        ]);
+    },
+  });
+  const app = createApp(Host);
+  app.mount(container);
+  mounts.push({ app, container });
+  await nextTick();
+  return { container, viewport: () => el.value as HTMLElement, api: () => api };
+}
+
+function pointer(type: string, id: number, x: number, y: number): PointerEvent {
+  return new PointerEvent(type, { bubbles: true, pointerId: id, pointerType: "touch", clientX: x, clientY: y });
+}
+
+describe("useZoomPan", () => {
+  /** The composable only pans once the view is zoomed in (`zoom < 1`), and it
+   *  clamps the pan to the overflow it can measure — which a layout-less
+   *  environment has none of. Both are stated here: this file is about the pan
+   *  maths, not about the zoom state machine. */
+  async function zoomIn(api: () => ReturnType<typeof useZoomPan>, el: HTMLElement) {
+    Object.defineProperty(el, "clientWidth", { configurable: true, get: () => 400 });
+    Object.defineProperty(el, "clientHeight", { configurable: true, get: () => 300 });
+    Object.defineProperty(el.firstElementChild!, "scrollWidth", { configurable: true, get: () => 2000 });
+    Object.defineProperty(el.firstElementChild!, "scrollHeight", { configurable: true, get: () => 1500 });
+    api().zoom.value = 0.5;
+    await nextTick();
+    expect(api().isZoomed.value, "the view has something to pan").toBe(true);
+  }
+
+  it("wires its gestures once the host has mounted", async () => {
+    const { viewport, api } = await mountHost();
+    const el = viewport();
+    await zoomIn(api, el);
+    // The drag has to reach the composable at all: wiring it inline in
+    // `setup` left the ref empty and every gesture unattached.
+    el.dispatchEvent(pointer("pointerdown", 1, 100, 100));
+    el.dispatchEvent(pointer("pointermove", 1, 140, 160));
+    await nextTick();
+    expect(api().panX.value, "40 drawn px in an unscaled space").toBeCloseTo(40, 5);
+    expect(api().panY.value).toBeCloseTo(60, 5);
+    el.dispatchEvent(pointer("pointerup", 1, 140, 160));
+  });
+
+  it("pans by the pointer's own distance inside a scaled root", async () => {
+    const { viewport, api } = await mountHost();
+    const el = viewport();
+    await zoomIn(api, el);
+    // The container is drawn twice the size it is laid out at.
+    Object.defineProperty(el, "getBoundingClientRect", {
+      configurable: true,
+      value: () => ({ left: 0, top: 0, right: 800, bottom: 600, width: 800, height: 600, x: 0, y: 0 }) as DOMRect,
+    });
+    Object.defineProperty(el, "offsetWidth", { configurable: true, get: () => 400 });
+    Object.defineProperty(el, "offsetHeight", { configurable: true, get: () => 300 });
+
+    el.dispatchEvent(pointer("pointerdown", 1, 100, 100));
+    el.dispatchEvent(pointer("pointermove", 1, 140, 160));
+    await nextTick();
+    expect(api().panX.value, "40 drawn px are 20 of the container's own").toBeCloseTo(20, 5);
+    expect(api().panY.value, "60 drawn px are 30 of the container's own").toBeCloseTo(30, 5);
+    el.dispatchEvent(pointer("pointerup", 1, 140, 160));
+  });
+});

package/src/composables/useZoomPan.ts

@@ -1,6 +1,7 @@
-import { computed, onUnmounted, ref, type Ref } from "vue";
+import { computed, onMounted, onUnmounted, ref, watch, type Ref } from "vue";
 
 import { useReportedTransition } from "@celestia-island/hikari";
+import { drawnScale } from "./layoutGeometry";
 
 /** Duration of the transform settle transition (see `style` below) AND the
  *  window reported to the unified animation bus. JS == CSS so the bus
@@ -128,8 +129,22 @@ export function useZoomPan(options: ZoomPanOptions): ZoomPanState {
 
   function onPointerMove(e: PointerEvent) {
     if (!isPanning.value) return;
-    const dx = e.clientX - lastPointerX.value;
-    const dy = e.clientY - lastPointerY.value;
+    // The container's own pixels, not the drawn ones: a scaled or zoomed root
+    // would otherwise pan k times as far as the pointer moved.
+    const container = containerRef.value;
+    const scale = container ? drawnScale(container) : { x: 1, y: 1 };
+    const factor =
+      container && container.offsetWidth > 0
+        ? scale.x > 0
+          ? scale.x
+          : 1
+        : container && container.offsetHeight > 0
+          ? scale.y > 0
+            ? scale.y
+            : 1
+          : 1;
+    const dx = (e.clientX - lastPointerX.value) / factor;
+    const dy = (e.clientY - lastPointerY.value) / factor;
     lastPointerX.value = e.clientX;
     lastPointerY.value = e.clientY;
     panX.value += dx;
@@ -146,23 +161,33 @@ export function useZoomPan(options: ZoomPanOptions): ZoomPanState {
   }
 
   let detach: (() => void) | null = null;
-  if (typeof window !== "undefined") {
+  /** Wire the gestures to whatever element the ref resolves to. A ref is
+   *  still empty while `setup` runs, so this has to happen once the host has
+   *  mounted — wiring it inline left every gesture unattached. */
+  function attach(): void {
+    detach?.();
+    detach = null;
     const el = containerRef.value;
-    if (el) {
-      const wheelOpts = { passive: false } as AddEventListenerOptions;
-      el.addEventListener("wheel", onWheel, wheelOpts);
-      el.addEventListener("pointerdown", onPointerDown);
-      el.addEventListener("pointermove", onPointerMove);
-      el.addEventListener("pointerup", onPointerUp);
-      el.addEventListener("pointercancel", onPointerUp);
-      detach = () => {
-        el.removeEventListener("wheel", onWheel, wheelOpts);
-        el.removeEventListener("pointerdown", onPointerDown);
-        el.removeEventListener("pointermove", onPointerMove);
-        el.removeEventListener("pointerup", onPointerUp);
-        el.removeEventListener("pointercancel", onPointerUp);
-      };
-    }
+    if (!el) return;
+    const wheelOpts = { passive: false } as AddEventListenerOptions;
+    el.addEventListener("wheel", onWheel, wheelOpts);
+    el.addEventListener("pointerdown", onPointerDown);
+    el.addEventListener("pointermove", onPointerMove);
+    el.addEventListener("pointerup", onPointerUp);
+    el.addEventListener("pointercancel", onPointerUp);
+    detach = () => {
+      el.removeEventListener("wheel", onWheel, wheelOpts);
+      el.removeEventListener("pointerdown", onPointerDown);
+      el.removeEventListener("pointermove", onPointerMove);
+      el.removeEventListener("pointerup", onPointerUp);
+      el.removeEventListener("pointercancel", onPointerUp);
+    };
+  }
+
+  if (typeof window !== "undefined") {
+    onMounted(attach);
+    // A host that swaps the element out from under the ref re-wires too.
+    watch(containerRef, () => attach());
   }
 
   const style = computed(() => ({

package/src/index.ts

@@ -270,6 +270,22 @@ export type { ZoomPanOptions, ZoomPanState } from "./composables/useZoomPan";
 export { extOf, isImageFile, isAudioFile, codeLanguage, isCodeFile, isArchiveFile, isTextFile, fileIcon, mediaKindOf } from "./utils/fileType";
 
 export { useReducedMotion } from "./composables/useReducedMotion";
+export {
+  drawnScale,
+  frameMetrics,
+  frameScale,
+  laidOffsetWithin,
+  laidSize,
+  layoutOffset,
+  layoutRect,
+  nearestLaidAncestor,
+  placePoint,
+} from "./composables/layoutGeometry";
+export type {
+  FrameMetrics,
+  LayoutOffset,
+  LayoutRect,
+} from "./composables/layoutGeometry";
 export { useMeasuredHighlight } from "./composables/useMeasuredHighlight";
 export type { UseMeasuredHighlightOptions, MeasuredHighlight } from "./composables/useMeasuredHighlight";
 export {