@celestia-island/hikari 0.55.102 → 0.55.103

package/package.json

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

package/src/board3dSurface.test.ts

@@ -52,6 +52,23 @@ describe("hikari barrel — 3D board surface", () => {
     expect(barrel.BOARD3D_HELPERS_LAYER).toBe(1);
   });
 
+  it("exports the main-camera gizmo layer and the hover-frame geometry", () => {
+    // Consumers drawing their own main-camera-only affordance (and the
+    // tests pinning that the minimap never sees one) need the layer; the
+    // corner-bracket maths is shared so a bespoke frame matches the
+    // built-in one.
+    expect(barrel.BOARD3D_MAIN_LAYER).toBe(2);
+    expect(typeof barrel.hoverBoxSegments).toBe("function");
+    expect(barrel.hoverBoxSegments([1, 1, 1])).toHaveLength(48 * 3);
+    for (const name of [
+      "HOVER_BOX_ARM_RATIO",
+      "HOVER_BOX_PADDING",
+      "HOVER_BOX_MIN_EXTENT_RATIO",
+    ] as const) {
+      expect(typeof (barrel as Record<string, unknown>)[name], name).toBe("number");
+    }
+  });
+
   it("exports the scene3d utilities (palette, orbit, fit, zoom)", () => {
     const fns = [
       "hashIdToUnit",

package/src/components/HkBoard3D.test.tsx

@@ -74,7 +74,7 @@ vi.mock("three/examples/jsm/renderers/CSS2DRenderer.js", async (importOriginal)
   return { ...actual, CSS2DRenderer: FakeCSS2DRenderer };
 });
 
-import HkBoard3D, { type Board3DEngine } from "./HkBoard3D";
+import HkBoard3D, { BOARD3D_MAIN_LAYER, type Board3DEngine } from "./HkBoard3D";
 
 const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
 
@@ -687,3 +687,379 @@ describe("HkBoard3D", () => {
     expect(engine!.objects().size).toBe(0);
   });
 });
+
+describe("HkBoard3D hover frame", () => {
+  /** The frame is the only scene child on the main-camera-only layer. */
+  function frameOf(engine: Board3DEngine): THREE.LineSegments {
+    const found = engine.scene.children.find((c) => c.layers.isEnabled(BOARD3D_MAIN_LAYER));
+    expect(found, "hover frame in the scene").toBeDefined();
+    return found as THREE.LineSegments;
+  }
+
+  function canvasOf(): HTMLCanvasElement {
+    const canvas = mounts[0].container.querySelector("canvas")!;
+    canvas.getBoundingClientRect = () =>
+      ({ left: 0, top: 0, width: 800, height: 600, right: 800, bottom: 600 }) as DOMRect;
+    return canvas;
+  }
+
+  /** The board root — the element the pointer must actually leave. */
+  function boardOf(): HTMLElement {
+    return mounts[0].container.querySelector(".hk-board3d") as HTMLElement;
+  }
+
+  function moveTo(canvas: HTMLCanvasElement, x: number, y: number): void {
+    canvas.dispatchEvent(new PointerEvent("pointermove", { bubbles: true, clientX: x, clientY: y }));
+  }
+
+  interface HoverHandlers {
+    hover?: (id: string | null) => void;
+    click?: (id: string) => void;
+  }
+
+  async function hoveredBoard(props: Record<string, unknown> = {}, on: HoverHandlers = {}) {
+    let engine: Board3DEngine | null = null;
+    mountBoard(props, {
+      ready: ((e: Board3DEngine) => { engine = e; }) as never,
+      objectHover: ((id: string | null) => on.hover?.(id)) as never,
+      objectClick: ((id: string) => on.click?.(id)) as never,
+    });
+    await nextTick();
+    const canvas = canvasOf();
+    const body = new THREE.Mesh(
+      new THREE.SphereGeometry(2, 16, 12),
+      new THREE.MeshBasicMaterial(),
+    );
+    body.name = "body";
+    engine!.setObject("star-1", { object: body });
+    await tickFrames();
+    moveTo(canvas, 400, 300);
+    await tickFrames();
+    return { engine: engine!, canvas, board: boardOf(), body };
+  }
+
+  it("wraps the hovered object in the corner frame without resizing it", async () => {
+    const { engine, body } = await hoveredBoard();
+    const frame = frameOf(engine);
+    expect(frame.visible).toBe(true);
+    // A radius-2 sphere at the origin: a 4-unit box plus the padding,
+    // placed by the frame's own matrix — the object is untouched.
+    expect(frame.matrix.elements[0]).toBeCloseTo(4 * 1.08, 4);
+    expect(frame.matrix.elements[13]).toBeCloseTo(0, 5);
+    expect(body.scale.x).toBe(1);
+    // The gizmo never joins picking or framing.
+    expect(engine.objects().get("star-1")!.object).toBe(body);
+    expect(frame.material).toBeInstanceOf(THREE.LineBasicMaterial);
+    expect((frame.material as THREE.LineBasicMaterial).depthTest).toBe(false);
+  });
+
+  it("hides the frame once the pointer leaves the body and the board", async () => {
+    const hovers: Array<string | null> = [];
+    const { engine, canvas, board } = await hoveredBoard({}, { hover: (id) => hovers.push(id) });
+    const frame = frameOf(engine);
+    expect(frame.visible).toBe(true);
+
+    moveTo(canvas, 10, 10);
+    await tickFrames();
+    expect(frame.visible).toBe(false);
+
+    moveTo(canvas, 400, 300);
+    await tickFrames();
+    expect(frame.visible).toBe(true);
+    board.dispatchEvent(new PointerEvent("pointerleave", { bubbles: false }));
+    await tickFrames();
+    expect(frame.visible).toBe(false);
+    // The event a page closes its hover card on.
+    expect(hovers).toEqual(["star-1", null, "star-1", null]);
+  });
+
+  it("keeps the hover while the pointer is on the board's own chrome", async () => {
+    const hovers: Array<string | null> = [];
+    const { engine, canvas } = await hoveredBoard({}, { hover: (id) => hovers.push(id) });
+    const frame = frameOf(engine);
+
+    // The CSS2D label chips and the minimap card overlap the canvas as
+    // SIBLINGS: reaching for a chip fires pointerleave on the canvas while
+    // the user is still on the object. The hover must survive that.
+    canvas.dispatchEvent(new PointerEvent("pointerleave", { bubbles: false }));
+    await tickFrames();
+    expect(frame.visible).toBe(true);
+    expect(hovers).toEqual(["star-1"]);
+  });
+
+  it("measures the frame target, and honours a per-object opt-out", async () => {
+    let engine: Board3DEngine | null = null;
+    mountBoard({}, { ready: ((e: Board3DEngine) => { engine = e; }) as never });
+    await nextTick();
+    const canvas = canvasOf();
+
+    // A body wearing a corona ten times its size AND a satellite parked
+    // 10 units out. The sprite is pruned as decoration either way, so the
+    // satellite is what makes this test discriminate: measuring the group
+    // instead of `frameObject` would wrap the moon system, not the body.
+    const group = new THREE.Group();
+    const mesh = new THREE.Mesh(new THREE.SphereGeometry(1, 16, 12), new THREE.MeshBasicMaterial());
+    group.add(mesh);
+    const corona = new THREE.Sprite(new THREE.SpriteMaterial());
+    corona.scale.setScalar(20);
+    group.add(corona);
+    const satellite = new THREE.Mesh(
+      new THREE.SphereGeometry(0.2, 8, 6),
+      new THREE.MeshBasicMaterial(),
+    );
+    satellite.position.set(10, 0, 0);
+    group.add(satellite);
+    engine!.setObject("hub", { object: group, frameObject: mesh });
+    await tickFrames();
+    moveTo(canvas, 400, 300);
+    await tickFrames();
+    expect(frameOf(engine!).matrix.elements[0]).toBeCloseTo(2 * 1.08, 4);
+    expect(frameOf(engine!).matrix.elements[12]).toBeCloseTo(0, 5);
+    // Sanity: the group as a whole would have measured far wider.
+    expect(frameOf(engine!).matrix.elements[0]).toBeLessThan(10);
+
+    // frameObject: null opts the object out entirely.
+    engine!.setObject("hub", { object: group, frameObject: null });
+    await tickFrames();
+    expect(frameOf(engine!).visible).toBe(false);
+  });
+
+  it("never shows a frame when hoverBox is off, and still clicks", async () => {
+    const clicks: string[] = [];
+    const { engine, canvas } = await hoveredBoard({ hoverBox: false }, { click: (id) => clicks.push(id) });
+    expect(frameOf(engine).visible).toBe(false);
+    moveTo(canvas, 400, 300);
+    await tickFrames();
+    expect(frameOf(engine).visible).toBe(false);
+    // The picking contract itself is untouched by the opt-out.
+    canvas.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, clientX: 400, clientY: 300 }));
+    canvas.dispatchEvent(new PointerEvent("pointerup", { bubbles: true, clientX: 400, clientY: 300 }));
+    expect(clicks).toEqual(["star-1"]);
+  });
+
+  it("keeps only the main camera on the gizmo layer", async () => {
+    let engine: Board3DEngine | null = null;
+    mountBoard({}, { ready: ((e: Board3DEngine) => { engine = e; }) as never });
+    await nextTick();
+    expect(engine!.camera.layers.isEnabled(BOARD3D_MAIN_LAYER)).toBe(true);
+    // The minimap camera enables the helper layer only — its render pass
+    // must not pick the pointer affordance up.
+    expect(frameOf(engine!).layers.mask).toBe(1 << BOARD3D_MAIN_LAYER);
+  });
+
+  it("re-measures the frame when a rebuild hands the hovered id a new object", async () => {
+    const { engine } = await hoveredBoard();
+    const frame = frameOf(engine);
+    expect(frame.matrix.elements[12]).toBeCloseTo(0, 5);
+
+    // Pages rebuild their content: the frame must follow the object that
+    // is actually registered now, not the one that left the scene.
+    const next = new THREE.Mesh(
+      new THREE.SphereGeometry(1, 12, 8),
+      new THREE.MeshBasicMaterial(),
+    );
+    next.position.set(30, 0, 0);
+    engine.setObject("star-1", { object: next });
+    await tickFrames();
+    expect(frame.visible).toBe(true);
+    expect(frame.matrix.elements[12]).toBeCloseTo(30, 4);
+    expect(frame.matrix.elements[0]).toBeCloseTo(2 * 1.08, 4);
+  });
+
+  it("follows the target in and out of visibility, and drops a stale opt-out", async () => {
+    const hovers: Array<string | null> = [];
+    const { engine, body, canvas } = await hoveredBoard({}, { hover: (id) => hovers.push(id) });
+    const frame = frameOf(engine);
+    expect(frame.visible).toBe(true);
+
+    // Hidden under a hidden ancestor (three renders by the CHAIN, not by
+    // the node's own flag): the bracket must stop painting the air.
+    body.visible = false;
+    await tickFrames();
+    expect(frame.visible).toBe(false);
+
+    body.visible = true;
+    await tickFrames();
+    expect(frame.visible).toBe(true);
+
+    // …and an id re-registered as unselectable loses its frame too.
+    engine.setObject("star-1", { object: body, pickable: false });
+    await tickFrames();
+    expect(frame.visible).toBe(false);
+    // The pointer can no longer select it: the page must hear that here,
+    // because no pointer movement is coming to say it.
+    expect(hovers.at(-1)).toBeNull();
+    expect(canvas.style.cursor).toBe("");
+  });
+
+  it("hides the frame when an ANCESTOR of the frame target is hidden", async () => {
+    const hovers: Array<string | null> = [];
+    let engine: Board3DEngine | null = null;
+    mountBoard({}, {
+      ready: ((e: Board3DEngine) => { engine = e; }) as never,
+      objectHover: ((id: string | null) => hovers.push(id)) as never,
+    });
+    await nextTick();
+    const canvas = canvasOf();
+
+    // The target stays `visible = true` while its PARENT is hidden: only
+    // the renderer's ancestor-chain rule catches that.
+    const group = new THREE.Group();
+    const mesh = new THREE.Mesh(new THREE.SphereGeometry(1, 12, 8), new THREE.MeshBasicMaterial());
+    group.add(mesh);
+    engine!.setObject("wrap", { object: group, frameObject: mesh });
+    await tickFrames();
+    moveTo(canvas, 400, 300);
+    await tickFrames();
+    expect(frameOf(engine!).visible).toBe(true);
+
+    group.visible = false;
+    await tickFrames();
+    expect(mesh.visible).toBe(true);
+    expect(frameOf(engine!).visible).toBe(false);
+
+    group.visible = true;
+    await tickFrames();
+    expect(frameOf(engine!).visible).toBe(true);
+  });
+
+  it("picks the frame up when the content arrives after the hover", async () => {
+    let engine: Board3DEngine | null = null;
+    mountBoard({}, { ready: ((e: Board3DEngine) => { engine = e; }) as never });
+    await nextTick();
+    const canvas = canvasOf();
+
+    // Content streams in: the registered group is empty (its only mesh is
+    // still hidden) when the pointer settles on it.
+    const group = new THREE.Group();
+    const mesh = new THREE.Mesh(new THREE.SphereGeometry(1, 12, 8), new THREE.MeshBasicMaterial());
+    mesh.visible = false;
+    group.add(mesh);
+    engine!.setObject("stream", { object: group });
+    await tickFrames();
+    moveTo(canvas, 400, 300);
+    await tickFrames();
+    expect(frameOf(engine!).visible).toBe(false);
+
+    mesh.visible = true;
+    await tickFrames();
+    expect(frameOf(engine!).visible).toBe(true);
+  });
+
+  it("re-measures an unmeasurable target on a cadence, not every frame", async () => {
+    let engine: Board3DEngine | null = null;
+    // No minimap: its marker sync calls updateWorldMatrix on every
+    // registered object each frame, which would drown the measurement
+    // cadence this test is about.
+    mountBoard({ minimap: false }, { ready: ((e: Board3DEngine) => { engine = e; }) as never });
+    await nextTick();
+    const canvas = canvasOf();
+
+    // Content that never becomes measurable (a group of decor only) must
+    // not turn every frame into a subtree walk — but the board must still
+    // look again, or streaming content would never be framed.
+    const group = new THREE.Group();
+    const decor = new THREE.Sprite(new THREE.SpriteMaterial());
+    group.add(decor);
+    engine!.setObject("empty", { object: group });
+    await tickFrames();
+    moveTo(canvas, 400, 300);
+    await tickFrames();
+    expect(frameOf(engine!).visible).toBe(false);
+
+    let frames = 0;
+    engine!.addTick(() => {
+      frames += 1;
+    });
+    // The measurement is the walk `frameLocalBounds` makes on the anchor.
+    const walk = vi.spyOn(group, "updateWorldMatrix");
+    await tickFrames();
+    expect(frames).toBeGreaterThan(10);
+    expect(walk.mock.calls.length).toBeGreaterThan(0);
+    expect(walk.mock.calls.length).toBeLessThan(frames / 3);
+  });
+
+  it("tints the frame from the palette: near-white by night, grey by day", async () => {
+    const previous = ["--color-background", "--color-text", "--color-muted"].map((name) => [
+      name,
+      document.documentElement.style.getPropertyValue(name),
+    ] as const);
+    try {
+      // Deliberately NOT the fallback literals: a variable read that fell
+      // through to its default must fail these assertions.
+      document.documentElement.style.setProperty("--color-background", "10 15 25");
+      document.documentElement.style.setProperty("--color-text", "250 10 10");
+      document.documentElement.style.setProperty("--color-muted", "10 250 10");
+      const { engine } = await hoveredBoard();
+      const color = (frameOf(engine).material as THREE.LineBasicMaterial).color;
+      // Night: the TEXT channel.
+      expect(color.r * 255).toBeCloseTo(250, 0);
+      expect(color.g * 255).toBeCloseTo(10, 0);
+
+      // Day: the MUTED channel — and a live theme mutation re-tints the
+      // frame in place.
+      document.documentElement.style.setProperty("--color-background", "245 245 240");
+      await tickFrames();
+      expect(color.g * 255).toBeCloseTo(250, 0);
+      expect(color.r * 255).toBeCloseTo(10, 0);
+    } finally {
+      for (const [name, value] of previous) {
+        document.documentElement.style.removeProperty(name);
+        if (value) document.documentElement.style.setProperty(name, value);
+      }
+    }
+  });
+
+  it("detaches and frees the frame, and its listeners, on unmount", async () => {
+    const { engine, board } = await hoveredBoard();
+    const frame = frameOf(engine);
+    const geoSpy = vi.spyOn(frame.geometry, "dispose");
+    const matSpy = vi.spyOn(frame.material as THREE.Material, "dispose");
+    // A container listener left behind keeps a dead board reachable — and
+    // a remount would stack a second one.
+    const removeSpy = vi.spyOn(board, "removeEventListener");
+
+    const m = mounts.splice(0)[0];
+    m.app.unmount();
+    m.container.remove();
+
+    expect(geoSpy).toHaveBeenCalled();
+    expect(matSpy).toHaveBeenCalled();
+    expect(removeSpy).toHaveBeenCalledWith("pointerleave", expect.any(Function));
+    expect(engine.scene.children.some((c) => c.layers.isEnabled(BOARD3D_MAIN_LAYER))).toBe(false);
+  });
+
+  it("never resurrects the hover after the pointer has left the board", async () => {
+    const hovers: Array<string | null> = [];
+    const { engine, canvas, board } = await hoveredBoard({}, { hover: (id) => hovers.push(id) });
+    const frame = frameOf(engine);
+    expect(frame.visible).toBe(true);
+
+    // A move and a leave inside ONE frame: the pending pick must not be
+    // replayed against the stale position on the next loop iteration.
+    moveTo(canvas, 400, 300);
+    board.dispatchEvent(new PointerEvent("pointerleave", { bubbles: false }));
+    await tickFrames();
+    expect(frame.visible).toBe(false);
+    expect(hovers.at(-1)).toBeNull();
+
+    // …and it stays left, however many frames pass.
+    await tickFrames();
+    expect(frame.visible).toBe(false);
+    expect(hovers.filter((id) => id === "star-1").length).toBe(1);
+  });
+
+  it("tells the page when the hovered object leaves the registry", async () => {
+    const hovers: Array<string | null> = [];
+    const { engine, canvas } = await hoveredBoard({}, { hover: (id) => hovers.push(id) });
+    expect(canvas.style.cursor).toBe("pointer");
+
+    // The object is gone: no pointer movement will ever clear the hover,
+    // so the board has to say it here (and stop promising a click).
+    engine.setObject("star-1", null);
+    await tickFrames();
+    expect(hovers.at(-1)).toBeNull();
+    expect(canvas.style.cursor).toBe("");
+    expect(frameOf(engine).visible).toBe(false);
+  });
+});

package/src/components/HkBoard3D.tsx

@@ -17,6 +17,9 @@
  *  - PICKING: click (press-release inside a 4 px slop) and hover both
  *    raycast the pickable set and surface the REGISTERED id (children
  *    walk up to the registered root via userData);
+ *  - HOVER FRAME: the hovered object is wrapped in an 8-corner selection
+ *    frame (default ON, see the `hoverBox` prop) — the pointer marks what
+ *    it is aiming at instead of resizing it;
  *  - LABELS: a CSS2DRenderer overlay — HTML chips that track world
  *    anchors, pointer-events opt-in per chip so drags still orbit;
  *  - MINIMAP: HkMinimap3D pinned bottom-right — a second, stereoscopic
@@ -71,11 +74,16 @@ import {
   type Board3DLightingDescriptor,
   type LightingRigOptions,
 } from "../scene3d/lighting";
-import { BOARD3D_HELPERS_LAYER, fitDistance } from "../utils/scene3d";
+import { BOARD3D_HELPERS_LAYER, BOARD3D_MAIN_LAYER, fitDistance } from "../utils/scene3d";
+import {
+  createHoverBox,
+  isVisibleInHierarchy,
+  type HoverBoxHandle,
+} from "./board3dHoverBox";
 import HkMinimap3D from "./HkMinimap3D";
 import "./HkBoard3D.scss";
 
-export { BOARD3D_HELPERS_LAYER };
+export { BOARD3D_HELPERS_LAYER, BOARD3D_MAIN_LAYER };
 
 export interface Board3DObjectDef {
   /** The scene-graph root for this content item. The board adds/removes
@@ -94,6 +102,11 @@ export interface Board3DObjectDef {
   marker?: "dot" | "cube" | "none";
   /** Minimap marker colour (any CSS colour; default theme primary). */
   markerColor?: string;
+  /** What the hover frame wraps, measured inside `object`'s space
+   *  (default `object` itself). Point it at the body mesh when satellites,
+   *  coronas or other decoration should stay outside the box, or pass
+   *  `null` to opt this object out of the frame entirely. */
+  frameObject?: THREE.Object3D | null;
 }
 
 export interface Board3DEngine {
@@ -225,6 +238,13 @@ function studioEnvironment(renderer: THREE.WebGLRenderer): THREE.Texture {
   return tex;
 }
 
+/** How many frames to wait before re-measuring a hovered target that had
+ *  nothing measurable (≈ 100 ms at 60 fps): fast enough that content
+ *  streaming in under a resting pointer gets its frame, slow enough that
+ *  an unmeasurable target costs one subtree walk per interval instead of
+ *  one per frame. */
+const HOVER_BOX_RETRY_FRAMES = 6;
+
 /** A pose component is usable only if all three numbers are finite. */
 function isFiniteVec3(v: readonly number[] | undefined): v is readonly [number, number, number] {
   return (
@@ -250,6 +270,27 @@ function cssRgbToColor(raw: string): THREE.Color {
   );
 }
 
+/** Perceived brightness of a palette triplet, 0 (black) … 1 (white). */
+function colorLuminance(color: THREE.Color): number {
+  return 0.2126 * color.r + 0.7152 * color.g + 0.0722 * color.b;
+}
+
+/**
+ * The hover frame's tint, taken from the page's own palette: the TEXT
+ * channel in a dark room, the MUTED channel in a light one. That is the
+ * user's rule — a whitish bracket over a night sky, a grey one over a day
+ * sky — expressed with tokens rather than literals, so a consumer that
+ * re-skins the palette re-skins the frame with it.
+ */
+function hoverFrameColor(background: THREE.Color): THREE.Color {
+  const dark = colorLuminance(background) < 0.5;
+  return cssRgbToColor(
+    dark
+      ? readCssColor("--color-text", "247 249 252")
+      : readCssColor("--color-muted", "80 80 80"),
+  );
+}
+
 export default defineComponent({
   name: "HkBoard3D",
   props: {
@@ -285,9 +326,16 @@ export default defineComponent({
     /** Keep the camera's near/far planes clipped to the framed extent
      *  (large scenes lose depth precision without it). */
     autoClipping: { type: Boolean, default: false },
+    /** Wrap the hovered object in the 8-corner selection frame. Defaults
+     *  ON: anything the pointer can select gets one, and `frameObject:
+     *  null` opts a single object out. Turn it off for boards whose
+     *  content is not "selected" at all. */
+    hoverBox: { type: Boolean, default: true },
     /** Freeze the frame loop (content keeps its last pose). An animated
      *  flight issued while paused lands in a single jump on resume: the
-     *  tween is evaluated against wall-clock time. */
+     *  tween is evaluated against wall-clock time. Hover is frozen with
+     *  it: the frame keeps whatever it had painted until the loop resumes
+     *  (nothing re-renders while paused). */
     paused: { type: Boolean, default: false },
   },
   emits: {
@@ -308,6 +356,7 @@ export default defineComponent({
     let scene: THREE.Scene | null = null;
     let camera: THREE.PerspectiveCamera | null = null;
     let controls: OrbitControls | null = null;
+    let hoverFrame: HoverBoxHandle | null = null;
     let resizeObs: ResizeObserver | null = null;
     let themeObs: MutationObserver | null = null;
     let rafId = 0;
@@ -353,6 +402,7 @@ export default defineComponent({
       const bg = cssRgbToColor(bgRaw);
       if (scene) scene.background = bg;
       if (renderer) renderer.setClearColor(bg, 1);
+      hoverFrame?.setColor(hoverFrameColor(bg));
       for (const cb of themeHooks) cb(bgRaw, primaryRaw);
     }
 
@@ -399,6 +449,16 @@ export default defineComponent({
     }
 
     const lastPointer = { x: 0, y: 0 };
+    /** True while the frame has been measured for the current hover. The
+     *  measurement is the expensive half, so it happens on hover change
+     *  only — the per-frame half is one matrix composition. */
+    let frameBound = false;
+    /** Frames still to skip before the next measurement attempt while the
+     *  hovered target has nothing measurable to wrap (content still
+     *  streaming in). A permanently unmeasurable target — a group of
+     *  sprites, content that stays hidden — must not turn the loop into a
+     *  full subtree walk every frame. */
+    let measureCooldown = 0;
 
     function onPointerMove(e: PointerEvent): void {
       hoverDirty = true;
@@ -406,6 +466,26 @@ export default defineComponent({
       lastPointer.y = e.clientY;
     }
 
+    /** Leaving the BOARD drops the hover: nothing is under the pointer any
+     *  more, and a frame left hanging around reads as a stuck selection.
+     *
+     *  This listens on the CONTAINER, not the canvas, and that is the whole
+     *  point: the CSS2D label chips and the minimap card sit ON TOP of the
+     *  canvas as siblings, so a pointer moving from a body onto its own
+     *  chip fires `pointerleave` on the canvas while the user is still
+     *  "on" the object — a hover card opened from `objectHover` would slam
+     *  shut as the user reached for it. */
+    function onPointerLeave(): void {
+      // Drop the PENDING pick as well: a move and a leave can land inside
+      // one frame, and the loop would otherwise re-pick the stale position
+      // and resurrect the hover after the pointer has left the board.
+      hoverDirty = false;
+      if (lastHover === null) return;
+      lastHover = null;
+      if (canvasRef.value) canvasRef.value.style.cursor = "";
+      emit("objectHover", null);
+    }
+
     function onPointerDown(e: PointerEvent): void {
       pressAt = { pointerId: e.pointerId, x: e.clientX, y: e.clientY };
       // Capture every press: up/cancel are only guaranteed while capture
@@ -444,6 +524,42 @@ export default defineComponent({
       return x < 0.5 ? 4 * x * x * x : 1 - Math.pow(-2 * x + 2, 3) / 2;
     }
 
+    /**
+     * Keep the hover frame on what the pointer is aiming at: measure once
+     * per hover, then ride the target's world matrix.
+     *
+     * The frame is hidden — and the latch released, so the next frame
+     * looks again — whenever there is nothing to mark: no hover, a cleared
+     * id, `hoverBox: false`, an object re-registered as `pickable: false`
+     * (the pointer can no longer select it), `frameObject: null`, or a
+     * target the renderer is not drawing (hidden itself or under a hidden
+     * ancestor). A target that measures to nothing measurable yet —
+     * content still streaming in under a resting pointer — also stays
+     * un-latched, which is what lets the frame appear when the content
+     * finally lands.
+     */
+    function syncHoverFrame(): void {
+      if (!hoverFrame) return;
+      const def = props.hoverBox && lastHover !== null ? registry.get(lastHover) : undefined;
+      const target = def ? (def.frameObject === null ? null : (def.frameObject ?? def.object)) : null;
+      if (!def || def.pickable === false || !target || !isVisibleInHierarchy(target)) {
+        hoverFrame.hide();
+        frameBound = false;
+        measureCooldown = 0;
+        return;
+      }
+      if (!frameBound) {
+        if (measureCooldown > 0) {
+          measureCooldown -= 1;
+          return;
+        }
+        frameBound = hoverFrame.attach(def.object, target);
+        measureCooldown = frameBound ? 0 : HOVER_BOX_RETRY_FRAMES;
+        return;
+      }
+      hoverFrame.refresh();
+    }
+
     function frame(): void {
       if (disposed) return;
       rafId = requestAnimationFrame(frame);
@@ -468,12 +584,17 @@ export default defineComponent({
         const id = pickAt(lastPointer.x, lastPointer.y);
         if (id !== lastHover) {
           lastHover = id;
+          frameBound = false;
+          measureCooldown = 0;
           if (canvasRef.value) {
             canvasRef.value.style.cursor = id ? "pointer" : "";
           }
           emit("objectHover", id);
         }
       }
+      // After the tick hooks have posed the content, so the frame lands on
+      // this frame's pose rather than the previous one.
+      syncHoverFrame();
 
       renderer.render(scene, camera);
       labelRenderer?.render(scene, camera);
@@ -486,11 +607,18 @@ export default defineComponent({
       if (!canvas || !container) return;
 
       scene = new THREE.Scene();
+      // The hover frame is a pointer affordance, not scenery: it hangs off
+      // the scene root (so it never joins framing, markers or picking) and
+      // rides the main-camera-only layer, keeping the minimap render clean.
+      hoverFrame = createHoverBox();
+      hoverFrame.object.layers.set(BOARD3D_MAIN_LAYER);
+      scene.add(hoverFrame.object);
       // A degenerate fov (≤ 0 or ≥ 180) silently bricks the projection —
       // projectionMatrix[5] becomes Infinity/negative, projection and
       // picking return NaN, and nothing throws. Fall back to the default.
       const fov = Number.isFinite(props.fov) && props.fov > 0 && props.fov < 180 ? props.fov : 45;
       camera = new THREE.PerspectiveCamera(fov, 1, 0.1, 4000);
+      camera.layers.enable(BOARD3D_MAIN_LAYER);
       // Guard the initial pose too: a non-finite component (an untyped
       // caller passing a short/garbage array) would poison every
       // projection for the board's whole lifetime.
@@ -547,6 +675,7 @@ export default defineComponent({
       canvas.addEventListener("pointerup", onPointerUp);
       canvas.addEventListener("pointercancel", onPointerCancel);
       canvas.addEventListener("lostpointercapture", onLostPointerCapture, true);
+      container.addEventListener("pointerleave", onPointerLeave);
 
       /** Depth planes from a subject distance (large scenes need it). */
       function applyClipping(dist: number): void {
@@ -573,6 +702,25 @@ export default defineComponent({
         },
         setObject(id, def) {
           const prev = registry.get(id);
+          // A re-register can hand over a DIFFERENT object (pages rebuild
+          // their content), and a frame still measured against the old one
+          // would hang where that object used to be — it is out of the
+          // scene now and never moves again. Measure again on the next
+          // frame instead.
+          if (id === lastHover) {
+            frameBound = false;
+            measureCooldown = 0;
+            // The hovered object either left the board or became
+            // unselectable. Nothing will move the pointer for us, so the
+            // page has to be told here — otherwise its hover card outlives
+            // the object and the cursor keeps promising a click that can
+            // no longer land.
+            if (!def || def.pickable === false) {
+              lastHover = null;
+              if (canvasRef.value) canvasRef.value.style.cursor = "";
+              emit("objectHover", null);
+            }
+          }
           if (prev) {
             // One Object3D can be registered under several ids; only
             // detach it from the scene when no other id still owns it.
@@ -816,6 +964,13 @@ export default defineComponent({
         canvas.removeEventListener("pointercancel", onPointerCancel);
         canvas.removeEventListener("lostpointercapture", onLostPointerCapture, true);
       }
+      containerRef.value?.removeEventListener("pointerleave", onPointerLeave);
+      if (hoverFrame) {
+        scene?.remove(hoverFrame.object);
+        hoverFrame.dispose();
+        hoverFrame = null;
+      }
+      frameBound = false;
       controls?.dispose();
       if (labelRenderer?.domElement.parentNode) {
         labelRenderer.domElement.parentNode.removeChild(labelRenderer.domElement);

package/src/components/board3dHoverBox.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, it, vi } from "vitest";
+import * as THREE from "three";
+
+import {
+  createHoverBox,
+  frameLocalBounds,
+  isVisibleInHierarchy,
+  normalizeHoverBounds,
+} from "./board3dHoverBox";
+import { HOVER_BOX_MIN_EXTENT_RATIO, HOVER_BOX_PADDING } from "../utils/scene3d";
+
+/** A body mesh plus the decoration a scene normally hangs off it: a glow
+ *  sprite far larger than the body and a CSS2D label anchor. */
+function fixture() {
+  const anchor = new THREE.Group();
+  const body = new THREE.Mesh(
+    new THREE.BoxGeometry(2, 2, 2),
+    new THREE.MeshBasicMaterial(),
+  );
+  body.position.set(3, 0, 0);
+  anchor.add(body);
+
+  const corona = new THREE.Sprite(new THREE.SpriteMaterial());
+  corona.scale.setScalar(100);
+  anchor.add(corona);
+
+  const chip = new THREE.Mesh(new THREE.BoxGeometry(50, 50, 50), new THREE.MeshBasicMaterial());
+  (chip as unknown as { isCSS2DObject: boolean }).isCSS2DObject = true;
+  anchor.add(chip);
+
+  anchor.updateMatrixWorld(true);
+  return { anchor, body, corona, chip };
+}
+
+describe("frameLocalBounds", () => {
+  it("measures the shape only — sprites and CSS2D anchors are decoration", () => {
+    const { anchor } = fixture();
+    const box = frameLocalBounds(anchor, anchor);
+    expect(box.min.x).toBeCloseTo(2, 5);
+    expect(box.max.x).toBeCloseTo(4, 5);
+    expect(box.min.y).toBeCloseTo(-1, 5);
+    expect(box.max.z).toBeCloseTo(1, 5);
+  });
+
+  it("measures inside the anchor's space, not the world's", () => {
+    const { anchor } = fixture();
+    const before = frameLocalBounds(anchor, anchor).clone();
+    anchor.position.set(40, -12, 7);
+    anchor.updateMatrixWorld(true);
+    const after = frameLocalBounds(anchor, anchor);
+    for (let axis = 0; axis < 3; axis += 1) {
+      expect(after.min.getComponent(axis)).toBeCloseTo(before.min.getComponent(axis), 5);
+      expect(after.max.getComponent(axis)).toBeCloseTo(before.max.getComponent(axis), 5);
+    }
+  });
+
+  it("can bound a subtree the frame target points at", () => {
+    const { anchor, body } = fixture();
+    const box = frameLocalBounds(anchor, body);
+    // The body alone: centred on its own origin, no corona, no chip.
+    expect(box.getSize(new THREE.Vector3()).toArray()).toEqual([2, 2, 2]);
+  });
+
+  it("prunes invisible subtrees", () => {
+    const { anchor } = fixture();
+    const hidden = new THREE.Mesh(
+      new THREE.BoxGeometry(80, 80, 80),
+      new THREE.MeshBasicMaterial(),
+    );
+    anchor.add(hidden);
+    expect(frameLocalBounds(anchor, anchor).max.x).toBeCloseTo(40, 5);
+
+    hidden.visible = false;
+    expect(frameLocalBounds(anchor, anchor).max.x).toBeCloseTo(4, 5);
+  });
+
+  it("returns an empty box for a subtree with nothing measurable", () => {
+    const anchor = new THREE.Group();
+    anchor.add(new THREE.Object3D());
+    expect(frameLocalBounds(anchor, anchor).isEmpty()).toBe(true);
+  });
+});
+
+describe("normalizeHoverBounds", () => {
+  it("pads every axis around the centre", () => {
+    const box = new THREE.Box3(new THREE.Vector3(-1, -2, -3), new THREE.Vector3(1, 2, 3));
+    expect(normalizeHoverBounds(box)).toBe(true);
+    expect(box.min.x).toBeCloseTo(-HOVER_BOX_PADDING, 5);
+    expect(box.max.y).toBeCloseTo(2 * HOVER_BOX_PADDING, 5);
+    expect(box.getCenter(new THREE.Vector3()).toArray()).toEqual([0, 0, 0]);
+  });
+
+  it("floors a degenerate axis so a flat card still reads as a box", () => {
+    const box = new THREE.Box3(
+      new THREE.Vector3(0, 0, 0),
+      new THREE.Vector3(10, 10, 0),
+    );
+    expect(normalizeHoverBounds(box)).toBe(true);
+    const size = box.getSize(new THREE.Vector3());
+    expect(size.z).toBeCloseTo(10 * HOVER_BOX_MIN_EXTENT_RATIO, 5);
+    // …and the axis it was floored on stays centred on the original plane.
+    expect(box.getCenter(new THREE.Vector3()).z).toBeCloseTo(0, 6);
+  });
+
+  it("rejects boxes there is nothing to wrap", () => {
+    expect(normalizeHoverBounds(new THREE.Box3())).toBe(false);
+    const point = new THREE.Box3(new THREE.Vector3(5, 5, 5), new THREE.Vector3(5, 5, 5));
+    expect(normalizeHoverBounds(point)).toBe(false);
+    // An infinite extent would compose a NaN matrix and un-render the
+    // frame silently: it counts as nothing to wrap.
+    const infinite = new THREE.Box3(
+      new THREE.Vector3(0, 0, 0),
+      new THREE.Vector3(Number.POSITIVE_INFINITY, 1, 1),
+    );
+    expect(normalizeHoverBounds(infinite)).toBe(false);
+  });
+});
+
+describe("isVisibleInHierarchy", () => {
+  it("follows the renderer's rule — a hidden ANCESTOR hides the child", () => {
+    const root = new THREE.Group();
+    const parent = new THREE.Group();
+    const leaf = new THREE.Object3D();
+    root.add(parent);
+    parent.add(leaf);
+    expect(isVisibleInHierarchy(leaf)).toBe(true);
+
+    parent.visible = false;
+    // The leaf still reads visible=true: three only skips the subtree.
+    expect(leaf.visible).toBe(true);
+    expect(isVisibleInHierarchy(leaf)).toBe(false);
+    expect(isVisibleInHierarchy(parent)).toBe(false);
+
+    parent.visible = true;
+    leaf.visible = false;
+    expect(isVisibleInHierarchy(leaf)).toBe(false);
+    expect(isVisibleInHierarchy(parent)).toBe(true);
+  });
+});
+
+describe("createHoverBox", () => {
+  it("wraps a target and follows its anchor's world matrix", () => {
+    const { anchor, body } = fixture();
+    const frame = createHoverBox();
+    expect(frame.object.visible).toBe(false);
+
+    frame.attach(anchor, body);
+    expect(frame.object.visible).toBe(true);
+    // The body is 2 units at x = 3 → padded half-extent on every axis.
+    const half = (2 * HOVER_BOX_PADDING) / 2;
+    expect(frame.object.matrix.elements[12]).toBeCloseTo(3, 5);
+    expect(frame.object.matrix.elements[0]).toBeCloseTo(half * 2, 5);
+
+    // Rigid motion of the anchor is tracked exactly, at O(1).
+    anchor.position.set(-8, 5, 1);
+    anchor.updateMatrixWorld(true);
+    frame.refresh();
+    expect(frame.object.matrix.elements[12]).toBeCloseTo(-5, 5);
+    expect(frame.object.matrix.elements[13]).toBeCloseTo(5, 5);
+    expect(frame.object.matrix.elements[14]).toBeCloseTo(1, 5);
+    // …and the frame never rewrites three's own transform bookkeeping.
+    expect(frame.object.matrixWorldNeedsUpdate).toBe(true);
+
+    frame.dispose();
+  });
+
+  it("stays hidden for a null target, an empty subtree, or a hide()", () => {
+    const { anchor } = fixture();
+    const frame = createHoverBox();
+    // The return value is the caller's "look again" signal: an empty
+    // measurement must not latch a hidden frame for good.
+    expect(frame.attach(anchor, null)).toBe(false);
+    expect(frame.object.visible).toBe(false);
+
+    expect(frame.attach(anchor, new THREE.Object3D())).toBe(false);
+    expect(frame.object.visible).toBe(false);
+
+    expect(frame.attach(anchor, anchor)).toBe(true);
+    expect(frame.object.visible).toBe(true);
+    // A hidden frame is not re-placed behind the consumer's back.
+    frame.hide();
+    const before = frame.object.matrix.clone();
+    frame.refresh();
+    expect(frame.object.matrix.equals(before)).toBe(true);
+    frame.dispose();
+  });
+
+  it("takes its colour from the caller and frees its own GPU resources", () => {
+    const frame = createHoverBox();
+    frame.setColor("#123456");
+    const material = frame.object.material as THREE.LineBasicMaterial;
+    expect(material.color.getHexString()).toBe("123456");
+
+    const geoSpy = vi.spyOn(frame.object.geometry, "dispose");
+    const matSpy = vi.spyOn(material, "dispose");
+    frame.dispose();
+    expect(geoSpy).toHaveBeenCalled();
+    expect(matSpy).toHaveBeenCalled();
+  });
+});

package/src/components/board3dHoverBox.ts

@@ -0,0 +1,210 @@
+/**
+ * board3dHoverBox — the 8-corner selection frame HkBoard3D draws around
+ * the object under the pointer.
+ *
+ * Why a frame instead of a highlight: hovering used to be the consumer's
+ * job, and the usual implementation is "scale the mesh up a little". That
+ * resizes the thing the user is aiming at (targets move under the
+ * pointer) and tells the user nothing about the object's extent. A
+ * corner bracket marks the object without touching it.
+ *
+ * The frame's colour is the page's: HkBoard3D hands in the palette's text
+ * channel in a dark room and its muted channel in a light one.
+ *
+ * COST MODEL — the box is measured ONCE per hover, in the registered
+ * object's own space, and each frame is placed by composing that local
+ * box with the object's world matrix. Rigid motion (orbits, a parent's
+ * spin, camera-independent flights) is tracked exactly, at O(1) per frame
+ * however heavy the object's subtree is. Animation INSIDE the frame
+ * target is deliberately not chased: a spinning sphere must not tumble
+ * its own selection frame.
+ *
+ * DECORATION IS NOT SHAPE — sprites (a star's corona) and CSS2D label
+ * anchors are skipped when measuring, and invisible subtrees are pruned:
+ * a glow that is six times the body must not blow the frame up with it.
+ */
+
+import * as THREE from "three";
+
+import {
+  HOVER_BOX_MIN_EXTENT_RATIO,
+  HOVER_BOX_PADDING,
+  hoverBoxSegments,
+} from "../utils/scene3d";
+
+/** Drawn in the transparent pass, over whatever the content left behind:
+ *  the frame is a pointer affordance, not scenery, so all eight corners
+ *  stay readable even where the body covers them (gizmo convention). */
+const HOVER_BOX_RENDER_ORDER = 10;
+
+export interface HoverBoxHandle {
+  /** The gizmo itself — add it to the scene, never to content. */
+  readonly object: THREE.LineSegments;
+  /** Wrap `target` measured inside `anchor`'s space; `null` hides the
+   *  frame. Measuring happens here and only here. Returns false when
+   *  there was nothing measurable to wrap (empty or hidden content), so
+   *  the caller knows to look again instead of latching onto a hidden
+   *  frame forever. */
+  attach(anchor: THREE.Object3D, target: THREE.Object3D | null): boolean;
+  /** Re-place the frame from the anchor's current world matrix (per
+   *  frame). A no-op while the frame is hidden. */
+  refresh(): void;
+  /** Hide without forgetting the attachment. */
+  hide(): void;
+  setColor(color: THREE.ColorRepresentation): void;
+  dispose(): void;
+}
+
+/**
+ * `Object3D.visible` is per NODE: an object under a hidden parent is
+ * invisible to the renderer while reading `true` itself. The hover frame
+ * must follow the renderer's rule, or it keeps painting a bracket around
+ * something nobody can see.
+ */
+export function isVisibleInHierarchy(obj: THREE.Object3D): boolean {
+  for (let node: THREE.Object3D | null = obj; node; node = node.parent) {
+    if (!node.visible) return false;
+  }
+  return true;
+}
+
+/** Sprites and CSS2D/CSS3D anchors are decoration, never the object's
+ *  shape. */
+function isDecoration(obj: THREE.Object3D): boolean {
+  const probe = obj as unknown as {
+    isSprite?: boolean;
+    isCSS2DObject?: boolean;
+    isCSS3DObject?: boolean;
+  };
+  return (
+    probe.isSprite === true || probe.isCSS2DObject === true || probe.isCSS3DObject === true
+  );
+}
+
+/**
+ * Bounding box of `target`'s subtree expressed in `anchor`'s local space.
+ * Prunes invisible subtrees and decoration; an empty box means "nothing
+ * measurable here".
+ */
+export function frameLocalBounds(
+  anchor: THREE.Object3D,
+  target: THREE.Object3D,
+  out = new THREE.Box3(),
+): THREE.Box3 {
+  anchor.updateWorldMatrix(true, true);
+  const inverseAnchor = anchor.matrixWorld.clone().invert();
+  const probe = new THREE.Box3();
+  const intoLocal = new THREE.Matrix4();
+
+  out.makeEmpty();
+  const walk = (obj: THREE.Object3D): void => {
+    if (!obj.visible || isDecoration(obj)) return;
+    const mesh = obj as THREE.Mesh;
+    if (mesh.geometry) {
+      if (!mesh.geometry.boundingBox) mesh.geometry.computeBoundingBox();
+      const bb = mesh.geometry.boundingBox;
+      if (bb) {
+        intoLocal.multiplyMatrices(inverseAnchor, obj.matrixWorld);
+        probe.copy(bb).applyMatrix4(intoLocal);
+        out.union(probe);
+      }
+    }
+    for (const child of obj.children) walk(child);
+  };
+  walk(target);
+  return out;
+}
+
+/**
+ * Pad the box and floor every degenerate axis so the frame stays a box.
+ * Returns false when there is nothing to wrap (an empty or zero-size
+ * box), which callers turn into "stay hidden".
+ */
+export function normalizeHoverBounds(
+  box: THREE.Box3,
+  padding = HOVER_BOX_PADDING,
+  minExtentRatio = HOVER_BOX_MIN_EXTENT_RATIO,
+): boolean {
+  if (box.isEmpty()) return false;
+  const size = box.getSize(new THREE.Vector3());
+  const longest = Math.max(size.x, size.y, size.z);
+  // A non-finite extent (NaN or ±Infinity from a degenerate geometry
+  // bounding box) would compose a NaN placement matrix and silently
+  // un-render the frame: nothing measurable, stay hidden.
+  if (!(longest > 0) || !Number.isFinite(longest)) return false;
+  const floor = minExtentRatio * longest;
+  const center = box.getCenter(new THREE.Vector3());
+  const half = new THREE.Vector3(
+    Math.max(size.x * padding, floor) / 2,
+    Math.max(size.y * padding, floor) / 2,
+    Math.max(size.z * padding, floor) / 2,
+  );
+  box.min.set(center.x - half.x, center.y - half.y, center.z - half.z);
+  box.max.set(center.x + half.x, center.y + half.y, center.z + half.z);
+  return true;
+}
+
+export function createHoverBox(): HoverBoxHandle {
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute(
+    "position",
+    new THREE.BufferAttribute(hoverBoxSegments([1, 1, 1]), 3),
+  );
+  const material = new THREE.LineBasicMaterial({
+    color: 0xffffff,
+    transparent: true,
+    opacity: 0.9,
+    depthTest: false,
+    depthWrite: false,
+  });
+  const object = new THREE.LineSegments(geometry, material);
+  // The placement matrix is composed from the anchor's world matrix, so
+  // three must not derive it from position/quaternion/scale.
+  object.matrixAutoUpdate = false;
+  object.renderOrder = HOVER_BOX_RENDER_ORDER;
+  object.frustumCulled = false;
+  object.visible = false;
+
+  const localBox = new THREE.Box3();
+  const localMatrix = new THREE.Matrix4();
+  const center = new THREE.Vector3();
+  const size = new THREE.Vector3();
+  const identity = new THREE.Quaternion();
+  let anchor: THREE.Object3D | null = null;
+
+  function refresh(): void {
+    if (!object.visible || !anchor) return;
+    anchor.updateWorldMatrix(true, false);
+    object.matrix.multiplyMatrices(anchor.matrixWorld, localMatrix);
+    object.matrixWorldNeedsUpdate = true;
+  }
+
+  return {
+    object,
+    attach(nextAnchor, target) {
+      anchor = nextAnchor;
+      localBox.makeEmpty();
+      object.visible = false;
+      if (!target) return false;
+      frameLocalBounds(nextAnchor, target, localBox);
+      if (!normalizeHoverBounds(localBox)) return false;
+      localBox.getCenter(center);
+      localBox.getSize(size);
+      localMatrix.compose(center, identity, size);
+      object.visible = true;
+      refresh();
+      return true;
+    },
+    refresh,
+    hide() {
+      object.visible = false;
+    },
+    setColor(color) {
+      material.color.set(color);
+    },
+    dispose() {
+      geometry.dispose();
+      material.dispose();
+    },
+  };
+}

package/src/index.ts

@@ -215,6 +215,10 @@ export {
   viewPlaneHalfExtents,
   planeCorners,
   clampMinimapZoom,
+  hoverBoxSegments,
+  HOVER_BOX_ARM_RATIO,
+  HOVER_BOX_PADDING,
+  HOVER_BOX_MIN_EXTENT_RATIO,
   MINIMAP_MIN_POLAR,
   MINIMAP_MAX_POLAR,
   MINIMAP_DRAG_RADIANS_PER_PX,
@@ -759,7 +763,11 @@ export { default as HkMediaVisualizer } from "./components/HkMediaVisualizer";
 export { default as HkImageViewer } from "./components/HkImageViewer";
 export { default as HkZoomToolbar } from "./components/HkZoomToolbar";
 export { default as HkMinimap } from "./components/HkMinimap";
-export { default as HkBoard3D, BOARD3D_HELPERS_LAYER } from "./components/HkBoard3D";
+export {
+  default as HkBoard3D,
+  BOARD3D_HELPERS_LAYER,
+  BOARD3D_MAIN_LAYER,
+} from "./components/HkBoard3D";
 export { default as HkMinimap3D } from "./components/HkMinimap3D";
 export { default as HkTrendChart } from "./components/HkTrendChart";
 export { default as HkErrorBoundary } from "./components/HkErrorBoundary";

package/src/utils/scene3d.test.ts

@@ -3,6 +3,8 @@ import { describe, expect, it } from "vitest";
 import {
   clampMinimapZoom,
   fitDistance,
+  HOVER_BOX_ARM_RATIO,
+  hoverBoxSegments,
   hashIdToUnit,
   lerpPalette,
   MINIMAP_MAX_POLAR,
@@ -161,3 +163,70 @@ describe("clampMinimapZoom", () => {
     expect(clampMinimapZoom(Number.NaN)).toBe(100);
   });
 });
+
+describe("hoverBoxSegments", () => {
+  it("emits eight corners with three inward arms each", () => {
+    const size: [number, number, number] = [2, 4, 6];
+    const positions = hoverBoxSegments(size);
+    // 8 corners × 3 arms × 2 vertices.
+    expect(positions).toHaveLength(8 * 3 * 2 * 3);
+
+    const cornerSet = new Set<string>();
+    const armLengths: number[] = [];
+    // One arm per axis, each a fraction of ITS OWN side: that is what lets
+    // the built-in frame scale a unit box by `size`.
+    const arms = size.map((side) => HOVER_BOX_ARM_RATIO * side);
+    for (let i = 0; i < positions.length; i += 6) {
+      const a: [number, number, number] = [positions[i], positions[i + 1], positions[i + 2]];
+      const b: [number, number, number] = [positions[i + 3], positions[i + 4], positions[i + 5]];
+      cornerSet.add(a.join(","));
+      // Every arm runs along exactly one axis…
+      const deltas = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
+      expect(deltas.filter((d) => d !== 0)).toHaveLength(1);
+      const axis = deltas.findIndex((d) => d !== 0);
+      const len = Math.abs(deltas[axis]);
+      expect(len).toBeCloseTo(arms[axis], 6);
+      armLengths.push(len);
+      // …and points INWARD: the arm may never leave the box.
+      for (let axis = 0; axis < 3; axis += 1) {
+        const limit = size[axis] / 2;
+        expect(Math.abs(a[axis])).toBeLessThanOrEqual(limit + 1e-9);
+        expect(Math.abs(b[axis])).toBeLessThanOrEqual(limit + 1e-9);
+      }
+    }
+    // Every corner of the box is present exactly once.
+    expect(cornerSet.size).toBe(8);
+    for (const x of [-1, 1]) {
+      for (const y of [-2, 2]) {
+        for (const z of [-3, 3]) {
+          expect(cornerSet.has([x, y, z].join(",")), `${x},${y},${z}`).toBe(true);
+        }
+      }
+    }
+    expect(armLengths).toHaveLength(24);
+  });
+
+  it("gives each axis its own arm, and survives junk sizes", () => {
+    const flat = hoverBoxSegments([10, 0, 10]);
+    // A zero side ⇒ zero-length arms on that axis rather than a throw.
+    expect(flat.every((v) => Number.isFinite(v))).toBe(true);
+    expect(flat.every((v) => !Number.isNaN(v))).toBe(true);
+
+    const cubic = hoverBoxSegments([4, 4, 4]);
+    const arm = HOVER_BOX_ARM_RATIO * 4;
+    const firstLen = Math.abs(cubic[3] - cubic[0]) + Math.abs(cubic[4] - cubic[1]) + Math.abs(cubic[5] - cubic[2]);
+    expect(firstLen).toBeCloseTo(arm, 6);
+
+    // Scale invariance: the unit box scaled by `size` is the box's own
+    // bracket — the contract the barrel documents for bespoke frames.
+    const scaled = hoverBoxSegments([1, 1, 1]);
+    const stretched = hoverBoxSegments([2, 4, 6]);
+    for (let i = 0; i < stretched.length; i += 3) {
+      const axis = i % 3;
+      expect(stretched[i + axis] / scaled[i + axis]).toBeCloseTo([2, 4, 6][axis], 6);
+    }
+
+    const junk = hoverBoxSegments([Number.NaN, -3, 0] as [number, number, number]);
+    expect(junk.every((v) => Number.isFinite(v))).toBe(true);
+  });
+});

package/src/utils/scene3d.ts

@@ -20,6 +20,11 @@ export type Vec3 = [number, number, number];
  *  runtime import of the board — the two components stay acyclic.) */
 export const BOARD3D_HELPERS_LAYER = 1;
 
+/** Layer the main-camera-only gizmos live on — the hover frame. The
+ *  minimap camera never enables it, so a pointer affordance stays out of
+ *  the map render while the page's own eye still sees it. */
+export const BOARD3D_MAIN_LAYER = 2;
+
 /** FNV-1a 32-bit hash of a string folded into [0, 1). Stable across runs
  *  and platforms — the same node id always lands on the same palette stop. */
 export function hashIdToUnit(id: string): number {
@@ -163,6 +168,68 @@ export function planeCorners(
   return [at(-1, 1), at(1, 1), at(1, -1), at(-1, -1)];
 }
 
+// ── Hover frame (the 8-corner selection box) ────────────────────────────
+
+/** Corner arm length, as a fraction of the side it runs along. */
+export const HOVER_BOX_ARM_RATIO = 0.24;
+
+/** Breathing room between the object's bounds and its frame. */
+export const HOVER_BOX_PADDING = 1.08;
+
+/** Floor on a degenerate axis — a flat card or a zero-thickness plane
+ *  must still read as a box instead of collapsing onto one line. As a
+ *  fraction of the box's LONGEST side. */
+export const HOVER_BOX_MIN_EXTENT_RATIO = 0.12;
+
+/**
+ * The line-segment positions of a hover frame for a box of `size`
+ * centred on the origin: EIGHT CORNERS, three arms each (8 × 3 × 2 = 48
+ * vertices). Corner brackets rather than a full wireframe — the frame
+ * reads as a box around the object without drawing a cage over it.
+ *
+ * Each arm runs along one axis and is HOVER_BOX_ARM_RATIO of THAT axis,
+ * which is what makes the geometry scale-invariant: the built-in frame
+ * builds a unit box and scales it by `size`, so a consumer building its
+ * own frame from this helper gets the same bracket.
+ *
+ * Degenerate sizes (non-finite, ≤ 0) are treated as 0; callers that care
+ * about a zero-size box collapse check it before building the frame.
+ */
+export function hoverBoxSegments(size: Vec3): Float32Array {
+  const [sx, sy, sz] = [0, 1, 2].map((i) => {
+    const v = size[i];
+    return Number.isFinite(v) && v > 0 ? v : 0;
+  }) as Vec3;
+  const arms: Vec3 = [
+    HOVER_BOX_ARM_RATIO * sx,
+    HOVER_BOX_ARM_RATIO * sy,
+    HOVER_BOX_ARM_RATIO * sz,
+  ];
+  const out = new Float32Array(8 * 3 * 2 * 3);
+  let at = 0;
+  for (const ix of [-1, 1]) {
+    for (const iy of [-1, 1]) {
+      for (const iz of [-1, 1]) {
+        const corner: Vec3 = [(ix * sx) / 2, (iy * sy) / 2, (iz * sz) / 2];
+        for (let axis = 0; axis < 3; axis += 1) {
+          // One arm per axis, all pointing INWARD from the corner (the
+          // sign flip is what makes the bracket hug the box).
+          const tip: Vec3 = [corner[0], corner[1], corner[2]];
+          tip[axis] -= [ix, iy, iz][axis] * arms[axis];
+          out[at] = corner[0];
+          out[at + 1] = corner[1];
+          out[at + 2] = corner[2];
+          out[at + 3] = tip[0];
+          out[at + 4] = tip[1];
+          out[at + 5] = tip[2];
+          at += 6;
+        }
+      }
+    }
+  }
+  return out;
+}
+
 /** Minimap zoom-ladder governance: the ± buttons step the view-radius
  *  factor by a fixed 15% rung inside [50%, 250%] of the auto-fit radius. */
 export const MINIMAP_ZOOM_STEP_PERCENT = 15;