@celestia-island/hikari 0.55.281 → 0.55.283

package/package.json

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

package/src/components/HkSettingsDialog.test.tsx

@@ -3,12 +3,15 @@ import { readFileSync } from "node:fs";
 import { createApp, defineComponent, h, nextTick, ref } from "vue";
 import { Languages, Globe } from "lucide-vue-next";
 import {
+  SHEET_MORPH_MS,
+  sheetMorphMs,
   HkSettingsBody as HSettingsBody,
   HkSettingsDialog as HSettingsDialog,
   HkSettingsGroup as HSettingsGroup,
   HkSettingsHint as HSettingsHint,
   HkSettingsSub as HSettingsSub,
 } from "./HkSettingsDialog";
+import { STEPFLOW_SWAP_EVENT } from "./HkStepFlow";
 
 function mount(component: ReturnType<typeof defineComponent>) {
   const container = document.createElement("div");
@@ -524,3 +527,169 @@ describe("phone shell (rail → top tab strip, 2026-10-28 user direction)", () =
     expect(phoneBlock).toContain("font-size: var(--text-base);");
   });
 });
+
+/**
+ * Docked-sheet height hand-off (2026-11-04 chest phone report).
+ *
+ * Inside a phone sheet the modal sizes the window from this shell's
+ * content, but it observes `.hk-modal-body-inner` — pinned at
+ * `height: 100%` by the host rule — so a section swap never changes the
+ * observed box and the sheet kept the height of whichever section it
+ * OPENED with (the About card clipped inside a ~24px pane). The shell
+ * therefore forwards the pane's settled swap through the family's
+ * `hk-stepflow-swap` protocol, which HkModal already turns into a frame
+ * re-measure.
+ *
+ * The morph container only emits `swap` once its ResizeObserver has seen
+ * the incoming stage and its settle timer has run, so these tests drive
+ * the observer directly (happy-dom ships no layout engine: every rect
+ * would read zero, which the container correctly reads as "same box" and
+ * never settles).
+ */
+class StageResizeObserver implements ResizeObserver {
+  static all: StageResizeObserver[] = [];
+  observed: Element[] = [];
+  private readonly callback: ResizeObserverCallback;
+  constructor(callback: ResizeObserverCallback) {
+    this.callback = callback;
+    StageResizeObserver.all.push(this);
+  }
+  observe(target: Element): void {
+    this.observed.push(target);
+  }
+  unobserve(): void {}
+  disconnect(): void {}
+  /** Fire the callback for the observer watching the transition stage. */
+  static settleStage(height = 220): boolean {
+    const ro = StageResizeObserver.all.find((o) =>
+      o.observed.some((el) => el.classList.contains("hk-tc-stage")),
+    );
+    if (!ro) return false;
+    // Only `contentRect` is consumed by the container; the rest of the
+    // entry descriptor is layout detail happy-dom cannot produce.
+    const entry = { contentRect: { width: 320, height } } as ResizeObserverEntry;
+    ro.callback([entry], ro);
+    return true;
+  }
+}
+
+describe("HSettingsBody — docked-sheet height hand-off", () => {
+  const originalRO = globalThis.ResizeObserver;
+  const originalMatchMedia = window.matchMedia;
+
+  afterEach(() => {
+    globalThis.ResizeObserver = originalRO;
+    window.matchMedia = originalMatchMedia;
+    StageResizeObserver.all = [];
+    document.documentElement.removeAttribute("data-css-animations");
+  });
+
+  function mountWithSwapLog() {
+    StageResizeObserver.all = [];
+    globalThis.ResizeObserver = StageResizeObserver;
+    const events: Array<{ phase?: string; durationMs?: number }> = [];
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    container.addEventListener(STEPFLOW_SWAP_EVENT, (e) => {
+      events.push((e as CustomEvent).detail ?? {});
+    });
+    const app = createApp(Host);
+    app.mount(container);
+    return { container, events, unmount: () => { app.unmount(); container.remove(); } };
+  }
+
+  async function switchToNetwork(container: HTMLElement) {
+    container.querySelectorAll<HTMLButtonElement>(".hk-settings__rail-item")[1].click();
+    await nextTick();
+  }
+
+  it("forwards a settled section swap as a morph beat for the modal", async () => {
+    const { container, events, unmount } = mountWithSwapLog();
+    await switchToNetwork(container);
+    expect(StageResizeObserver.settleStage(220)).toBe(true);
+    // The container arms its settle timer for the choreography remainder
+    // (300ms default) plus a 40ms grace; give it room.
+    await new Promise((r) => setTimeout(r, 500));
+    expect(events).toEqual([{ phase: "morph", durationMs: 300 }]);
+    unmount();
+  });
+
+  it("announces an instant settle as soon as the pane height is final", async () => {
+    // Growing swap: the stage has already reached its incoming height when
+    // the container settles, so the sheet must be told on the first frame —
+    // not after the bounded wait (which exists only for the leaving
+    // generation still holding a shrink at the old height).
+    window.matchMedia = (query: string): MediaQueryList => ({
+      matches: query.includes("prefers-reduced-motion"),
+      media: query,
+      onchange: null,
+      addListener: () => undefined,
+      removeListener: () => undefined,
+      addEventListener: () => undefined,
+      removeEventListener: () => undefined,
+      dispatchEvent: () => false,
+    });
+    const { container, events, unmount } = mountWithSwapLog();
+    const host = container.querySelector(".hk-tc") as HTMLElement;
+    let height = 100;
+    Object.defineProperty(host, "offsetHeight", {
+      configurable: true,
+      get: () => height,
+    });
+    await switchToNetwork(container); // records the pre-swap height (100)
+    height = 150; // the incoming section is taller
+    expect(StageResizeObserver.settleStage(220)).toBe(true);
+    await new Promise((r) => setTimeout(r, 120));
+    expect(events).toEqual([{ phase: "instant" }]);
+    unmount();
+  });
+
+  it("snaps the sheet when the swap settles with no animation", async () => {
+    // Reduced motion zeroes the container's morph duration.
+    window.matchMedia = (query: string): MediaQueryList => ({
+      matches: query.includes("prefers-reduced-motion"),
+      media: query,
+      onchange: null,
+      addListener: () => undefined,
+      removeListener: () => undefined,
+      addEventListener: () => undefined,
+      removeEventListener: () => undefined,
+      dispatchEvent: () => false,
+    });
+    const { container, events, unmount } = mountWithSwapLog();
+    const host = container.querySelector(".hk-tc") as HTMLElement;
+    Object.defineProperty(host, "offsetHeight", {
+      configurable: true,
+      get: () => 150,
+    });
+    await switchToNetwork(container);
+    expect(StageResizeObserver.settleStage(220)).toBe(true);
+    // No layout in happy-dom: the stage never changes, so the instant
+    // branch must WAIT out its bounded settle window (a shrink keeps the
+    // leaving generation in the flow) — nothing may be announced early…
+    await new Promise((r) => setTimeout(r, 150));
+    expect(events).toEqual([]);
+    // …and the bounded window must still fire (a swap that never changes
+    // height must not swallow the announcement).
+    await new Promise((r) => setTimeout(r, 500));
+    expect(events).toEqual([{ phase: "instant" }]);
+    unmount();
+  });
+});
+
+
+describe("sheetMorphMs — the sheet's own morph window", () => {
+  it("caps the container's full choreography at the family morph beat", () => {
+    // A height-changing swap reports enterDelay + morph (600ms); the sheet
+    // must resize inside the family's 300ms window, not twice as long.
+    expect(sheetMorphMs(600)).toBe(SHEET_MORPH_MS);
+    expect(sheetMorphMs(SHEET_MORPH_MS)).toBe(SHEET_MORPH_MS);
+    expect(sheetMorphMs(120)).toBe(120);
+  });
+
+  it("maps a non-positive choreography to the instant snap", () => {
+    expect(sheetMorphMs(0)).toBe(0);
+    expect(sheetMorphMs(-1)).toBe(0);
+    expect(sheetMorphMs(Number.NaN)).toBe(0);
+  });
+});

package/src/components/HkSettingsDialog.tsx

@@ -2,6 +2,7 @@ import {
   defineComponent,
   h,
   nextTick,
+  onBeforeUnmount,
   ref,
   watch,
   type Component,
@@ -9,12 +10,24 @@ import {
 } from "vue";
 
 import HkTransitionContainer from "./HkTransitionContainer";
+import { STEPFLOW_SWAP_EVENT } from "./HkStepFlow";
 import HkScrollContainer from "./HkScrollContainer";
 import HTabs from "./HkTabs";
 import { useBreakpoint } from "../runtime/useBreakpoint";
 import HModal from "./HkModal";
 import "./HkSettingsDialog.scss";
 
+/** The family's sheet-morph window (HkStepFlow announces the same beat):
+ *  the pane container reports its WHOLE choreography (enter delay + morph),
+ *  but the sheet's own resize must not inherit that doubling. */
+export const SHEET_MORPH_MS = 300;
+
+/** Morph duration to hand the modal for a settled swap. */
+export function sheetMorphMs(choreographyMs: number): number {
+  if (!(choreographyMs > 0)) return 0;
+  return Math.min(choreographyMs, SHEET_MORPH_MS);
+}
+
 /** One rail entry of the settings dialog. */
 export interface HkSettingsSection {
   /** Identity of the section — also the name of the slot that renders its
@@ -63,6 +76,22 @@ export interface HkSettingsSection {
  * Desktop keeps the rail exactly as it was; the flip is live on resize
  * and shared by every consumer of this shell (page-embedded bodies
  * included).
+ *
+ * Docked-sheet height hand-off (2026-11-04 chest report): inside a phone
+ * sheet the modal sizes the window from this shell's content, but it
+ * measures the frame through `.hk-modal-body-inner` — which the host
+ * rule pins at `height: 100%` (unscoped, so it pins the phone sheet too),
+ * so the observed box never changes on a section swap and the sheet froze
+ * at whichever section it OPENED with (the 470px About card inside a 24px
+ * pane; the freeze survives hikari #1041's phone fill). Every settled
+ * swap of the pane's morph container is therefore forwarded as the
+ * family's sheet protocol event (`hk-stepflow-swap`, detail
+ * `{phase: "morph", durationMs}`, where the duration is capped to the
+ * family's own sheet morph beat — the container reports its whole
+ * choreography, enter delay included — or `{phase: "instant"}` when the
+ * swap settled with no animation), which HkModal already turns into a
+ * frame re-measure. Page-embedded bodies (no modal ancestor) simply
+ * bubble it nowhere.
  */
 export const HkSettingsBody = defineComponent({
   name: "HkSettingsBody",
@@ -114,16 +143,109 @@ export const HkSettingsBody = defineComponent({
     // typed here — the scroll reset needs the live viewport element and
     // nothing else.
     const paneRef = ref<{ getScrollElement(): HTMLElement | undefined } | null>(null);
+    const shellRef = ref<HTMLElement | null>(null);
+    const morphRef = ref<{ $el?: HTMLElement } | null>(null);
+    let stageBeforeSwap = 0;
+    // One instant-wait loop at a time: a new section change (or unmount)
+    // retires the previous epoch so a stale poll can never announce against
+    // the next swap's half-settled geometry.
+    let instantEpoch = 0;
+    let instantPoll: number | null = null;
+    const scheduleFrame = (cb: () => void): number =>
+      typeof requestAnimationFrame === "function"
+        ? requestAnimationFrame(cb)
+        : window.setTimeout(cb, 16);
+    const cancelFrame = (id: number): void => {
+      if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(id);
+      else clearTimeout(id);
+    };
+    const cancelInstantPoll = (): void => {
+      if (instantPoll !== null) {
+        cancelFrame(instantPoll);
+        instantPoll = null;
+      }
+    };
+    onBeforeUnmount(() => {
+      instantEpoch += 1;
+      cancelInstantPoll();
+    });
     // Section switches restart the pane from the top. Written through the
     // public ref slice (the viewport element) rather than scrollTo so the
     // reset stays synchronous and testable in no-layout environments.
     watch(active, () => {
+      // The instant settle below needs the height the pane had BEFORE the
+      // swap; watchers run before the component patches, so this is still
+      // the outgoing stage.
+      instantEpoch += 1;
+      cancelInstantPoll();
+      stageBeforeSwap = morphRef.value?.$el?.offsetHeight ?? 0;
       void nextTick(() => {
         const viewport = paneRef.value?.getScrollElement();
         if (viewport) viewport.scrollTop = 0;
       });
     });
 
+    // ── docked-sheet height hand-off ──────────────────────────────────
+    // A phone sheet is sized from this shell's content, but HkModal
+    // observes `.hk-modal-body-inner`, which the host rule pins at
+    // `height: 100%` (see the SCSS): the box never changes on a section
+    // swap, so the sheet would keep the section it OPENED with — about
+    // 24px of pane for a 470px 「About」 card (2026-11-04 chest report;
+    // the same freeze survives hikari #1041). The pane's own morph
+    // container already knows when a swap settles; forward that beat
+    // through the family's sheet protocol (`hk-stepflow-swap`, the one
+    // HkModal listens for) so the modal re-measures the frame.
+    //
+    // `durationMs` 0 = the swap settled instantly (reduced motion / the
+    // global animation switch) — the protocol's `instant` phase snaps the
+    // sheet instead of animating. That snap must not be announced from the
+    // settle beat itself: with no choreography the settle lands while the
+    // pane's crossfade still holds the LEAVING generation in the flow, so
+    // the modal would measure the outgoing (taller) height and a shrink
+    // would no-op — the sheet stayed 621px over a 251px section in the
+    // round-1 probe. Wait (bounded) for the stage to actually change, then
+    // hand the beat over; a growing swap has already changed by then and
+    // dispatches on the first frame.
+    function dispatchSheetSwap(durationMs: number): void {
+      const el = shellRef.value;
+      if (!el) return;
+      el.dispatchEvent(
+        new CustomEvent(STEPFLOW_SWAP_EVENT, {
+          bubbles: true,
+          detail:
+            durationMs > 0
+              ? { phase: "morph", durationMs }
+              : { phase: "instant" },
+        }),
+      );
+    }
+
+    function announceSheetSwap(payload: { durationMs: number }): void {
+      if (!shellRef.value) return;
+      if (payload.durationMs > 0) {
+        dispatchSheetSwap(sheetMorphMs(payload.durationMs));
+        return;
+      }
+      cancelInstantPoll();
+      const epoch = instantEpoch;
+      const stage = (): number => morphRef.value?.$el?.offsetHeight ?? 0;
+      const before = stageBeforeSwap;
+      const deadline = Date.now() + 400;
+      const tick = (): void => {
+        if (epoch !== instantEpoch) {
+          instantPoll = null;
+          return;
+        }
+        if (stage() !== before || Date.now() >= deadline) {
+          instantPoll = null;
+          dispatchSheetSwap(0);
+          return;
+        }
+        instantPoll = scheduleFrame(tick);
+      };
+      instantPoll = scheduleFrame(tick);
+    }
+
     function pick(key: string) {
       // Belt-and-braces: every caller already refuses disabled entries
       // upstream (rail: natively disabled buttons; strip: HTabs' disabled
@@ -144,7 +266,7 @@ export const HkSettingsBody = defineComponent({
     const { isMobile } = useBreakpoint();
 
     return () => (
-      <div class="hk-settings" data-phone={isMobile.value || undefined}>
+      <div class="hk-settings" data-phone={isMobile.value || undefined} ref={shellRef}>
         {/* Scroll ownership (see the docblock): both scrollers are
             HkScrollContainers — the overlay chrome replaces the native
             bars, and the paired-class rules in the SCSS carry each
@@ -219,7 +341,12 @@ export const HkSettingsBody = defineComponent({
               incoming section's height and the contents dissolve, the
               same mechanism HkTabs panels use. A settings pane is a page
               slot — it must not hard-cut. */}
-          <HkTransitionContainer swapKey={active()} axis="height">
+          <HkTransitionContainer
+            ref={morphRef}
+            swapKey={active()}
+            axis="height"
+            onSwap={(payload: { durationMs: number }) => announceSheetSwap(payload)}
+          >
             {slots[active()]?.()}
           </HkTransitionContainer>
         </HkScrollContainer>

package/src/components/HkSolarLocationSetting.scss

@@ -1,10 +1,16 @@
-/* HkSolarLocationSetting — the solar-clock location strategy row and
+/* HkSolarLocationSetting — the solar-clock location strategy card and
  * its editor modal body (see the component docblock for the strategy
  * ladder). AI-generated: developed with the ZCode agent (model
  * GLM-5.3); human-directed. */
 
-/* ── The settings-page row: live summary + Edit button ────────────────── */
+/* ── The settings-page card (HkCard root; header/body classes are the
+ *    card family's own) ─────────────────────────────────────────────── */
 .hk-solar-setting {
+  min-width: 0;
+}
+
+/* ── The card body's live summary + Edit button line ──────────────────── */
+.hk-solar-row {
   display: flex;
   align-items: center;
   gap: var(--space-8, 0.5rem);
@@ -59,6 +65,61 @@
   line-height: 1.5;
 }
 
+/* ── Detected-value readout (timezone / ip panes) ───────────────────────
+ * One info item per line: a fixed label column and a value column of
+ * copyable tags, so long values keep their own row and the two columns
+ * stay aligned across rows. */
+.hk-solar-detected {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-8, 0.5rem);
+}
+
+.hk-solar-detected-row {
+  display: grid;
+  grid-template-columns: max-content minmax(0, 1fr);
+  gap: var(--space-8, 0.5rem);
+  align-items: start;
+}
+
+.hk-solar-detected-label {
+  padding-top: var(--space-1, 0.125rem);
+  font-size: var(--text-xs);
+  color: rgb(var(--color-muted));
+  /* Long localized labels wrap instead of pushing the value column out. */
+  overflow-wrap: anywhere;
+}
+
+.hk-solar-detected-value {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-6, 0.375rem);
+  min-width: 0;
+}
+
+/* Values are labels, not prose — but a readout value that outruns the
+ * modal soft-wraps inside its chip instead of clipping or overflowing. */
+.hk-solar-detected-value .hk-badge {
+  white-space: normal;
+  overflow-wrap: anywhere;
+  text-align: left;
+}
+
+/* Probe status line (IP pane): muted progress / failure note, with the
+ * retry affordance inline after the text. */
+.hk-solar-detected-status {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: var(--space-6, 0.375rem);
+  color: rgb(var(--color-muted));
+  font-size: var(--text-xs);
+}
+
+.hk-solar-detected-retry {
+  flex-shrink: 0;
+}
+
 .hk-solar-manual {
   display: flex;
   flex-direction: column;