@celestia-island/hikari 0.55.262 → 0.55.263

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.262",
+  "version": "0.55.263",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",

package/src/components/HkBoard3D.controls.test.tsx

@@ -138,3 +138,102 @@ describe("HkBoard3D × real OrbitControls", () => {
     expect(engine!.controls.maxDistance).toBe(80);
   });
 });
+
+/* The orbit ELEVATION window: the solar globe pins min === max to become a
+ * turntable (user direction 2026-11-01: the sphere must only spin about
+ * its vertical axis, never tip / roll). The distance-window suite above
+ * pins the same normalisation discipline for the other orbit axis. */
+const DEG = Math.PI / 180;
+const RING_TILT_DEG = 72;
+
+describe("HkBoard3D orbit elevation window", () => {
+  it("pins the controls' polar angle from the equal prop pair", async () => {
+    let engine: Board3DEngine | null = null;
+    mountBoard(
+      { interactive: true, minPolarAngle: RING_TILT_DEG, maxPolarAngle: RING_TILT_DEG },
+      (e) => (engine = e),
+    );
+    await nextTick();
+    await tickFrames();
+
+    expect(engine!.controls.minPolarAngle).toBeCloseTo(RING_TILT_DEG * DEG, 6);
+    expect(engine!.controls.maxPolarAngle).toBeCloseTo(RING_TILT_DEG * DEG, 6);
+  });
+
+  it("normalises a reversed, out-of-range or non-finite window", async () => {
+    let engine: Board3DEngine | null = null;
+    mountBoard(
+      // 120 > -30 (reversed) and both bounds are outside the sphere.
+      { interactive: true, minPolarAngle: 120, maxPolarAngle: -30 },
+      (e) => (engine = e),
+    );
+    await nextTick();
+    await tickFrames();
+
+    expect(engine!.controls.minPolarAngle).toBe(0);
+    expect(engine!.controls.maxPolarAngle).toBe(120 * DEG);
+
+    mountBoard(
+      { interactive: true, minPolarAngle: Number.NaN, maxPolarAngle: 999 },
+      (e) => (engine = e),
+    );
+    await nextTick();
+    await tickFrames();
+    expect(engine!.controls.minPolarAngle).toBe(0);
+    expect(engine!.controls.maxPolarAngle).toBeCloseTo(Math.PI, 6);
+  });
+
+  it("relaxes the elevation window when the board is not interactive", async () => {
+    let engine: Board3DEngine | null = null;
+    mountBoard(
+      { interactive: false, minPolarAngle: RING_TILT_DEG, maxPolarAngle: RING_TILT_DEG },
+      (e) => (engine = e),
+    );
+    await nextTick();
+    await tickFrames();
+
+    // Same contract as the distance window: an externally driven camera
+    // is never fought, so a locked elevation must not survive here.
+    expect(engine!.controls.minPolarAngle).toBe(0);
+    expect(engine!.controls.maxPolarAngle).toBeCloseTo(Math.PI, 6);
+    engine!.camera.position.set(0, 6, 0);
+    engine!.controls.target.set(0, 0, 0);
+    engine!.controls.update();
+    expect(engine!.camera.position.y).toBeCloseTo(6, 5);
+  });
+
+  it("keeps the elevation fixed while azimuth alone can orbit (turntable)", async () => {
+    let engine: Board3DEngine | null = null;
+    mountBoard(
+      { interactive: true, minPolarAngle: RING_TILT_DEG, maxPolarAngle: RING_TILT_DEG },
+      (e) => (engine = e),
+    );
+    await nextTick();
+    await tickFrames();
+
+    const controls = engine!.controls;
+    const camera = engine!.camera;
+    controls.enableDamping = false;
+
+    // An external pose far above the ring snaps down onto it: the eye
+    // cannot climb toward the pole.
+    camera.position.set(0, 6, 0);
+    controls.target.set(0, 0, 0);
+    controls.update();
+    const ringRadius = camera.position.length();
+    const fixedY = ringRadius * Math.cos(RING_TILT_DEG * DEG);
+    expect(camera.position.y).toBeCloseTo(fixedY, 5);
+
+    // A vertical orbit input is absorbed; a horizontal one still turns.
+    controls.rotateUp(0.8);
+    controls.update();
+    expect(camera.position.y).toBeCloseTo(fixedY, 5);
+    const azimuthBefore = Math.atan2(camera.position.x, camera.position.z);
+    controls.rotateLeft(0.6);
+    controls.update();
+    expect(camera.position.y).toBeCloseTo(fixedY, 5);
+    expect(
+      Math.abs(Math.atan2(camera.position.x, camera.position.z) - azimuthBefore),
+    ).toBeGreaterThan(0.3);
+  });
+});

package/src/components/HkBoard3D.tsx

@@ -8,8 +8,12 @@
  * stereoscopic minimap; the page owns the content:
  *
  *  - CAMERA: perspective + OrbitControls (damped orbit / wheel zoom /
- *    right-or-two-finger pan), distance clamps, `frameAll` fit and
- *    animated `flyTo`;
+ *    right-or-two-finger pan), orbit distance AND elevation windows,
+ *    `frameAll` fit and animated `flyTo` — an equal
+ *    `minPolarAngle`/`maxPolarAngle` pair locks the eye's elevation, so
+ *    azimuth is the only ORBIT axis left; with panning off the scene
+ *    then spins about the vertical axis (the turntable behaviour a globe
+ *    picker needs);
  *  - CONTENT: `engine.setObject(id, def)` registers an Object3D as
  *    addressable content — it joins framing, minimap markers and (when
  *    `pickable`) raycast picking; `label` attaches a CSS2D chip that
@@ -326,6 +330,18 @@ function selectionFrameColor(): THREE.Color {
   return cssRgbToColor(readCssColor("--color-primary", "21 101 192"));
 }
 
+/** Orbit elevation window for the `minPolarAngle` / `maxPolarAngle` props:
+ *  degrees in, radians out, clamped to the sphere's 0…180° range. A
+ *  non-finite bound falls back to the OrbitControls default, and a
+ *  reversed window normalises (same rule as the distance window) instead
+ *  of leaving OrbitControls with min > max. */
+function polarWindow(minDeg: number, maxDeg: number): { min: number; max: number } {
+  const toRad = (deg: number) => (Math.min(180, Math.max(0, deg)) * Math.PI) / 180;
+  const min = Number.isFinite(minDeg) ? toRad(minDeg) : 0;
+  const max = Number.isFinite(maxDeg) ? toRad(maxDeg) : Math.PI;
+  return { min: Math.min(min, max), max: Math.max(min, max) };
+}
+
 export default defineComponent({
   name: "HkBoard3D",
   props: {
@@ -358,6 +374,19 @@ export default defineComponent({
     maxDistance: { type: Number, default: 600 },
     /** Wire two-finger / right-drag panning. STATIC after mount. */
     enablePan: { type: Boolean, default: true },
+    /** Orbit elevation window in DEGREES from the scene's +Y axis
+     *  (OrbitControls' polar angle). STATIC after mount (applied to the
+     *  controls once; at mount it is relaxed to 0…180° when the board
+     *  mounts non-interactive, because an externally driven camera is
+     *  never fought — the same rule as the distance window, and like that
+     *  window it is NOT re-applied on a runtime `interactive` flip). The
+     *  pair pins how far the eye
+     *  may climb toward either pole; EQUAL values lock the elevation
+     *  outright and leave azimuth as the only orbit axis — the turntable
+     *  behaviour a globe or instrument board needs. A reversed window
+     *  normalises; the default is the full 0…180° sphere. */
+    minPolarAngle: { type: Number, default: 0 },
+    maxPolarAngle: { type: Number, default: 180 },
     /** Options for the lighting rig created on first `applyLighting`
      *  (ambient floor, shadow map size). */
     lighting: {
@@ -756,15 +785,26 @@ export default defineComponent({
       // at min forever and defeating every frameAll. Normalise instead.
       controls.minDistance = Math.min(props.minDistance, props.maxDistance);
       controls.maxDistance = Math.max(props.minDistance, props.maxDistance);
+      // The elevation window: same normalisation discipline as the
+      // distance window above, in degrees at the prop boundary. Equal
+      // bounds pin the eye to one elevation (turntable/yaw-only orbit).
+      const polar = polarWindow(props.minPolarAngle, props.maxPolarAngle);
+      controls.minPolarAngle = polar.min;
+      controls.maxPolarAngle = polar.max;
       controls.enablePan = props.enablePan;
       controls.target.set(initTarget[0], initTarget[1], initTarget[2]);
       controls.enabled = props.interactive;
       if (!props.interactive) {
         // An externally-driven camera (the board is just its renderer)
-        // must not be fought by the orbit distance window — the panel
-        // flies to poses far beyond any interactive zoom range.
+        // must not be fought by the orbit windows — the panel flies to
+        // poses far beyond any interactive zoom range, from any
+        // elevation. OrbitControls' update() clamps BOTH bounds every
+        // frame regardless of `enabled`, so the elevation window has to
+        // be relaxed here too, not just the radius.
         controls.minDistance = 0;
         controls.maxDistance = Infinity;
+        controls.minPolarAngle = 0;
+        controls.maxPolarAngle = Math.PI;
       }
       controls.update();
 

package/src/components/HkSolarLocationSetting.tsx

@@ -233,9 +233,9 @@ export const HkSolarLocationSetting = defineComponent({
               <div class="hk-solar-manual">
                 {/* The globe picker (2026-10-31): 24 equal time-sector
                     wedges on a spinning, borderless world-plates sphere,
-                    translated tooltip included — the IANA dropdown it
-                    replaced listed hundreds of raw zone ids. Still
-                    writes the same draftTimeZone the engine applies. */}
+                    an always-on top-center readout included — the IANA
+                    dropdown it replaced listed hundreds of raw zone ids.
+                    Still writes the same draftTimeZone the engine applies. */}
                 <HkTimeZoneGlobe
                   modelValue={draftTimeZone.value}
                   onUpdate:modelValue={onSelectTimeZone}

package/src/components/HkTimeZoneGlobe.board.test.tsx

@@ -0,0 +1,263 @@
+// AI-generated: developed with the ZCode agent (model GLM-5.3); human-directed.
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createApp, h, nextTick, ref, type Ref } from "vue";
+
+/**
+ * HkTimeZoneGlobe × HkBoard3D — the picker's WEBGL branch contract.
+ *
+ * The real board cannot init in happy-dom (no WebGL), so this suite stubs
+ * it and keeps the board's whole props surface addressable. Two product
+ * directions from 2026-11-01 are template-level promises and belong here:
+ *
+ *  - TURNTABLE: the globe passes equal min/max polar bounds (90° - the
+ *    eye's 18° ring tilt) so the board can only spin about the vertical
+ *    axis — the sphere never tips toward a pole or rolls;
+ *  - READOUT: the SELECTED sector's chip is the globe's own always-on
+ *    layer pinned to the top-center of the stage — not a pointer-following
+ *    tooltip (which sat under the finger on a touch drag), not gated on
+ *    hover, and not rewritten by hover either (a drag re-selects without
+ *    moving the pointer, so a hover preview would go stale as it is read).
+ *
+ * The no-WebGL assertions (fallback list, readout stepping aside) live in
+ * HkTimeZoneGlobe.test.tsx, which mounts the real board.
+ */
+
+interface CapturedBoard {
+  minPolarAngle?: number;
+  maxPolarAngle?: number;
+  interactive?: boolean;
+  minimap?: boolean;
+  minimapCollapsible?: boolean;
+  minimapDefaultCollapsed?: boolean;
+  enablePan?: boolean;
+  minDistance?: number;
+  maxDistance?: number;
+  /** The globe's onObjectHover listener (preview a wedge). */
+  onObjectHover: ((id: string | null) => void) | null;
+  /** The globe's onError listener (no-WebGL report). */
+  onError: ((message: string) => void) | null;
+}
+
+const captured = vi.hoisted(() => ({ boards: [] as CapturedBoard[] }));
+
+vi.mock("./HkBoard3D", async () => {
+  const vue = await import("vue");
+  /** Narrow an undeclared-listener attr without a double cast. */
+  function listenerOf<T extends (...args: never[]) => void>(value: unknown): T | null {
+    return typeof value === "function" ? (value as T) : null;
+  }
+  const BoardStub = vue.defineComponent({
+    name: "HkBoard3D",
+    props: {
+      interactive: Boolean,
+      minimap: Boolean,
+      minimapCollapsible: Boolean,
+      minimapDefaultCollapsed: Boolean,
+      hoverBox: Boolean,
+      transparentBackground: Boolean,
+      enablePan: Boolean,
+      minPolarAngle: Number,
+      maxPolarAngle: Number,
+      fov: Number,
+      minDistance: Number,
+      maxDistance: Number,
+      initialPosition: Array,
+      initialTarget: Array,
+    },
+    // Deliberately NO `emits` declaration: the globe's listeners then land
+    // in `attrs`, which is exactly how this suite reaches onObjectHover /
+    // onError without the stub ever calling emit().
+    setup(props, { attrs }) {
+      captured.boards.push({
+        minPolarAngle: props.minPolarAngle,
+        maxPolarAngle: props.maxPolarAngle,
+        interactive: props.interactive,
+        minimap: props.minimap,
+        minimapCollapsible: props.minimapCollapsible,
+        minimapDefaultCollapsed: props.minimapDefaultCollapsed,
+        enablePan: props.enablePan,
+        minDistance: props.minDistance,
+        maxDistance: props.maxDistance,
+        onObjectHover: listenerOf<(id: string | null) => void>(attrs.onObjectHover),
+        onError: listenerOf<(message: string) => void>(attrs.onError),
+      });
+      return () => null;
+    },
+  });
+  return { default: BoardStub };
+});
+
+import HkTimeZoneGlobe from "./HkTimeZoneGlobe";
+import { setLocale } from "../i18n/context";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mountGlobe(modelValue = "Asia/Shanghai"): {
+  container: HTMLElement;
+  zone: Ref<string>;
+} {
+  captured.boards.length = 0;
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  // A live modelValue ref, so a test can drive a re-selection the way the
+  // host does (HkSolarLocationSetting writes draftTimeZone).
+  const zone = ref(modelValue);
+  const app = createApp({
+    render: () =>
+      h(HkTimeZoneGlobe, {
+        modelValue: zone.value,
+        "onUpdate:modelValue": (next: string) => {
+          zone.value = next;
+        },
+      }),
+  });
+  app.mount(container);
+  mounts.push({ app, container });
+  return { container, zone };
+}
+
+async function settle(): Promise<void> {
+  await nextTick();
+  await new Promise((resolve) => setTimeout(resolve, 20));
+  await nextTick();
+}
+
+function board(): CapturedBoard {
+  expect(captured.boards, "the globe mounted one board").toHaveLength(1);
+  return captured.boards[0]!;
+}
+
+function readout(): HTMLElement | null {
+  return document.body.querySelector<HTMLElement>('[data-test="hk-timezone-globe-readout"]');
+}
+
+beforeEach(() => {
+  localStorage.clear();
+});
+
+afterEach(async () => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+  await setLocale("en");
+});
+
+describe("HkTimeZoneGlobe turntable contract", () => {
+  it("locks the board's orbit elevation to the eye ring (equal polar bounds)", async () => {
+    mountGlobe();
+    await settle();
+
+    const { minPolarAngle, maxPolarAngle, interactive } = board();
+    // 90° - EYE_TILT_DEG (18°) = 72°, as a DEGREE-valued board prop.
+    expect(minPolarAngle).toBe(72);
+    expect(maxPolarAngle).toBe(72);
+    expect(minPolarAngle).toBe(maxPolarAngle);
+    // The lock only binds on an INTERACTIVE board: a non-interactive board
+    // deliberately relaxes the elevation window for its external driver,
+    // so the globe must never mount as one.
+    expect(interactive).toBe(true);
+  });
+
+  it("keeps the minimap (collapsible, folded by default) and disables panning", async () => {
+    mountGlobe();
+    await settle();
+
+    const b = board();
+    expect(b.minimap).toBe(true);
+    expect(b.minimapCollapsible).toBe(true);
+    expect(b.minimapDefaultCollapsed).toBe(true);
+    expect(b.enablePan).toBe(false);
+    // The picker still owns its own distance window and framing.
+    expect(b.minDistance).toBe(2.15);
+    expect(b.maxDistance).toBe(3.6);
+  });
+});
+
+describe("HkTimeZoneGlobe pinned readout", () => {
+  it("shows the selected sector with no hover needed (always on)", async () => {
+    mountGlobe("Asia/Shanghai");
+    await settle();
+
+    const el = readout();
+    expect(el, "the readout renders without any pointer interaction").toBeTruthy();
+    expect(el!.textContent).toContain("UTC+8");
+    expect(el!.textContent).toContain("Asia/Shanghai");
+    // A city from the SELECTED band's second line — "Singapore" is not a
+    // substring of the zone id, so only the cities row can satisfy it
+    // ("Shanghai" would have been satisfied by "Asia/Shanghai").
+    const cities = el!.querySelector<HTMLElement>(".hk-timezone-globe__readout-cities");
+    expect(cities, "the cities line renders").toBeTruthy();
+    expect(cities!.textContent).toContain("Singapore");
+    // A live region, so a COMMITTED re-pick is spoken; hover never
+    // rewrites the chip, so hovering cannot flood the announce queue.
+    expect(el!.getAttribute("role")).toBe("status");
+    expect(el!.getAttribute("aria-live")).toBe("polite");
+    expect(el!.getAttribute("aria-atomic")).toBe("true");
+    // The old pointer-following tooltip is gone for good.
+    expect(document.body.querySelector('[data-test="hk-timezone-globe-tooltip"]')).toBeNull();
+  });
+
+  it("follows a committed re-selection when the host writes a new zone", async () => {
+    const { zone } = mountGlobe("Asia/Shanghai");
+    await settle();
+    expect(readout()!.textContent).toContain("Asia/Shanghai");
+
+    // The host's write path (draftTimeZone → modelValue), not a click: the
+    // chip must re-render on the new band, not stay frozen at mount.
+    zone.value = "Africa/Cairo";
+    await settle();
+    expect(readout()!.textContent).toContain("Africa/Cairo");
+    expect(readout()!.textContent).toContain("UTC+2");
+    expect(readout()!.textContent).not.toContain("Asia/Shanghai");
+  });
+
+  it("keeps showing the committed selection while a wedge is hovered", async () => {
+    mountGlobe("Asia/Shanghai");
+    await settle();
+
+    const onObjectHover = board().onObjectHover;
+    expect(onObjectHover, "the globe wired the board's hover event").toBeTruthy();
+    onObjectHover!("sector-20"); // offset +9 → Asia/Tokyo
+    await settle();
+    // The chip is a selection statement: hover only tints the wedge.
+    expect(readout()!.textContent).toContain("Asia/Shanghai");
+    expect(readout()!.textContent).not.toContain("Asia/Tokyo");
+
+    onObjectHover!(null);
+    await settle();
+    expect(readout()!.textContent).toContain("Asia/Shanghai");
+  });
+
+  it("does not repeat an English band name that IS its offset label", async () => {
+    await setLocale("en"); // explicit: this contract is locale-dependent
+    mountGlobe("Asia/Shanghai");
+    await settle();
+
+    const text = readout()!.textContent ?? "";
+    expect(text.match(/UTC\+8/g)).toHaveLength(1);
+    expect(text).toContain("Asia/Shanghai");
+  });
+
+  it("keeps the translated band name where the locale names the band (zh-Hans)", async () => {
+    await setLocale("zh-Hans");
+    mountGlobe("Asia/Shanghai");
+    await settle();
+
+    const text = readout()!.textContent ?? "";
+    expect(text).toContain("UTC+8");
+    expect(text).toContain("东八区");
+  });
+
+  it("steps aside when the board reports no WebGL (the fallback list is the interface)", async () => {
+    mountGlobe("Asia/Shanghai");
+    await settle();
+    expect(readout()).toBeTruthy();
+
+    const onError = board().onError;
+    expect(onError, "the globe wired the board's error event").toBeTruthy();
+    onError!("no webgl (test)");
+    await settle();
+    expect(readout()).toBeNull();
+  });
+});

package/src/components/HkTimeZoneGlobe.scss

@@ -1,6 +1,6 @@
-/* HkTimeZoneGlobe — the manual zone picker's globe stage, tooltip and
- * no-WebGL fallback list. AI-generated: developed with the ZCode agent
- * (model GLM-5.3); human-directed. */
+/* HkTimeZoneGlobe — the manual zone picker's globe stage, always-on
+ * readout and no-WebGL fallback list. AI-generated: developed with the
+ * ZCode agent (model GLM-5.3); human-directed. */
 
 .hk-timezone-globe {
   display: flex;
@@ -23,35 +23,64 @@
   touch-action: none;
 }
 
-.hk-timezone-globe__tooltip {
+/* The always-on sector readout: pinned to the TOP-CENTER of the stage
+ * (user direction 2026-11-01). It replaced the pointer-following
+ * tooltip, which on a touch screen sat under the very finger dragging
+ * the globe. A passive HUD layer — pointer-events none, so a drag that
+ * begins on the chip still orbits. */
+.hk-timezone-globe__readout {
   position: absolute;
+  top: var(--space-6, 0.375rem);
+  left: 50%;
   z-index: 2;
-  pointer-events: none;
+  transform: translateX(-50%);
   display: flex;
   flex-direction: column;
-  gap: var(--space-4, 0.25rem);
-  max-width: 15rem;
-  padding: var(--space-8, 0.5rem) var(--space-10, 0.625rem);
+  align-items: center;
+  gap: 1px;
+  max-width: calc(100% - var(--space-16, 1rem));
+  padding: var(--space-4, 0.25rem) var(--space-10, 0.625rem);
   border: 1px solid rgb(var(--color-muted) / 0.35);
   border-radius: var(--radius-sm, 0.375rem);
-  background: rgb(var(--color-background, 22 24 30) / 0.92);
+  background: rgb(var(--color-background, 22 24 30) / 0.88);
   color: inherit;
   font-size: var(--text-xs, 0.75rem);
-  line-height: 1.45;
+  line-height: 1.35;
+  text-align: center;
+  pointer-events: none;
+}
+
+.hk-timezone-globe__readout-head {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  justify-content: center;
+  gap: 0 var(--space-6, 0.375rem);
+  white-space: nowrap;
 }
 
-.hk-timezone-globe__tooltip-offset {
+.hk-timezone-globe__readout-offset {
   color: rgb(var(--color-text-secondary, var(--color-muted)));
   font-weight: 600;
+  font-variant-numeric: tabular-nums;
+}
+
+.hk-timezone-globe__readout-name {
+  font-weight: 600;
 }
 
-.hk-timezone-globe__tooltip-zone {
+.hk-timezone-globe__readout-zone {
+  color: rgb(var(--color-text-secondary, var(--color-muted)));
   font-family: var(--font-mono, ui-monospace, monospace);
   font-size: var(--text-xs, 0.75rem);
 }
 
-.hk-timezone-globe__tooltip-cities {
+.hk-timezone-globe__readout-cities {
+  max-width: 100%;
+  overflow: hidden;
   color: rgb(var(--color-text-secondary, var(--color-muted)));
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 
 .hk-timezone-globe__hint {

package/src/components/HkTimeZoneGlobe.test.tsx

@@ -116,6 +116,9 @@ describe("HkTimeZoneGlobe fallback list", () => {
     const root = document.body.querySelector<HTMLElement>('[data-test="hk-timezone-globe"]')!;
     expect(root.getAttribute("aria-label")).toBe("Time zone globe");
     expect(root.textContent).toContain("Drag to spin the globe");
+    // The pinned HUD is a canvas affordance: without WebGL the list IS the
+    // interface, so the chip must not cover its rows.
+    expect(document.body.querySelector('[data-test="hk-timezone-globe-readout"]')).toBeNull();
   });
 
   it("flows zh-Hans through the sector names and city lists", async () => {
@@ -140,6 +143,36 @@ describe("HkTimeZoneGlobe look contract (source-level)", () => {
     expect(src).toContain("minimapCollapsible");
     expect(src).toContain("minimapDefaultCollapsed");
   });
+
+  it("pins the readout to the stage's TOP-CENTER, pointer-transparent (user direction 2026-11-01)", () => {
+    const scss = readFileSync(join(import.meta.dirname, "HkTimeZoneGlobe.scss"), "utf8");
+    const block = (selector: string): string => {
+      const start = scss.indexOf(selector + " {");
+      expect(start, selector + " exists").toBeGreaterThanOrEqual(0);
+      const end = scss.indexOf("\n}", start);
+      expect(end, selector + " closes").toBeGreaterThan(start);
+      return scss.slice(start, end);
+    };
+
+    // The readout is absolutely positioned, so its containing block must
+    // stay the stage.
+    expect(block(".hk-timezone-globe__stage")).toContain("position: relative");
+
+    const readout = block(".hk-timezone-globe__readout");
+    expect(readout, "a HUD layer over the canvas").toContain("position: absolute");
+    expect(readout, "top-anchored").toMatch(/top:\s*var\(--space-6/);
+    expect(readout, "horizontally centered").toContain("left: 50%");
+    expect(readout, "horizontally centered").toContain("transform: translateX(-50%)");
+    // The board paints an opaque surface later in the DOM, so the chip is
+    // only visible while it stacks above it.
+    expect(readout, "above the board surface").toMatch(/z-index:\s*[1-9]/);
+    // The chip sits over the very surface the user drags; a drag that
+    // begins on it must still reach the canvas.
+    expect(readout, "a passive layer").toContain("pointer-events: none");
+
+    // A long city row must ellipsize inside the chip, not escape it.
+    expect(block(".hk-timezone-globe__readout-cities")).toContain("text-overflow: ellipsis");
+  });
 });
 describe("minimap reset icon contract (user direction 2026-10-31)", () => {
   it("reset buttons use RotateCcw, never the expand-looking Maximize2", () => {

package/src/components/HkTimeZoneGlobe.tsx

@@ -13,14 +13,26 @@
  *    white-alpha, the material tints it with the live theme accent, so
  *    one asset serves dark and light themes;
  *  - SECTORS: 24 pickable wedges of 15 deg longitude (theme/
- *    solarTimeZones.ts) — drag rotates (OrbitControls), settling snaps
- *    the wedge under the eye INTO the selection, clicking a wedge flies
- *    the camera to it; both write the wedge's REPRESENTATIVE IANA zone
+ *    solarTimeZones.ts) — drag spins the globe, settling snaps the wedge
+ *    under the eye INTO the selection, clicking a wedge flies the
+ *    camera to it; both write the wedge's REPRESENTATIVE IANA zone
  *    through update:modelValue (the engine stores exact ids, so a
  *    half-hour config survives until the user actually re-picks);
- *  - TOOLTIP: hovering a wedge surfaces its zone (translated sector
- *    name + the IANA id) and its representative cities — cities only,
- *    never countries (border disputes stay out of a theme picker);
+ *  - TURNTABLE: the board's orbit elevation window is pinned
+ *    (minPolarAngle === maxPolarAngle) to the eye's ring tilt, so the
+ *    sphere can only spin about its vertical axis. It never tips toward
+ *    a pole and never rolls — the north hemisphere keeps its 18° tilt
+ *    (user direction 2026-11-01: "the globe turns in front of you");
+ *  - READOUT: the SELECTED sector stays pinned to the TOP-CENTER of the
+ *    stage — always on, and hover never rewrites it (a drag re-selects
+ *    without moving the pointer, so a hover preview would be stale at
+ *    exactly the moment it is read). It replaced the pointer-following
+ *    tooltip, which on a touch screen landed under the very finger doing
+ *    the drag (user direction 2026-11-01). The head carries the IANA id
+ *    with the translated band name (dropped where the locale's band name
+ *    IS the offset label — English), the second line its representative
+ *    cities: cities only, never countries (border disputes stay out of a
+ *    theme picker);
  *  - MINIMAP: the board pins HkMinimap3D bottom-right — a second,
  *    stereoscopic render of the SAME scene, so the operator always sees
  *    where on the sphere the eye currently sits;
@@ -70,6 +82,11 @@ const DEG = Math.PI / 180;
 /** Eye distance and latitude tilt for the fixed-radius ring orbit. */
 const EYE_DISTANCE = 2.85;
 const EYE_TILT_DEG = 18;
+/** The locked orbit elevation (OrbitControls polar angle, degrees from
+ *  +Y) that pairs with EYE_TILT_DEG: equal min/max polar bounds keep the
+ *  eye on this one ring, so azimuth is the only orbit axis left — the
+ *  globe turns in place instead of tipping. */
+const ORBIT_POLAR_DEG = 90 - EYE_TILT_DEG;
 /** Sphere and wedge radii — the wedges ride slightly above the base to
  *  keep the highlight out of the texture's z-fight band. */
 const GLOBE_RADIUS = 1;
@@ -120,9 +137,12 @@ export default defineComponent({
   setup(props, { emit }) {
     const { t } = useI18n();
     const engine = shallowRef<Board3DEngine | null>(null);
-    const stageRef = ref<HTMLElement | null>(null);
     const hoveredSector = ref<number | null>(null);
-    const tooltipPos = ref({ x: 0, y: 0 });
+    // The stage readout is a HUD for the CANVAS; without WebGL the board's
+    // fallback list is the whole interface (every sector already shows its
+    // zone there), so the HUD steps aside instead of covering its first
+    // rows.
+    const webglFailed = ref(false);
 
     // Per-mount three handles the board does NOT own (we created them,
     // we dispose them — the board never disposes consumer objects).
@@ -138,10 +158,13 @@ export default defineComponent({
 
     const selectedSector = computed(() => sectorIndexForZone(props.modelValue));
 
-    const selectedInfo = computed(() => {
-      const idx = hoveredSector.value ?? selectedSector.value;
-      return SOLAR_TIME_ZONE_SECTORS[idx] ?? null;
-    });
+    // The pinned readout reports the COMMITTED selection, never the
+    // hovered wedge. Hover already answers "what am I pointing at" on the
+    // globe itself (the wedge highlight); the always-on chip must keep
+    // answering "what is selected", because a drag that re-selects does
+    // not move the pointer — a hover preview there would go stale at
+    // exactly the moment the user is looking at it.
+    const selectedInfo = computed(() => SOLAR_TIME_ZONE_SECTORS[selectedSector.value] ?? null);
 
     function citiesLine(sector: { cities: readonly string[] }): string {
       const sep = t("hikari::theme.solar.citySeparator", ", ");
@@ -281,11 +304,8 @@ export default defineComponent({
       hoveredSector.value = m ? parseInt(m[1] ?? "", 10) : null;
     }
 
-    function onPointerMove(ev: PointerEvent): void {
-      const stage = stageRef.value;
-      if (!stage) return;
-      const rect = stage.getBoundingClientRect();
-      tooltipPos.value = { x: ev.clientX - rect.left, y: ev.clientY - rect.top };
+    function onBoardError(): void {
+      webglFailed.value = true;
     }
 
     onBeforeUnmount(() => {
@@ -337,6 +357,11 @@ export default defineComponent({
 
     return () => {
       const info = selectedInfo.value;
+      // In `en`, a band's translated name IS its offset label ("UTC+8"), so
+      // rendering both would read "UTC+8 UTC+8". Keep the name only where
+      // the locale actually names the band differently.
+      const infoOffset = info ? offsetLabel(info.offset) : "";
+      const infoName = info ? t(sectorNameKey(info.offset)) : "";
       const initialEye = ringPosition(sectorCenterLngDeg(
         SOLAR_TIME_ZONE_SECTORS[selectedSector.value]?.offset ?? 0,
       ));
@@ -347,7 +372,25 @@ export default defineComponent({
           aria-label={t("hikari::theme.solar.globeLabel")}
           data-test="hk-timezone-globe"
         >
-          <div class="hk-timezone-globe__stage" ref={stageRef} onPointermove={onPointerMove}>
+          <div class="hk-timezone-globe__stage">
+            {info && !webglFailed.value && (
+              <div
+                class="hk-timezone-globe__readout"
+                data-test="hk-timezone-globe-readout"
+                role="status"
+                aria-live="polite"
+                aria-atomic="true"
+              >
+                <span class="hk-timezone-globe__readout-head">
+                  <span class="hk-timezone-globe__readout-offset">{infoOffset}</span>
+                  {infoName !== infoOffset && (
+                    <span class="hk-timezone-globe__readout-name">{infoName}</span>
+                  )}
+                  <span class="hk-timezone-globe__readout-zone">{info.zone}</span>
+                </span>
+                <span class="hk-timezone-globe__readout-cities">{citiesLine(info)}</span>
+              </div>
+            )}
             <HkBoard3D
               interactive
               minimap
@@ -356,6 +399,10 @@ export default defineComponent({
               hoverBox={false}
               transparentBackground
               enablePan={false}
+              // Turntable: equal polar bounds pin the eye to its ring, so
+              // the globe spins about its vertical axis only.
+              minPolarAngle={ORBIT_POLAR_DEG}
+              maxPolarAngle={ORBIT_POLAR_DEG}
               fov={38}
               minDistance={2.15}
               maxDistance={3.6}
@@ -364,25 +411,10 @@ export default defineComponent({
               onReady={onReady}
               onObjectClick={onObjectClick}
               onObjectHover={onObjectHover}
+              onError={onBoardError}
             >
               {{ fallback: fallbackList }}
             </HkBoard3D>
-            {info && hoveredSector.value !== null && (
-              <div
-                class="hk-timezone-globe__tooltip"
-                data-test="hk-timezone-globe-tooltip"
-                style={{
-                  left: tooltipPos.value.x + 14 + "px",
-                  top: tooltipPos.value.y + 14 + "px",
-                }}
-              >
-                <span class="hk-timezone-globe__tooltip-offset">
-                  {offsetLabel(info.offset)} · {t(sectorNameKey(info.offset))}
-                </span>
-                <span class="hk-timezone-globe__tooltip-zone">{info.zone}</span>
-                <span class="hk-timezone-globe__tooltip-cities">{citiesLine(info)}</span>
-              </div>
-            )}
           </div>
           <p class="hk-timezone-globe__hint">{t("hikari::theme.solar.globeHint")}</p>
         </div>

package/src/theme/solarGlobeMap.ts

@@ -5,7 +5,7 @@
  *
  * Deliberately a BORDERLESS world: the map carries continent silhouettes
  * and TECTONIC PLATE boundary lines only — never national borders, never
- * country labels (city names in the picker's tooltip are the only named
+ * country labels (city names in the picker's readout are the only named
  * places, and names of cities carry no border disputes). The 15°
  * meridian graticule doubles as the 24 time-sector edges the picker
  * selects between.

package/src/theme/solarTimeZones.ts

@@ -15,9 +15,9 @@
  *    offset (offset hours / 4 degrees... equivalently hours × 15°) — the
  *    picked wedge and the engine's derived fix AGREE by construction;
  *  - representative zones are the canonical IANA ids for each band;
- *  - representative CITIES are display-only examples (the tooltip lists
- *    them translated; deliberately never the countries — city names
- *    carry no border disputes);
+ *  - representative CITIES are display-only examples (the globe's pinned
+ *    readout lists them translated; deliberately never the countries —
+ *    city names carry no border disputes);
  *  - half-hour zones (Asia/Kolkata, Asia/Yangon, …) still SELECT fine:
  *    `sectorIndexForZone` rounds the zone's standard offset to the
  *    nearest whole-hour band, and the stored zone id keeps the exact
@@ -37,9 +37,9 @@ export interface SolarTimeZoneSector {
   offset: number;
   /** Representative IANA zone id — what selecting the wedge stores. */
   zone: string;
-  /** Representative city slugs for the hover tooltip (locale keys live
-   *  under `hikari::theme.solar.city.<slug>`, translated per language;
-   *  cities only, never countries). */
+  /** Representative city slugs for the globe's pinned readout (locale
+   *  keys live under `hikari::theme.solar.city.<slug>`, translated per
+   *  language; cities only, never countries). */
   cities: readonly string[];
 }