@celestia-island/hikari 0.55.261 → 0.55.263

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.261",
+  "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/HkMenu.rail.test.tsx

@@ -200,6 +200,11 @@ describe("HkMenu sidebar icon rail", () => {
 
     const children = c.querySelector(".hk-menu-sidebar-rail-children");
     expect(children, "the open group lists its children in the rail").toBeTruthy();
+    // The rail wrapper wears the SHARED children class too: the expanded
+    // sidebar's 2px margin step reaches the rail through it — that class
+    // union IS the vertical-invariance carrier (2026-10-31). A rail-only
+    // wrapper would re-introduce the per-density step.
+    expect(children!.classList.contains("hk-menu-sidebar-children")).toBe(true);
     const childRows = railRows(children!);
     expect(childRows.map((row) => row.getAttribute("aria-label"))).toEqual(["Users", "Audit log"]);
     for (const row of childRows) {
@@ -238,6 +243,15 @@ describe("HkMenu sidebar icon rail", () => {
     expect(c.querySelector(".hk-menu-sidebar-group[data-open]"), "the group is still open").toBeTruthy();
     expect(groupRows(c)[0]!.getAttribute("aria-expanded")).toBe("true");
     expect(c.textContent).toContain("Users");
+    // TWO-SIDED class-union pin: the EXPANDED wrapper must wear the
+    // shared class too. Dropping it there removes the 2px step from the
+    // expanded sidebar — rows below an open group would move on every
+    // flip, the exact drift this contract kills (a rail-only pin let
+    // that through).
+    expect(
+      c.querySelector(".hk-menu-sidebar-group[data-open] > .hk-menu-sidebar-children"),
+      "the expanded children wrapper keeps the shared step class",
+    ).toBeTruthy();
 
     // Reverse direction: collapse it from the expanded sidebar, flip
     // back into the rail — it must stay collapsed (no resurrection).
@@ -508,10 +522,65 @@ describe("HkMenu rail styles (compiled sheet contracts)", () => {
     expect(row).toContain("justify-content: center");
   });
 
-  it("keeps open group children in the same one-column rhythm (no indent step)", () => {
+  it("keeps open group children at the EXPANDED vertical step (no rail re-step)", () => {
+    // Vertical rhythm is density-invariant (2026-10-31 user direction:
+    // the collapse toggle must not move rows). The rail children wrapper
+    // therefore carries NO margin rule of its own — the expanded
+    // sidebar's 2px step from the shared .hk-menu-sidebar-children rule
+    // applies in the rail too, and the wrapper stays width-only (its
+    // selector survives only inside the comma-grouped width rule, which
+    // the exact-line ruleBody skips — the null here asserts no
+    // STANDALONE rail-children rule came back).
     const children = ruleBody(".hk-menu-sidebar[data-collapsed] .hk-menu-sidebar-rail-children");
-    expect(children, "the rail children rule exists").not.toBeNull();
-    expect(children).toContain("margin-top: 0");
+    expect(children, "a standalone rail-children rule re-stepped the margin").toBeNull();
+    const shared = ruleBody(".hk-menu-sidebar-children");
+    expect(shared, "the shared children rule exists").not.toBeNull();
+    expect(shared).toContain("margin-top: var(--space-2, 2px)");
+    // A rule whose selector is EXACTLY a rail wrapper class — top-level,
+    // outside any density dress — would restyle the rail children while
+    // evading every dress-keyed scan below (the compiled chunk then
+    // carries no carrier text). The wrappers' geometry must come from
+    // the shared rules alone.
+    expect(css.match(/^\s*\.hk-menu-sidebar-rail-(?:children|group)\s*\{/gm)).toBeNull();
+  });
+
+  it("the rail dress authors no vertical rhythm in any spelling", () => {
+    // The stronger form of the contract above, so a re-step cannot hide
+    // inside a comma-grouped selector the per-selector ruleBody skips
+    // AND cannot return through alternate spellings or sister metrics:
+    // every rule of the density dress is scanned and banned for ANY
+    // margin/padding spelling that reaches a block edge — the shorthand
+    // (it sets the block side too: the historical `margin-top: 0`
+    // regression spelled `margin: 0` evaded a longhand-only scan) and
+    // every vertical longhand, top AND bottom — plus the block-FLOW
+    // metrics that move rows just the same (gap/row-gap/height/
+    // min-height/max-height: a `gap:` inside the comma-grouped width
+    // rule once passed a margin/padding-only scan). Horizontal-only
+    // tracks (margin-inline*, padding-inline*) stay legal; absolute
+    // INSETS (the caret corner's inset-block-end) are flow-neutral
+    // decoration and stay legal. A rail band that truly needs a
+    // different block metric must move the BASE rule for BOTH densities.
+    // Keyed to BOTH carrier spellings so a future [data-rail]-keyed
+    // carrier in this sheet cannot slip the scan.
+    const dressRules = css
+      .split("}")
+      .filter(
+        (rule) =>
+          rule.includes(".hk-menu-sidebar[data-collapsed]") ||
+          rule.includes(".hk-menu-sidebar[data-rail]"),
+      );
+    expect(dressRules.length, "the rail dress rules exist").toBeGreaterThan(3);
+    for (const rule of dressRules) {
+      expect(rule, `vertical margin in the rail dress: ${rule}`).not.toMatch(
+        /\bmargin(?:-(?:top|bottom|block(?:-(?:start|end))?))?\s*:/,
+      );
+      expect(rule, `vertical padding in the rail dress: ${rule}`).not.toMatch(
+        /\bpadding(?:-(?:top|bottom|block(?:-(?:start|end))?))?\s*:/,
+      );
+      expect(rule, `block-flow metric in the rail dress: ${rule}`).not.toMatch(
+        /\b(?:gap|row-gap|height|min-height|max-height)\s*:/,
+      );
+    }
   });
 
   it("mirrors the rail caret in RTL with the scaleX convention, never a rotate", () => {

package/src/components/HkMenu.scss

@@ -193,18 +193,18 @@
     font-weight: 600;
   }
 
-  /* Rail groups keep the rail rhythm at every depth: the children
-   * wrapper spends the rail's own row gap, with no margin step above
-   * the first child and never an indent. */
+  /* Rail groups keep the ONE-COLUMN rhythm at every depth: width-only,
+   * never an indent. The children wrapper deliberately carries NO
+   * margin override of its own — the expanded sidebar's 2px step (the
+   * shared .hk-menu-sidebar-children rule above) applies in the rail
+   * too, because vertical rhythm is density-invariant (2026-10-31 user
+   * direction): a rail-specific step would move every row below an open
+   * group on each collapse/expand flip. */
   .hk-menu-sidebar-rail-group,
   .hk-menu-sidebar-rail-children {
     width: 100%;
   }
 
-  .hk-menu-sidebar-rail-children {
-    margin-top: 0;
-  }
-
   /* Disclosure ink, at the same secondary weight as the expanded
    * sidebar's .hk-menu-more. The placeholder form lives in the glyph
    * cell and centers like every other row icon. */

package/src/components/HkSidebar.scss

@@ -86,23 +86,27 @@
  * kit (HkSidebarRailSwap) — the generation's [data-rail] flips with the
  * swap key, so the leaving generation keeps its dress for the dissolve
  * while the entering one takes the new one. A root-level attr cannot do
- * that: it would restyle the frozen leaving copy mid-dissolve. */
+ * that: it would restyle the frozen leaving copy mid-dissolve.
+ *
+ * VERTICAL RHYTHM IS DENSITY-INVARIANT (2026-10-31 user direction: the
+ * collapse toggle must not move rows). The dress authors INLINE geometry
+ * only — the header/footer rules below narrow the horizontal padding for
+ * the rail column and recentre the header, while every BLOCK metric (the
+ * header's 16px band, the body's 20px leading air + scroll tail, the
+ * footer's 16px band) stays with the base rules alone. Shrinking the
+ * collapsed paddings used to lift the whole nav by up to two paddings'
+ * worth on every flip; a band that needs a different vertical dress in
+ * rail mode would have to move the base values for BOTH densities, never
+ * add a per-density block padding. */
 .hk-sidebar[data-collapsed],
 .hk-sidebar-rail-generation[data-rail] {
   .hk-sidebar-header {
     justify-content: center;
-    padding: var(--space-12) var(--space-8);
-  }
-
-  .hk-sidebar-body {
-    /* Same end-cap as the expanded body — collapsed rows are icon-only
-     * but the tail's job (announcing the end of the scroll range) is
-     * identical, so only the leading air shrinks here. */
-    padding-block: var(--space-12) var(--hk-sidebar-scroll-tail);
+    padding: var(--space-16) var(--space-8);
   }
 
   .hk-sidebar-footer {
-    padding: var(--space-12) var(--space-8);
+    padding: var(--space-16) var(--space-8);
   }
 }
 

package/src/components/HkSidebar.styles.test.ts

@@ -74,16 +74,61 @@ describe("HkSidebar scroll end-cap", () => {
     expect(body).not.toMatch(/padding-block:[^;]*--space-4/);
   });
 
-  it("keeps the same tail on the collapsed body", () => {
-    // The density dress is keyed off EITHER carrier — the legacy root's
-    // [data-collapsed] or the rail swap generation's [data-rail] (the
-    // generation attr freezes on the leaving copy for the dissolve, a
-    // root attr cannot). ruleBody needs the arm its brace follows, so the
-    // legacy arm is asserted as text and the body read from the group.
-    expect(css).toContain(".hk-sidebar[data-collapsed] .hk-sidebar-body");
-    const body = ruleBody(css, ".hk-sidebar-rail-generation[data-rail] .hk-sidebar-body");
-    expect(body, "the collapsed body rule exists (grouped density carriers)").not.toBeNull();
-    expect(body).toContain("padding-block: var(--space-12) var(--hk-sidebar-scroll-tail)");
+  it("the density dress keeps every vertical metric at the expanded value", () => {
+    // Vertical rhythm is density-invariant (2026-10-31 user direction:
+    // the collapse toggle must not move rows). The body therefore has no
+    // density rule AT ALL — the leading air AND the scroll tail ride the
+    // single base rule in both densities — and the header/footer dress
+    // rules keep the expanded BLOCK padding, narrowing only the inline
+    // track for the rail column.
+    expect(css).not.toContain(".hk-sidebar[data-collapsed] .hk-sidebar-body");
+    expect(css).not.toContain(".hk-sidebar-rail-generation[data-rail] .hk-sidebar-body");
+    // The two carrier literals above are the compiled spellings; a brand
+    // NEW carrier (a third density hook) is a new dress and must re-run
+    // this contract — not mechanically foreseeable here.
+    // ruleBody needs the arm its brace follows; the dress compiles to one
+    // comma-grouped rule per band, so the generation arm is the one the
+    // helper can read (the legacy arm shares its body).
+    const header = ruleBody(css, ".hk-sidebar-rail-generation[data-rail] .hk-sidebar-header");
+    expect(header, "the collapsed header rule exists (grouped density carriers)").not.toBeNull();
+    expect(header).toContain("padding: var(--space-16) var(--space-8)");
+    const footer = ruleBody(css, ".hk-sidebar-rail-generation[data-rail] .hk-sidebar-footer");
+    expect(footer, "the collapsed footer rule exists (grouped density carriers)").not.toBeNull();
+    expect(footer).toContain("padding: var(--space-16) var(--space-8)");
+    // The stronger, spelling-proof form (whole-dress scan): EVERY
+    // padding declaration in ANY dress rule must be EXACTLY the expanded
+    // two-track shorthand — exact, not a prefix: a three-track spelling
+    // (`padding: var(--space-16) var(--space-8) var(--space-12)`) drifts
+    // the block END past a block-start-only check, and a longhand
+    // (`padding-block-start:`) hides from a shorthand-only one; both
+    // green-holed earlier rounds. Physical `bottom` longhands are banned
+    // beside the logical ones. Horizontal-only tracks (padding-inline*)
+    // cannot match the value pin and are rejected the same way; a band
+    // that truly needs different block metrics must move the BASE rule
+    // for BOTH densities. Margins are banned outright — the bands
+    // separate by their paddings alone — and so are the block-FLOW
+    // metrics that move rows just the same (gap/row-gap/height/
+    // min-height/max-height).
+    const dressRules = css
+      .split("}")
+      .filter((rule) => rule.includes("[data-collapsed]") || rule.includes("[data-rail]"));
+    expect(dressRules.length, "the density dress rules exist").toBeGreaterThan(1);
+    for (const rule of dressRules) {
+      for (const decl of rule.matchAll(
+        /\bpadding(?:-(?:top|bottom|block(?:-(?:start|end))?))?\s*:[^;}]*/g,
+      )) {
+        expect(
+          decl[0].trim(),
+          `a dress padding is not the expanded two-track shorthand: ${decl[0]}`,
+        ).toBe("padding: var(--space-16) var(--space-8)");
+      }
+      expect(rule, `a margin crept into the dress: ${rule}`).not.toMatch(
+        /\bmargin(?:-(?:top|bottom|block(?:-(?:start|end))?))?\s*:/,
+      );
+      expect(rule, `block-flow metric in the dress: ${rule}`).not.toMatch(
+        /\b(?:gap|row-gap|height|min-height|max-height)\s*:/,
+      );
+    }
   });
 
   it("reads the tail fallback from the scss source, not a drifted literal", () => {

package/src/components/HkSidebar.tsx

@@ -155,11 +155,12 @@ export default defineComponent({
     // dissolve), which is where the position is read from — an event-only
     // save would miss programmatic scrolls (no `scroll` event fires for
     // them), so the read happens on the ref hand-off itself and the
-    // onScroll below merely keeps the value fresh between flips. Raw
-    // scrollTop is an approximation across dresses (rail rows and full
-    // rows have different heights) — an exact restore would need an
-    // item-keyed anchor, not worth it for a nav list; the browser clamps
-    // any overshoot.
+    // onScroll below merely keeps the value fresh between flips. For
+    // library-owned rows the raw restore is EXACT since the vertical
+    // rhythm became density-invariant (2026-10-31: both dresses render
+    // the same band paddings and row heights, so y offsets match); the
+    // browser clamps any overshoot a host's density-dependent content
+    // could still produce.
     const savedScrollTop = ref(0);
     const onBodyScroll = (e: Event): void => {
       savedScrollTop.value = (e.currentTarget as HTMLElement).scrollTop;

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}