@celestia-island/hikari 0.35.0 → 0.36.0

package/package.json

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

package/src/components/HkAuthCard.test.tsx

@@ -0,0 +1,259 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createApp, h } from "vue";
+
+import { HkAuthCard } from "./HkAuthCard";
+
+/** Injectable ResizeObserver: captures the callback so tests can fire
+ *  content changes deterministically (happy-dom's own RO never fires —
+ *  there is no layout engine). Same harness as useSizeMorph.test.ts. */
+class FakeResizeObserver {
+  static instances: FakeResizeObserver[] = [];
+  callback: () => void;
+  observed: Element[] = [];
+  disconnected = false;
+
+  constructor(callback: () => void) {
+    this.callback = callback;
+    FakeResizeObserver.instances.push(this);
+  }
+  observe(el: Element): void {
+    this.observed.push(el);
+  }
+  disconnect(): void {
+    this.disconnected = true;
+  }
+}
+
+const originalRO = globalThis.ResizeObserver;
+
+/** The prototype that actually defines `offsetHeight` in this DOM
+ *  implementation, so the stub below is portable across environments. */
+function offsetHeightOwner(): object {
+  let proto = Object.getPrototypeOf(document.createElement("div")) as object | null;
+  while (proto) {
+    if (Object.getOwnPropertyDescriptor(proto, "offsetHeight")) return proto;
+    proto = Object.getPrototypeOf(proto);
+  }
+  return HTMLElement.prototype;
+}
+
+const originalOffsetHeight = Object.getOwnPropertyDescriptor(
+  offsetHeightOwner(),
+  "offsetHeight",
+);
+
+/** Natural height every element reports for `offsetHeight` in tests. */
+let naturalHeight = 0;
+
+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 cardOf(c: HTMLElement) {
+  return c.querySelector<HTMLElement>(".s-auth-card")!;
+}
+
+function wrapperOf(c: HTMLElement) {
+  return c.querySelector<HTMLElement>(".s-auth-card-height")!;
+}
+
+function fireTransitionEnd(el: HTMLElement, propertyName: string) {
+  const event = new Event("transitionend", { bubbles: true });
+  Object.defineProperty(event, "propertyName", { value: propertyName });
+  el.dispatchEvent(event);
+}
+
+beforeEach(() => {
+  FakeResizeObserver.instances = [];
+  naturalHeight = 140;
+  globalThis.ResizeObserver = FakeResizeObserver as unknown as typeof ResizeObserver;
+  Object.defineProperty(offsetHeightOwner(), "offsetHeight", {
+    configurable: true,
+    get: () => naturalHeight,
+  });
+});
+
+afterEach(() => {
+  globalThis.ResizeObserver = originalRO;
+  if (originalOffsetHeight) {
+    Object.defineProperty(offsetHeightOwner(), "offsetHeight", originalOffsetHeight);
+  } else {
+    delete (offsetHeightOwner() as { offsetHeight?: number }).offsetHeight;
+  }
+  vi.restoreAllMocks();
+  vi.useRealTimers();
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+describe("HkAuthCard", () => {
+  it("renders title, subtitle and every slot inside the unchanged card shell", () => {
+    const c = mount(
+      h(HkAuthCard, { title: "Sign in", subtitle: "Welcome back" }, {
+        default: () => h("input", { name: "probe-field" }),
+        methods: () => h("div", { class: "probe-methods" }, "methods"),
+        footer: () => h("div", { class: "probe-footer" }, "footer"),
+      }),
+    );
+    // The measuring wrapper is present and the card is still `.s-auth-card`.
+    const wrapper = wrapperOf(c);
+    const card = cardOf(c);
+    expect(wrapper).toBeTruthy();
+    expect(card).toBeTruthy();
+    expect(c.querySelector(".s-auth-title")?.textContent).toBe("Sign in");
+    expect(c.querySelector(".s-auth-subtitle")?.textContent).toBe("Welcome back");
+    expect(card.querySelector(".s-auth-form input[name='probe-field']")).toBeTruthy();
+    expect(card.querySelector(".s-auth-methods .probe-methods")).toBeTruthy();
+    expect(card.querySelector(".s-auth-footer .probe-footer")).toBeTruthy();
+    // The wrapper is transparent to descendant styling: the header, form,
+    // methods and footer blocks all remain children of `.s-auth-card`.
+    expect(wrapper.querySelector(".s-auth-card")).toBe(card);
+  });
+
+  it("seeds the wrapper height from the card on mount without animating", () => {
+    naturalHeight = 140;
+    const c = mount(h(HkAuthCard, { title: "T" }));
+    const wrapper = wrapperOf(c);
+    expect(wrapper.style.height).toBe("140px");
+    // Seeding must not animate: the measuring class is absent on first paint.
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(false);
+    // The observer watches the card element itself, not the wrapper.
+    expect(FakeResizeObserver.instances).toHaveLength(1);
+    expect(FakeResizeObserver.instances[0]!.observed).toEqual([cardOf(c)]);
+  });
+
+  it("animates growth through the measuring class and releases it on the backstop timer", () => {
+    vi.useFakeTimers();
+    naturalHeight = 140;
+    const c = mount(h(HkAuthCard, { title: "T" }));
+    const wrapper = wrapperOf(c);
+    expect(wrapper.style.height).toBe("140px");
+
+    naturalHeight = 240;
+    FakeResizeObserver.instances[0]!.callback();
+    expect(wrapper.style.height).toBe("240px");
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(true);
+
+    vi.advanceTimersByTime(449);
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(true);
+    vi.advanceTimersByTime(1);
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(false);
+  });
+
+  it("releases the measuring class when the height transition finishes", () => {
+    naturalHeight = 100;
+    const c = mount(h(HkAuthCard, { title: "T" }));
+    const wrapper = wrapperOf(c);
+
+    naturalHeight = 180;
+    FakeResizeObserver.instances[0]!.callback();
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(true);
+
+    // An unrelated property finishing its transition must not release.
+    fireTransitionEnd(wrapper, "color");
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(true);
+
+    fireTransitionEnd(wrapper, "height");
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(false);
+  });
+
+  it("ignores height transitionsend events bubbling up from descendant content", () => {
+    naturalHeight = 100;
+    const c = mount(
+      h(HkAuthCard, { title: "T" }, { default: () => h("div", { class: "probe-anim" }) }),
+    );
+    const wrapper = wrapperOf(c);
+    const child = c.querySelector<HTMLElement>(".probe-anim")!;
+
+    naturalHeight = 180;
+    FakeResizeObserver.instances[0]!.callback();
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(true);
+
+    // A descendant slot element's own height transition bubbling up must
+    // NOT release the clip — it did not open this measuring window.
+    fireTransitionEnd(child, "height");
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(true);
+
+    // Only the wrapper's own height transition may end it.
+    fireTransitionEnd(wrapper, "height");
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(false);
+  });
+
+  it("snaps unclipped under prefers-reduced-motion without arming the backstop", () => {
+    vi.useFakeTimers();
+    vi.spyOn(window, "matchMedia").mockReturnValue({ matches: true } as unknown as MediaQueryList);
+    naturalHeight = 140;
+    const c = mount(h(HkAuthCard, { title: "T" }));
+    const wrapper = wrapperOf(c);
+
+    naturalHeight = 240;
+    FakeResizeObserver.instances[0]!.callback();
+    // Height still tracks the content…
+    expect(wrapper.style.height).toBe("240px");
+    // …but with the transition disabled there is nothing to animate, so
+    // no measuring window opens: no clip, no pending backstop timer.
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(false);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("ignores observer firings that move the height by less than a pixel", () => {
+    naturalHeight = 140;
+    const c = mount(h(HkAuthCard, { title: "T" }));
+    const wrapper = wrapperOf(c);
+
+    naturalHeight = 140.6;
+    FakeResizeObserver.instances[0]!.callback();
+    expect(wrapper.style.height).toBe("140px");
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(false);
+  });
+
+  it("with smoothHeight=false renders the wrapper but installs no measuring", () => {
+    naturalHeight = 140;
+    const c = mount(h(HkAuthCard, { title: "T", smoothHeight: false }));
+    const wrapper = wrapperOf(c);
+    // The wrapper still exists (stable DOM shape for consumers) but is
+    // completely unmanaged: no explicit height and no observer.
+    expect(wrapper).toBeTruthy();
+    expect(wrapper.style.height).toBe("");
+    expect(FakeResizeObserver.instances).toHaveLength(0);
+  });
+
+  it("degrades to an unmanaged wrapper when ResizeObserver is unavailable", () => {
+    (globalThis as { ResizeObserver?: unknown }).ResizeObserver = undefined;
+    naturalHeight = 140;
+    const c = mount(h(HkAuthCard, { title: "T" }));
+    const wrapper = wrapperOf(c);
+    expect(wrapper).toBeTruthy();
+    expect(wrapper.style.height).toBe("");
+    expect(wrapper.classList.contains("s-auth-card--measuring")).toBe(false);
+  });
+
+  it("disconnects the observer and clears the backstop on unmount", () => {
+    vi.useFakeTimers();
+    naturalHeight = 140;
+    const c = mount(h(HkAuthCard, { title: "T" }));
+    const ro = FakeResizeObserver.instances[0]!;
+
+    naturalHeight = 200;
+    ro.callback();
+    expect(wrapperOf(c).classList.contains("s-auth-card--measuring")).toBe(true);
+
+    // Pop the entry so the shared afterEach does not unmount it twice.
+    const entry = mounts.pop()!;
+    entry.app.unmount();
+    expect(ro.disconnected).toBe(true);
+    // The pending backstop timer was cleared on unmount: nothing is left
+    // scheduled (a leaked timer here would also fire releaseClip on a
+    // dead element).
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});

package/src/components/HkAuthCard.tsx

@@ -1,4 +1,10 @@
-import { defineComponent, type PropType } from "vue";
+import { defineComponent, onBeforeUnmount, onMounted, ref } from "vue";
+
+/** Grace window that force-releases the `--measuring` clip if the height
+ *  `transitionend` never arrives (interrupted transition, backgrounded
+ *  tab, reduced-motion). Slightly longer than the 0.3s CSS height
+ *  transition so a normal completion is always released by the event. */
+const MEASURE_BACKSTOP_MS = 450;
 
 /**
  * HkAuthCard — the shared shell of every Celestia auth screen (login,
@@ -19,42 +25,162 @@ import { defineComponent, type PropType } from "vue";
  *   per-row centering; content that must sit on one row belongs inside
  *   one child element.
  * - `logo` swaps the header's logo slot; `default` is the form body.
+ *
+ * Smooth height contract:
+ * The card's content is consumer-driven and changes at runtime — channel
+ * tabs swap the OAuth `methods` list (3 buttons ↔ 1), validation banners
+ * appear, locale switches reflow labels — and the card's height would
+ * otherwise snap between the two layouts. The root card is therefore
+ * wrapped in a `.s-auth-card-height` measuring wrapper that owns an
+ * explicit `height` and animates toward whatever natural height the card
+ * grows or shrinks to:
+ *
+ * - On mount the wrapper seeds its `height` from the card's current
+ *   `offsetHeight` while the animating state is impossible, so the first
+ *   paint never animates.
+ * - A `ResizeObserver` on the card element (not the wrapper) fires when
+ *   the content-driven natural height changes. Changes smaller than 1px
+ *   are ignored to keep rounding noise from starting a cycle. A real
+ *   change adds the `s-auth-card--measuring` class — the ONLY place
+ *   `overflow: hidden` is applied — then rewrites the height, and the CSS
+ *   `height` transition animates the wrapper between the two sizes.
+ * - The clipping class is released by the wrapper's `transitionend`
+ *   (propertyName === "height") and, if that event never fires, by a
+ *   450ms backstop timer. Between animations the card carries no clip,
+ *   so its shadow, focus rings and popovers are never cut off at rest.
+ * - `smoothHeight: false` opts out entirely: the wrapper still renders
+ *   (the DOM shape stays stable for consumers) but no height style, no
+ *   observer and no listeners are installed, and height changes snap as
+ *   before. The prop is read ONCE at mount time — runtime toggles are
+ *   ignored, making it a static opt-out rather than a reactive switch
+ *   (remount with a changed `:key` to apply a new value).
+ * - Environments without `ResizeObserver` degrade the same way: instant
+ *   snap, no measurement, no clipping.
+ * - `prefers-reduced-motion: reduce` disables the transition in CSS, so
+ *   the height still tracks the content, just without animation. While
+ *   it matches, the observer updates the height directly WITHOUT opening
+ *   a measuring window — no clip and no backstop timer — because a clip
+ *   held for the backstop would cut off the card's shadow with nothing
+ *   animating to mask it.
+ *
+ * The wrapper is transparent to descendant styling: nothing inside
+ * `.s-auth-card` changes, and no hikari stylesheet targets the card as a
+ * direct child. Only consumer styles that select `.s-auth-card` as a
+ * DIRECT child of a specific parent must account for the extra wrapper
+ * (e.g. `.us-main > .s-auth-card` becomes
+ * `.us-main > .s-auth-card-height > .s-auth-card`).
  */
 export const HkAuthCard = defineComponent({
   name: "HkAuthCard",
   props: {
     title: { type: String, required: true },
     subtitle: { type: String, default: "" },
+    smoothHeight: { type: Boolean, default: true },
   },
   setup(props, { slots }) {
+    const heightEl = ref<HTMLElement | null>(null);
+    const cardEl = ref<HTMLElement | null>(null);
+
+    let observer: ResizeObserver | null = null;
+    let backstopTimer: ReturnType<typeof setTimeout> | null = null;
+
+    /** End the current measuring window: drop the clip and the backstop. */
+    const releaseClip = () => {
+      if (backstopTimer !== null) {
+        clearTimeout(backstopTimer);
+        backstopTimer = null;
+      }
+      heightEl.value?.classList.remove("s-auth-card--measuring");
+    };
+
+    const onTransitionEnd = (event: TransitionEvent) => {
+      // Only the wrapper's OWN height transition may release the clip —
+      // a descendant slot element's height transition bubbling up must
+      // not end a measuring window it did not open.
+      if (event.target !== heightEl.value) return;
+      if (event.propertyName !== "height") return;
+      releaseClip();
+    };
+
+    onMounted(() => {
+      if (!props.smoothHeight) return;
+      const wrapper = heightEl.value;
+      const card = cardEl.value;
+      if (!wrapper || !card || typeof ResizeObserver === "undefined") return;
+
+      // Seed the explicit height BEFORE any animating class exists, so
+      // the first paint (wrapper already at the natural size) never
+      // animates.
+      wrapper.style.height = `${card.offsetHeight}px`;
+      wrapper.addEventListener("transitionend", onTransitionEnd);
+
+      observer = new ResizeObserver(() => {
+        const next = card.offsetHeight;
+        const current = parseFloat(wrapper.style.height) || 0;
+        // Ignore sub-pixel churn — rounding noise must not start a
+        // clip-and-animate cycle.
+        if (Math.abs(next - current) < 1) return;
+
+        // Reduced motion: the CSS transition is `none`, so transitionend
+        // will never fire and the clip would just sit there for the
+        // backstop window, cutting off the shadow with nothing to mask.
+        // Snap unclipped instead — no class, no timer.
+        if (window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+          wrapper.style.height = `${next}px`;
+          return;
+        }
+
+        // Clip ONLY while a height transition is actually running; the
+        // class is released by transitionend or the backstop timer.
+        wrapper.classList.add("s-auth-card--measuring");
+        wrapper.style.height = `${next}px`;
+
+        if (backstopTimer !== null) clearTimeout(backstopTimer);
+        backstopTimer = setTimeout(releaseClip, MEASURE_BACKSTOP_MS);
+      });
+      observer.observe(card);
+    });
+
+    onBeforeUnmount(() => {
+      observer?.disconnect();
+      observer = null;
+      heightEl.value?.removeEventListener("transitionend", onTransitionEnd);
+      if (backstopTimer !== null) {
+        clearTimeout(backstopTimer);
+        backstopTimer = null;
+      }
+    });
+
     return () => (
-      <div class="s-auth-card">
-        {slots.logo && (
-          <div class="s-auth-header">
-            {slots.logo()}
-            <h1 class="s-auth-title">{props.title}</h1>
-            {props.subtitle && <p class="s-auth-subtitle">{props.subtitle}</p>}
-          </div>
-        )}
-        {!slots.logo && (
-          <div class="s-auth-header">
-            <h1 class="s-auth-title">{props.title}</h1>
-            {props.subtitle && <p class="s-auth-subtitle">{props.subtitle}</p>}
+      <div class="s-auth-card-height" ref={heightEl}>
+        <div class="s-auth-card" ref={cardEl}>
+          {slots.logo && (
+            <div class="s-auth-header">
+              {slots.logo()}
+              <h1 class="s-auth-title">{props.title}</h1>
+              {props.subtitle && <p class="s-auth-subtitle">{props.subtitle}</p>}
+            </div>
+          )}
+          {!slots.logo && (
+            <div class="s-auth-header">
+              <h1 class="s-auth-title">{props.title}</h1>
+              {props.subtitle && <p class="s-auth-subtitle">{props.subtitle}</p>}
+            </div>
+          )}
+          <div class="s-auth-form">
+            {slots.default?.()}
           </div>
-        )}
-        <div class="s-auth-form">
-          {slots.default?.()}
+          {slots.methods && (
+            <div class="s-auth-methods">
+              {slots.methods()}
+            </div>
+          )}
+          {slots.footer && (
+            <div class="s-auth-footer">
+              {slots.footer()}
+            </div>
+          )}
         </div>
-        {slots.methods && (
-          <div class="s-auth-methods">
-            {slots.methods()}
-          </div>
-        )}
-        {slots.footer && (
-          <div class="s-auth-footer">
-            {slots.footer()}
-          </div>
-        )}
       </div>
     );
   },

package/src/components/HkBoard.tsx

@@ -44,6 +44,7 @@ import { useBoardCamera } from "../composables/useBoardCamera";
 import HkMinimap, { type MinimapBox } from "./HkMinimap";
 import {
   boardBBox,
+  boardStepRung,
   type BoardCamera,
   type BoardPoint,
   type BoardRect,
@@ -52,13 +53,19 @@ import {
 import {
   boardAnchor,
   boardEdgePath,
+  boardFanOrdinals,
   boardViaPath,
   type BoardAnchorMode,
   type BoardEdgeStyle,
 } from "../utils/boardEdges";
 import "./HkBoard.scss";
 
-/** A node on the board. `hidden` nodes are junction-only (invisible). */
+/**
+ * A node on the board. `hidden` nodes are junction-only (invisible).
+ * During a node drag the board mutates the node objects IN PLACE and
+ * emits the live reference through `node-move` / `nodeClick` — pass
+ * deep-reactive, mutable node objects, not frozen copies.
+ */
 export interface BoardNodeInput {
   id: string;
   x: number;
@@ -138,16 +145,7 @@ export default defineComponent({
     });
 
     /** Edges sharing a `from` node fan across its border (天女散花). */
-    const fanOrdinal = computed(() => {
-      const counters = new Map<string, number>();
-      const ordinals = new Map<string, { index: number; count: number }>();
-      for (const e of props.edges) {
-        const next = (counters.get(e.from) ?? 0) + 1;
-        counters.set(e.from, next);
-        ordinals.set(e.id, { index: next - 1, count: counters.get(e.from)! });
-      }
-      return ordinals;
-    });
+    const fanOrdinal = computed(() => boardFanOrdinals(props.edges));
 
     const edgePaths = computed(() => {
       const rects = rectOf.value;
@@ -209,6 +207,9 @@ export default defineComponent({
     let panState: { px: number; py: number } | null = null;
     let pinchBase: { cam: BoardCamera; dist: number; mid: BoardPoint } | null = null;
     let dragState: { node: BoardNodeInput; sx: number; sy: number; ox: number; oy: number; moved: boolean } | null = null;
+    // Every node press is tracked (draggable or not) so read-only boards
+    // — SCADA scenes, mind maps — still get `nodeClick` on a short tap.
+    let pressed: { id: string; pointerId: number; x: number; y: number } | null = null;
 
     const localPoint = (e: PointerEvent | WheelEvent): BoardPoint => {
       const rect = viewportRef.value?.getBoundingClientRect();
@@ -230,23 +231,39 @@ export default defineComponent({
 
     let resizeObs: ResizeObserver | null = null;
 
+    /** Snapshot the camera + current finger pair as the pinch baseline —
+     *  at gesture start, or whenever the pair's composition changes — so
+     *  the scale keeps following the fingers 1:1 without a jump. */
+    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),
+        },
+      };
+    }
+
     function onPointerDown(e: PointerEvent): void {
       if (!props.interactive) return;
+      // Defensive prune: tracked pointers no gesture is using are stale
+      // (their up/cancel AND capture loss were both lost) — drop them so
+      // the next single-finger touch cannot become a phantom pinch.
+      if (pointers.size > 0 && !pinchBase && !panState && !dragState) pointers.clear();
       pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
-      if (pointers.size === 2) {
-        // pinch begins: snapshot camera + finger geometry
-        const [a, b] = [...pointers.values()];
-        pinchBase = {
-          cam: { ...camera.value },
-          dist: Math.hypot(a.x - b.x, a.y - b.y) || 1,
-          mid: localPoint(e),
-        };
-        panState = null;
-        return;
-      }
+      // Capture EVERY finger: up/cancel are only guaranteed while capture
+      // holds, and an uncaptured pinch finger would never leave `pointers`.
+      viewportRef.value?.setPointerCapture(e.pointerId);
       if (pointers.size === 1) {
         panState = { px: e.clientX, py: e.clientY };
-        viewportRef.value?.setPointerCapture(e.pointerId);
+      } else if (pointers.size === 2) {
+        // pinch begins: snapshot camera + finger geometry, suspend panning
+        rearmPinch();
+        panState = null;
       }
     }
 
@@ -256,10 +273,12 @@ 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 - (viewportRef.value?.getBoundingClientRect().left ?? 0),
-          y: (a.y + b.y) / 2 - (viewportRef.value?.getBoundingClientRect().top ?? 0),
+          x: (a.x + b.x) / 2 - (rect?.left ?? 0),
+          y: (a.y + b.y) / 2 - (rect?.top ?? 0),
         };
+        pinchBase.mid = mid;
         cam.pinchZoom(pinchBase.cam, dist / pinchBase.dist, mid);
         return;
       }
@@ -280,17 +299,62 @@ export default defineComponent({
     }
 
     function onPointerUp(e: PointerEvent): void {
-      pointers.delete(e.pointerId);
-      if (pointers.size < 2 && pinchBase) {
+      const press = pressed;
+      pressed = null;
+      dragState = null;
+      retirePointer(e.pointerId);
+      // nodeClick: a press that belongs to THIS pointer and stayed within
+      // the drag slop clicks — regardless of `draggable`.
+      if (press && press.pointerId === e.pointerId
+        && Math.abs(e.clientX - press.x) + Math.abs(e.clientY - press.y) < 3) {
+        const node = props.nodes.find((n) => n.id === press.id);
+        if (node) emit("nodeClick", node);
+      }
+    }
+
+    function onPointerCancel(e: PointerEvent): void {
+      // An aborted gesture must never synthesize a click: prune state only.
+      pressed = null;
+      dragState = null;
+      retirePointer(e.pointerId);
+    }
+
+    /** A pointer left the gesture (up, cancel, or capture loss): prune it,
+     *  re-baseline or settle the pinch, and hand panning to any surviving
+     *  pointer so a pinch that ends with one finger down keeps panning. */
+    function retirePointer(pointerId: number): void {
+      if (!pointers.delete(pointerId)) return;
+      if (pinchBase && pointers.size >= 2) {
+        // The pinch pair composition changed (a finger lifted while two
+        // or more remain): re-baseline onto the surviving pair.
+        rearmPinch();
+        return;
+      }
+      if (pinchBase) {
+        const mid = pinchBase.mid;
         pinchBase = null;
-        cam.settlePinch();
+        cam.settlePinch(mid);
       }
-      if (pointers.size === 0) panState = null;
-      if (dragState && !dragState.moved) emit("nodeClick", dragState.node);
+      const rest = pointers.values().next().value;
+      panState = rest ? { px: rest.x, py: rest.y } : null;
+    }
+
+    /** Capture-loss backstop: up/cancel are only guaranteed while pointer
+     *  capture holds; a pointer that was released without an up is pruned
+     *  here — otherwise the next single-finger touch would silently become
+     *  a phantom pinch. The event fires on the capture target and does not
+     *  bubble, hence the capture-phase listener; after a normal up it is a
+     *  no-op (the pointer was already pruned there). */
+    function onLostPointerCapture(e: PointerEvent): void {
+      pressed = null;
       dragState = null;
+      retirePointer(e.pointerId);
     }
 
     function onNodePointerDown(e: PointerEvent, node: BoardNodeInput): void {
+      pressed = { id: node.id, pointerId: e.pointerId, x: e.clientX, y: e.clientY };
+      // Draggable nodes own the gesture (no board pan); every other press
+      // bubbles on so the board can pan — and still click on a short tap.
       if (!props.interactive || !node.draggable) return;
       e.stopPropagation();
       dragState = { node, sx: e.clientX, sy: e.clientY, ox: node.x, oy: node.y, moved: false };
@@ -308,12 +372,17 @@ export default defineComponent({
       resizeObs = new ResizeObserver(refreshSize);
       if (viewportRef.value) resizeObs.observe(viewportRef.value);
       viewportRef.value?.addEventListener("wheel", onWheel, { passive: false });
+      // Capture phase: lostpointercapture does not bubble and fires on the
+      // element that held capture.
+      viewportRef.value?.addEventListener("lostpointercapture", onLostPointerCapture, true);
       if (props.fitOnMount) cam.fit();
     });
 
     onBeforeUnmount(() => {
+      cam.stop(); // kill any in-flight tween rAF
       resizeObs?.disconnect();
       viewportRef.value?.removeEventListener("wheel", onWheel);
+      viewportRef.value?.removeEventListener("lostpointercapture", onLostPointerCapture, true);
     });
 
     expose({
@@ -332,7 +401,7 @@ export default defineComponent({
         onPointerdown={onPointerDown}
         onPointermove={onPointerMove}
         onPointerup={onPointerUp}
-        onPointercancel={onPointerUp}
+        onPointercancel={onPointerCancel}
       >
         <div class="hk-board-grid" style={gridStyle.value} />
         <div class="hk-board-world" style={worldStyle.value}>
@@ -384,7 +453,7 @@ export default defineComponent({
               minZoomPercent={Math.round(props.minK * 100)}
               maxZoomPercent={Math.round(props.maxK * 100)}
               showReset
-              onZoomTo={(percent: number) => cam.zoomToPercent(percent)}
+              onZoomTo={(percent: number) => cam.zoomToK(boardStepRung(camera.value.k, percent / 100))}
               onReset={() => cam.fit()}
               onPanDelta={(dx: number, dy: number) => cam.panBy(dx, dy)}
             />

package/src/components/HkIconButton.scss

@@ -150,7 +150,6 @@
       width: var(--hi-icon-button-icon-size);
       height: var(--hi-icon-button-icon-size);
       display: block;
-      fill: currentColor;
     }
   }
 

package/src/components/HkMinimap.scss

@@ -11,6 +11,10 @@
   cursor: pointer;
   overflow: hidden;
   pointer-events: auto;
+  /* The minimap owns its own drag gestures — the surrounding pannable
+     surface must never claim them (mobile browsers would otherwise fire
+     pointercancel and kill the drag). */
+  touch-action: none;
 
   &:hover {
     border-color: rgb(var(--color-primary) / 0.3);

package/src/composables/useBoardCamera.ts

@@ -63,12 +63,15 @@ export interface UseBoardCameraReturn {
   zoomOut: () => void;
   /** Raw (unquantized, unanimated) pinch zoom — call per pointermove. */
   pinchZoom: (base: BoardCamera, ratio: number, anchor: BoardPoint) => void;
-  /** Snap the post-pinch camera onto the nearest rung (animated). */
-  settlePinch: () => void;
+  /** Snap the post-pinch camera onto the nearest rung (animated), keeping
+   *  the world point under `anchor` (the pinch midpoint) fixed. */
+  settlePinch: (anchor?: BoardPoint) => void;
   panBy: (dx: number, dy: number) => void;
   setCamera: (cam: BoardCamera, opts?: { animate?: boolean }) => void;
   fit: () => void;
   reset: () => void;
+  /** Cancel any in-flight tween and its pending rAF (call on unmount). */
+  stop: () => void;
 }
 
 export function useBoardCamera(options: UseBoardCameraOptions): UseBoardCameraReturn {
@@ -83,6 +86,12 @@ export function useBoardCamera(options: UseBoardCameraOptions): UseBoardCameraRe
   const camera = ref<BoardCamera>({ x: 0, y: 0, k: 1 });
   const isAnimating = ref(false);
 
+  // fit() may park the camera BELOW the interaction minimum (show the
+  // whole board wins over the zoom ladder, as in HkImageViewer) — the
+  // clamp floor follows it down so the fitted framing survives; any
+  // quantized gesture lands back on the ladder at ≥ minK.
+  let kFloor = minK;
+
   let raf = 0;
   let tweenFrom: BoardCamera = { x: 0, y: 0, k: 1 };
   let tweenTo: BoardCamera = { x: 0, y: 0, k: 1 };
@@ -100,7 +109,7 @@ export function useBoardCamera(options: UseBoardCameraOptions): UseBoardCameraRe
   const contentRect = (): BoardRect => toValue(content);
 
   const clampCam = (cam: BoardCamera): BoardCamera => {
-    const k = Math.min(maxK, Math.max(minK, cam.k));
+    const k = Math.min(maxK, Math.max(kFloor, cam.k));
     return boardClampPan({ ...cam, k }, contentRect(), viewport());
   };
 
@@ -135,13 +144,16 @@ export function useBoardCamera(options: UseBoardCameraOptions): UseBoardCameraRe
   };
 
   function zoomByFactor(factor: number, anchor?: BoardPoint): void {
-    const next = boardZoomAt(camera.value, camera.value.k * factor, anchorPoint(anchor));
-    animateTo({ ...next, k: quantizeBoardK(next.k) });
+    // Quantize FIRST, then solve the anchored pan for the QUANTIZED k —
+    // anchoring on the raw k and swapping in the quantized one afterwards
+    // lets the anchored world point jump by the raw/quantized ratio.
+    const k = quantizeBoardK(camera.value.k * factor);
+    animateTo(boardZoomAt(camera.value, k, anchorPoint(anchor)));
   }
 
   function zoomToK(targetK: number, anchor?: BoardPoint): void {
-    const next = boardZoomAt(camera.value, targetK, anchorPoint(anchor));
-    animateTo({ ...next, k: quantizeBoardK(next.k) });
+    const k = quantizeBoardK(targetK);
+    animateTo(boardZoomAt(camera.value, k, anchorPoint(anchor)));
   }
 
   function zoomToPercent(percent: number, anchor?: BoardPoint): void {
@@ -162,9 +174,11 @@ export function useBoardCamera(options: UseBoardCameraOptions): UseBoardCameraRe
     camera.value = clampCam(boardZoomAt(base, base.k * ratio, anchor));
   }
 
-  function settlePinch(): void {
-    const settled = { ...camera.value, k: quantizeBoardK(camera.value.k) };
-    animateTo(settled);
+  function settlePinch(anchor?: BoardPoint): void {
+    // Same quantize-then-anchor discipline as the wheel path: the pinch
+    // midpoint stays pinned to its world point while k snaps onto the rung.
+    const k = quantizeBoardK(camera.value.k);
+    animateTo(boardZoomAt(camera.value, k, anchorPoint(anchor)));
   }
 
   function panBy(dx: number, dy: number): void {
@@ -181,7 +195,9 @@ export function useBoardCamera(options: UseBoardCameraOptions): UseBoardCameraRe
   }
 
   function fit(): void {
-    animateTo(boardFit(contentRect(), viewport()));
+    const target = boardFit(contentRect(), viewport());
+    kFloor = Math.min(minK, target.k);
+    animateTo(target);
   }
 
   function reset(): void {
@@ -214,5 +230,6 @@ export function useBoardCamera(options: UseBoardCameraOptions): UseBoardCameraRe
     setCamera,
     fit,
     reset,
+    stop: stopTween,
   };
 }

package/src/styles/admin-tokens.scss

@@ -527,6 +527,30 @@
   to   { opacity: 1; transform: translateY(0) scale(1); }
 }
 
+/* Measuring wrapper (HkAuthCard): owns an explicit height so content-
+   driven height changes (channel tabs swapping the methods list, error
+   banners, …) animate instead of snapping. The transition lives here,
+   always on; the `--measuring` clip below is applied by HkAuthCard only
+   for the duration of a height transition, so an idle card never clips
+   its shadow, focus rings or popovers. */
+.s-auth-card-height {
+  /* The wrapper is sized from the card's offsetHeight (border-box); an
+     explicit box-sizing keeps that mapping honest on hosts without a
+     global border-box reset. */
+  box-sizing: border-box;
+  transition: height 0.3s var(--ease-out-expo, cubic-bezier(0.19, 1, 0.22, 1));
+
+  &.s-auth-card--measuring {
+    overflow: hidden;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .s-auth-card-height {
+    transition: none;
+  }
+}
+
 .s-auth-card input {
   transition: color calc(infinity * 1s) step-end, background-color calc(infinity * 1s) step-end;
   appearance: none;

package/src/theme/tokenGroups.test.ts

@@ -343,14 +343,19 @@ describe("late registration", () => {
     setMode("dark");
     initTheme();
     const el = document.documentElement;
+    // Theme vars live in the managed :root block (lean injection), so the
+    // html inline style stays clean until the late group lands.
+    const block = () => document.head.querySelector("style[data-hikari-theme-vars]")?.textContent ?? "";
     expect(el.style.getPropertyValue("--late-wires-a")).toBe("");
+    expect(block()).not.toContain("--late-wires-a");
 
     registerTokenGroup(LATE_GROUP);
     await flushMicrotasks();
 
     // The injected hook re-applied the current dark theme, so the late
-    // group's registry defaults are already on the document element.
-    expect(el.style.getPropertyValue("--late-wires-a")).toBe("1 2 3");
+    // group's registry defaults are already in the managed block.
+    expect(block()).toContain("--late-wires-a:1 2 3");
+    expect(el.style.getPropertyValue("--late-wires-a")).toBe("");
   });
 
   it("coalesces same-tick registrations into a single re-apply", async () => {

package/src/theme/useTheme.test.ts

@@ -70,3 +70,70 @@ describe("useTheme theme clock", () => {
     expect(theme.useTheme().geo.value).toEqual({ lat: 1, lng: 2 });
   });
 });
+
+describe("useTheme lean cssvar injection", () => {
+  let theme: ThemeModule;
+
+  beforeEach(async () => {
+    vi.resetModules();
+    vi.unstubAllGlobals();
+    localStorage.clear();
+    document.documentElement.style.cssText = "";
+    document.documentElement.removeAttribute("data-theme");
+    document.documentElement.removeAttribute("data-mode");
+    document.head.querySelectorAll("style[data-hikari-theme-vars]").forEach((el) => el.remove());
+    vi.stubGlobal("fetch", vi.fn(async () => {
+      throw new Error("offline");
+    }));
+    theme = await import("./useTheme");
+  });
+
+  afterEach(() => {
+    theme.stopThemeClock();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("pickThemeVarDeltas keeps only values differing from the static cascade", () => {
+    const vars = {
+      "--a": "1 2 3",
+      "--b": "4 5 6",
+      "--c": "7 8 9",
+      "--d": " 10 11 12 ",
+    };
+    const baseline = {
+      "--a": "1 2 3",
+      "--b": "4  5 6",
+      "--c": "",
+      "--d": "10 11 12",
+    };
+    // Whitespace-only differences collapse (normalization), so only the
+    // genuinely absent/divergent values are injected.
+    expect(theme.pickThemeVarDeltas(vars, baseline)).toEqual({
+      "--c": "7 8 9",
+    });
+  });
+
+  it("writes theme vars into a managed :root style block, never inline", () => {
+    theme.initTheme();
+    const styleEl = document.head.querySelector("style[data-hikari-theme-vars]");
+    expect(styleEl).not.toBeNull();
+    // Real browsers compute the static defaults, so the block holds only the
+    // true deltas; either way it is a :root block, not an inline attribute.
+    expect(styleEl!.textContent).toMatch(/^:root\{/);
+    expect(styleEl!.textContent).toContain("--color-primary");
+    // The html inline style attribute stays clean — no token vars on it.
+    expect(document.documentElement.style.getPropertyValue("--color-primary")).toBe("");
+    // The epoch attributes that consumers watch are still written.
+    expect(document.documentElement.getAttribute("data-theme")).toBeTruthy();
+    expect(document.documentElement.getAttribute("data-mode")).toBeTruthy();
+    // Swapping theme keeps ONE managed block (no duplicates per apply) and
+    // actually re-applies: the block content changes with the preset.
+    const before = document.head.querySelector("style[data-hikari-theme-vars]")!.textContent;
+    theme.useTheme().setTheme("nord");
+    const blocks = document.head.querySelectorAll("style[data-hikari-theme-vars]");
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0].textContent).toMatch(/^:root\{/);
+    expect(blocks[0].textContent).not.toBe(before);
+  });
+});

package/src/theme/useTheme.ts

@@ -148,6 +148,76 @@ function resolveEffectiveMode(mode: ThemeMode): "dark" | "light" {
 const THEME_TRANSITION_DURATION = 300;
 let transitionTimer: CronHandle | null = null;
 
+/**
+ * Theme vars live in ONE managed stylesheet block (`:root` overrides)
+ * instead of a hundred inline declarations on `<html style="...">`.
+ *  - Inline style attributes bloat the DOM, show up as giant devtools
+ *    noise on the root element, defeat caching of the token set and make
+ *    every style recalc parse the whole attribute again.
+ *  - A stylesheet block is a single atomic replacement (one recalc for
+ *    the whole theme apply) and inspectable/serializable.
+ *  - Only the DELTAS are written: hikari's static stylesheet already
+ *    seeds :root with the full default token set (including pure
+ *    derivations like `--hi-color-primary: rgb(var(--color-primary))`),
+ *    so a token whose value already resolves identically needs no
+ *    override at all — a default-ish theme injects a handful of vars
+ *    instead of ~80.
+ */
+const THEME_VARS_STYLE_ATTR = "data-hikari-theme-vars";
+
+function normalizeVarValue(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+/** Keep only the vars whose value differs from the static cascade. */
+export function pickThemeVarDeltas(
+  vars: Record<string, string>,
+  baseline: Record<string, string>,
+): Record<string, string> {
+  const deltas: Record<string, string> = {};
+  for (const [key, value] of Object.entries(vars)) {
+    const normalized = normalizeVarValue(value);
+    if (normalizeVarValue(baseline[key] ?? "") !== normalized) {
+      deltas[key] = normalized;
+    }
+  }
+  return deltas;
+}
+
+function themeVarsStyleElement(): HTMLStyleElement {
+  let styleEl = document.head.querySelector<HTMLStyleElement>(
+    `style[${THEME_VARS_STYLE_ATTR}]`,
+  );
+  if (!styleEl) {
+    styleEl = document.createElement("style");
+    styleEl.setAttribute(THEME_VARS_STYLE_ATTR, "");
+    document.head.appendChild(styleEl);
+  }
+  return styleEl;
+}
+
+function injectThemeVars(el: HTMLElement, vars: Record<string, string>): void {
+  const styleEl = themeVarsStyleElement();
+  // Measure the cascade WITHOUT our own previous overrides: disable the
+  // managed block, read every candidate, re-enable. One recalc serves
+  // all reads, and applyTheme is a rare switch-time action.
+  const baseline: Record<string, string> = {};
+  try {
+    styleEl.disabled = true;
+    const computed = getComputedStyle(el);
+    for (const key of Object.keys(vars)) {
+      baseline[key] = computed.getPropertyValue(key);
+    }
+  } finally {
+    styleEl.disabled = false;
+  }
+
+  const deltas = pickThemeVarDeltas(vars, baseline);
+  styleEl.textContent = Object.keys(deltas).length > 0
+    ? `:root{${Object.entries(deltas).map(([key, value]) => `${key}:${value}`).join(";")}}`
+    : "";
+}
+
 function applyTheme() {
   const el = document.documentElement;
   const all = getAllThemePresets();
@@ -168,9 +238,7 @@ function applyTheme() {
 
   invalidateLuminanceCache();
 
-  for (const [key, value] of Object.entries(vars)) {
-    el.style.setProperty(key, value);
-  }
+  injectThemeVars(el, vars);
 
   el.setAttribute("data-theme", currentTheme.value);
   el.setAttribute("data-mode", effectiveMode);

package/src/utils/boardCamera.test.ts

@@ -2,12 +2,14 @@ import { describe, expect, it } from "vitest";
 
 import {
   BOARD_FIT_CAP,
+  BOARD_K_MAX,
   BOARD_ZOOM_FACTOR,
   boardBBox,
   boardClampPan,
   boardEaseOutCubic,
   boardFit,
   boardLevelOf,
+  boardStepRung,
   boardToScreen,
   boardTweenCam,
   boardToWorld,
@@ -51,6 +53,20 @@ describe("boardCamera — anchor zoom", () => {
     expect(zoomed.k).toBe(1.5);
   });
 
+  it("keeps the anchor world point fixed when zooming to a QUANTIZED rung", () => {
+    // The settle path (wheel notch / pinch release) must quantize k FIRST
+    // and then solve the anchored pan for the quantized k — anchoring on
+    // the raw k and swapping the rung in afterwards jumps the world point.
+    const cam = { x: 40, y: -20, k: 2.3 };
+    const anchor = { x: 300, y: 200 };
+    const worldBefore = boardToWorld(cam, anchor.x, anchor.y);
+    const settled = boardZoomAt(cam, quantizeBoardK(cam.k), anchor);
+    const worldAfter = boardToWorld(settled, anchor.x, anchor.y);
+    expect(worldAfter.x).toBeCloseTo(worldBefore.x, 6);
+    expect(worldAfter.y).toBeCloseTo(worldBefore.y, 6);
+    expect(settled.k).toBe(quantizeBoardK(cam.k));
+  });
+
   it("round-trips screen→world→screen", () => {
     const cam = { x: -130, y: 88, k: 1.3 };
     const p = boardToScreen(cam, 42, -7);
@@ -83,6 +99,45 @@ describe("boardCamera — pan clamp + fit", () => {
     const tiny = boardFit({ x: 0, y: 0, w: 60, h: 40 }, viewport);
     expect(tiny.k).toBeLessThanOrEqual(BOARD_FIT_CAP);
   });
+
+  it("shrinks below the interaction minimum to fit very wide boards", () => {
+    // 8000 world px in an 800 px viewport: fit k = 720/8000 = 0.09, far
+    // below the old 0.2 floor that cropped such boards on open.
+    const wide = { x: 0, y: 0, w: 8000, h: 600 };
+    const cam = boardFit(wide, viewport);
+    expect(cam.k).toBeCloseTo((800 - 80) / 8000, 6);
+    expect(cam.k).toBeLessThan(0.2);
+    // the whole board lands inside the viewport
+    const tl = boardToScreen(cam, 0, 0);
+    const br = boardToScreen(cam, 8000, 600);
+    expect(tl.x).toBeGreaterThanOrEqual(0);
+    expect(br.x).toBeLessThanOrEqual(viewport.w);
+  });
+});
+
+describe("boardCamera — minimap step rungs", () => {
+  const lastRung = BOARD_ZOOM_FACTOR ** 28; // ≈3.92 — last rung below the cap
+
+  it("pushes a linear +5% step that nearest-rounds onto the current rung", () => {
+    // from 392%, the + button targets 397% — nearest rounding falls back
+    // onto rung 28 (the dead band), so the step resolves one rung further
+    // and clamps to the cap.
+    expect(quantizeBoardK(3.97)).toBeCloseTo(lastRung, 5);
+    expect(boardStepRung(lastRung, 3.97)).toBe(BOARD_K_MAX);
+  });
+
+  it("pushes a linear −5% step onto the rung below, not the current one", () => {
+    expect(boardStepRung(lastRung, 3.87)).toBeCloseTo(BOARD_ZOOM_FACTOR ** 27, 5);
+  });
+
+  it("leaves steps that already resolve to a different rung untouched", () => {
+    expect(boardStepRung(1, 1.05)).toBeCloseTo(BOARD_ZOOM_FACTOR, 5);
+    expect(boardStepRung(1, 0.95)).toBeCloseTo(BOARD_ZOOM_FACTOR ** -1, 5);
+  });
+
+  it("steps from the ladder floor up onto the nearest live rung", () => {
+    expect(boardStepRung(0.2, 0.25)).toBeCloseTo(BOARD_ZOOM_FACTOR ** -28, 5);
+  });
 });
 
 describe("boardCamera — animated tween", () => {

package/src/utils/boardCamera.ts

@@ -14,7 +14,9 @@
  *  - pan is CLAMPED so the content bbox can never be pushed fully out of
  *    view (half a viewport of slack on each side); content smaller than
  *    the viewport re-centers;
- *  - `boardFit` fits the whole bbox (pad + floor + cap);
+ *  - `boardFit` fits the whole bbox (pad + cap) and may shrink as far as
+ *    needed to show the whole board — fit sits below the interaction
+ *    ladder freely;
  *  - `boardTweenCam` eases between two cameras with an ease-out curve and
  *    GEOMETRIC k interpolation (log-space lerp) so animated zooms still
  *    land exactly on ladder rungs.
@@ -51,8 +53,6 @@ export interface BoardViewport {
 export const BOARD_ZOOM_FACTOR = 1.05;
 export const BOARD_K_MIN = 0.2;
 export const BOARD_K_MAX = 4;
-/** fit() may shrink as far as needed to show the whole board. */
-export const BOARD_FIT_FLOOR = 0.2;
 /** fit() never blows above this (nearly-empty boards). */
 export const BOARD_FIT_CAP = 1.25;
 /** Padding around the bbox used by fit(), world px. */
@@ -87,6 +87,26 @@ export function quantizeBoardStep(base: number, ratio: number): number {
   return boardClampK(base * boardKOf(level));
 }
 
+/**
+ * Quantize a fixed-step zoom target (the minimap ± button: linear ±5% on
+ * a geometric ladder) into a rung, in the step's DIRECTION. Nearest-rung
+ * rounding alone can collapse onto the rung the camera already sits on —
+ * from the last reachable rung below the cap, a +5% percent target rounds
+ * straight back to it and the press does nothing. A target that resolves
+ * to the current rung is therefore pushed ONE rung further in the press
+ * direction (clamped to the global bounds); targets that already resolve
+ * elsewhere are untouched.
+ */
+export function boardStepRung(currentK: number, targetK: number): number {
+  const clamped = boardClampK(targetK);
+  const rung = quantizeBoardK(clamped);
+  const currentLevel = Math.round(boardLevelOf(boardClampK(currentK)));
+  const rungLevel = Math.round(boardLevelOf(rung));
+  if (rungLevel !== currentLevel) return rung;
+  const dir = clamped >= currentK ? 1 : -1;
+  return boardClampK(boardKOf(currentLevel + dir));
+}
+
 export function boardToScreen(cam: BoardCamera, wx: number, wy: number): BoardPoint {
   return { x: wx * cam.k + cam.x, y: wy * cam.k + cam.y };
 }
@@ -136,19 +156,20 @@ export function boardClampPan(
 
 /**
  * Fit the whole content bbox into the viewport (centered, padded). Wide
- * boards shrink fully into view; tiny boards never blow up past the cap.
+ * boards shrink as far as needed to show everything — fit is allowed
+ * below the interaction minimum (the ladder is for gestures, not for
+ * the initial framing); tiny boards never blow up past the cap.
  */
 export function boardFit(
   content: BoardRect,
   viewport: BoardViewport,
-  opts: { pad?: number; floor?: number; cap?: number } = {},
+  opts: { pad?: number; cap?: number } = {},
 ): BoardCamera {
   const pad = opts.pad ?? BOARD_FIT_PAD;
-  const floor = opts.floor ?? BOARD_FIT_FLOOR;
   const cap = opts.cap ?? BOARD_FIT_CAP;
   const kw = content.w > 0 ? (viewport.w - pad * 2) / content.w : cap;
   const kh = content.h > 0 ? (viewport.h - pad * 2) / content.h : cap;
-  const k = Math.min(cap, Math.max(floor, Math.min(kw, kh)));
+  const k = Math.min(cap, Math.min(kw, kh));
   return {
     k,
     x: (viewport.w - content.w * k) / 2 - content.x * k,

package/src/utils/boardEdges.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
 import {
   boardAnchor,
   boardEdgePath,
+  boardFanOrdinals,
   boardViaPath,
   type BoardNodeRect,
 } from "./boardEdges";
@@ -39,6 +40,39 @@ describe("boardEdges — anchor modes", () => {
   });
 });
 
+describe("boardEdges — fan ordinals", () => {
+  it("gives a single edge the full fan (count = 1, no spread)", () => {
+    const ord = boardFanOrdinals([{ id: "e1", from: "a" }]);
+    expect(ord.get("e1")).toEqual({ index: 0, count: 1 });
+  });
+
+  it("spreads three edges from one node as {0,3} {1,3} {2,3}", () => {
+    const ord = boardFanOrdinals([
+      { id: "e1", from: "a" },
+      { id: "e2", from: "a" },
+      { id: "e3", from: "a" },
+    ]);
+    expect(ord.get("e1")).toEqual({ index: 0, count: 3 });
+    expect(ord.get("e2")).toEqual({ index: 1, count: 3 });
+    expect(ord.get("e3")).toEqual({ index: 2, count: 3 });
+  });
+
+  it("counts each source node independently", () => {
+    const ord = boardFanOrdinals([
+      { id: "e1", from: "a" },
+      { id: "e2", from: "b" },
+      { id: "e3", from: "a" },
+    ]);
+    expect(ord.get("e1")).toEqual({ index: 0, count: 2 });
+    expect(ord.get("e2")).toEqual({ index: 0, count: 1 });
+    expect(ord.get("e3")).toEqual({ index: 1, count: 2 });
+  });
+
+  it("returns an empty map for empty input", () => {
+    expect(boardFanOrdinals([]).size).toBe(0);
+  });
+});
+
 describe("boardEdges — route styles", () => {
   const a = { x: 220, y: 130 };
   const b = { x: 400, y: 260 };

package/src/utils/boardEdges.ts

@@ -35,6 +35,29 @@ export interface BoardPoint {
   y: number;
 }
 
+/**
+ * Fan ordinals for a set of edges: every edge sharing a `from` node gets
+ * its `{ index, count }` slot in the 天女散花 spread across that node's
+ * exit border. Two passes — totals first, then positions — so `count` is
+ * the FINAL total per node (a running count would feed the first edges
+ * count = 1 and collapse the whole fan onto one anchor point). Edges from
+ * different nodes are counted independently.
+ */
+export function boardFanOrdinals(
+  edges: ReadonlyArray<{ id: string; from: string }>,
+): Map<string, { index: number; count: number }> {
+  const totals = new Map<string, number>();
+  for (const e of edges) totals.set(e.from, (totals.get(e.from) ?? 0) + 1);
+  const seen = new Map<string, number>();
+  const ordinals = new Map<string, { index: number; count: number }>();
+  for (const e of edges) {
+    const index = seen.get(e.from) ?? 0;
+    seen.set(e.from, index + 1);
+    ordinals.set(e.id, { index, count: totals.get(e.from)! });
+  }
+  return ordinals;
+}
+
 export interface BoardNodeRect {
   x: number;
   y: number;