@celestia-island/hikari 0.55.32 → 0.55.34

package/package.json

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

package/src/components/HkBlockingToast.test.tsx

@@ -215,11 +215,19 @@ describe("HkBlockingToast", () => {
     expect(slot).not.toBeNull();
     const wrapper = slot!.parentElement as HTMLElement;
     Object.defineProperty(wrapper, "clientWidth", { value: 384, configurable: true });
+    Object.defineProperty(wrapper, "getBoundingClientRect", {
+      configurable: true,
+      value: () => ({ width: 384, height: 0, top: 0, left: 0 }),
+    });
     Object.defineProperty(slot!, "offsetParent", { value: wrapper, configurable: true });
     Object.defineProperty(slot!, "offsetTop", { value: 0, configurable: true });
     Object.defineProperty(slot!, "offsetLeft", { value: 0, configurable: true });
     Object.defineProperty(slot!, "offsetWidth", { value: 384, configurable: true });
     Object.defineProperty(slot!, "offsetHeight", { value: 120, configurable: true });
+    Object.defineProperty(slot!, "getBoundingClientRect", {
+      configurable: true,
+      value: () => ({ width: 384, height: 120, top: 0, left: 0 }),
+    });
 
     // Dismiss (not confirm): this case only cares about the leave animation.
     cancelButton(cards()[0]).click();
@@ -256,6 +264,10 @@ describe("HkBlockingToast", () => {
       configurable: true,
       get: () => (reflowed() ? 138 : 384),
     });
+    Object.defineProperty(wrapper, "getBoundingClientRect", {
+      configurable: true,
+      value: () => ({ width: reflowed() ? 138 : 384, height: 0, top: 0, left: 0 }),
+    });
     const stub = (
       el: HTMLElement,
       box: { top: number; left: number; width: number; height: number },
@@ -265,6 +277,15 @@ describe("HkBlockingToast", () => {
       Object.defineProperty(el, "offsetLeft", { configurable: true, get: () => (reflowed() ? 0 : box.left) });
       Object.defineProperty(el, "offsetWidth", { configurable: true, get: () => (reflowed() ? 138 : box.width) });
       Object.defineProperty(el, "offsetHeight", { configurable: true, get: () => box.height });
+      Object.defineProperty(el, "getBoundingClientRect", {
+        configurable: true,
+        value: () => ({
+          width: reflowed() ? 138 : box.width,
+          height: box.height,
+          top: 0,
+          left: 0,
+        }),
+      });
     };
     stub(first, { top: 0, left: 0, width: 384, height: 120 });
     stub(second, { top: 132, left: 0, width: 384, height: 120 });

package/src/components/HkBlockingToast.tsx

@@ -118,26 +118,27 @@ export default defineComponent({
     const handles = new Map<number, PopupHandle>();
 
     // Pre-patch geometry of every card, refreshed on each update — same
-    // multi-removal guard as HkToast (see the full rationale there):
-    // within one patch pass an earlier leaving card's position:absolute
-    // re-fits the shrink-to-fit column before a later card's beforeLeave
-    // reads its box, so live offset reads would teleport and squash the
-    // later cards. Snap the right anchor at snapshot time too — the
-    // wrapper's live clientWidth is already re-fit when the pin runs.
+    // multi-removal guard as HkToast (see the full rationale there,
+    // including the getBoundingClientRect choice for sizes: offset*
+    // integer rounding would shrink the pinned card by up to half a
+    // pixel and rewrap its last character). Snap the right anchor at
+    // snapshot time too — the wrapper is already re-fit when the pin
+    // runs.
     const hostRef = ref<{ $el?: Element } | null>(null);
     const preLeaveBoxes = new WeakMap<Element, LeaveBoxSnapshot>();
     onBeforeUpdate(() => {
       const host = hostRef.value?.$el;
       if (host == null || host.nodeType !== 1) return;
-      const parentWidth = (host as HTMLElement).clientWidth;
+      const hostWidth = (host as HTMLElement).getBoundingClientRect().width;
       for (const child of Array.from(host.children)) {
         const e = child as HTMLElement;
+        const rect = e.getBoundingClientRect();
         preLeaveBoxes.set(e, {
           top: e.offsetTop,
           left: e.offsetLeft,
-          width: e.offsetWidth,
-          height: e.offsetHeight,
-          right: parentWidth - (e.offsetLeft + e.offsetWidth),
+          width: rect.width,
+          height: rect.height,
+          right: hostWidth - (e.offsetLeft + rect.width),
         });
       }
     });

package/src/components/HkCrossfade.test.tsx

@@ -252,7 +252,10 @@ describe("HkCrossfade — stylesheet contract", () => {
 
 describe("HkCrossfade — wiring contract", () => {
   const here = dirname(fileURLToPath(import.meta.url));
-  const src = readFileSync(join(here, "HkCrossfade.tsx"), "utf-8");
+  // Windows checkouts (core.autocrlf) hand the working tree CRLF sources;
+  // normalize before text-pinning so the contract is EOL-agnostic instead
+  // of green-on-CI / red-on-Windows.
+  const src = readFileSync(join(here, "HkCrossfade.tsx"), "utf-8").replace(/\r\n?/g, "\n");
 
   it("runs the Transition in default (simultaneous) mode and never overrides its duration", () => {
     expect(src).toContain('<Transition\n            name="hk-crossfade"');

package/src/components/HkMenu.test.ts

@@ -877,6 +877,145 @@ describe("HkMenu sidebar variant", () => {
   });
 });
 
+describe("HkMenu sidebar defaultExpandGroups", () => {
+  /** Two INDEPENDENT groups, no active row anywhere — the shape where
+   *  accordion mode keeps everything closed and table-of-contents mode
+   *  must open everything. */
+  const groupedItems: HkMenuItem[] = [
+    { key: "g1", label: "Group One", children: [{ key: "g1-a", label: "One A" }] },
+    { key: "g2", label: "Group Two", children: [{ key: "g2-a", label: "Two A" }] },
+  ];
+
+  function mountSidebar(
+    items: HkMenuItem[],
+    props: Record<string, unknown> = {},
+  ): HTMLElement {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const app = createApp({
+      render: () => h(HkMenu, { variant: "sidebar", open: true, items, ...props }),
+    });
+    mounts.push(app);
+    app.mount(container);
+    return container;
+  }
+
+  const toggleOf = (root: HTMLElement, label: string): HTMLButtonElement =>
+    Array.from(root.querySelectorAll(".hk-menu-sidebar-group-toggle")).find(
+      (r) => r.textContent?.includes(label),
+    ) as HTMLButtonElement;
+
+  it("keeps the accordion default when the prop is absent (additive no-op)", () => {
+    // Pinned at the DOM level: with no prop the group carries no open
+    // marker and its children stay unrendered — every existing consumer
+    // (drawer account menus, nav sidebars) is untouched.
+    const root = mountSidebar(groupedItems);
+    expect(root.textContent).not.toContain("One A");
+    expect(root.textContent).not.toContain("Two A");
+    expect(root.querySelector(".hk-menu-sidebar-group[data-open]")).toBeNull();
+  });
+
+  it("renders every group expanded at mount, active row or not", () => {
+    const root = mountSidebar(groupedItems, { defaultExpandGroups: true });
+    expect(root.textContent).toContain("One A");
+    expect(root.textContent).toContain("Two A");
+    expect(root.querySelectorAll(".hk-menu-sidebar-group[data-open]")).toHaveLength(2);
+    // The toggle rows' a11y state agrees with the rendered children.
+    for (const toggle of root.querySelectorAll(".hk-menu-sidebar-group-toggle")) {
+      expect(toggle.getAttribute("aria-expanded")).toBe("true");
+    }
+  });
+
+  it("a user collapse sticks across navigation — no auto-resurrection", async () => {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+    const activeKey = ref("none");
+    const app = createApp({
+      render: () =>
+        h(HkMenu, {
+          variant: "sidebar",
+          open: true,
+          items: groupedItems,
+          activeKey: activeKey.value,
+          defaultExpandGroups: true,
+        }),
+    });
+    mounts.push(app);
+    app.mount(container);
+    await settle();
+
+    // First toggle COLLAPSES (open is the default state here).
+    toggleOf(container, "Group One").click();
+    await settle();
+    expect(container.textContent).not.toContain("One A");
+    // The sibling keeps its default-open state.
+    expect(container.textContent).toContain("Two A");
+
+    // Navigating INTO the collapsed group must not resurrect it: the
+    // user's collapse is the user's word (the auto-expand watch fires on
+    // activeKey changes and must stay inert in this mode).
+    activeKey.value = "g1-a";
+    await settle();
+    expect(container.textContent).not.toContain("One A");
+
+    // Re-expanding works, lands the active row, and stays open.
+    toggleOf(container, "Group One").click();
+    await settle();
+    expect(container.textContent).toContain("One A");
+    const active = container.querySelector(".hk-menu-sidebar-row[data-active]");
+    expect(active?.textContent).toContain("One A");
+  });
+
+  it("collapsing one group never touches its siblings' default-open state", async () => {
+    const root = mountSidebar(groupedItems, { defaultExpandGroups: true });
+    await settle();
+    toggleOf(root, "Group Two").click();
+    await settle();
+    expect(root.textContent).toContain("One A");
+    expect(root.textContent).not.toContain("Two A");
+    expect(toggleOf(root, "Group One").getAttribute("aria-expanded")).toBe("true");
+  });
+
+  it("expands nested groups too, and a parent round-trip restores the still-open inner group", async () => {
+    const root = mountSidebar(
+      [
+        {
+          key: "outer",
+          label: "Outer",
+          children: [
+            {
+              key: "inner",
+              label: "Inner",
+              children: [{ key: "leaf", label: "Deep Leaf" }],
+            },
+          ],
+        },
+      ],
+      { defaultExpandGroups: true },
+    );
+    await settle();
+
+    // Both levels render expanded at mount (depth > 1 included).
+    expect(root.textContent).toContain("Deep Leaf");
+    expect(root.querySelectorAll(".hk-menu-sidebar-group[data-open]")).toHaveLength(2);
+
+    // Collapse the parent: the whole subtree unmounts…
+    toggleOf(root, "Outer").click();
+    await settle();
+    expect(root.textContent).not.toContain("Deep Leaf");
+    expect(root.querySelectorAll(".hk-menu-sidebar-group[data-open]")).toHaveLength(0);
+
+    // …and re-expanding restores the inner group still open — its state
+    // lived in the key sets, so no re-toggle of "Inner" is needed.
+    toggleOf(root, "Outer").click();
+    await settle();
+    expect(root.textContent).toContain("Deep Leaf");
+    expect(root.querySelectorAll(".hk-menu-sidebar-group[data-open]")).toHaveLength(2);
+  });
+});
+
 describe("HkMenu close linger (leave-transition window)", () => {
   it("keeps the panel tree mounted briefly after close, then unmounts", async () => {
     const openRef = ref(true);

package/src/components/HkMenu.tsx

@@ -156,6 +156,16 @@ export default defineComponent({
      * length, applied on the `dvh`-capable branch, never sanitized.
      */
     maxHeight: { type: String, default: undefined },
+    /**
+     * Sidebar variant only: every collapsible group renders EXPANDED
+     * until the user collapses it — nav sidebars that read as a table of
+     * contents instead of an accordion. Default false keeps the accordion
+     * behavior (only the group holding the active row auto-opens). The
+     * user's first toggle on a group still takes over and sticks:
+     * expansion is the default, never a resurrection. No-op in the
+     * popup variant (sub-levels there are cascades, not inline groups).
+     */
+    defaultExpandGroups: { type: Boolean, default: false },
   },
   emits: ["update:open", "select"],
   setup(props, { emit, slots }) {
@@ -696,6 +706,10 @@ export default defineComponent({
     const userCollapsed = ref<Set<string>>(new Set());
 
     function isGroupExpanded(key: string): boolean {
+      // Table-of-contents mode (defaultExpandGroups): open IS the default
+      // state — only an explicit user collapse closes a group, and it
+      // stays closed (no auto-resurrection on activeKey/items changes).
+      if (props.defaultExpandGroups) return !userCollapsed.value.has(key);
       if (userGroups.value.has(key)) return true;
       if (autoGroups.value.has(key)) return !userCollapsed.value.has(key);
       return false;
@@ -779,8 +793,10 @@ export default defineComponent({
 
     function renderSidebarItem(item: HkMenuItem, depth: number) {
       if (!isGroup(item)) return renderSidebarRow(item, depth);
-      // Auto-expanded when containing the active row (fresh mount shows
-      // where you are); the user's first toggle on a group takes over.
+      // Accordion mode: auto-expanded when containing the active row
+      // (fresh mount shows where you are). defaultExpandGroups mode:
+      // everything starts open instead. Either way the user's first
+      // toggle on a group takes over and sticks.
       const expanded = isGroupExpanded(item.key);
       return (
         <div key={item.key} class="hk-menu-sidebar-group" data-open={expanded || undefined}>

package/src/components/HkToast.test.tsx

@@ -16,6 +16,10 @@ import { useToast } from "../runtime/useToast";
  *   same patch pass, so live offset reads in a later sibling's
  *   before-leave hook would teleport it onto the reflowed slot and
  *   squash its bar (HkListTransition's pre-patch snapshot pattern)
+ * - the pin reproduces the box EXACTLY (getBoundingClientRect sizes):
+ *   offsetWidth/Height round to integers, and pinning a round-down
+ *   integer shrank the box by the sub-pixel gap — enough to push a
+ *   last character onto a second line the instant the leave started
  * - the toast is gone after the leave settles
  *
  * (Repo test convention: raw createApp + document queries, no
@@ -48,16 +52,30 @@ function stubLayout(el: HTMLElement, over: Partial<{
   offsetLeft: number;
   offsetWidth: number;
   offsetHeight: number;
+  /** getBoundingClientRect width — the exact fractional box the pin
+   *  must reproduce (offsetWidth is its integer rounding). */
+  rectWidth: number;
+  rectHeight: number;
 }>): void {
   // happy-dom has no layout engine; feed the leave hook the geometry a
   // real browser would read from the laid-out stack.
   const wrapper = el.parentElement as HTMLElement;
+  const rectWidth = over.rectWidth ?? over.offsetWidth ?? 384;
+  const rectHeight = over.rectHeight ?? over.offsetHeight ?? 83;
   Object.defineProperty(wrapper, "clientWidth", { value: 384, configurable: true });
+  Object.defineProperty(wrapper, "getBoundingClientRect", {
+    configurable: true,
+    value: () => ({ width: rectWidth, height: 0, top: 0, left: 0 }),
+  });
   Object.defineProperty(el, "offsetParent", { value: wrapper, configurable: true });
   Object.defineProperty(el, "offsetTop", { value: over.offsetTop ?? 0, configurable: true });
   Object.defineProperty(el, "offsetLeft", { value: over.offsetLeft ?? 0, configurable: true });
   Object.defineProperty(el, "offsetWidth", { value: over.offsetWidth ?? 384, configurable: true });
   Object.defineProperty(el, "offsetHeight", { value: over.offsetHeight ?? 83, configurable: true });
+  Object.defineProperty(el, "getBoundingClientRect", {
+    configurable: true,
+    value: () => ({ width: rectWidth, height: rectHeight, top: 0, left: 0 }),
+  });
 }
 
 afterEach(async () => {
@@ -132,6 +150,10 @@ describe("HkToast", () => {
       configurable: true,
       get: () => (reflowed() ? 138 : 384),
     });
+    Object.defineProperty(wrapper, "getBoundingClientRect", {
+      configurable: true,
+      value: () => ({ width: reflowed() ? 138 : 384, height: 0, top: 0, left: 0 }),
+    });
     const stub = (
       el: HTMLElement,
       pre: { top: number; left: number; width: number; height: number },
@@ -145,6 +167,15 @@ describe("HkToast", () => {
           get: () => (reflowed() ? post[short] : pre[short]),
         });
       }
+      Object.defineProperty(el, "getBoundingClientRect", {
+        configurable: true,
+        value: () => ({
+          width: reflowed() ? post.width : pre.width,
+          height: reflowed() ? post.height : pre.height,
+          top: 0,
+          left: 0,
+        }),
+      });
     };
     stub(first, { top: 0, left: 0, width: 384, height: 83 }, { top: 0, left: 0, width: 384, height: 83 });
     stub(second, { top: 95, left: 0, width: 384, height: 48 }, { top: 0, left: 0, width: 138, height: 48 });
@@ -170,4 +201,37 @@ describe("HkToast", () => {
     await settle();
     expect(items().length).toBe(0);
   });
+
+  it("pins the exact fractional box so the rounding gap cannot rewrap the text", async () => {
+    mountHost();
+    const toast = useToast();
+    toast.error("message whose single line sits within a half pixel of the boundary");
+    await settle();
+
+    const item = items()[0];
+    // offsetWidth rounds the real box DOWN (369.40625 → 369): pinning
+    // that integer shrank the box by the rounding gap, which pushed the
+    // last character to a second line the moment the leave started. The
+    // pin must reproduce the exact fractional box instead.
+    stubLayout(item, {
+      offsetTop: 0,
+      offsetLeft: 0,
+      offsetWidth: 369,
+      offsetHeight: 83,
+      rectWidth: 369.40625,
+      rectHeight: 83,
+    });
+
+    item.querySelector<HTMLButtonElement>(".hk-toast-close")!.click();
+    await nextTick();
+
+    const leaving = document.querySelector<HTMLElement>(".hk-toast-leave-active");
+    expect(leaving).not.toBeNull();
+    expect(leaving!.style.width).toBe("369.40625px");
+    expect(leaving!.style.right).toBe("0px");
+    expect(leaving!.style.height).toBe("83px");
+
+    await settle();
+    expect(items().length).toBe(0);
+  });
 });

package/src/components/HkToast.tsx

@@ -185,20 +185,33 @@ export default defineComponent({
     // texts read as one squashed multi-line blob. The wrapper itself may
     // also have re-fit when the pin runs, so the right anchor is snapped
     // at snapshot time too (see LeaveBoxSnapshot.right).
+    //
+    // Sizes come from getBoundingClientRect, NOT the offset* family:
+    // offsetWidth/Height round to integers, and the pinned box shrinks
+    // whenever the real box rounds down — a toast whose text sits within
+    // that sub-pixel distance of the wrap boundary loses its last
+    // character to the next line the instant the leave pins it. Rect
+    // width/height are exact and translation-invariant (enter/move only
+    // ever translate these surfaces, and translation does not change a
+    // box's size), so the pin reproduces the visible box to the pixel.
+    // Positions stay on offsetTop/offsetLeft — the transform-immune
+    // layout slot, where the ±0.5px integer error is invisible.
     const hostRef = ref<{ $el?: Element } | null>(null);
     const preLeaveBoxes = new WeakMap<Element, LeaveBoxSnapshot>();
     onBeforeUpdate(() => {
       const host = hostRef.value?.$el;
       if (host == null || host.nodeType !== 1) return;
-      const parentWidth = (host as HTMLElement).clientWidth;
+      const hostEl = host as HTMLElement;
+      const hostWidth = hostEl.getBoundingClientRect().width;
       for (const child of Array.from(host.children)) {
         const e = child as HTMLElement;
+        const rect = e.getBoundingClientRect();
         preLeaveBoxes.set(e, {
           top: e.offsetTop,
           left: e.offsetLeft,
-          width: e.offsetWidth,
-          height: e.offsetHeight,
-          right: parentWidth - (e.offsetLeft + e.offsetWidth),
+          width: rect.width,
+          height: rect.height,
+          right: hostWidth - (e.offsetLeft + rect.width),
         });
       }
     });

package/src/i18n/usageSurface.test.ts

@@ -24,6 +24,13 @@ import { describe, expect, it } from "vitest";
  * belong to the HOST-app namespace (registered at runtime via
  * mergeMessages, or passed in as props.t) and are pinned by their own
  * suites (timeKeys.test.ts & co.) — out of scope here by construction.
+ *
+ * Interpolated keys cannot be pinned by literal, so their CONSTRUCTION
+ * SITES are scanned wherever the backtick template appears — adjacency to
+ * t() is NOT required (F1: HkStatusBar.tsx:233 builds the key into a
+ * variable first) — and each discovered family is whitelisted and, when
+ * its enum is closed inside hikari, pinned key-by-key (see
+ * CONSTRUCTED_FAMILY_KEYS).
  */
 const modules = import.meta.glob<{ default: Record<string, unknown> }>(
   "./locales/*/*.json",
@@ -75,18 +82,23 @@ function walkSources(dir: string, acc: string[] = []): string[] {
  *  `t(` and the key; the character class covers ", ', and ` so a template
  *  literal WITHOUT interpolation is still a pinned literal. */
 const STATIC_USE_RE = /\bt\(\s*(["'`])hikari::[A-Za-z0-9_.]+\1/g;
-/** Dynamic families: a template key with `${…}` interpolation can never be
- *  resolved statically — they are enumerated in DYNAMIC_KEY_FAMILIES. */
-const DYNAMIC_USE_RE = /\bt\(\s*`hikari::[A-Za-z0-9_.]*\$\{/g;
+/** Constructed key families: a template key with `${…}` interpolation can
+ *  never be resolved statically — they are enumerated in
+ *  DYNAMIC_KEY_FAMILIES. The regex matches the template construction
+ *  ANYWHERE in source, NOT only adjacent to `t(`: F1 (verify-hk603,
+ *  2026-09-19) — HkStatusBar.tsx builds `hikari::statusBar.tier.${tier}`
+ *  into a variable and only calls t(tierLabelKey) 135 lines later, so the
+ *  old adjacency-only regex never saw the family at all. */
+const CONSTRUCTED_KEY_RE = /`hikari::[A-Za-z0-9_.]*\$\{/g;
 
 interface Site {
   key: string;
   where: string;
 }
 
-function scanSources(): { statics: Site[]; dynamics: string[] } {
+function scanSources(): { statics: Site[]; constructed: Site[] } {
   const statics: Site[] = [];
-  const dynamics: string[] = [];
+  const constructed: Site[] = [];
   for (const path of walkSources(SRC_ROOT)) {
     const text = readFileSync(path, "utf8");
     const rel = path.slice(SRC_ROOT.length + 1);
@@ -94,13 +106,14 @@ function scanSources(): { statics: Site[]; dynamics: string[] } {
       const key = match[0].slice(match[0].indexOf("hikari::"), -1);
       statics.push({ key, where: `${rel}:${text.slice(0, match.index).split("\n").length}` });
     }
-    for (const match of text.matchAll(DYNAMIC_USE_RE)) {
+    for (const match of text.matchAll(CONSTRUCTED_KEY_RE)) {
       // The literal portion before "${" — e.g. "hikari::context." — which
       // is the family prefix the whitelist is keyed by.
-      dynamics.push(match[0].slice(match[0].indexOf("hikari::"), -2));
+      const family = match[0].slice(1, -2);
+      constructed.push({ key: family, where: `${rel}:${text.slice(0, match.index).split("\n").length}` });
     }
   }
-  return { statics, dynamics };
+  return { statics, constructed };
 }
 
 /** Interpolated key families that intentionally escape the static scan,
@@ -112,13 +125,25 @@ const DYNAMIC_KEY_FAMILIES: Record<string, string> = {
   "hikari::context.": "HkContextRing section keys — closed enum, pinned by name in contextKeys.test.ts.",
   "hikari::statusBar.backend.": "HkConnectionStatus — enumerated connection-state suffixes.",
   "hikari::statusBar.region.": "HkStatusBar region names — OPTIONAL per-locale overrides over Intl.DisplayNames (see LOCALE_SPECIFIC_NESTED in flatKeyParity.test.ts).",
+  "hikari::statusBar.tier.": "HkStatusBar transport tiers — constructed into a variable at a distance from its t() call (F1); the four concrete ids are pinned by name in CONSTRUCTED_FAMILY_KEYS below.",
   "hikari::theme.groups.": "Registry type: group/slot ids are registered by downstream apps; t() resolves via a resolveLocalizedText fallback, never a hikari bundle.",
   "hikari::theme.tokens.": "HkColorSchemeEditor token enum — closed set defined in platform.json locales.",
 };
 
+/** Concrete suffixes each constructed family resolves to, for families whose
+ *  enum is closed INSIDE hikari (the whitelist reason records which). Each
+ *  listed key is asserted to exist, non-empty, in every locale — that is
+ *  the tooth the adjacency regex lacked: deleting the whole family from
+ *  every bundle used to leave every audit pin green (F1 blind spot).
+ *  Families resolved by downstream apps (theme.groups.) or optional
+ *  per-locale overrides (statusBar.region.) deliberately stay out. */
+const CONSTRUCTED_FAMILY_KEYS: Record<string, string[]> = {
+  "hikari::statusBar.tier.": ["local", "poll", "sse", "ws"],
+};
+
 describe("t() usage surface vs locale bundles", () => {
   const universes = new Map(EXPECTED_LOCALES.map((l) => [l, buildLocaleUniverse(l)]));
-  const { statics, dynamics } = scanSources();
+  const { statics, constructed } = scanSources();
 
   it("covers all 11 locales in the merged bundle universe", () => {
     const found = new Set(
@@ -144,6 +169,11 @@ describe("t() usage surface vs locale bundles", () => {
     expect(firstSiteOf("hikari::filePicker.currentPath")).toMatch(/HkFileBrowserDialog\.tsx/);
     // Split-across-lines call form (t( and the key on different lines):
     expect(firstSiteOf("hikari::phoneInput.searchCountries")).toMatch(/HkPhoneInput\.tsx/);
+    // Constructed-key scan positive (F1): the tier template is built into a
+    // variable 135 lines away from its t() call — the scan must still see it.
+    expect(
+      constructed.find((s) => s.key === "hikari::statusBar.tier.")?.where ?? "NOT FOUND",
+    ).toMatch(/HkStatusBar\.tsx/);
   });
 
   it("resolves every statically referenced hikari:: key in every locale, non-empty", () => {
@@ -165,13 +195,36 @@ describe("t() usage surface vs locale bundles", () => {
     expect(violations, "every referenced key must resolve in all 11 locales").toEqual([]);
   });
 
-  it("enumerates exactly the whitelisted dynamic key families, both directions", () => {
-    const found = [...new Set(dynamics)].sort();
-    expect(found, "families found in source but missing from the whitelist").toEqual(
+  it("enumerates exactly the whitelisted constructed key families, both directions", () => {
+    const found = [...new Set(constructed.map((s) => s.key))].sort();
+    expect(found, "families constructed in source but missing from the whitelist").toEqual(
       Object.keys(DYNAMIC_KEY_FAMILIES).sort(),
     );
     for (const family of Object.keys(DYNAMIC_KEY_FAMILIES)) {
-      expect(found, `${family} is whitelisted but no longer used — prune it`).toContain(family);
+      expect(found, `${family} is whitelisted but no longer constructed — prune it`).toContain(family);
+    }
+  });
+
+  it("resolves every named concrete key of the constructed families in every locale", () => {
+    const violations: string[] = [];
+    for (const [family, suffixes] of Object.entries(CONSTRUCTED_FAMILY_KEYS)) {
+      expect(
+        DYNAMIC_KEY_FAMILIES[family],
+        `${family} carries named keys but has no whitelist entry`,
+      ).toBeDefined();
+      for (const suffix of suffixes) {
+        const key = family + suffix;
+        for (const locale of EXPECTED_LOCALES) {
+          const value = universes.get(locale)!.get(key);
+          if (typeof value !== "string" || value.length === 0) {
+            violations.push(`${key} is missing or empty in ${locale}`);
+          }
+        }
+      }
     }
+    expect(
+      violations,
+      "constructed families' concrete keys must resolve in all 11 locales",
+    ).toEqual([]);
   });
 });