@celestia-island/hikari 0.42.1 → 0.43.0

package/package.json

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

package/src/components/HkColorSchemeDialog.test.ts

@@ -84,22 +84,28 @@ describe("HkColorSchemeDialog extension groups", () => {
   it("renders the extension section reactively when a group is registered after mount", async () => {
     mountDialog();
     await nextTick();
-    // Zero-cost for consumers that register nothing.
-    expect(document.body.querySelector(".s-scheme-groups")).toBeNull();
+    // The section always renders now (the on-brand content group lives
+    // here); before any registration it holds exactly that one panel.
+    const before = document.body.querySelector(".s-scheme-groups");
+    expect(before).toBeTruthy();
+    expect(before!.querySelectorAll(".hk-expansion-panel")).toHaveLength(1);
 
     // Late registration (after the dialog is already rendered): the
     // registry's reactive version invalidates the computed and the
-    // section appears without a remount.
+    // group's panel appears without a remount.
     registerTokenGroup(DIALOG_GROUP);
     await nextTick();
 
     const section = document.body.querySelector(".s-scheme-groups");
     expect(section).toBeTruthy();
-    // Un-sectioned group: one expansion panel, all slots on its grid.
-    expect(section!.querySelectorAll(".hk-expansion-panel")).toHaveLength(1);
-    const grid = section!.querySelector(".s-scheme-group-grid");
-    expect(grid).toBeTruthy();
-    expect(grid!.querySelectorAll(".hk-color-picker")).toHaveLength(2);
+    // The late group's panel lands after the on-brand content panel.
+    expect(section!.querySelectorAll(".hk-expansion-panel")).toHaveLength(2);
+    // The late group's own grid: scoped by its panel title, 2 slots.
+    const groupPanel = [...section!.querySelectorAll<HTMLElement>(".hk-expansion-panel")].find(
+      (p) => p.querySelector(".hk-expansion-panel-title")?.textContent === "Dialog wires",
+    );
+    expect(groupPanel).toBeTruthy();
+    expect(groupPanel!.querySelectorAll(".hk-color-picker")).toHaveLength(2);
   });
 
   it("renders one expansion panel per section of a sectioned group", async () => {

package/src/components/HkColorSchemeEditor.test.ts

@@ -143,6 +143,23 @@ async function setSwatchHex(swatchIndex: number, hex: string): Promise<void> {
   await nextTick();
 }
 
+/** Set an on-brand content slot (0 = onSolidText, 1 = onSolidIcon) of the
+ *  active mode to a hex color — the pair edits inside the extended-colors
+ *  section's first group panel, not the accent row. */
+async function setOnSolidHex(slotIndex: number, hex: string): Promise<void> {
+  const swatches = document.body.querySelectorAll(
+    ".s-scheme-groups .s-scheme-group-grid .hk-color-picker-swatch-btn",
+  );
+  (swatches[slotIndex] as HTMLButtonElement).click();
+  await settle();
+  const input = document.body.querySelector(
+    ".hk-color-picker-hex-row input.hk-input-element",
+  ) as HTMLInputElement | null;
+  input!.value = hex;
+  input!.dispatchEvent(new Event("input", { bubbles: true }));
+  await nextTick();
+}
+
 beforeEach(() => {
   // Pin the effective mode so edits deterministically target the dark side.
   useTheme().setMode("dark");
@@ -156,14 +173,21 @@ afterEach(() => {
 });
 
 describe("HkColorSchemeEditor", () => {
-  it("renders the seven accent pickers plus the two on-solid content pickers", async () => {
+  it("renders seven accent pickers and moves the on-solid pair into the extended section", async () => {
     const { container } = mountEditor();
     await nextTick();
 
     const pickers = container.querySelectorAll(".s-scheme-colors .hk-color-picker");
-    expect(pickers).toHaveLength(9); // 7 accents + onSolidText + onSolidIcon
-    // No groups registered in this file yet: the extension section is absent.
-    expect(container.querySelector(".s-scheme-groups")).toBeNull();
+    expect(pickers).toHaveLength(7); // accents only — the on-solid pair moved out
+    // The extended section is always rendered: the on-brand content group
+    // lives there even with no extension token group registered.
+    const groups = container.querySelector(".s-scheme-groups");
+    expect(groups).not.toBeNull();
+    expect(groups!.querySelector(".s-scheme-groups-title")).not.toBeNull();
+    const onSolidPickers = groups!.querySelectorAll(
+      ".s-scheme-group-grid .hk-color-picker",
+    );
+    expect(onSolidPickers).toHaveLength(2); // onSolidText + onSolidIcon
   });
 
   it("editing a token updates getDraft() with the edited RGB", async () => {
@@ -175,15 +199,15 @@ describe("HkColorSchemeEditor", () => {
     expect(draft.dark.primary).toEqual({ r: 255, g: 0, b: 0 });
   });
 
-  it("editing an on-solid content color updates getDraft()", async () => {
+  it("editing an on-brand content color updates getDraft()", async () => {
     const { ref } = mountEditor();
     await nextTick();
 
-    // 9th picker in the grid = onSolidIcon (7 accents, then text, then icon).
+    // 2nd picker in the on-brand group grid = onSolidIcon (text first).
     const swatches = document.body.querySelectorAll(
-      ".s-scheme-colors .hk-color-picker-swatch-btn",
+      ".s-scheme-groups .s-scheme-group-grid .hk-color-picker-swatch-btn",
     );
-    (swatches[8] as HTMLButtonElement).click();
+    (swatches[1] as HTMLButtonElement).click();
     await settle();
     const input = document.body.querySelector(
       ".hk-color-picker-hex-row input.hk-input-element",
@@ -237,8 +261,8 @@ describe("HkColorSchemeEditor", () => {
     const { ref } = mountEditor({ initialDark: legacyDark });
     await nextTick();
 
-    // 8th picker in the grid = onSolidText (7 accents, then text, then icon).
-    await setSwatchHex(7, "00ff00");
+    // 1st picker in the on-brand group grid = onSolidText.
+    await setOnSolidHex(0, "00ff00");
     expect(ref.value!.getDraft().dark.onSolidText).toEqual({ r: 0, g: 255, b: 0 });
 
     ref.value!.reset();
@@ -259,7 +283,7 @@ describe("HkColorSchemeEditor", () => {
     });
     await nextTick();
 
-    await setSwatchHex(7, "00ff00");
+    await setOnSolidHex(0, "00ff00");
     expect(ref.value!.getDraft().dark.onSolidText).toEqual({ r: 0, g: 255, b: 0 });
 
     ref.value!.reset();

package/src/components/HkColorSchemeEditor.tsx

@@ -123,14 +123,16 @@ export interface HCustomTheme {
  * their own surface (tabs, drawers, panels) instead of the built-in modal.
  *
  * Edits the seven accent tokens (primary/secondary/accent/success/error/
- * warning/info) plus the on-solid content colors (onSolidText — text on
- * brand fills, onSolidIcon — icons/shapes such as the switch thumb) per
- * mode (dark/light); the remaining surface tokens are derived. When
- * extension token groups are registered (`registerTokenGroup` /
- * `registerTokenGroupConfig`), the "Extended colors" section renders one
- * Material expansion panel per group — sub-sectioned groups get one panel
- * per section — with the slots laid out on a 2–3 column grid of
- * hue-clamped pickers showing full localized color names.
+ * warning/info) per mode (dark/light); the remaining surface tokens are
+ * derived. The on-solid content colors (onSolidText — text on brand
+ * fills, onSolidIcon — icons/shapes such as the switch thumb) are
+ * user-choosable too and edit as the FIRST group of the "Extended
+ * colors" section (2026-09-11 user direction: moved out of the accent
+ * row). When extension token groups are registered
+ * (`registerTokenGroup` / `registerTokenGroupConfig`), the section
+ * renders one Material expansion panel per group — sub-sectioned groups
+ * get one panel per section — with the slots laid out on a 2–3 column
+ * grid of hue-clamped pickers showing full localized color names.
  *
  * Exposes `reset()` (re-seed from props + current effective mode) and
  * `getDraft()` (snapshot the current edits as a `HCustomTheme`) for the
@@ -365,6 +367,40 @@ export const HkColorSchemeEditor = defineComponent({
       return panels;
     }
 
+    // ── On-brand content colors as their own extended group ──────────
+    // The two content tokens (text / icons on solid brand fills) USED to
+    // sit in the top accent row (2026-09-11 user direction: they are
+    // niche, rarely-tuned colors — they belong with the other extension
+    // palettes, as the section's FIRST group). Editing them here writes
+    // the exact same draft slots as before; only the location moved.
+    function renderOnSolidGroup() {
+      return (
+        <HExpansionPanel
+          key="on-solid-content"
+          title={t("hikari::theme.onSolidGroupTitle", "On-brand content")}
+          subtitle={countLabel(contentTokens.length)}
+        >
+          <div class="s-scheme-group-grid">
+            {contentTokens.map((key) => {
+              // Optional slots: an older prefilled custom theme may omit them.
+              const rgb = currentTokens.value[key] ?? WHITE;
+              return (
+                <HColorPicker
+                  key={key}
+                  r={rgb.r}
+                  g={rgb.g}
+                  b={rgb.b}
+                  label={t(`hikari::theme.tokens.${key}`)}
+                  layout="row"
+                  onChange={(next: { r: number; g: number; b: number }) => updateToken(key, next)}
+                />
+              );
+            })}
+          </div>
+        </HExpansionPanel>
+      );
+    }
+
     return () => (
       <div class="s-scheme-dialog">
         {props.showName && (
@@ -393,31 +429,18 @@ export const HkColorSchemeEditor = defineComponent({
               onChange={(rgb: { r: number; g: number; b: number }) => updateToken(key, rgb)}
             />
           ))}
-          {contentTokens.map((key) => {
-            // Optional slots: an older prefilled custom theme may omit them.
-            const rgb = currentTokens.value[key] ?? WHITE;
-            return (
-              <HColorPicker
-                key={key}
-                r={rgb.r}
-                g={rgb.g}
-                b={rgb.b}
-                label={t(`hikari::theme.tokens.${key}`)}
-                onChange={(next: { r: number; g: number; b: number }) => updateToken(key, next)}
-              />
-            );
-          })}
         </div>
-        {registeredGroups.value.length > 0 && (
-          <div class="s-scheme-groups">
-            <div class="s-scheme-groups-title">
-              {t("hikari::theme.extendedColors", "Extended colors")}
-            </div>
-            <div class="s-scheme-group-panels">
-              {registeredGroups.value.map((group) => renderGroup(group))}
-            </div>
+        {/* Always rendered now: the on-brand content group lives here even
+            when no extension token group is registered. */}
+        <div class="s-scheme-groups">
+          <div class="s-scheme-groups-title">
+            {t("hikari::theme.extendedColors", "Extended colors")}
           </div>
-        )}
+          <div class="s-scheme-group-panels">
+            {renderOnSolidGroup()}
+            {registeredGroups.value.map((group) => renderGroup(group))}
+          </div>
+        </div>
       </div>
     );
   },

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

@@ -0,0 +1,44 @@
+/**
+ * Source contract for the immersive lightbox layout (2026-09-11 field
+ * report wave). Pinned as scss-text assertions because the failure class
+ * is invisible to DOM tests: happy-dom has no layout engine, so a
+ * collapsed flex chain (the "white lightbox" — viewer 0px tall inside a
+ * full-size modal frame) and a cascade-losing hover state (the floating
+ * close button melting into the page) both pass every render test.
+ */
+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 read = (f: string): string => readFileSync(join(here, f), "utf-8");
+
+describe("HkImageLightbox layout contract", () => {
+  it("makes the modal scroll region a flex container so the body chain can fill the frame", () => {
+    const css = read("HkImageLightbox.scss");
+    // The lightbox override block must carry the display itself: the inner
+    // only carries flex: 1, which is inert inside a block parent — without
+    // this the stage collapses to its padding and the viewer renders 0px
+    // tall (white canvas, dead gestures).
+    const block = css.slice(
+      css.indexOf(".hk-modal-content.hk-image-lightbox"),
+      css.indexOf(".hk-image-lightbox-stage"),
+    );
+    expect(block).toContain(".hk-modal-body-scroll");
+    expect(block).toMatch(/\.hk-modal-body-scroll\s*\{[^}]*display:\s*flex/);
+  });
+
+  it("re-asserts the dark chip on hover/focus above the window-close cascade", () => {
+    const css = read("HkImageLightbox.scss");
+    // window-close.scss's :hover paints the light theme tint and loses to
+    // nothing here — the lightbox hover must re-assert the real background
+    // (not just the custom properties) at higher specificity, and push the
+    // color into the glyph span (which keeps its own white declaration).
+    expect(css).toContain("&.hk-window-close:hover");
+    expect(css).toContain("&.hk-window-close:focus-visible");
+    const hoverBlock = css.slice(css.indexOf("&.hk-window-close:hover"));
+    expect(hoverBlock.indexOf("background:")).toBeGreaterThan(-1);
+    expect(hoverBlock).toContain(".hk-icon-button-icon");
+  });
+});

package/src/components/HkImageLightbox.scss

@@ -8,6 +8,13 @@
 // The frame is a fixed-size stage; the body chain (body → scroll →
 // inner) is flattened to pure flex so the HImageViewer fills it, and the
 // floating close button rides on top of the stage.
+//
+// The scroll link MUST become a flex container itself: the inner below it
+// only carries `flex: 1`, which does nothing inside a block parent —
+// without `display: flex` here the chain collapses to the stage's own
+// padding and the viewer renders 0px tall (the 2026-09-11 "white
+// lightbox" field report: full-size modal frame, invisible canvas, and
+// every wheel/pointer gesture dead because their surface had no area).
 // ------
 
 .hk-modal-content.hk-image-lightbox {
@@ -28,6 +35,8 @@
     flex: 1;
     min-height: 0;
     overflow: hidden;
+    display: flex;
+    flex-direction: column;
   }
 
   .hk-modal-body-inner {
@@ -61,6 +70,17 @@
 // Floating close button — legible on any image: translucent dark chip
 // with a blur, light glyph. Colors ride HIconButton's variable layer
 // (--hi-icon-button-*) so the icon span picks them up too.
+//
+// The hover/focus state must RE-ASSERT the real `background`/`color`
+// properties, not just the custom properties: the shared window-close
+// grammar (imported after this sheet, equal specificity on :hover) wins
+// the cascade tie and paints the near-transparent light-theme tint over
+// the dark chip, while the glyph span keeps its own
+// `color: var(--hi-icon-button-icon-color)` (white) — white glyph on the
+// white modal, the button visibly vanished (2026-09-11 field report).
+// The selectors carry the extra `.hk-window-close` class the lightbox
+// button always wears, so the pair here outranks window-close's
+// `&:hover` regardless of bundle order.
 // ------
 
 .hk-image-lightbox-close.hk-icon-button {
@@ -77,11 +97,24 @@
   color: var(--hi-icon-button-icon-color);
   backdrop-filter: blur(6px);
 
-  &:hover {
+  &:hover,
+  &:focus-visible {
     --hi-icon-button-bg: rgb(0 0 0 / 65%);
     --hi-icon-button-icon-color: #fff;
   }
 
+  // (0,4,0) with the pseudo-class counted — beats
+  // `.hk-icon-button.hk-window-close:hover` at (0,3,0).
+  &.hk-window-close:hover,
+  &.hk-window-close:focus-visible {
+    background: var(--hi-icon-button-bg);
+    color: var(--hi-icon-button-icon-color);
+
+    .hk-icon-button-icon {
+      color: var(--hi-icon-button-icon-color);
+    }
+  }
+
   &:focus-visible {
     outline: 2px solid rgb(255 255 255 / 80%);
     outline-offset: 2px;

package/src/components/HkImageViewer.tsx

@@ -327,7 +327,13 @@ export default defineComponent({
           </div>
         )}
 
-        {loaded.value && isZoomed.value && (
+        {/* The controls are visible for the WHOLE session, not only once
+            zoomed past fit (2026-09-11 user report: at fit the viewer
+            offered no affordance at all — no buttons, no percent, no hint
+            that wheel/pinch/drag exist). At fit the viewport rect says
+            nothing worth drawing, so the minimap runs toolbar-only and
+            grows the overview map back the moment zooming starts. */}
+        {loaded.value && (
           <HMinimap
             imageSrc={props.src}
             imageBounds={contentBounds.value}
@@ -344,6 +350,7 @@ export default defineComponent({
             minZoomPercent={Math.max(1, Math.round(fit.value * 100))}
             maxZoomPercent={Math.round(MAX_ZOOM * 100)}
             showReset
+            toolbarOnly={!isZoomed.value}
             onZoomTo={(percent: number) => setZoom(percent / 100)}
             onReset={resetView}
             onPanDelta={onPanDelta}

package/src/components/HkMinimap.scss

@@ -41,6 +41,16 @@
   pointer-events: auto;
 }
 
+// Toolbar-only form (no overview map): shrink-wrap the card around the
+// zoom bar and drop the map's separator — the bar IS the whole surface.
+.hk-minimap[data-toolbar-only] {
+  width: auto;
+
+  .hk-mm-zoom-bar {
+    border-top: none;
+  }
+}
+
 .hk-mm-zoom-btn {
   display: flex;
   align-items: center;

package/src/components/HkMinimap.toolbarOnly.test.tsx

@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h } from "vue";
+
+import HkMinimap from "./HkMinimap";
+
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+afterEach(() => {
+  for (const app of mounts.splice(0)) app.unmount();
+  for (const el of containers.splice(0)) el.remove();
+});
+
+function mountMinimap(props: Record<string, unknown>): HTMLElement {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+
+  const Host = defineComponent({
+    setup() {
+      return () => h("div", [h(HkMinimap, props)]);
+    },
+  });
+  const app = createApp(Host);
+  mounts.push(app);
+  app.mount(container);
+  return container;
+}
+
+describe("HkMinimap toolbar-only form", () => {
+  it("renders nothing without boxes, an image, or the toolbar-only flag", () => {
+    const c = mountMinimap({ zoomPercent: 100 });
+    expect(c.querySelector(".hk-minimap")).toBeNull();
+  });
+
+  it("renders only the zoom bar under toolbarOnly (no overview map)", () => {
+    const c = mountMinimap({ zoomPercent: 100, toolbarOnly: true });
+    const root = c.querySelector<HTMLElement>(".hk-minimap");
+    expect(root).not.toBeNull();
+    expect(root!.hasAttribute("data-toolbar-only")).toBe(true);
+    expect(root!.querySelector(".hk-minimap-svg")).toBeNull();
+    expect(root!.querySelector(".hk-mm-zoom-bar")).not.toBeNull();
+    expect(root!.querySelectorAll(".hk-mm-zoom-btn").length).toBe(2);
+  });
+
+  it("keeps the overview map when toolbarOnly is not set and an image is given", () => {
+    const c = mountMinimap({ imageSrc: "data:image/gif;base64,", toolbarOnly: false });
+    const root = c.querySelector<HTMLElement>(".hk-minimap");
+    expect(root).not.toBeNull();
+    expect(root!.hasAttribute("data-toolbar-only")).toBe(false);
+    expect(root!.querySelector(".hk-minimap-svg")).not.toBeNull();
+    expect(root!.querySelector(".hk-mm-zoom-bar")).not.toBeNull();
+  });
+});

package/src/components/HkMinimap.tsx

@@ -65,6 +65,12 @@ export default defineComponent({
     /** Show the reset/fit button in the zoom bar (chest only rendered it
      *  when a reset handler was wired up). */
     showReset: { type: Boolean, default: false },
+    /** Toolbar-only form: render just the zoom bar, no overview map. For
+     *  hosts whose viewport rect is uninformative at rest (e.g. the image
+     *  lightbox at fit zoom) but that still want the zoom controls
+     *  visible; the map is expected to reappear once it has something to
+     *  say (the viewer switches this off when zoomed past fit). */
+    toolbarOnly: { type: Boolean, default: false },
     /** Optional prop-callback surface (alternative to the emits). */
     onZoomTo: { type: Function as PropType<(percent: number) => void>, default: undefined },
     onReset: { type: Function as PropType<() => void>, default: undefined },
@@ -180,7 +186,7 @@ export default defineComponent({
     });
 
     return () => {
-      if (props.boxes.length === 0 && !props.imageSrc) return null;
+      if (props.boxes.length === 0 && !props.imageSrc && !props.toolbarOnly) return null;
 
       const s = scale.value;
       const vr = viewportRect.value;
@@ -213,42 +219,45 @@ export default defineComponent({
           ref={rootRef}
           class="hk-minimap"
           data-dragging={dragging.value ? "" : undefined}
+          data-toolbar-only={props.toolbarOnly ? "" : undefined}
         >
-          <svg viewBox={`0 0 ${svgW} ${svgH}`} width={svgW} height={svgH} class="hk-minimap-svg">
-            {imgPos && (
-              <image
-                href={props.imageSrc}
-                x={imgPos[0]}
-                y={imgPos[1]}
-                width={ib.w * s}
-                height={ib.h * s}
-                preserveAspectRatio="none"
-                class="hk-mm-image"
+          {!props.toolbarOnly && (
+            <svg viewBox={`0 0 ${svgW} ${svgH}`} width={svgW} height={svgH} class="hk-minimap-svg">
+              {imgPos && (
+                <image
+                  href={props.imageSrc}
+                  x={imgPos[0]}
+                  y={imgPos[1]}
+                  width={ib.w * s}
+                  height={ib.h * s}
+                  preserveAspectRatio="none"
+                  class="hk-mm-image"
+                />
+              )}
+              {boxRects}
+              {hubP && (
+                <circle
+                  cx={hubP[0]}
+                  cy={hubP[1]}
+                  r={3}
+                  fill="rgb(var(--color-primary))"
+                  filter="drop-shadow(0 0 2px rgb(var(--color-primary) / 0.6))"
+                />
+              )}
+              <rect
+                x={vr.x}
+                y={vr.y}
+                width={Math.max(1, vr.w)}
+                height={Math.max(1, vr.h)}
+                fill="none"
+                stroke="rgb(var(--color-primary))"
+                stroke-width="1"
+                stroke-dasharray="3 2"
+                rx="2"
+                opacity="0.85"
               />
-            )}
-            {boxRects}
-            {hubP && (
-              <circle
-                cx={hubP[0]}
-                cy={hubP[1]}
-                r={3}
-                fill="rgb(var(--color-primary))"
-                filter="drop-shadow(0 0 2px rgb(var(--color-primary) / 0.6))"
-              />
-            )}
-            <rect
-              x={vr.x}
-              y={vr.y}
-              width={Math.max(1, vr.w)}
-              height={Math.max(1, vr.h)}
-              fill="none"
-              stroke="rgb(var(--color-primary))"
-              stroke-width="1"
-              stroke-dasharray="3 2"
-              rx="2"
-              opacity="0.85"
-            />
-          </svg>
+            </svg>
+          )}
           <div class="hk-mm-zoom-bar">
             <button
               class="hk-mm-zoom-btn"

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

@@ -0,0 +1,28 @@
+/**
+ * Source contract for the theme-row leading cell sizing (2026-09-11
+ * field report: chest's 28px three-dot palette swatch overflowed its
+ * 16px generic icon cell and bled into the row gap — at fractional zoom
+ * rounding the dots visually overlapped the row name). happy-dom has no
+ * layout engine, so the geometry contract is pinned as an scss-text
+ * assertion: the theme-row lead cell must carry an explicit size that
+ * fits the widest host lead mark, not just the mixin's generic box.
+ */
+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 read = (f: string): string => readFileSync(join(here, f), "utf-8");
+
+describe("HkThemeToggle row lead-cell contract", () => {
+  it("sizes the theme-row lead cell to fit a 28px swatch mark", () => {
+    const css = read("HkThemeToggle.scss");
+    const block = css.match(
+      /\.s-theme-item-btn \.hk-menu-item-icon\s*\{[^}]*\}/,
+    );
+    expect(block).not.toBeNull();
+    expect(block![0]).toContain("width: 28px");
+    expect(block![0]).toContain("height: 28px");
+  });
+});

package/src/components/HkThemeToggle.scss

@@ -188,9 +188,19 @@
   @include mi.label;
 }
 
-/* Leading check / customize glyphs share the spec's fixed icon cell. */
+/* Leading check / customize glyphs share the spec's fixed icon cell —
+ * sized for the WIDEST lead mark hosts render there, not the generic
+ * 16px box: chest's three-dot palette swatch is 28px (3×8px dots + 2px
+ * gaps), and a mark wider than its cell bleeds symmetrically out of the
+ * cell into the row gap — at fractional zoom rounding the dots visually
+ * overlap the name (2026-09-11 field report). A uniform 28px cell keeps
+ * every row's name starting at the same x (swatch rows and icon rows
+ * stay aligned) and leaves the bleed zero room at any zoom. */
 .s-theme-item-btn .hk-menu-item-icon {
   @include mi.icon;
+
+  width: 28px;
+  height: 28px;
 }
 
 /* Custom rows keep the name clear of the overlaid delete button. */

package/src/i18n/locales/ar/platform.json

@@ -41,6 +41,7 @@
     "hikari::theme.tokens.onSolidIcon": "أيقونات على لون العلامة",
     "hikari::theme.groupCount": "{count} ألوان",
     "hikari::theme.extendedColors": "ألوان موسعة",
+    "hikari::theme.onSolidGroupTitle": "المحتوى على لون العلامة",
     "hikari::secret.title": "سر",
     "hikari::secret.notice": "يُعرض هذا السر مرة واحدة فقط. انسخه واحفظه قبل الإغلاق.",
     "hikari::secret.copy": "نسخ",

package/src/i18n/locales/ar/time.json

@@ -0,0 +1,9 @@
+{
+  "time": {
+    "common.time.justNow": "الآن",
+    "common.time.minutesAgo": "قبل {n} دقيقة",
+    "common.time.hoursAgo": "قبل {n} ساعة",
+    "common.time.daysAgo": "قبل {n} يوم",
+    "common.time.weeksAgo": "قبل {n} أسبوع"
+  }
+}

package/src/i18n/locales/de/platform.json

@@ -41,6 +41,7 @@
     "hikari::theme.tokens.onSolidIcon": "Symbole auf Markenfarbe",
     "hikari::theme.groupCount": "{count} Farben",
     "hikari::theme.extendedColors": "Erweiterte Farben",
+    "hikari::theme.onSolidGroupTitle": "Inhalte auf Brandfarben",
     "hikari::secret.title": "Geheimnis",
     "hikari::secret.notice": "Dieses Geheimnis wird nur einmal angezeigt. Kopieren und speichern Sie es vor dem Schließen.",
     "hikari::secret.copy": "Kopieren",

package/src/i18n/locales/de/time.json

@@ -0,0 +1,9 @@
+{
+  "time": {
+    "common.time.justNow": "Gerade eben",
+    "common.time.minutesAgo": "vor {n} Min.",
+    "common.time.hoursAgo": "vor {n} Std.",
+    "common.time.daysAgo": "vor {n} Tg.",
+    "common.time.weeksAgo": "vor {n} Wo."
+  }
+}

package/src/i18n/locales/en/platform.json

@@ -41,6 +41,7 @@
     "hikari::theme.tokens.onSolidIcon": "Icons on brand fill",
     "hikari::theme.groupCount": "{count} colors",
     "hikari::theme.extendedColors": "Extended colors",
+    "hikari::theme.onSolidGroupTitle": "On-brand content",
     "hikari::secret.title": "Secret",
     "hikari::secret.notice": "This secret is shown only once. Copy and store it before closing.",
     "hikari::secret.copy": "Copy",

package/src/i18n/locales/en/time.json

@@ -0,0 +1,9 @@
+{
+  "time": {
+    "common.time.justNow": "Just now",
+    "common.time.minutesAgo": "{n} min ago",
+    "common.time.hoursAgo": "{n} h ago",
+    "common.time.daysAgo": "{n} d ago",
+    "common.time.weeksAgo": "{n} w ago"
+  }
+}

package/src/i18n/locales/es/platform.json

@@ -41,6 +41,7 @@
     "hikari::theme.tokens.onSolidIcon": "Iconos sobre color de marca",
     "hikari::theme.groupCount": "{count} colores",
     "hikari::theme.extendedColors": "Colores extendidos",
+    "hikari::theme.onSolidGroupTitle": "Contenido sobre el color de marca",
     "hikari::secret.title": "Secreto",
     "hikari::secret.notice": "Este secreto se muestra solo una vez. Cópielo y guárdelo antes de cerrar.",
     "hikari::secret.copy": "Copiar",

package/src/i18n/locales/es/time.json

@@ -0,0 +1,9 @@
+{
+  "time": {
+    "common.time.justNow": "Ahora mismo",
+    "common.time.minutesAgo": "hace {n} min",
+    "common.time.hoursAgo": "hace {n} h",
+    "common.time.daysAgo": "hace {n} d",
+    "common.time.weeksAgo": "hace {n} sem"
+  }
+}

package/src/i18n/locales/fr/platform.json

@@ -41,6 +41,7 @@
     "hikari::theme.tokens.onSolidIcon": "Icônes sur la couleur de marque",
     "hikari::theme.groupCount": "{count} couleurs",
     "hikari::theme.extendedColors": "Couleurs étendues",
+    "hikari::theme.onSolidGroupTitle": "Contenu sur la couleur de marque",
     "hikari::secret.title": "Secret",
     "hikari::secret.notice": "Ce secret n'est affiché qu'une seule fois. Copiez-le et conservez-le avant de fermer.",
     "hikari::secret.copy": "Copier",

package/src/i18n/locales/fr/time.json

@@ -0,0 +1,9 @@
+{
+  "time": {
+    "common.time.justNow": "À l'instant",
+    "common.time.minutesAgo": "il y a {n} min",
+    "common.time.hoursAgo": "il y a {n} h",
+    "common.time.daysAgo": "il y a {n} j",
+    "common.time.weeksAgo": "il y a {n} sem."
+  }
+}

package/src/i18n/locales/ja/platform.json

@@ -41,6 +41,7 @@
     "hikari::theme.tokens.onSolidIcon": "ブランド色上のアイコン",
     "hikari::theme.groupCount": "{count} 色",
     "hikari::theme.extendedColors": "拡張カラー",
+    "hikari::theme.onSolidGroupTitle": "ブランドカラー上のコンテンツ",
     "hikari::secret.title": "シークレット",
     "hikari::secret.notice": "このシークレットは一度だけ表示されます。閉じる前にコピーして保存してください。",
     "hikari::secret.copy": "コピー",

package/src/i18n/locales/ja/time.json

@@ -0,0 +1,9 @@
+{
+  "time": {
+    "common.time.justNow": "たった今",
+    "common.time.minutesAgo": "{n} 分前",
+    "common.time.hoursAgo": "{n} 時間前",
+    "common.time.daysAgo": "{n} 日前",
+    "common.time.weeksAgo": "{n} 週間前"
+  }
+}

package/src/i18n/locales/ko/platform.json

@@ -41,6 +41,7 @@
     "hikari::theme.tokens.onSolidIcon": "브랜드 색 위의 아이콘",
     "hikari::theme.groupCount": "색상 {count}개",
     "hikari::theme.extendedColors": "확장 색상",
+    "hikari::theme.onSolidGroupTitle": "브랜드 색상 콘텐츠",
     "hikari::secret.title": "비밀",
     "hikari::secret.notice": "이 비밀은 한 번만 표시됩니다. 닫기 전에 복사하여 저장하세요.",
     "hikari::secret.copy": "복사",

package/src/i18n/locales/ko/time.json

@@ -0,0 +1,9 @@
+{
+  "time": {
+    "common.time.justNow": "방금 전",
+    "common.time.minutesAgo": "{n}분 전",
+    "common.time.hoursAgo": "{n}시간 전",
+    "common.time.daysAgo": "{n}일 전",
+    "common.time.weeksAgo": "{n}주 전"
+  }
+}

package/src/i18n/locales/pt/platform.json

@@ -41,6 +41,7 @@
     "hikari::theme.tokens.onSolidIcon": "Ícones sobre a cor da marca",
     "hikari::theme.groupCount": "{count} cores",
     "hikari::theme.extendedColors": "Cores estendidas",
+    "hikari::theme.onSolidGroupTitle": "Conteúdo sobre a cor da marca",
     "hikari::secret.title": "Segredo",
     "hikari::secret.notice": "Este segredo é mostrado apenas uma vez. Copie e guarde antes de fechar.",
     "hikari::secret.copy": "Copiar",

package/src/i18n/locales/pt/time.json

@@ -0,0 +1,9 @@
+{
+  "time": {
+    "common.time.justNow": "Agora mesmo",
+    "common.time.minutesAgo": "há {n} min",
+    "common.time.hoursAgo": "há {n} h",
+    "common.time.daysAgo": "há {n} d",
+    "common.time.weeksAgo": "há {n} sem"
+  }
+}

package/src/i18n/locales/ru/platform.json

@@ -41,6 +41,7 @@
     "hikari::theme.tokens.onSolidIcon": "Значки на фирменном цвете",
     "hikari::theme.groupCount": "Цветов: {count}",
     "hikari::theme.extendedColors": "Расширенные цвета",
+    "hikari::theme.onSolidGroupTitle": "Контент на фирменном цвете",
     "hikari::secret.title": "Секрет",
     "hikari::secret.notice": "Этот секрет показывается только один раз. Скопируйте и сохраните его до закрытия.",
     "hikari::secret.copy": "Копировать",

package/src/i18n/locales/ru/time.json

@@ -0,0 +1,9 @@
+{
+  "time": {
+    "common.time.justNow": "Только что",
+    "common.time.minutesAgo": "{n} мин. назад",
+    "common.time.hoursAgo": "{n} ч. назад",
+    "common.time.daysAgo": "{n} дн. назад",
+    "common.time.weeksAgo": "{n} нед. назад"
+  }
+}

package/src/i18n/locales/zh-Hans/platform.json

@@ -41,6 +41,7 @@
     "hikari::theme.tokens.onSolidIcon": "品牌色上的图标",
     "hikari::theme.groupCount": "{count} 种颜色",
     "hikari::theme.extendedColors": "扩展配色",
+    "hikari::theme.onSolidGroupTitle": "品牌色内容",
     "hikari::secret.title": "密钥",
     "hikari::secret.notice": "此密钥仅显示一次，请先复制并妥善保存。",
     "hikari::secret.copy": "复制",

package/src/i18n/locales/zh-Hans/time.json

@@ -0,0 +1,9 @@
+{
+  "time": {
+    "common.time.justNow": "刚刚",
+    "common.time.minutesAgo": "{n} 分钟前",
+    "common.time.hoursAgo": "{n} 小时前",
+    "common.time.daysAgo": "{n} 天前",
+    "common.time.weeksAgo": "{n} 周前"
+  }
+}

package/src/i18n/locales/zh-Hant/platform.json

@@ -41,6 +41,7 @@
     "hikari::theme.tokens.onSolidIcon": "品牌色上的圖示",
     "hikari::theme.groupCount": "{count} 種顏色",
     "hikari::theme.extendedColors": "擴充配色",
+    "hikari::theme.onSolidGroupTitle": "品牌色內容",
     "hikari::secret.title": "金鑰",
     "hikari::secret.notice": "此金鑰僅顯示一次，請先複製並妥善保存。",
     "hikari::secret.copy": "複製",

package/src/i18n/locales/zh-Hant/time.json

@@ -0,0 +1,9 @@
+{
+  "time": {
+    "common.time.justNow": "剛剛",
+    "common.time.minutesAgo": "{n} 分鐘前",
+    "common.time.hoursAgo": "{n} 小時前",
+    "common.time.daysAgo": "{n} 天前",
+    "common.time.weeksAgo": "{n} 週前"
+  }
+}

package/src/i18n/timeKeys.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+
+import { setLocale, useI18n } from "./context";
+
+/**
+ * Locale key pack for the formatRelativeTime facility
+ * (common.time.justNow/minutesAgo/hoursAgo/daysAgo/weeksAgo, served from
+ * the new locales/<lang>/time.json bundles). The JSON keys are the literal
+ * unprefixed full names because t() resolves by exact full-name match
+ * (context.ts merges string leaves under their literal key) and the
+ * facility + its host-t consumers call t("common.time.*") unprefixed —
+ * the "hikari::" prefix convention is reserved for
+ * hikari-component-owned keys. A key missing from any locale silently
+ * falls back to English there, so every locale must define all five keys
+ * with matching {n} placeholder presence (hikari review lessons
+ * #373/#374, same shape as contextKeys.test.ts).
+ */
+const modules = import.meta.glob<{ default: Record<string, Record<string, string>> }>(
+  "./locales/*/time.json",
+  { eager: true },
+);
+
+const EXPECTED_LOCALES = [
+  "ar", "de", "en", "es", "fr", "ja", "ko", "pt", "ru", "zh-Hans", "zh-Hant",
+];
+
+const REQUIRED_KEYS = [
+  "common.time.justNow",
+  "common.time.minutesAgo",
+  "common.time.hoursAgo",
+  "common.time.daysAgo",
+  "common.time.weeksAgo",
+];
+
+describe("common.time locale keys", () => {
+  const bundles = Object.entries(modules).map(([path, mod]) => ({
+    locale: path.match(/locales\/([^/]+)\/time\.json/)?.[1] ?? "",
+    flat: mod.default.time ?? {},
+  }));
+
+  it("covers all 11 time.json locale files", () => {
+    expect(bundles.map((b) => b.locale).sort()).toEqual(EXPECTED_LOCALES);
+  });
+
+  it("defines all 5 common.time.* keys in every locale, non-empty", () => {
+    for (const { locale, flat } of bundles) {
+      for (const key of REQUIRED_KEYS) {
+        expect(typeof flat[key], `${locale} must define ${key}`).toBe("string");
+        expect((flat[key] ?? "").length, `${locale} ${key} must not be empty`).toBeGreaterThan(0);
+      }
+    }
+  });
+
+  it("matches the {n} placeholder pattern of en in every locale", () => {
+    const en = bundles.find((b) => b.locale === "en");
+    expect(en, "en bundle renders").toBeTruthy();
+    for (const { locale, flat } of bundles) {
+      for (const key of REQUIRED_KEYS) {
+        const wantsN = en!.flat[key].includes("{n}");
+        expect(flat[key].includes("{n}"), `${locale} ${key} {n} parity`).toBe(wantsN);
+      }
+    }
+  });
+
+  it("resolves through useI18n at runtime, per locale", async () => {
+    await setLocale("zh-Hans");
+    const zh = useI18n();
+    expect(zh.t("common.time.justNow", "Just now")).toBe("刚刚");
+    expect(zh.t("common.time.hoursAgo", "{n} h ago").replace("{n}", "3")).toBe("3 小时前");
+
+    await setLocale("de");
+    const de = useI18n();
+    expect(de.t("common.time.daysAgo", "{n} d ago").replace("{n}", "2")).toBe("vor 2 Tg.");
+
+    await setLocale("en");
+    const en = useI18n();
+    expect(en.t("common.time.weeksAgo", "{n} w ago")).toBe("{n} w ago");
+  });
+});

package/src/utils/format.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "vitest";
+
+import { formatRelativeTime, type RelativeTimeT } from "./format";
+
+const MIN = 60_000;
+const HOUR = 3_600_000;
+const DAY = 86_400_000;
+
+function ago(ms: number): Date {
+  return new Date(Date.now() - ms);
+}
+
+interface CapturedCall {
+  key: string;
+  fallback: string;
+  named?: Record<string, unknown>;
+}
+
+/** Fake translator: records every lookup and renders the {n} slot so
+ *  injection can be asserted end-to-end. */
+function makeCaptureT(): { t: RelativeTimeT; calls: CapturedCall[] } {
+  const calls: CapturedCall[] = [];
+  const t: RelativeTimeT = (key, fallback, named) => {
+    calls.push({ key, fallback, named });
+    return fallback.replace("{n}", String(named?.n ?? ""));
+  };
+  return { t, calls };
+}
+
+describe("formatRelativeTime", () => {
+  it("returns an empty string for missing input", () => {
+    expect(formatRelativeTime("")).toBe("");
+    expect(formatRelativeTime(0)).toBe("");
+  });
+
+  it("returns an empty string for unparseable input", () => {
+    expect(formatRelativeTime("not-a-date")).toBe("");
+    expect(formatRelativeTime(Number.NaN)).toBe("");
+  });
+
+  it("renders the compact English fallback per tier", () => {
+    expect(formatRelativeTime(ago(59_000))).toBe("Just now");
+    expect(formatRelativeTime(ago(MIN))).toBe("1m ago");
+    expect(formatRelativeTime(ago(59 * MIN))).toBe("59m ago");
+    expect(formatRelativeTime(ago(HOUR))).toBe("1h ago");
+    expect(formatRelativeTime(ago(23 * HOUR))).toBe("23h ago");
+    expect(formatRelativeTime(ago(DAY))).toBe("1d ago");
+    expect(formatRelativeTime(ago(6 * DAY))).toBe("6d ago");
+  });
+
+  it("adds the weeks tier from 7d up to (excluding) 30d", () => {
+    expect(formatRelativeTime(ago(7 * DAY))).toBe("1w ago");
+    expect(formatRelativeTime(ago(13 * DAY))).toBe("1w ago");
+    expect(formatRelativeTime(ago(14 * DAY))).toBe("2w ago");
+    expect(formatRelativeTime(ago(29 * DAY))).toBe("4w ago");
+  });
+
+  it("falls to the absolute-date path at >= 30d", () => {
+    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);
+  });
+
+  it("clamps future timestamps into the justNow tier", () => {
+    expect(formatRelativeTime(ago(-5 * MIN))).toBe("Just now");
+    expect(formatRelativeTime(ago(-2 * DAY))).toBe("Just now");
+  });
+
+  it("passes the documented keys with injected {n} to the translator", () => {
+    const { t, calls } = makeCaptureT();
+
+    expect(formatRelativeTime(ago(30_000), t)).toBe("Just now");
+    expect(calls[0]).toEqual({
+      key: "common.time.justNow",
+      fallback: "Just now",
+      named: undefined,
+    });
+
+    expect(formatRelativeTime(ago(5 * MIN), t)).toBe("5 min ago");
+    expect(calls[1]).toEqual({
+      key: "common.time.minutesAgo",
+      fallback: "{n} min ago",
+      named: { n: 5 },
+    });
+
+    expect(formatRelativeTime(ago(3 * HOUR), t)).toBe("3 h ago");
+    expect(calls[2]).toEqual({
+      key: "common.time.hoursAgo",
+      fallback: "{n} h ago",
+      named: { n: 3 },
+    });
+
+    expect(formatRelativeTime(ago(2 * DAY), t)).toBe("2 d ago");
+    expect(calls[3]).toEqual({
+      key: "common.time.daysAgo",
+      fallback: "{n} d ago",
+      named: { n: 2 },
+    });
+
+    expect(formatRelativeTime(ago(8 * DAY), t)).toBe("1 w ago");
+    expect(calls[4]).toEqual({
+      key: "common.time.weeksAgo",
+      fallback: "{n} w ago",
+      named: { n: 1 },
+    });
+  });
+
+  it("keeps absolute dates away from the translator", () => {
+    const { t, calls } = makeCaptureT();
+    const d = ago(45 * DAY);
+    expect(formatRelativeTime(d, t)).toBe(d.toLocaleDateString());
+    expect(calls).toHaveLength(0);
+  });
+});

package/src/utils/format.ts

@@ -37,7 +37,8 @@ export function formatPriceUsd(n: number, currency = "$"): string {
   return `${currency}${n.toFixed(2)}`;
 }
 
-/** Timestamp -> "Just now" / "5m ago" / "3h ago" / "2d ago" / locale date. */
+/** Timestamp -> "Just now" / "5m ago" / "3h ago" / "2d ago" / "2w ago" /
+ *  locale date. */
 export type RelativeTimeT = (
   key: string,
   fallback: string,
@@ -46,7 +47,12 @@ export type RelativeTimeT = (
 
 /** Relative-time formatting ("just now / {n} min ago / …").
  *  Pass an optional translator for localized variants; defaults to
- *  compact English text. */
+ *  compact English text. Tiers: <1min justNow, <60min minutes,
+ *  <24h hours, <7d days, <30d weeks, otherwise an absolute
+ *  locale-rendered date (browser 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). */
 export function formatRelativeTime(
   input: string | number | Date,
   t?: RelativeTimeT,
@@ -54,7 +60,8 @@ export function formatRelativeTime(
   if (!input) return "";
   const d = input instanceof Date ? input : new Date(input);
   if (isNaN(d.getTime())) return "";
-  const diff = Date.now() - d.getTime();
+  // Clamp future timestamps to "just now" — no negative weeks/days.
+  const diff = Math.max(0, Date.now() - d.getTime());
   const mins = Math.floor(diff / 60000);
   const hours = Math.floor(diff / 3600000);
   const days = Math.floor(diff / 86400000);
@@ -62,6 +69,12 @@ export function formatRelativeTime(
   if (mins < 60) return t?.("common.time.minutesAgo", "{n} min ago", { n: mins }) ?? `${mins}m ago`;
   if (hours < 24) return t?.("common.time.hoursAgo", "{n} h ago", { n: hours }) ?? `${hours}h ago`;
   if (days < 7) return t?.("common.time.daysAgo", "{n} d ago", { n: days }) ?? `${days}d ago`;
+  if (days < 30) {
+    const weeks = Math.floor(days / 7);
+    return (
+      t?.("common.time.weeksAgo", "{n} w ago", { n: weeks }) ?? `${weeks}w ago`
+    );
+  }
   return d.toLocaleDateString();
 }