@celestia-island/hikari 0.54.1 → 0.54.3

package/package.json

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

package/src/DemoApp.tsx

@@ -4,6 +4,7 @@
 import { computed, defineComponent, ref } from "vue";
 import { ChevronDown, ChevronUp, PackageOpen } from "lucide-vue-next";
 import { HIKARI_FONT_MONO } from "./theme/fontContext";
+import { utf8ToBase64 } from "./utils/base64";
 import {
   HButton, HIconButton, HIconButtonGroup, HTooltip, HBadge, HTag, HIcon, HSpinner,
   HProgressBar, HProgressRing, HGaugeRing,
@@ -164,7 +165,7 @@ export default defineComponent({
     const demoAudioSrc = makeSilentWav();
     const demoImageSrc =
       "data:image/svg+xml;base64," +
-      btoa(`<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="900">
+      utf8ToBase64(`<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="900">
     <rect width="1600" height="900" fill="#1b2333"/>
     <g stroke="#2c3a55" stroke-width="1">
       ${Array.from({ length: 15 }, (_, i) => `<line x1="${i * 110}" y1="0" x2="${i * 110}" y2="900"/>`).join("")}

package/src/animation/registerAnimations.ts

@@ -103,6 +103,9 @@ registerCssAnimation("s-voice-wave-bounce", { infinite: true });
 // components/HkPlaceholderMarquee.scss — overflowing placeholder sweep
 // (loops forever; pure CSS, loop geometry on inline custom properties).
 registerCssAnimation("hk-placeholder-marquee-scroll", { infinite: true });
+// styles/admin-tokens.scss — admin header emergency-stop chip while
+// engaged (loops forever).
+registerCssAnimation("s-admin-header-emergency-pulse", { infinite: true });
 // The styles/theme/mixins.scss ambient/glow/entrance keyframes were
 // retired with the legacy Gen-1 sheet vendoring (hikari #476) — their
 // registrar entries went with them.

package/src/components/HkAdminHeader.tsx

@@ -166,7 +166,7 @@ export const HkAdminHeader = defineComponent({
       <header
         class={[
           "s-glass-header",
-          props.compact ? "px-4 gap-2" : "px-6 gap-3",
+          props.compact ? "s-glass-header--compact" : "",
         ]}
       >
         {props.showHamburger && (
@@ -175,13 +175,13 @@ export const HkAdminHeader = defineComponent({
             size="sm"
             onClick={() => emit("hamburger")}
           >
-            <Menu size={20} class="w-5 h-5" />
+            <Menu size={20} class="s-admin-header-hamburger-icon" />
           </HButton>
         )}
 
-        <div ref={userTriggerRef} class="flex items-center gap-2 min-w-0">
+        <div ref={userTriggerRef} class="s-admin-header-user">
           <button
-            class="w-7 h-7 rounded-full overflow-hidden shrink-0 cursor-pointer transition-opacity relative group p-0 border-0"
+            class="s-admin-header-avatar"
             aria-label={props.avatarTriggerLabel ?? t("hikari::adminHeader.avatarTrigger", "Account menu")}
             aria-haspopup={props.avatarAction === "drawer" ? "dialog" : "menu"}
             aria-expanded={props.avatarAction === "menu" ? userMenuOpen.value : undefined}
@@ -191,7 +191,7 @@ export const HkAdminHeader = defineComponent({
               <img
                 src={props.avatarUrl}
                 alt={props.username}
-                class="w-full h-full object-cover"
+                class="s-admin-header-avatar-img"
                 onError={() => { avatarFailed.value = true; }}
               />
             ) : (
@@ -205,24 +205,19 @@ export const HkAdminHeader = defineComponent({
               </span>
             )}
             {props.avatarAction === "menu" && (
-              <div class="absolute inset-0 rounded-full bg-black/30 opacity-0 group-hover:opacity-100 transition-opacity flex items-center justify-center">
-                <Camera size={10} class="text-white" />
+              <div class="s-admin-header-avatar-veil">
+                <Camera size={10} class="s-admin-header-veil-icon" />
               </div>
             )}
           </button>
           {/* WHERE am I — the open view's title, not the nickname. The
-              explicit 1.5 line-height keeps descenders (g, y, p) inside
-              the truncate clip box: the default text-sm box is exactly
-              the em advance, so zoom/subpixel rounding in a scaled root
-              shaves the ink off at the bottom (user report 2026-09-12:
-              the "g" tail of the nickname was visibly cut). */}
+              1.5 line-height (in the class) keeps descenders (g, y, p)
+              inside the truncate clip box: the default text-sm box is
+              exactly the em advance, so zoom/subpixel rounding in a
+              scaled root shaves the ink off at the bottom (user report
+              2026-09-12: the "g" tail of the nickname was visibly cut). */}
           {props.avatarAction === "menu" && props.title && (
-            <span
-              class="text-sm font-semibold text-text truncate max-w-[8rem]"
-              style={{ lineHeight: "1.5" }}
-            >
-              {props.title}
-            </span>
+            <span class="s-admin-header-title">{props.title}</span>
           )}
         </div>
 
@@ -289,15 +284,15 @@ export const HkAdminHeader = defineComponent({
           }}
         </HkMenu>
 
-        <div class="ml-auto flex items-center gap-1.5 shrink-0">
+        <div class="s-admin-header-actions">
           {props.showEmergencyStop && (
             <button
               class={[
-                "px-3 py-1 rounded-md text-xs font-bold border transition-all",
-                props.emergencyStopLoading ? "opacity-50 cursor-wait" : "cursor-pointer",
-                props.emergencyStopActive
-                  ? "bg-red-600 text-white border-red-700 animate-pulse"
-                  : "bg-red-600/10 text-red-500 border-red-500/40 hover:bg-red-600/25",
+                "s-admin-header-emergency",
+                props.emergencyStopLoading
+                  ? "is-loading"
+                  : "",
+                props.emergencyStopActive ? "is-active" : "",
               ]}
               disabled={props.emergencyStopLoading}
               title={props.emergencyStopActive
@@ -312,7 +307,7 @@ export const HkAdminHeader = defineComponent({
           )}
           {slots["emergency-stop-extra"]?.()}
           {(props.actions || []).map((vnode, i) => (
-            <span key={i} class="flex items-center gap-1">
+            <span key={i} class="s-admin-header-action">
               {vnode}
             </span>
           ))}

package/src/components/HkAdminShell.tsx

@@ -45,7 +45,7 @@ export const HkAdminShell = defineComponent({
     };
 
     return () => (
-      <div class="flex flex-col h-full w-full overflow-hidden">
+      <div class="s-admin-shell">
         {slots.header && (
           <div style={{ flexShrink: 0 }}>
             {slots.header({
@@ -61,7 +61,7 @@ export const HkAdminShell = defineComponent({
           </div>
         )}
 
-        <div class="flex flex-1 min-h-0" style={{ paddingBottom: props.footerHeight }}>
+        <div class="s-admin-shell-body" style={{ paddingBottom: props.footerHeight }}>
           {isDesktop.value && !props.sidebarCollapsed && slots.sidebar && (
             <aside
               style={{
@@ -75,8 +75,8 @@ export const HkAdminShell = defineComponent({
               {slots.sidebar({ collapsed: false, onNavigate: closeSidebar })}
             </aside>
           )}
-          <main class="flex-1 flex flex-col min-w-0 min-h-0">
-            <HScrollContainer class="flex-1 min-h-0">
+          <main class="s-admin-shell-main">
+            <HScrollContainer class="s-admin-shell-scroll">
               {/* Padding lives INSIDE the scroll viewport (an inner
                   wrapper) so card box-shadows are not clipped at the
                   viewport edges. */}

package/src/components/HkColorPicker.scss

@@ -71,7 +71,13 @@
   margin-bottom: var(--space-4);
   color: rgb(var(--color-text) / var(--hk-field-label-alpha, 72%));
   white-space: nowrap;
-  line-height: 1;
+  /* The row layout below clips this label with `overflow: hidden` for its
+   * ellipsis, and that clip box IS the line box: at `line-height: 1` the 12px
+   * box was shorter than the font's ink box (14.05px Roboto, 17.38px once a
+   * CJK fallback renders the glyphs), so every g/j/p/q/y in a colour name lost
+   * its tail. 1.5 = 18px, exactly the swatch height in the row layout, so the
+   * dense grids keep their geometry. */
+  line-height: 1.5;
   transition: color var(--duration-short);
 
   .hk-color-picker-swatch-btn:hover & {

package/src/components/HkFileBrowserDialog.tsx

@@ -81,7 +81,7 @@ function formatModified(value: string | number | undefined): string {
   if (value === undefined) return "";
   if (typeof value === "number") {
     const date = new Date(value);
-    return Number.isNaN(date.getTime()) ? String(value) : date.toLocaleString();
+    return Number.isNaN(date.getTime()) ? String(value) : formatDateTime(date);
   }
   return value;
 }

package/src/components/HkGaugeRing.scss

@@ -3,6 +3,44 @@
   display: inline-flex;
 }
 
+/* The centered read-out. The markup used to borrow the HOST's atomic layer
+ * for its whole anatomy (`absolute inset-0 flex flex-col items-center
+ * justify-center pointer-events-none` + `text-lg font-bold text-text
+ * leading-none` / `text-2xs text-muted mt-0.5`): a host without one (the
+ * evernight flasher) rendered the value as a static sibling beside the ring,
+ * and a host WITH one (chest/UnoCSS) owned values the design system could not
+ * fix. Self-contained rules below instead. */
+.hk-gauge-ring-center {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  pointer-events: none;
+}
+
+/* The 1.45 ratio is load-bearing: `leading-none` pinned line-height: 1, which
+ * put the descender of any g/j/p/q/y ~0.95px below the 18px line box — it
+ * overlapped the label underneath and was cut outright inside a truncating
+ * wrapper. 1.45 covers the CJK fallback metrics (ascent+descent up to 1.45em),
+ * so the ring owns the ratio instead of borrowing a host utility. */
+.hk-gauge-ring-value {
+  font-size: var(--text-lg);
+  font-weight: 700;
+  line-height: 1.45;
+  color: rgb(var(--color-text));
+}
+
+.hk-gauge-ring-label {
+  font-size: var(--text-2xs);
+  /* Uno's font-size utilities also emit `line-height: 1`; the label is a
+   * single clipped-free line, so the host rendering is kept here. */
+  line-height: 1;
+  color: rgb(var(--color-muted));
+  margin-top: 0.125rem;
+}
+
 // The 0.8s dash sweep rides an INLINE transition on the progress circles
 // (HkGaugeRing.tsx), so the guard needs !important to beat it.
 @media (prefers-reduced-motion: reduce) {

package/src/components/HkGaugeRing.tsx

@@ -115,12 +115,12 @@ export default defineComponent({
           ))}
         </svg>
         {(props.centerValue || props.centerLabel) && (
-          <div class="absolute inset-0 flex flex-col items-center justify-center pointer-events-none">
+          <div class="hk-gauge-ring-center">
             {props.centerValue && (
-              <div class="text-lg font-bold text-text leading-none">{props.centerValue}</div>
+              <div class="hk-gauge-ring-value">{props.centerValue}</div>
             )}
             {props.centerLabel && (
-              <div class="text-2xs text-muted mt-0.5">{props.centerLabel}</div>
+              <div class="hk-gauge-ring-label">{props.centerLabel}</div>
             )}
           </div>
         )}

package/src/components/HkModal.close-collapse.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Source contract for the DESKTOP modal close choreography (user report
+ * 2026-09-15): the unveil expands the visible box outward from the
+ * center (bottom-10% clip + +5% offset at t=0, full box at t=1), but the
+ * close had degenerated into a fade + downward drift — the box read as
+ * shrinking straight down instead of folding back into its center.
+ *
+ * The close now runs the unveil's TRUE reverse, which is only safe
+ * because the leave pins an identity clip: interpolating
+ * `none → inset()` is DISCRETE (the #508 regression — the footer band
+ * vanished at the first frame), while identical `inset → inset` shape
+ * functions interpolate continuously.
+ *
+ * Pinned on the stylesheet SOURCE (computed animation geometry is not
+ * observable in happy-dom), mirroring the themeToggleChrome /
+ * tokenHygiene guard pattern.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const src = readFileSync(join(here, "HkModal.scss"), "utf-8");
+
+/** The desktop choreography block — the mobile sheet block (≤767px)
+ *  carries its own enter/leave classes and must not leak in. */
+const desktop = src.slice(
+  src.indexOf("@media (min-width: 768px)"),
+  src.indexOf("@media (max-width: 767px)"),
+);
+
+/** Body of one flat rule (no nested braces in this block). */
+function bodyOf(selector: string): string {
+  const escaped = selector.replace(/\./g, "\\.");
+  const match = desktop.match(new RegExp(`${escaped}\\s*{([^}]*)}`));
+  expect(match, `rule ${selector} must exist in the desktop block`).toBeTruthy();
+  return match![1].replace(/\s+/g, " ").trim();
+}
+
+function clipOf(selector: string): string {
+  const body = bodyOf(selector);
+  const match = body.match(/clip-path:\s*([^;]+);?/);
+  expect(match, `${selector} must declare a clip-path`).toBeTruthy();
+  return match![1].replace(/\s+/g, " ").trim();
+}
+
+describe("HkModal desktop close-collapse contract (user report 2026-09-15)", () => {
+  it("pins the identity clip in leave-from, identical to enter-to (no discrete clip jump)", () => {
+    // The #508 regression guard: leave-from WITHOUT a clip makes
+    // none → inset() interpolate discretely and the footer band vanish
+    // at the first frame of the close.
+    expect(clipOf(".hk-modal-content-leave-from")).toBe(
+      clipOf(".hk-modal-content-enter-to"),
+    );
+  });
+
+  it("mirrors the unveil geometry: leave-to clips like enter-from", () => {
+    // Bottom-10% clip + same rounding on both ends of the mirror — the
+    // visible box collapses symmetrically back to 90% centered.
+    expect(clipOf(".hk-modal-content-leave-to")).toBe(
+      clipOf(".hk-modal-content-enter-from"),
+    );
+  });
+
+  it("transitions clip-path on leave (the collapse animates, not snaps)", () => {
+    const body = bodyOf(".hk-modal-content-leave-active");
+    expect(body).toMatch(/clip-path\s+var\(--hk-modal-duration/);
+    expect(body).toMatch(/will-change:\s*[^;]*clip-path/);
+  });
+
+  it("keeps the close a rigid ride: no scaleY squash anywhere in the desktop block", () => {
+    // History: #512 collapsed via scaleY (content squashed), #524
+    // reverted to a bare drift. The clip choreography moves whole
+    // pixels of the visible window — the frame itself never distorts.
+    expect(desktop).not.toContain("scaleY");
+    expect(desktop).not.toContain("transform-origin");
+  });
+});

package/src/components/HkModal.scss

@@ -123,18 +123,26 @@
     will-change: transform, opacity, clip-path;
   }
 
-  // Close: the whole frame fades and drifts down as ONE piece — the
-  // unveil's clip does NOT re-run on close. Re-clipping first made the
-  // bottom band (usually the footer) vanish at the very first frame of
-  // the close while the rest was still on screen, which read as broken
-  // (user report 2026-09-14).
+  // Close: the unveil's TRUE reverse — the visible box collapses back
+  // toward the center (top edge sweeps down, bottom edge sweeps up,
+  // content rides rigidly — never squashed) while the frame fades
+  // (user report 2026-09-15: the fade+drift close read as the box
+  // shrinking straight down instead of folding back into its center).
+  // The earlier re-clip attempt (#508) broke because leave-from had no
+  // clip at all: interpolating `none → inset()` is DISCRETE, so the
+  // bottom band (the footer) vanished at the first frame. Pinning the
+  // identity clip in leave-from — byte-identical to enter-to — makes
+  // the same-shape insets interpolate continuously, which structurally
+  // rules that jump out while restoring the symmetric collapse.
   .hk-modal-content-leave-active {
     transition:
       opacity var(--hk-modal-duration, 0.32s)
         var(--hk-modal-ease-in, cubic-bezier(0.45, 0, 0.55, 1)),
       transform var(--hk-modal-duration, 0.32s)
+        var(--hk-modal-ease-in, cubic-bezier(0.45, 0, 0.55, 1)),
+      clip-path var(--hk-modal-duration, 0.32s)
         var(--hk-modal-ease-in, cubic-bezier(0.45, 0, 0.55, 1));
-    will-change: transform, opacity;
+    will-change: transform, opacity, clip-path;
   }
 
   .hk-modal-content-enter-from {
@@ -154,11 +162,20 @@
   .hk-modal-content-leave-from {
     opacity: 1;
     transform: translate(-50%, -50%);
+    // The pinned identity clip: identical to enter-to so the leave's
+    // clip interpolates (never jumps) — see the close note above.
+    clip-path: inset(0 0 0 0 round 0 0 var(--hk-modal-radius, var(--radius-lg, 12px))
+                              var(--hk-modal-radius, var(--radius-lg, 12px)));
   }
 
   .hk-modal-content-leave-to {
     opacity: 0;
+    // Mirror of enter-from: shifted +5% with the bottom 10% clipped, the
+    // visible box is 90% and centered — both edges ease toward the
+    // center line, exactly reversing the unveil.
     transform: translate(-50%, -50%) translateY(5%);
+    clip-path: inset(0 0 10% 0 round 0 0 var(--hk-modal-radius, var(--radius-lg, 12px))
+                                 var(--hk-modal-radius, var(--radius-lg, 12px)));
   }
 }
 

package/src/components/HkNavSidebar.tsx

@@ -75,7 +75,7 @@ export const HkNavSidebar = defineComponent({
                       icon: () => (IconComp ? h(IconComp, { size: 16 }) : null),
                       default: () => (
                         <span class="s-nav-item-content">
-                          <span class="truncate">{item.label}</span>
+                          <span class="s-nav-item-label">{item.label}</span>
                           {item.badge && (
                             <span
                               class="s-nav-item-badge"

package/src/components/HkSignInCard.tsx

@@ -118,15 +118,13 @@ export const HkSignInCard = defineComponent({
                     ) : (
                       <svg
                         xmlns="http://www.w3.org/2000/svg"
-                        width="16"
-                        height="16"
                         viewBox="0 0 24 24"
                         fill="none"
                         stroke="currentColor"
                         stroke-width="2"
                         stroke-linecap="round"
                         stroke-linejoin="round"
-                        class="w-4 h-4"
+                        class="s-auth-card-field-icon"
                         aria-hidden="true"
                       >
                         <path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2"></path>

package/src/components/HkStatCard.scss

@@ -61,7 +61,12 @@
 .hk-stat-card-value {
   font-size: var(--text-2xl, 1.5rem);
   font-weight: 700;
-  line-height: 1.2;
+  /* `overflow: hidden` below hangs the ellipsis on the line box, so the line
+   * box has to cover the ink box: 1.2 (28.8px at the 24px token) cleared the
+   * shipped Latin stacks by only 0.6-1.1px and clipped 2.9-3.1px per edge as
+   * soon as a host swapped --font-sans for a CJK fallback (ascent+descent
+   * 1.34-1.45em, see theme/fontContext). 1.35 covers those metrics. */
+  line-height: 1.35;
   color: rgb(var(--color-text));
   overflow: hidden;
   text-overflow: ellipsis;

package/src/components/HkTable.scss

@@ -200,8 +200,8 @@
   color: rgb(var(--color-on-solid-icon, 255 255 255));
 }
 
-/* SR-only utility */
-.sr-only {
+/* Visually hidden caption (kept in the a11y tree) */
+.hk-table-sr-only {
   position: absolute;
   width: 1px;
   height: 1px;

package/src/components/HkTable.tsx

@@ -131,7 +131,7 @@ export default defineComponent({
       <div ref={wrapperHostRef} class="hk-table-host">
         <div ref={wrapperRef} class="hk-table-wrapper">
         <table class={tableCls.value}>
-          {props.caption && <caption class="sr-only">{props.caption}</caption>}
+          {props.caption && <caption class="hk-table-sr-only">{props.caption}</caption>}
           <thead>
             <tr class="hk-table-header-row">
               {props.selectable && (

package/src/components/componentSelfSufficiency.test.ts

@@ -0,0 +1,152 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+/**
+ * Component self-sufficiency guard.
+ *
+ * A hikari component must carry its own styling. Class literals in a
+ * component's TSX are allowed to name hikari's own namespaces (`hk-`, the
+ * plana-ui shared surface `s-`, state modifiers `is-`, `hii-`, `hljs`) —
+ * those are defined in this package and ship with it. Anything else in a
+ * class literal is a HOST-DIALECT utility (`flex`, `inset-0`, `w-7 h-7`,
+ * `text-2xs`, `animate-pulse`, …): it resolves only if the consuming app
+ * happens to run an atomic-CSS layer, and silently does nothing otherwise.
+ *
+ * That silent degradation is exactly what shipped: four components
+ * (HkAdminHeader, HkAdminShell, HkGaugeRing, HkNavSidebar) spoke the
+ * utility dialect, so the evernight flasher rendered its gauge ring with
+ * the value unstyled beside the circle and its header with no gap or
+ * padding at all — while hosts with UnoCSS (chest) owned values the
+ * design system could not fix. Those four were rewritten to component
+ * scss (2026-09-15) and the utility sheet they had been propped up with
+ * was deleted; this test is the fence that keeps the dialect out.
+ *
+ * Adding a component that needs a utility class means either giving it a
+ * semantic class with rules in its own scss (the house style) or adding
+ * it here — and the second should feel like the wrong answer.
+ */
+
+const componentsDir = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "components",
+);
+
+/** Namespaces that are hikari's own (semantic classes, not host dialect). */
+const OWN_NAMESPACE = /^(?:hk-|s-|is-|hii-|hljs)/;
+
+/** `"desc"` inside `sortDirection === "desc"` is a comparison operand, not
+ *  a class name — the only false-positive source a class-literal scan has. */
+const COMPARISON_BEFORE = /(?:===|!==|==|!=)\s*$/;
+
+/**
+ * Cut the literal source of every `class=` attribute and say whether it is
+ * bare class text (`class="a b"` — a token list already) or an expression
+ * (`class={…}` — token lists hide inside its string literals).
+ */
+function classAttributeSources(source: string): { text: string; expression: boolean }[] {
+  const out: { text: string; expression: boolean }[] = [];
+  const attr = "class=";
+  for (let i = source.indexOf(attr); i !== -1; i = source.indexOf(attr, i + 1)) {
+    const start = i + attr.length;
+    const first = source[start];
+    if (first === '"' || first === "'") {
+      const end = source.indexOf(first, start + 1);
+      if (end !== -1) out.push({ text: source.slice(start + 1, end), expression: false });
+      continue;
+    }
+    if (first === "{") {
+      let depth = 0;
+      for (let j = start; j < source.length; j += 1) {
+        if (source[j] === "{") depth += 1;
+        else if (source[j] === "}") {
+          depth -= 1;
+          if (depth === 0) {
+            out.push({ text: source.slice(start + 1, j), expression: true });
+            break;
+          }
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/** String literals in an expression, with the text right before each one. */
+function literals(expression: string): { value: string; before: string }[] {
+  const out: { value: string; before: string }[] = [];
+  const pattern = /(["'])((?:\\.|(?!\1)[^\\])*)\1/g;
+  for (let m = pattern.exec(expression); m !== null; m = pattern.exec(expression)) {
+    out.push({ value: m[2], before: expression.slice(0, m.index) });
+  }
+  return out;
+}
+
+/** Host-dialect utility tokens found in the component sources, mapped to
+ *  the files that write them. */
+function utilityUsages(): Map<string, Set<string>> {
+  const usage = new Map<string, Set<string>>();
+  for (const name of readdirSync(componentsDir).sort()) {
+    if (!name.endsWith(".tsx") || name.endsWith(".test.tsx")) continue;
+    const source = readFileSync(join(componentsDir, name), "utf8").replace(/\r\n/g, "\n");
+    for (const attr of classAttributeSources(source)) {
+      const lists = attr.expression
+        ? literals(attr.text)
+            .filter(({ before }) => !COMPARISON_BEFORE.test(before))
+            .map(({ value }) => value)
+        : [attr.text];
+      for (const list of lists) {
+        for (const token of list.split(/\s+/)) {
+          if (!token || token.includes("${") || OWN_NAMESPACE.test(token)) continue;
+          if (!usage.has(token)) usage.set(token, new Set());
+          usage.get(token)!.add(name);
+        }
+      }
+    }
+  }
+  return usage;
+}
+
+describe("component self-sufficiency", () => {
+  it("keeps host-dialect utility classes out of component markup", () => {
+    const used = utilityUsages();
+    const offenders = [...used.keys()].sort();
+    expect(
+      offenders,
+      `components must style themselves (hk-*/s-*/is-* classes + their own scss), ` +
+        `not rely on the host's atomic layer: ${offenders
+          .map((t) => `${t} (${[...used.get(t)!].join(", ")})`)
+          .join("; ")}`,
+    ).toEqual([]);
+  });
+
+  it("still sees the class literals it is supposed to guard", () => {
+    // An extractor that silently stopped matching would make the assertion
+    // above pass on an empty set. Anchor it: the four rewritten components
+    // carry semantic classes, and the scan must find them.
+    const seen = new Map<string, Set<string>>();
+    for (const name of readdirSync(componentsDir).sort()) {
+      if (!name.endsWith(".tsx") || name.endsWith(".test.tsx")) continue;
+      const source = readFileSync(join(componentsDir, name), "utf8");
+      for (const attr of classAttributeSources(source)) {
+        const lists = attr.expression
+          ? literals(attr.text).map(({ value }) => value)
+          : [attr.text];
+        for (const list of lists) {
+          for (const token of list.split(/\s+/)) {
+            if (!token) continue;
+            if (!seen.has(token)) seen.set(token, new Set());
+            seen.get(token)!.add(name);
+          }
+        }
+      }
+    }
+    for (const anchor of ["s-glass-header", "hk-gauge-ring-center", "s-admin-shell"]) {
+      expect(seen.has(anchor), `scan lost ${anchor}`).toBe(true);
+    }
+    expect(seen.size).toBeGreaterThan(50);
+  });
+});

package/src/components/textClip.contract.test.ts

@@ -0,0 +1,186 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compile } from "sass";
+import { describe, expect, it } from "vitest";
+
+/**
+ * Descender-clipping contract for every hikari stylesheet.
+ *
+ * `text-overflow: ellipsis` is not a vertical safeguard: the same
+ * `overflow: hidden` that truncates the line horizontally clips glyph ink to
+ * the padding box, and that box is the LINE BOX. When the line box is shorter
+ * than the font's ink box the bottom of every g/j/p/q/y is cut off flat —
+ * reported twice by users (the chest header workspace pill, and the 'g' tail
+ * of an admin-header nickname). `line-height: 1` is the classic way to build
+ * that trap, because it is reached for as a centring fix inside a fixed-height
+ * chip.
+ *
+ * The floor below is `line-height / font-size`. Descender depth is ~0.21em and
+ * the tallest ink (accents, Han) needs another ~1.0-1.1em, so Latin stacks need
+ * >= 1.10-1.15; the ceiling is set by the CJK fallbacks hikari supports
+ * (`theme/fontContext` lets a host swap --font-sans, and YaHei / Noto Sans CJK
+ * carry ascent+descent of 1.34-1.45em). 1.30 is the value that keeps a host
+ * font swap from turning a clip box into a paper cut, and it still leaves room
+ * for the deliberately tight designs (`--hk-menu-item-lh: 1.3`).
+ *
+ * A rule is only flagged when the clip and the too-small line box sit in the
+ * SAME declaration block: that is the combination that actually cuts ink. An
+ * inherited line-height from an ancestor is invisible here, which is why the
+ * fix for a flagged rule is to declare a safe ratio on the clipping rule
+ * itself rather than somewhere up the tree.
+ */
+
+const componentDir = resolve(dirname(fileURLToPath(import.meta.url)));
+const stylesDir = resolve(componentDir, "../styles");
+
+/** line-height / font-size below this clips descenders on some supported font. */
+const SAFE_LINE_HEIGHT_RATIO = 1.3;
+
+/**
+ * Reviewed exemptions. Every entry must say why the ink cannot be text or why
+ * the clip is intended — an unexplained entry is a bug, not a pass.
+ */
+const ALLOWED: ReadonlyArray<{ file: string; selector: string; why: string }> = [];
+
+type Block = { file: string; selector: string; body: string; order: number };
+
+/** Walk a compiled stylesheet, flattening at-rules into their inner blocks. */
+function* blocksOf(css: string, file: string, prefix = "", order = { value: 0 }): Generator<Block> {
+  let i = 0;
+  while (i < css.length) {
+    const open = css.indexOf("{", i);
+    if (open === -1) return;
+    const prelude = css.slice(i, open).trim();
+    let depth = 1;
+    let j = open + 1;
+    while (j < css.length && depth > 0) {
+      if (css[j] === "{") depth++;
+      else if (css[j] === "}") depth--;
+      j++;
+    }
+    const body = css.slice(open + 1, j - 1);
+    if (prelude.startsWith("@")) {
+      yield* blocksOf(body, file, prefix, order);
+    } else {
+      yield { file, selector: prefix ? `${prefix} ${prelude}` : prelude, body, order: order.value++ };
+    }
+    i = j;
+  }
+}
+
+function declaration(body: string, property: string): string | null {
+  const match = body.match(new RegExp(`(?:^|;)\\s*${property}\\s*:([^;]+)`, "i"));
+  return match ? match[1]!.trim() : null;
+}
+
+function clipsOverflow(body: string): boolean {
+  return ["overflow", "overflow-x", "overflow-y"].some((property) => {
+    const value = declaration(body, property);
+    return value !== null && /\b(hidden|clip)\b/.test(value);
+  });
+}
+
+function px(value: string | null): number | null {
+  if (value === null) return null;
+  const match = value.match(/^([\d.]+)px$/);
+  return match ? Number(match[1]) : null;
+}
+
+function ratioOf(body: string): number | null {
+  const lineHeight = declaration(body, "line-height");
+  if (lineHeight === null) return null;
+  const unitless = lineHeight.match(/^[\d.]+$/);
+  if (unitless) return Number(lineHeight);
+  const lineHeightPx = px(lineHeight);
+  const fontSizePx = px(declaration(body, "font-size"));
+  if (lineHeightPx !== null && fontSizePx !== null && fontSizePx > 0) {
+    return lineHeightPx / fontSizePx;
+  }
+  return null;
+}
+
+function sheets(): string[] {
+  const components = readdirSync(componentDir)
+    .filter((name) => name.endsWith(".scss"))
+    .map((name) => resolve(componentDir, name));
+  const styles = readdirSync(stylesDir)
+    .filter((name) => name.endsWith(".scss"))
+    .map((name) => resolve(stylesDir, name));
+  return [...components, ...styles];
+}
+
+/** The element a rule actually styles: the last compound of its selector. */
+function subject(selector: string): string {
+  const parts = selector.split(/\s+|>/).filter(Boolean);
+  return parts[parts.length - 1] ?? selector;
+}
+
+/** Rough CSS specificity, enough to pick the rule that wins inside one sheet. */
+function specificity(selector: string): number {
+  return (selector.match(/[.#[\]]/g)?.length ?? 0) * 10 + (selector.match(/[a-z]+[a-z0-9-]*/gi)?.length ?? 0);
+}
+
+/**
+ * Effective `line-height / font-size` for a clipping rule, resolving the
+ * cascade *within the sheet*: the clip and the line box very often live in two
+ * different blocks for the same element (the row-layout override adds
+ * `overflow: hidden`, the base rule declares `line-height: 1`), which is why a
+ * per-block scan sees nothing. Rules that declare no line-height are skipped —
+ * the inherited value is `normal`, which cannot clip.
+ */
+function effectiveRatio(clip: Block, blocks: Block[]): number | null {
+  const element = subject(clip.selector);
+  const candidates = blocks
+    .filter((block) => block.selector === clip.selector || subject(block.selector) === element)
+    .map((block) => ({ block, ratio: ratioOf(block.body) }))
+    .filter((entry): entry is { block: Block; ratio: number } => entry.ratio !== null);
+  if (!candidates.length) return null;
+  candidates.sort(
+    (a, b) => specificity(b.block.selector) - specificity(a.block.selector) || b.block.order - a.block.order,
+  );
+  return candidates[0]!.ratio;
+}
+
+describe("stylesheet descender-clipping contract", () => {
+  // Compiling ~130 stylesheets takes ~1s on a warm cache and several seconds on
+  // a cold one; the default 5s budget turns a slow machine into a red suite.
+  it("never pairs a clip box with a line box shorter than the ink box", { timeout: 60_000 }, () => {
+    const findings: string[] = [];
+    const allowed = new Set(ALLOWED.map((entry) => `${entry.file}|${entry.selector}`));
+
+    for (const file of sheets()) {
+      const name = file.slice(file.indexOf("/src/") + 1);
+      // sass keeps `/* … */` comments in expanded output, and a comment that
+      // *talks* about `overflow: hidden` or `line-height: 1` would otherwise be
+      // parsed as a declaration (that bug made this guard pass while the very
+      // clip it was written for was live).
+      const css = compile(file, { style: "expanded", loadPaths: [componentDir, stylesDir] }).css.replace(
+        /\/\*[\s\S]*?\*\//g,
+        "",
+      );
+      const blocks = [...blocksOf(css, name)];
+      for (const block of blocks) {
+        if (!clipsOverflow(block.body)) continue;
+        const ratio = effectiveRatio(block, blocks);
+        if (ratio === null || ratio >= SAFE_LINE_HEIGHT_RATIO) continue;
+        if (allowed.has(`${block.file}|${block.selector}`)) continue;
+        findings.push(
+          `${block.file} — ${block.selector} — clips overflow with an effective line-height ratio of ${ratio.toFixed(2)} (< ${SAFE_LINE_HEIGHT_RATIO}): the ink box of g/j/p/q/y is cut`,
+        );
+      }
+    }
+
+    expect(findings.sort(), "clip boxes whose line box is too short for the font's ink").toEqual([]);
+  });
+
+  it("keeps the review list honest", () => {
+    const unmatched = ALLOWED.filter((entry) => {
+      const file = resolve(componentDir, "..", entry.file.replace(/^src\//, ""));
+      return !readFileSync(file, "utf8").includes(entry.selector.split(" ").pop()!);
+    }).map((entry) => `${entry.file} — ${entry.selector} (${entry.why})`);
+    // A stale exemption hides a future regression: it must be deleted.
+    expect(unmatched).toEqual([]);
+  });
+});

package/src/index.ts

@@ -339,7 +339,7 @@ export type { MessagePayload, MessageSeverity, MessageTransport, NotifyOptions,
 export { useResourceListModal } from "./composables/useResourceListModal";
 
 export { downloadBlob, downloadTextAsFile } from "./utils/download";
-export { bytesToBase64, base64ToBytes, blobToBase64 } from "./utils/base64";
+export { bytesToBase64, utf8ToBase64, base64ToBytes, blobToBase64 } from "./utils/base64";
 
 export { THEME_MODE_STORAGE_KEY } from "./theme/useTheme";
 

package/src/styles/admin-tokens.scss

@@ -316,14 +316,205 @@
   z-index: var(--z-header);
   display: flex;
   align-items: center;
+  /* Horizontal rhythm + gap live in the class (not in host utilities):
+   * the markup used to carry `px-6 gap-3` / `px-4 gap-2` utility classes,
+   * which a host WITHOUT an atomic layer simply did not have — the header
+   * silently fell back to this file's old `padding: 0 var(--space-12)`
+   * and no gap at all. */
+  gap: var(--space-12);
+  padding: 0 var(--space-24);
   height: var(--s-header-height);
-  padding: 0 var(--space-12);
   background: rgb(var(--color-surface) / var(--opacity-half));
   backdrop-filter: blur(var(--blur-md));
   border-bottom: 1px solid var(--border-faint, rgb(var(--color-border) / 10%));
   flex-shrink: 0;
 }
 
+.s-glass-header--compact {
+  gap: var(--space-8);
+  padding: 0 var(--space-16);
+}
+
+/* ── Admin header chrome (HkAdminHeader) ────────────────────────────────
+ * The header's own layout. Every declaration below replaces a utility
+ * class the markup used to depend on (`w-7 h-7`, `rounded-full`,
+ * `object-cover`, `max-w-[8rem]`, `animate-pulse`, …) — a host without an
+ * atomic layer rendered the header without them, and a host with one
+ * (chest/UnoCSS) owned values the design system could not fix. Values are
+ * the verified computed ones (audit 2026-09-15 against chest's generated
+ * CSS), so no host's rendering changes. */
+
+.s-admin-header-user {
+  display: flex;
+  align-items: center;
+  gap: var(--space-8);
+  min-width: 0;
+}
+
+.s-admin-header-avatar {
+  position: relative;
+  width: var(--space-28);
+  height: var(--space-28);
+  flex-shrink: 0;
+  border-radius: var(--radius-full);
+  overflow: hidden;
+  cursor: pointer;
+  transition: opacity 150ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+/* The hamburger's leading icon (lucide `Menu`), sized in rem so it tracks
+ * a scaled root the way the utility it replaces did. */
+.s-admin-header-hamburger-icon {
+  width: var(--space-20);
+  height: var(--space-20);
+}
+
+.s-admin-header-avatar-img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+/* Hover veil: the "change avatar" affordance over the trigger. The Uno
+ * form was `group-hover:opacity-100` scoped by a `group` marker class on
+ * the button; this descendant selector expresses the same scope. */
+.s-admin-header-avatar-veil {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--radius-full);
+  background: rgb(0 0 0 / 30%);
+  opacity: 0;
+  transition: opacity 150ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+.s-admin-header-avatar:hover .s-admin-header-avatar-veil {
+  opacity: 1;
+}
+
+.s-admin-header-veil-icon {
+  color: #fff;
+}
+
+/* The open view's title. The 1.5 line-height is load-bearing: the default
+ * text-sm box is exactly the em advance, so descenders (g, y, p) fall
+ * outside the truncate clip box under subpixel rounding (user report
+ * 2026-09-12: the "g" tail of the nickname was visibly cut). */
+.s-admin-header-title {
+  font-size: var(--text-sm);
+  font-weight: 600;
+  color: rgb(var(--color-text));
+  line-height: 1.5;
+  max-width: 8rem;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.s-admin-header-actions {
+  display: flex;
+  align-items: center;
+  gap: var(--space-6);
+  margin-left: auto;
+  flex-shrink: 0;
+}
+
+.s-admin-header-action {
+  display: flex;
+  align-items: center;
+  gap: var(--space-4);
+}
+
+/* Emergency stop chip: quiet destructive by default, solid red + pulse
+ * while engaged (`is-active`), dimmed + wait cursor while the request is
+ * in flight (`is-loading`). */
+.s-admin-header-emergency {
+  padding: var(--space-4) var(--space-12);
+  border-width: 1px;
+  border-radius: 0.375rem;
+  font-size: var(--text-xs);
+  /* Uno's font-size utilities also emit `line-height: 1`; the chip
+   * rendered that way in chest, so the class keeps it. */
+  line-height: 1;
+  font-weight: 700;
+  cursor: pointer;
+  transition: all 150ms cubic-bezier(0.4, 0, 0.2, 1);
+  background: rgb(220 38 38 / 10%);
+  color: #ef4444;
+  border-color: rgb(239 68 68 / 40%);
+}
+
+.s-admin-header-emergency:hover {
+  background: rgb(220 38 38 / 25%);
+}
+
+.s-admin-header-emergency.is-loading {
+  opacity: 0.5;
+  cursor: wait;
+}
+
+.s-admin-header-emergency.is-active {
+  background: #dc2626;
+  color: #fff;
+  border-color: #b91c1c;
+  animation: s-admin-header-emergency-pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+}
+
+@keyframes s-admin-header-emergency-pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.5;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .s-admin-header-emergency.is-active {
+    animation: none;
+  }
+}
+
+/* ── Admin shell layout (HkAdminShell) ──────────────────────────────────
+ * Replaces the `flex flex-col h-full w-full overflow-hidden` /
+ * `flex-1 min-h-0` utility chain the shell used to require. */
+.s-admin-shell {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  width: 100%;
+  overflow: hidden;
+}
+
+.s-admin-shell-body {
+  display: flex;
+  flex: 1 1 0%;
+  min-height: 0;
+}
+
+.s-admin-shell-main {
+  display: flex;
+  flex: 1 1 0%;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+}
+
+.s-admin-shell-scroll {
+  flex: 1 1 0%;
+  min-height: 0;
+}
+
+/* ── Nav sidebar labels (HkNavSidebar) ─ */
+.s-nav-item-label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
 /* ── Popup menu items ─ */
 /* Unified menu-item spec (packages/vue/src/components/_menu-item.scss):
  * one row grammar across menus, selects, theme pills, admin header
@@ -558,6 +749,14 @@
   animation: s-auth-card-in 0.45s var(--ease-out-expo, cubic-bezier(0.19, 1, 0.22, 1)) both;
 }
 
+/* Field leading icon (HkSignInCard's inline user glyph) — sized in rem so
+ * it tracks a scaled root, the way the `w-4 h-4` utility it replaces did
+ * only in hosts that had an atomic layer. */
+.s-auth-card-field-icon {
+  width: var(--space-16);
+  height: var(--space-16);
+}
+
 @keyframes s-auth-card-in {
   from { opacity: 0; transform: translateY(-16px) scale(0.92); }
   to   { opacity: 1; transform: translateY(0) scale(1); }

package/src/styles/index.scss

@@ -9,7 +9,10 @@
 //   2. theme/scale.scss — the L2 scale tokens: spacing, type, radius,
 //      blur, opacity, durations, easings, z bands, fonts (vendored from
 //      src/scale.scss).
-//   3. admin-tokens.scss — the plana-ui shared surface: layout tokens,
+//   3. theme/scrollbar.scss — the shared overlay-scrollbar chrome
+//      (.hk-scrollbar-track/thumb) that attachOverlayScrollbars() attaches
+//      to every scroll region (vendored from packages/theme/styles).
+//   4. admin-tokens.scss — the plana-ui shared surface: layout tokens,
 //      brand-color aliases and the shared admin component classes.
 //
 // initTheme() (runtime) writes only deltas against this base into a
@@ -24,4 +27,5 @@
 @use "./reset.scss";
 @use "./theme/channels.scss";
 @use "./theme/scale.scss";
+@use "./theme/scrollbar.scss";
 @use "./admin-tokens.scss";

package/src/styles/theme/scrollbar.scss

@@ -0,0 +1,80 @@
+// Vendored from packages/theme/styles/_scrollbar.scss so npm registry
+// installs can resolve it — the exports map only exposes ./styles/*, and the
+// overlay scrollbar the composable attaches (attachOverlayScrollbars) renders
+// NOTHING without these rules: every host hid its native bar per the
+// composable's contract and got an unstyled, invisible thumb in exchange
+// (audited 2026-09-15: zero .hk-scrollbar-* rules in any consumer bundle).
+// Edit the upstream file, then re-copy; do not hand-edit here.
+
+// _scrollbar.scss — the shared overlay scrollbar chrome.
+//
+// ONE scrollbar system for the whole library: the `.hk-scrollbar-track` /
+// `.hk-scrollbar-thumb` DOM is created imperatively by
+// packages/vue/src/composables/useOverlayScrollbar.ts
+// (attachOverlayScrollbars) and styled here. HkScrollContainer keeps its
+// container-specific rules in HkScrollContainer.scss; every other scroll
+// region in the library attaches the same overlay and hides its native
+// bar with the standard two-liner:
+//
+//   scrollbar-width: none;
+//   &::-webkit-scrollbar { display: none; }
+
+.hk-scrollbar-track {
+  position: absolute;
+  z-index: 10;
+  background: transparent;
+  /* Click-through while faded: an invisible rail must never steal
+     clicks from the content beneath it (the track hugs the region's
+     edge, exactly where end-of-line links/buttons live). The rail
+     becomes interactive only while it is visible — the flash window
+     after a scroll (and while hovered/dragged within that window). */
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity var(--hi-duration-fast, 0.15s) ease;
+
+  &[data-axis="horizontal"] {
+    left: 4px;
+    right: 4px;
+    bottom: 2px;
+    height: 6px;
+  }
+
+  &:not([data-axis="horizontal"]) {
+    top: 4px;
+    bottom: 4px;
+    right: 2px;
+    width: 6px;
+  }
+
+  &.is-scrolling,
+  &.is-hovering {
+    opacity: 1;
+    pointer-events: auto;
+  }
+}
+
+.hk-scrollbar-thumb {
+  position: absolute;
+  border-radius: 3px;
+  background: color-mix(in srgb, var(--hi-color-muted) 35%, transparent);
+  transition: background var(--hi-duration-fast, 0.15s) ease;
+
+  .is-hovering &,
+  &.is-dragging {
+    background: color-mix(in srgb, var(--hi-color-muted) 55%, transparent);
+  }
+}
+
+.hk-scrollbar-track[data-axis="horizontal"] .hk-scrollbar-thumb {
+  top: 0;
+  left: 0;
+  height: 100%;
+  min-width: 20px;
+}
+
+.hk-scrollbar-track:not([data-axis="horizontal"]) .hk-scrollbar-thumb {
+  top: 0;
+  left: 0;
+  width: 100%;
+  min-height: 20px;
+}

package/src/styles/vendoredSync.test.ts

@@ -48,6 +48,10 @@ function stripProvenanceHeader(source: string): string {
 const VENDORED_FROM_VUE: Array<[string, string]> = [
   ["theme/channels.scss", "tokens.scss"],
   ["theme/scale.scss", "scale.scss"],
+  // The overlay-scrollbar chrome lives with the other theme partials
+  // (packages/theme/styles) and is vendored here so npm consumers can
+  // resolve it — the exports map only exposes ./styles/*.
+  ["theme/scrollbar.scss", "../../theme/styles/_scrollbar.scss"],
 ];
 
 

package/src/utils/base64.ts

@@ -9,6 +9,18 @@ export function bytesToBase64(bytes: ArrayBuffer | Uint8Array): string {
   return btoa(binary);
 }
 
+/**
+ * Encode a JS string as base64, UTF-8 first.
+ *
+ * `btoa` throws `InvalidCharacterError` on any code point above U+00FF, which
+ * silently kills whatever called it — the demo gallery died on an em dash
+ * inside an inline SVG (`Hikari — zoom / pan demo`). Encode through
+ * `TextEncoder` so every string is encodable.
+ */
+export function utf8ToBase64(text: string): string {
+  return bytesToBase64(new TextEncoder().encode(text));
+}
+
 /** Decode a base64 string into raw bytes. */
 export function base64ToBytes(b64: string): Uint8Array {
   const binary = atob(b64);

package/src/utils/format.test.ts

@@ -55,12 +55,16 @@ describe("formatRelativeTime", () => {
     expect(formatRelativeTime(ago(29 * DAY))).toBe("4w ago");
   });
 
-  it("falls to the absolute-date path at >= 30d", () => {
+  it("falls to the absolute-date path at >= 30d, in the app locale", async () => {
     const d = ago(30 * DAY);
-    // Do not pin a locale-specific rendering; assert the value comes
-    // from the same Date's toLocaleDateString().
-    expect(formatRelativeTime(d)).toBe(d.toLocaleDateString());
-    expect(formatRelativeTime(d).length).toBeGreaterThan(0);
+    // The absolute tier must follow the app-selected hikari locale (the
+    // R2 sweep found the old assertion compared the BROWSER default,
+    // which proves nothing about locale-following).
+    const { setLocale } = await import("../i18n/context");
+    await setLocale("zh-Hans");
+    expect(formatRelativeTime(d)).toBe(d.toLocaleDateString("zh-Hans"));
+    await setLocale("en");
+    expect(formatRelativeTime(d)).toBe(d.toLocaleDateString("en"));
   });
 
   it("clamps future timestamps into the justNow tier", () => {
@@ -107,10 +111,11 @@ describe("formatRelativeTime", () => {
     });
   });
 
-  it("keeps absolute dates away from the translator", () => {
+  it("keeps absolute dates away from the translator", async () => {
     const { t, calls } = makeCaptureT();
     const d = ago(45 * DAY);
-    expect(formatRelativeTime(d, t)).toBe(d.toLocaleDateString());
+    const { activeLocale } = await import("../i18n/context");
+    expect(formatRelativeTime(d, t)).toBe(d.toLocaleDateString(activeLocale()));
     expect(calls).toHaveLength(0);
   });
 });

package/src/utils/format.ts

@@ -56,7 +56,8 @@ export type RelativeTimeT = (
  *  Pass an optional translator for localized variants; defaults to
  *  compact English text. Tiers: <1min justNow, <60min minutes,
  *  <24h hours, <7d days, <30d weeks, otherwise an absolute
- *  locale-rendered date (browser locale, like formatDateTime).
+ *  locale-rendered date (the app-selected hikari locale, like
+ *  formatDateTime).
  *  The translator owns {n} interpolation — hikari's own useI18n().t
  *  does NOT interpolate named params, so wrap it (the canonical key
  *  set lives in the per-locale i18n time bundles). */