@celestia-island/hikari 0.55.103 → 0.55.105

package/package.json

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

@@ -109,6 +109,20 @@ describe("hikari barrel — 3D board surface", () => {
     expect(has).toBe(true);
   });
 
+  it("pins the engine's selection surface", () => {
+    // `setSelection` is how a page keeps the 8-corner frame on its
+    // selected object (the fleet sky's cube cursor). Type-level probe:
+    // vue-tsc covers this file, so dropping the method breaks the gate
+    // rather than the consumer's build.
+    const engine = null as Engine | null;
+    void engine;
+    type HasSelection = Engine extends { setSelection(id: string | null): void }
+      ? true
+      : false;
+    const has: HasSelection = true;
+    expect(has).toBe(true);
+  });
+
   it("exports the minimap governance constants, drag sensitivity included", () => {
     // A consumer writing its own drag control needs the same sensitivity
     // the built-in one uses — it must not stay module-private.

package/src/components/HkBoard3D.scss

@@ -45,6 +45,13 @@
 }
 
 .hk-board3d-fallback {
+  // Self-carried contrast chip: in transparent-backdrop mode the root
+  // paints nothing, so the note cannot lean on the old surface fill.
+  background: rgb(var(--color-surface) / 0.9);
+  border-radius: var(--radius-md, 8px);
+  padding: 6px 12px;
+  margin: auto;
+  width: fit-content;
   position: absolute;
   inset: 0;
   display: flex;

package/src/components/HkBoard3D.test.tsx

@@ -15,20 +15,28 @@ const H = vi.hoisted(() => {
     renders: Array<{ scene: unknown; camera: unknown }> = [];
     sizes: Array<[number, number]> = [];
     clearColor: unknown = null;
+    clearAlpha: number | null = null;
+    /** The drawing buffer's alpha channel — only present when the board
+     *  asks for a transparent backdrop (`alpha: true`). */
+    alpha: boolean;
     toneMapping: unknown = null;
     shadowMap = { enabled: false };
     disposed = false;
-    constructor(opts: { canvas: HTMLCanvasElement }) {
+    constructor(opts: { canvas: HTMLCanvasElement; alpha?: boolean }) {
       if (FakeWebGLRenderer.failNext) {
         FakeWebGLRenderer.failNext = false;
         throw new Error("no webgl (test)");
       }
       this.domElement = opts.canvas;
+      this.alpha = opts.alpha === true;
       FakeWebGLRenderer.instances.push(this);
     }
     setPixelRatio(): void {}
     setSize(w: number, h: number): void { this.sizes.push([w, h]); }
-    setClearColor(c: unknown): void { this.clearColor = c; }
+    setClearColor(c: unknown, alpha = 1): void {
+      this.clearColor = c;
+      this.clearAlpha = alpha;
+    }
     render(scene: unknown, camera: unknown): void {
       // A real renderer maintains world matrices every pass; picking and
       // projection both read them.
@@ -105,6 +113,25 @@ async function tickFrames(): Promise<void> {
   await new Promise((r) => setTimeout(r, 50));
 }
 
+/** Both gizmo frames — hover, then selection — are the only scene
+ *  children on the main-camera-only layer, and init() creates them in
+ *  that order, so the index is a stable discriminator. */
+function framesOf(engine: Board3DEngine): THREE.LineSegments[] {
+  const found = engine.scene.children.filter((c) => c.layers.isEnabled(BOARD3D_MAIN_LAYER));
+  expect(found, "both gizmo frames in the scene").toHaveLength(2);
+  return found as THREE.LineSegments[];
+}
+
+/** The hover frame (created first in init). */
+function frameOf(engine: Board3DEngine): THREE.LineSegments {
+  return framesOf(engine)[0]!;
+}
+
+/** The selection frame (created second in init). */
+function selectionOf(engine: Board3DEngine): THREE.LineSegments {
+  return framesOf(engine)[1]!;
+}
+
 beforeEach(() => {
   H.FakeWebGLRenderer.instances = [];
   H.FakeWebGLRenderer.failNext = false;
@@ -689,13 +716,6 @@ describe("HkBoard3D", () => {
 });
 
 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 = () =>
@@ -1063,3 +1083,318 @@ describe("HkBoard3D hover frame", () => {
     expect(frameOf(engine).visible).toBe(false);
   });
 });
+
+describe("HkBoard3D selection frame", () => {
+  /** A board with one body registered and the id selected — NO pointer
+   *  involvement anywhere: the selection frame must not need one. */
+  async function selectedBoard(props: Record<string, unknown> = {}) {
+    const hovers: Array<string | null> = [];
+    let engine: Board3DEngine | null = null;
+    mountBoard({ minimap: false, ...props }, {
+      ready: ((e: Board3DEngine) => { engine = e; }) as never,
+      objectHover: ((id: string | null) => hovers.push(id)) as never,
+    });
+    await nextTick();
+    const body = new THREE.Mesh(
+      new THREE.SphereGeometry(2, 16, 12),
+      new THREE.MeshBasicMaterial(),
+    );
+    body.name = "body";
+    engine!.setObject("star-1", { object: body });
+    engine!.setSelection("star-1");
+    await tickFrames();
+    return { engine: engine!, body, hovers };
+  }
+
+  it("pins the persistent corner frame without any pointer", async () => {
+    const { engine, body } = await selectedBoard();
+    const selection = selectionOf(engine);
+    expect(selection.visible).toBe(true);
+    // Same measurement contract as the hover frame: the body's own
+    // extents plus the padding, composed through its world matrix.
+    expect(selection.matrix.elements[0]).toBeCloseTo(4 * 1.08, 4);
+    expect(selection.matrix.elements[13]).toBeCloseTo(0, 5);
+    // The pointer frame has nothing to say here — nothing is hovered.
+    expect(frameOf(engine).visible).toBe(false);
+    // The body itself is untouched, and the gizmo never joins the
+    // registry (framing and picking never see it).
+    expect(body.scale.x).toBe(1);
+    expect([...engine.objects().keys()]).toEqual(["star-1"]);
+
+    // A selected object re-registered as UN-pickable stays marked: the
+    // frame marks what the page selected, and pointer reachability is a
+    // hover concern (decision pinned — R1).
+    engine.setObject("star-1", { object: body, pickable: false });
+    await tickFrames();
+    expect(selectionOf(engine).visible).toBe(true);
+  });
+
+  it("re-selecting the same id does not re-measure", async () => {
+    const { engine, body } = await selectedBoard();
+    // Pages re-select on data refreshes; each redundant call must be a
+    // no-op, not a forced subtree walk (the hover path guards the same
+    // way at the event level — R2 P2). The measurement walk is the
+    // (updateParents=true, updateChildren=true) call; the per-frame
+    // refresh uses (true, false) and stays.
+    const walk = vi.spyOn(body, "updateWorldMatrix");
+    for (let i = 0; i < 5; i += 1) engine.setSelection("star-1");
+    await tickFrames();
+    const measured = walk.mock.calls.filter(
+      ([parents, children]) => parents === true && children === true,
+    ).length;
+    expect(measured).toBe(0);
+    expect(selectionOf(engine).visible).toBe(true);
+  });
+
+  it("only ever ends through setSelection(null)", async () => {
+    const { engine } = await selectedBoard();
+    expect(selectionOf(engine).visible).toBe(true);
+
+    // Frames pass — the selection is sticky, not a hover that decays.
+    await tickFrames();
+    await tickFrames();
+    expect(selectionOf(engine).visible).toBe(true);
+
+    engine.setSelection(null);
+    await tickFrames();
+    expect(selectionOf(engine).visible).toBe(false);
+  });
+
+  it("survives a rebuild: the removed id hides, re-registration re-measures", async () => {
+    const { engine } = await selectedBoard();
+    expect(selectionOf(engine).visible).toBe(true);
+
+    // A roster rebuild strips every body first — the frame hides while
+    // the id is gone but the SELECTION survives the interim.
+    engine.setObject("star-1", null);
+    await tickFrames();
+    expect(selectionOf(engine).visible).toBe(false);
+
+    // …and the re-registered body (a fresh object at a new spot) gets the
+    // frame measured against IT, not against the dead predecessor.
+    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(selectionOf(engine).visible).toBe(true);
+    expect(selectionOf(engine).matrix.elements[12]).toBeCloseTo(30, 4);
+    expect(selectionOf(engine).matrix.elements[0]).toBeCloseTo(2 * 1.08, 4);
+  });
+
+  it("re-measures when a rebuild hands the selected id a NEW object directly", async () => {
+    const { engine } = await selectedBoard();
+    expect(selectionOf(engine).matrix.elements[12]).toBeCloseTo(0, 5);
+
+    // The ONE-step rebuild (strip + re-register fused into a single
+    // setObject): the latch must release here too, or the frame keeps
+    // riding the dead predecessor's matrix — the two-step test above
+    // cannot see this, the hide path resets the latch for it (R1 P1).
+    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(selectionOf(engine).visible).toBe(true);
+    expect(selectionOf(engine).matrix.elements[12]).toBeCloseTo(30, 4);
+    expect(selectionOf(engine).matrix.elements[0]).toBeCloseTo(2 * 1.08, 4);
+  });
+
+  it("suppresses the hover frame on the selected body only", async () => {
+    const { engine, hovers } = await selectedBoard();
+    const canvas = mounts[0]!.container.querySelector("canvas")!;
+    canvas.getBoundingClientRect = () =>
+      ({ left: 0, top: 0, width: 800, height: 600, right: 800, bottom: 600 }) as DOMRect;
+    canvas.dispatchEvent(new PointerEvent("pointermove", { bubbles: true, clientX: 400, clientY: 300 }));
+    await tickFrames();
+    // Hovering the selected body draws ONE bracket, not two.
+    expect(selectionOf(engine).visible).toBe(true);
+    expect(frameOf(engine).visible).toBe(false);
+    // Suppression is frame-only: the page still HEARS the hover (its
+    // hover card must keep working on the selected body) and the cursor
+    // still promises the click (R1 P2).
+    expect(hovers.at(-1)).toBe("star-1");
+    expect(canvas.style.cursor).toBe("pointer");
+
+    // Moving the selection elsewhere un-suppresses the hover: the pointer
+    // is still over star-1, which is no longer the selected body.
+    const other = new THREE.Mesh(
+      new THREE.SphereGeometry(1, 12, 8),
+      new THREE.MeshBasicMaterial(),
+    );
+    other.position.set(500, 500, 500);
+    engine.setObject("star-2", { object: other });
+    engine.setSelection("star-2");
+    await tickFrames();
+    expect(frameOf(engine).visible).toBe(true);
+    expect(selectionOf(engine).visible).toBe(true);
+    expect(selectionOf(engine).matrix.elements[12]).toBeCloseTo(500, 4);
+  });
+
+  it("picks the selection up when the content arrives after the select", async () => {
+    let engine: Board3DEngine | null = null;
+    mountBoard({ minimap: false }, { ready: ((e: Board3DEngine) => { engine = e; }) as never });
+    await nextTick();
+
+    // Content streams in: the registered group's only mesh is still
+    // hidden when the page selects 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 });
+    engine!.setSelection("stream");
+    await tickFrames();
+    expect(selectionOf(engine!).visible).toBe(false);
+
+    mesh.visible = true;
+    await tickFrames();
+    expect(selectionOf(engine!).visible).toBe(true);
+  });
+
+  it("re-measures an unmeasurable selection 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 group = new THREE.Group();
+    const decor = new THREE.Sprite(new THREE.SpriteMaterial());
+    group.add(decor);
+    engine!.setObject("empty", { object: group });
+    engine!.setSelection("empty");
+    await tickFrames();
+    expect(selectionOf(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("hides while the body is invisible, and comes back with it", async () => {
+    const { engine, body } = await selectedBoard();
+    expect(selectionOf(engine).visible).toBe(true);
+
+    // three renders by the CHAIN: the frame must not paint the air.
+    body.visible = false;
+    await tickFrames();
+    expect(selectionOf(engine).visible).toBe(false);
+
+    body.visible = true;
+    await tickFrames();
+    expect(selectionOf(engine).visible).toBe(true);
+  });
+
+  it("tints the selection from the primary channel, apart from the hover", async () => {
+    const previous = ["--color-background", "--color-text", "--color-primary"].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-primary", "10 10 250");
+      const { engine } = await selectedBoard();
+      const hoverColor = (frameOf(engine).material as THREE.LineBasicMaterial).color;
+      const selectionColor = (selectionOf(engine).material as THREE.LineBasicMaterial).color;
+      expect(selectionColor.r * 255).toBeCloseTo(10, 0);
+      expect(selectionColor.b * 255).toBeCloseTo(250, 0);
+      // The hover frame keeps its own channel (text) — the two stay
+      // readable apart at a glance.
+      expect(hoverColor.r * 255).toBeCloseTo(250, 0);
+      expect(hoverColor.b * 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("disposes the selection frame on unmount", async () => {
+    const { engine } = await selectedBoard();
+    expect(selectionOf(engine).visible).toBe(true);
+    const selection = selectionOf(engine);
+    const geoSpy = vi.spyOn(selection.geometry, "dispose");
+    const matSpy = vi.spyOn(selection.material as THREE.Material, "dispose");
+
+    const m = mounts.splice(0)[0];
+    m.app.unmount();
+    m.container.remove();
+
+    expect(geoSpy).toHaveBeenCalled();
+    expect(matSpy).toHaveBeenCalled();
+    expect(engine.scene.children.some((c) => c.layers.isEnabled(BOARD3D_MAIN_LAYER))).toBe(false);
+  });
+});
+
+describe("HkBoard3D transparent background", () => {
+  function rendererOf(): InstanceType<typeof H.FakeWebGLRenderer> {
+    // The board's renderer is the first instance (the minimap spins up
+    // its own, and only when mounted).
+    return H.FakeWebGLRenderer.instances[0]!;
+  }
+
+  it("paints the theme background by default", async () => {
+    let engine: Board3DEngine | null = null;
+    mountBoard({ minimap: false }, { ready: ((e: Board3DEngine) => { engine = e; }) as never });
+    await nextTick();
+    expect(engine!.scene.background).toBeInstanceOf(THREE.Color);
+    expect(rendererOf().alpha).toBe(false);
+    expect(rendererOf().clearAlpha).toBe(1);
+  });
+
+  it("clears to transparent with the transparentBackground prop", async () => {
+    let engine: Board3DEngine | null = null;
+    mountBoard(
+      { minimap: false, transparentBackground: true },
+      { ready: ((e: Board3DEngine) => { engine = e; }) as never },
+    );
+    await nextTick();
+    // No scene backdrop: the page's own backdrop shows through. The
+    // drawing buffer must actually HAVE an alpha channel, and the clear
+    // must be fully transparent — an opaque clear would read as black.
+    expect(engine!.scene.background).toBeNull();
+    expect(rendererOf().alpha).toBe(true);
+    expect(rendererOf().clearAlpha).toBe(0);
+  });
+
+  it("drops the container's own surface paint in transparent mode", async () => {
+    const { container } = mountBoard(
+      { minimap: false, transparentBackground: true },
+      {},
+    );
+    await nextTick();
+    const root = container.querySelector(".hk-board3d") as HTMLElement;
+    // The stylesheet paints --color-surface on .hk-board3d; an inline
+    // transparent style must win, or a page-colored rectangle sits
+    // behind the alpha-0 canvas (user report 2026-10-01: the scene
+    // background differs from the page background).
+    expect(root.style.background).toContain("transparent");
+  });
+
+  it("keeps the stylesheet surface paint when the backdrop is opaque", async () => {
+    const { container } = mountBoard({ minimap: false }, {});
+    await nextTick();
+    const root = container.querySelector(".hk-board3d") as HTMLElement;
+    expect(root.style.background).toBe("");
+  });
+});

package/src/components/HkBoard3D.tsx

@@ -19,7 +19,16 @@
  *    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;
+ *    it is aiming at instead of resizing it; hovering the SELECTED body
+ *    shows nothing extra (the selection frame is already there);
+ *  - SELECTION FRAME: `engine.setSelection(id)` pins the same 8-corner
+ *    frame on a registered object for as long as the selection lasts —
+ *    the persistent counterpart of the hover frame, tinted with the
+ *    theme's primary instead of the text channel (user direction
+ *    2026-10-01: the fleet sky marks its selection with the cube cursor,
+ *    never with a ring). The frame survives the object being removed and
+ *    re-registered under the same id (a roster rebuild re-measures), and
+ *    only `setSelection(null)` clears 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
@@ -27,7 +36,9 @@
  *    plane and content markers layered in;
  *  - THEME: scene background follows --color-background, re-read on
  *    data-mode / data-theme / style mutations; `engine.onTheme` lets the
- *    page re-tone its materials on the same signal;
+ *    page re-tone its materials on the same signal. With the
+ *    `transparentBackground` prop the canvas clears to transparent
+ *    instead, so the page's own backdrop shows through the sky;
  *  - FALLBACK: no WebGL → the `fallback` slot (or a localized note) and
  *    an `error` event; nothing throws out of mount.
  *
@@ -119,6 +130,16 @@ export interface Board3DEngine {
   /** Post-render hook (the minimap lives here); returns the disposer. */
   addPostRender(fn: () => void): () => void;
   setObject(id: string, def: Board3DObjectDef | null): void;
+  /** Pin the persistent 8-corner selection frame on the registered
+   *  object `id` (`null` clears it). The frame is independent of the
+   *  pointer: it rides the object through orbits and rebuilds, hides
+   *  while the object is absent or unmeasurable, and re-measures when
+   *  the id is re-registered. It marks what the page SELECTED — a
+   *  `pickable: false` object is marked all the same (pointer
+   *  reachability is a hover concern, not a selection one). Selecting
+   *  an object also suppresses the HOVER frame on that same object —
+   *  the selection frame is already marking it. */
+  setSelection(id: string | null): void;
   /** Snapshot of the registered content (the minimap's marker set).
    *  Mutating it does not touch the board — register through
    *  `setObject` instead. */
@@ -291,6 +312,17 @@ function hoverFrameColor(background: THREE.Color): THREE.Color {
   );
 }
 
+/**
+ * The selection frame's tint: the theme's PRIMARY channel on both modes.
+ * It has to read apart from the hover frame (text/muted, i.e. near-white
+ * over a night sky) at a glance — the selection is a statement about the
+ * page's data, and primary is the one channel already reserved for
+ * exactly that.
+ */
+function selectionFrameColor(): THREE.Color {
+  return cssRgbToColor(readCssColor("--color-primary", "21 101 192"));
+}
+
 export default defineComponent({
   name: "HkBoard3D",
   props: {
@@ -329,13 +361,20 @@ export default defineComponent({
     /** 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. */
+     *  content is not "selected" at all. Hovering the object pinned by
+     *  `engine.setSelection` draws no second frame — the selection
+     *  frame is already there. */
     hoverBox: { type: Boolean, default: true },
+    /** Clear the canvas to transparent instead of painting the theme
+     *  background, so the page's own backdrop shows through the sky.
+     *  STATIC after mount (the drawing buffer's alpha channel exists or
+     *  it does not — remount to change it). */
+    transparentBackground: { type: Boolean, default: false },
     /** 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. Hover is frozen with
-     *  it: the frame keeps whatever it had painted until the loop resumes
-     *  (nothing re-renders while paused). */
+     *  tween is evaluated against wall-clock time. Both pointer/selection
+     *  frames are frozen with it: each keeps whatever it had painted
+     *  until the loop resumes (nothing re-renders while paused). */
     paused: { type: Boolean, default: false },
   },
   emits: {
@@ -357,6 +396,7 @@ export default defineComponent({
     let camera: THREE.PerspectiveCamera | null = null;
     let controls: OrbitControls | null = null;
     let hoverFrame: HoverBoxHandle | null = null;
+    let selectionFrame: HoverBoxHandle | null = null;
     let resizeObs: ResizeObserver | null = null;
     let themeObs: MutationObserver | null = null;
     let rafId = 0;
@@ -384,6 +424,8 @@ export default defineComponent({
     const ndc = new THREE.Vector2();
     let hoverDirty = false;
     let lastHover: string | null = null;
+    /** The id pinned by `engine.setSelection` (null = no selection). */
+    let selectionId: string | null = null;
     let pressAt: { pointerId: number; x: number; y: number } | null = null;
 
     // ── camera tween ──────────────────────────────────────────────────
@@ -400,9 +442,14 @@ export default defineComponent({
       const bgRaw = readCssColor("--color-background", "10 15 25");
       const primaryRaw = readCssColor("--color-primary", "21 101 192");
       const bg = cssRgbToColor(bgRaw);
-      if (scene) scene.background = bg;
-      if (renderer) renderer.setClearColor(bg, 1);
+      // Transparent mode keeps the TINT for the clear colour but drops
+      // the scene backdrop and the clear ALPHA to 0, so the page's own
+      // backdrop shows through (the renderer must have been mounted with
+      // `alpha: true` — the prop is static for exactly this reason).
+      if (scene) scene.background = props.transparentBackground ? null : bg;
+      if (renderer) renderer.setClearColor(bg, props.transparentBackground ? 0 : 1);
       hoverFrame?.setColor(hoverFrameColor(bg));
+      selectionFrame?.setColor(selectionFrameColor());
       for (const cb of themeHooks) cb(bgRaw, primaryRaw);
     }
 
@@ -453,6 +500,10 @@ export default defineComponent({
      *  measurement is the expensive half, so it happens on hover change
      *  only — the per-frame half is one matrix composition. */
     let frameBound = false;
+    /** Same latch/cooldown pair for the SELECTION frame (it re-measures
+     *  when the selected id is re-registered, i.e. after a rebuild). */
+    let selectionBound = false;
+    let selectionCooldown = 0;
     /** 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
@@ -537,10 +588,16 @@ export default defineComponent({
      * content still streaming in under a resting pointer — also stays
      * un-latched, which is what lets the frame appear when the content
      * finally lands.
+     *
+     * The SELECTED object is likewise unmarked: its selection frame is
+     * already on, and two nested brackets around one body read as noise,
+     * not information.
      */
     function syncHoverFrame(): void {
       if (!hoverFrame) return;
-      const def = props.hoverBox && lastHover !== null ? registry.get(lastHover) : undefined;
+      const def = props.hoverBox && lastHover !== null && lastHover !== selectionId
+        ? 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();
@@ -560,6 +617,36 @@ export default defineComponent({
       hoverFrame.refresh();
     }
 
+    /**
+     * The selection frame: the same measure-once / ride-the-world-matrix
+     * contract as the hover frame, driven by `engine.setSelection`
+     * instead of the pointer. It is deliberately STICKY — a removed id
+     * (a roster rebuild strips and re-registers every body) hides the
+     * frame for the interim and re-measures on re-registration, but the
+     * selection itself only ever ends through `setSelection(null)`.
+     */
+    function syncSelectionFrame(): void {
+      if (!selectionFrame) return;
+      const def = selectionId !== null ? registry.get(selectionId) : undefined;
+      const target = def ? (def.frameObject === null ? null : (def.frameObject ?? def.object)) : null;
+      if (!def || !target || !isVisibleInHierarchy(target)) {
+        selectionFrame.hide();
+        selectionBound = false;
+        selectionCooldown = 0;
+        return;
+      }
+      if (!selectionBound) {
+        if (selectionCooldown > 0) {
+          selectionCooldown -= 1;
+          return;
+        }
+        selectionBound = selectionFrame.attach(def.object, target);
+        selectionCooldown = selectionBound ? 0 : HOVER_BOX_RETRY_FRAMES;
+        return;
+      }
+      selectionFrame.refresh();
+    }
+
     function frame(): void {
       if (disposed) return;
       rafId = requestAnimationFrame(frame);
@@ -595,6 +682,7 @@ export default defineComponent({
       // After the tick hooks have posed the content, so the frame lands on
       // this frame's pose rather than the previous one.
       syncHoverFrame();
+      syncSelectionFrame();
 
       renderer.render(scene, camera);
       labelRenderer?.render(scene, camera);
@@ -607,12 +695,16 @@ 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.
+      // Both frames are pointer/selection affordances, not scenery: they
+      // hang off the scene root (so they never join framing, markers or
+      // picking) and ride the main-camera-only layer, keeping the minimap
+      // render clean.
       hoverFrame = createHoverBox();
       hoverFrame.object.layers.set(BOARD3D_MAIN_LAYER);
       scene.add(hoverFrame.object);
+      selectionFrame = createHoverBox();
+      selectionFrame.object.layers.set(BOARD3D_MAIN_LAYER);
+      scene.add(selectionFrame.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.
@@ -627,7 +719,15 @@ export default defineComponent({
       camera.position.set(initPos[0], initPos[1], initPos[2]);
       camera.lookAt(initTarget[0], initTarget[1], initTarget[2]);
 
-      renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: false });
+      renderer = new THREE.WebGLRenderer({
+        canvas,
+        antialias: true,
+        // Transparent backdrops need an alpha channel in the drawing
+        // buffer — an `alpha: false` context would paint the cleared
+        // pixels opaque black over the page. This is why the prop is
+        // documented STATIC after mount.
+        alpha: props.transparentBackground,
+      });
       renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
       renderer.toneMapping = THREE.ACESFilmicToneMapping;
       renderer.toneMappingExposure = 1.15;
@@ -706,7 +806,13 @@ export default defineComponent({
           // 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.
+          // frame instead. The selection frame follows the same rule for
+          // its own id (the fleet sky strips and re-registers every body
+          // on a roster refresh; the selection must survive that).
+          if (id === selectionId) {
+            selectionBound = false;
+            selectionCooldown = 0;
+          }
           if (id === lastHover) {
             frameBound = false;
             measureCooldown = 0;
@@ -753,6 +859,24 @@ export default defineComponent({
         // A snapshot: a consumer that casts it to Map and clears it must
         // not be able to desynchronise the board from its scene.
         objects: () => new Map(registry),
+        setSelection(id) {
+          // Re-selecting the SAME id is a no-op: releasing the latch would
+          // force a full re-measure next frame for a frame that is already
+          // correct — a page that re-selects on every data refresh would
+          // otherwise pay the subtree walk each time (the hover path makes
+          // the same guard at the event level).
+          if (selectionId === id) return;
+          // The frame hides itself while the id is absent from the
+          // registry (syncSelectionFrame runs every frame), so an unknown
+          // or not-yet-registered id is accepted as-is — a consumer may
+          // legitimately select before the content lands. A CHANGED id
+          // must also release the measurement latch: without this, the
+          // frame keeps riding the PREVIOUS anchor's world matrix and
+          // paints a bracket around the body the user just deselected.
+          selectionId = id;
+          selectionBound = false;
+          selectionCooldown = 0;
+        },
         flyTo(position, target, durationMs = 600) {
           if (!camera || !controls) return;
           // A non-finite pose would brick the camera silently (every later
@@ -970,7 +1094,13 @@ export default defineComponent({
         hoverFrame.dispose();
         hoverFrame = null;
       }
+      if (selectionFrame) {
+        scene?.remove(selectionFrame.object);
+        selectionFrame.dispose();
+        selectionFrame = null;
+      }
       frameBound = false;
+      selectionBound = false;
       controls?.dispose();
       if (labelRenderer?.domElement.parentNode) {
         labelRenderer.domElement.parentNode.removeChild(labelRenderer.domElement);
@@ -1004,7 +1134,16 @@ export default defineComponent({
     });
 
     return () => (
-      <div class="hk-board3d" ref={containerRef}>
+      <div
+        class="hk-board3d"
+        // The transparent-backdrop mode clears the CANVAS to alpha 0, but
+        // the container's own surface paint would still sit behind it —
+        // a page-colored rectangle where the page's backdrop should show.
+        // An inline style wins over the stylesheet without a specificity
+        // war with consumer classes.
+        style={props.transparentBackground ? { background: "transparent" } : undefined}
+        ref={containerRef}
+      >
         <canvas ref={canvasRef} class="hk-board3d-canvas" />
         {failed.value ? (
           slots.fallback ? (