@celestia-island/hikari 0.35.0 → 0.35.1

package/package.json

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

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/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;