@celestia-island/hikari 0.55.272 → 0.55.273

package/package.json

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

package/src/components/HkCardList.rowactions-touch.test.tsx

@@ -0,0 +1,77 @@
+import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { createApp, h, nextTick } from "vue";
+
+import { HkCardList, HkListRow } from "./HkCardList";
+
+/**
+ * Touch-first clients never get hover tooltips, so the option-control
+ * array swaps its inline icon lane for ONE trigger that opens the same
+ * actions as a named menu. The media query is stubbed here (this file
+ * runs in its own module graph — vitest isolates test files — so the
+ * shared useMediaQuery registry sees the touch-first answer).
+ */
+
+beforeAll(() => {
+  vi.spyOn(window, "matchMedia").mockImplementation(
+    (query: string): MediaQueryList => ({
+      matches: query.includes("hover: none") || query.includes("pointer: coarse"),
+      media: query,
+      onchange: null,
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      addListener: () => {},
+      removeListener: () => {},
+      dispatchEvent: () => false,
+    }),
+  );
+});
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+afterEach(() => {
+  while (mounts.length) {
+    const { app, container } = mounts.pop()!;
+    app.unmount();
+    container.remove();
+  }
+});
+
+const icon = { render: () => null };
+
+it("swaps the inline lane for a named upward menu trigger", async () => {
+  const picks: string[] = [];
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({
+    render: () =>
+      h(HkCardList, null, {
+        default: () => [
+          h(HkListRow, {
+            title: "row",
+            actionsLabel: "row actions",
+            actionsMenuLabel: "more actions",
+            actions: [
+              { name: "reinstall", icon, onSelect: () => picks.push("reinstall") },
+              { name: "uninstall", danger: true, onSelect: () => picks.push("uninstall") },
+            ],
+          }),
+        ],
+      }),
+  });
+  mounts.push({ app, container });
+  app.mount(container);
+
+  const lane = container.querySelector(".hk-list-row-actions") as HTMLElement;
+  expect(lane.classList.contains("hk-list-row-actions--touch")).toBe(true);
+  // No inline icon buttons — the names live in the menu on this client.
+  expect(lane.querySelector(".hk-list-row-actions__btn")).toBeNull();
+  const trigger = lane.querySelector(".hk-list-row-actions__trigger") as HTMLButtonElement;
+  expect(trigger).toBeTruthy();
+  expect(trigger.getAttribute("aria-haspopup")).toBe("menu");
+  expect(trigger.getAttribute("aria-label")).toBe("more actions");
+  expect(trigger.getAttribute("aria-expanded")).toBe("false");
+
+  trigger.click();
+  await nextTick();
+  expect(trigger.getAttribute("aria-expanded")).toBe("true");
+});

package/src/components/HkCardList.rowactions.test.tsx

@@ -0,0 +1,148 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h, nextTick, type Component } from "vue";
+
+import { HkCardList, HkListRow, hkListRowMenuItems, type HkListRowAction } from "./HkCardList";
+
+/**
+ * HkListRow's option-control array contract (pointer-client half):
+ *
+ * - persistent mode keeps the lane in the flow, one aria-labelled icon
+ *   button per action;
+ * - overlay mode (the default) parks the lane out of the flow and only
+ *   the touch reveal flips [data-revealed] (pointer devices reveal via
+ *   CSS :hover/:focus-within, which happy-dom cannot exercise);
+ * - every action's NAME is its accessible identity — the aria-label and
+ *   the menu model label (desktop tooltip / touch menu row);
+ * - the menu model maps the declared actions one-to-one.
+ *
+ * (Repo test convention: raw createApp + document queries; happy-dom
+ * has no layout engine.)
+ */
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+afterEach(() => {
+  while (mounts.length) {
+    const { app, container } = mounts.pop()!;
+    app.unmount();
+    container.remove();
+  }
+});
+
+function mount(render: () => ReturnType<typeof h>): HTMLElement {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render });
+  mounts.push({ app, container });
+  app.mount(container);
+  return container;
+}
+
+function actionsOf(selects: Array<() => void>, over: Partial<HkListRowAction> = {}): HkListRowAction[] {
+  return selects.map((onSelect, i) => ({ name: "action " + (i + 1), onSelect, ...over }));
+}
+
+/** pointerType cannot ride the Event constructor in every engine —
+ *  inject it on a plain bubbling event. */
+function pointerDown(target: EventTarget, pointerType: string): void {
+  const ev = new Event("pointerdown", { bubbles: true, cancelable: true });
+  Object.defineProperty(ev, "pointerType", { value: pointerType });
+  target.dispatchEvent(ev);
+}
+
+function mountRow(props: Record<string, unknown>, trailing?: () => unknown): HTMLElement {
+  return mount(() =>
+    h(HkCardList, null, {
+      default: () => [
+        h(HkListRow, { title: "row", ...props }, trailing ? { trailing } : undefined),
+      ],
+    }),
+  );
+}
+
+describe("HkListRow actions — persistent mode", () => {
+  it("renders one named button per action and reports selection", () => {
+    const picks: string[] = [];
+    const container = mountRow({
+      actions: [
+        { name: "reinstall", onSelect: () => picks.push("reinstall"), icon: { render: () => null } as Component },
+        { name: "uninstall", onSelect: () => picks.push("uninstall"), danger: true },
+        { name: "disabled one", onSelect: () => picks.push("no"), disabled: true },
+      ],
+      actionsMode: "persistent",
+      actionsLabel: "row actions",
+    });
+    const lane = container.querySelector(".hk-list-row-actions") as HTMLElement;
+    expect(lane).toBeTruthy();
+    expect(lane.classList.contains("hk-list-row-actions--persistent")).toBe(true);
+    expect(lane.getAttribute("role")).toBe("toolbar");
+    expect(lane.getAttribute("aria-label")).toBe("row actions");
+    const buttons = Array.from(lane.querySelectorAll<HTMLButtonElement>(".hk-list-row-actions__btn"));
+    expect(buttons.map((b) => b.getAttribute("aria-label"))).toEqual([
+      "reinstall",
+      "uninstall",
+      "disabled one",
+    ]);
+    expect(buttons[1].hasAttribute("data-danger")).toBe(true);
+    expect(buttons[2].disabled).toBe(true);
+    buttons[0].click();
+    buttons[1].click();
+    buttons[2].click();
+    expect(picks).toEqual(["reinstall", "uninstall"]);
+  });
+});
+
+describe("HkListRow actions — overlay mode", () => {
+  it("parks the lane out of the flow until a non-mouse pointer engages it", async () => {
+    const container = mountRow({
+      actions: actionsOf([() => {}]),
+      actionsMode: "overlay",
+    });
+    const lane = () => container.querySelector(".hk-list-row-actions") as HTMLElement;
+    expect(lane().classList.contains("hk-list-row-actions--overlay")).toBe(true);
+    expect(lane().getAttribute("data-revealed")).toBeNull();
+    const row = container.querySelector(".hk-list-row") as HTMLElement;
+
+    // Mouse presses never reveal — pointer devices reveal through CSS
+    // :hover/:focus-within, so the JS path stays silent for them.
+    pointerDown(row, "mouse");
+    await nextTick();
+    expect(lane().getAttribute("data-revealed")).toBeNull();
+
+    // A touch tap inside the row reveals the lane…
+    pointerDown(row, "touch");
+    await nextTick();
+    expect(lane().getAttribute("data-revealed")).not.toBeNull();
+
+    // …and a tap anywhere else dismisses it again.
+    pointerDown(document.body, "touch");
+    await nextTick();
+    expect(lane().getAttribute("data-revealed")).toBeNull();
+  });
+
+  it("keeps the overlay lane focusable for keyboard users", () => {
+    // Hiding is opacity/pointer-events only: visibility:hidden would
+    // drop the buttons out of the tab order and strand keyboard users.
+    const container = mountRow({
+      actions: actionsOf([() => {}]),
+      actionsMode: "overlay",
+    });
+    const btn = container.querySelector(".hk-list-row-actions__btn") as HTMLButtonElement;
+    expect(btn).toBeTruthy();
+    expect(btn.disabled).toBe(false);
+  });
+});
+
+describe("hkListRowMenuItems", () => {
+  it("maps every declared action onto its menu row, keyed by name", () => {
+    const icon = { render: () => null } as Component;
+    const items = hkListRowMenuItems([
+      { name: "reinstall", onSelect: () => {}, icon },
+      { name: "uninstall", onSelect: () => {}, danger: true, disabled: true },
+    ]);
+    expect(items).toEqual([
+      { key: "reinstall", label: "reinstall", icon, danger: undefined, disabled: undefined },
+      { key: "uninstall", label: "uninstall", icon: undefined, danger: true, disabled: true },
+    ]);
+  });
+});

package/src/components/HkCardList.scss

@@ -66,3 +66,106 @@
   align-items: center;
   gap: var(--space-8, 0.5rem);
 }
+
+/* ── Option-control array (HkListRow's `actions`) ───────────────────────
+ * The row's last lane: named icon buttons in one of two layouts (see
+ * HkListRowActionsMode). "persistent" keeps the lane in the flow — it
+ * costs the row its width and stays visible. "overlay" (the default)
+ * parks the lane OUT of the flow: pinned to the row's right edge,
+ * invisible and inert until engaged — hover / keyboard focus on pointer
+ * devices (CSS below), tap on touch (the [data-revealed] state) — and
+ * then temporarily covers the trailing content, so a dense list never
+ * pays for actions it is not using. Touch-first clients swap the lane
+ * for one trigger that opens the same actions as a named, upward menu
+ * (tooltips never fire there, so names must live in the menu). */
+.hk-list-row {
+  position: relative;
+}
+
+.hk-list-row-actions {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-4, 0.25rem);
+  flex-shrink: 0;
+
+  /* In the flow (persistent + touch): pin to the right edge when the
+     row carries no trailing slot of its own. */
+  &--persistent,
+  &--touch {
+    margin-left: auto;
+  }
+
+  /* Parked overlay: absolute over the row's right content. Kept
+     focusable for keyboard users — opacity alone hides it visually
+     while :focus-within reveals it (visibility:hidden would drop it
+     out of the tab order entirely). */
+  &--overlay {
+    position: absolute;
+    right: var(--space-8, 0.5rem);
+    top: 50%;
+    transform: translateY(-50%);
+    padding: 0.125rem;
+    border-radius: var(--radius-sm, 0.375rem);
+    background: rgb(var(--color-surface, 255 255 255));
+    box-shadow: 0 2px 10px rgb(var(--color-border, 100 100 100) / 22%);
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity var(--duration-fast, 0.15s) ease;
+  }
+
+  &--overlay[data-revealed],
+  &--overlay:focus-within {
+    opacity: 1;
+    pointer-events: auto;
+  }
+}
+
+/* Pointer devices: hovering the row reveals the parked overlay. */
+@media (hover: hover) {
+  .hk-list-row:hover > .hk-list-row-actions--overlay {
+    opacity: 1;
+    pointer-events: auto;
+  }
+}
+
+.hk-list-row-actions__btn,
+.hk-list-row-actions__trigger {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.625rem;
+  height: 1.625rem;
+  padding: 0;
+  border: 1px solid transparent;
+  border-radius: var(--radius-xs, 0.25rem);
+  background: transparent;
+  color: rgb(var(--color-muted, 108 108 108));
+  cursor: pointer;
+  transition:
+    background-color var(--duration-fast, 0.15s) ease,
+    color var(--duration-fast, 0.15s) ease;
+
+  &:hover:not(:disabled) {
+    background: rgb(var(--color-text, 30 30 30) / 6%);
+    color: rgb(var(--color-text, 30 30 30));
+  }
+
+  &:focus-visible {
+    outline: 2px solid rgb(var(--color-primary, 122 162 247));
+    outline-offset: -2px;
+  }
+
+  &:disabled {
+    opacity: 0.45;
+    cursor: default;
+  }
+
+  &[data-danger] {
+    color: rgb(var(--color-error, 247 118 142) / 90%);
+
+    &:hover:not(:disabled) {
+      background: rgb(var(--color-error, 247 118 142) / 10%);
+      color: rgb(var(--color-error, 247 118 142));
+    }
+  }
+}

package/src/components/HkCardList.tsx

@@ -1,7 +1,12 @@
-import { Comment, defineComponent, type Component, type PropType, type VNode } from "vue";
+import { Comment, computed, defineComponent, h, onBeforeUnmount, onMounted, ref, type Component, type PropType, type VNode } from "vue";
+import { MoreHorizontal } from "lucide-vue-next";
 
 import HkCard from "./HkCard";
 import { HkIconChip } from "./HkIconChip";
+import HkMenu from "./HkMenu";
+import type { HkMenuItem } from "./HkMenu";
+import HkTooltip from "./HkTooltip";
+import { useMediaQuery } from "../runtime/useMediaQuery";
 import type { StatTone } from "./HkStatCard";
 import "./HkCardList.scss";
 
@@ -57,6 +62,39 @@ export const HkCardList = defineComponent({
   },
 });
 
+/** One named action of an HkListRow's option-control array (the
+ *  `actions` prop). `name` is REQUIRED: it is the button's accessible
+ *  name and its only visible identity — the pointer tooltip's text on
+ *  hover devices, and the touch/narrow menu's row label where tooltips
+ *  never fire. */
+export interface HkListRowAction {
+  name: string;
+  icon?: Component;
+  danger?: boolean;
+  disabled?: boolean;
+  onSelect: () => void;
+}
+
+/** The option-control array's layout contract (see `actionsMode`):
+ *  "overlay" — the array costs the row no width; it stays hidden until
+ *  engaged (hover / keyboard focus on pointer devices, tap on touch)
+ *  and then temporarily covers the row's right content. "persistent" —
+ *  the array takes the last column and stays visible. */
+export type HkListRowActionsMode = "overlay" | "persistent";
+
+/** The touch trigger's menu model: one HkMenuItem per named action.
+ *  Keys are the action NAMES (unique per row by contract), so the
+ *  menu's select payload maps straight back onto `onSelect`. */
+export function hkListRowMenuItems(actions: readonly HkListRowAction[]): HkMenuItem[] {
+  return actions.map((a) => ({
+    key: a.name,
+    label: a.name,
+    icon: a.icon,
+    danger: a.danger,
+    disabled: a.disabled,
+  }));
+}
+
 /**
  * HkListRow — one entry of an HkCardList: an optional tone-tinted icon
  * chip, a main column (title / subtitle / free-form default slot), and a
@@ -76,11 +114,48 @@ export const HkListRow = defineComponent({
     subtitle: { type: String, default: undefined },
     /** Whole-row click (drill-through). */
     clickable: { type: Boolean, default: false },
+    /** The row's option-control array: named icon actions rendered as
+     *  the row's last lane. Omit for rows without row-level actions. */
+    actions: { type: Array as PropType<HkListRowAction[]>, default: undefined },
+    /** See HkListRowActionsMode. Default "overlay": the array is parked
+     *  out of the flow and only covers the right content while engaged. */
+    actionsMode: { type: String as PropType<HkListRowActionsMode>, default: "overlay" },
+    /** Accessible name of the action lane (role="toolbar"). */
+    actionsLabel: { type: String, default: undefined },
+    /** Accessible name / menu title of the touch trigger. Falls back to
+     *  `actionsLabel`. */
+    actionsMenuLabel: { type: String, default: undefined },
   },
   emits: { click: (_e: MouseEvent | KeyboardEvent) => true },
   setup(props, { emit, slots }) {
+    // Touch-first clients get the named menu (tooltips never fire there);
+    // pointer clients get the inline icon lane whose names ride tooltips.
+    const touchFirst = useMediaQuery("(hover: none), (pointer: coarse)");
+    /** Touch-driven overlay reveal. Pointer devices reveal through CSS
+     *  :hover/:focus-within — the common path stays declarative. */
+    const revealed = ref(false);
+    const menuOpen = ref(false);
+    const rowEl = ref<HTMLElement | null>(null);
+    const triggerEl = ref<HTMLElement | null>(null);
+    const hasActions = () => (props.actions?.length ?? 0) > 0;
+    /** A tap inside the row reveals the overlay lane; a tap anywhere
+     *  else dismisses it (capture-phase document listener). */
+    function onRowPointerDown(e: PointerEvent) {
+      if (!hasActions() || e.pointerType === "mouse") return;
+      revealed.value = true;
+    }
+    function onDocumentPointerDown(e: PointerEvent) {
+      if (!revealed.value) return;
+      if (rowEl.value?.contains(e.target as Node)) return;
+      revealed.value = false;
+    }
+    onMounted(() => document.addEventListener("pointerdown", onDocumentPointerDown, true));
+    onBeforeUnmount(() => document.removeEventListener("pointerdown", onDocumentPointerDown, true));
+    const menuItems = computed<HkMenuItem[]>(() => hkListRowMenuItems(props.actions ?? []));
     return () => (
       <div
+        ref={rowEl}
+        onPointerdown={onRowPointerDown}
         class={["hk-list-row", props.clickable && "hk-list-row-clickable"]}
         role="listitem"
         tabindex={props.clickable ? 0 : undefined}
@@ -107,6 +182,67 @@ export const HkListRow = defineComponent({
           {slots.default?.()}
         </div>
         {slots.trailing ? <div class="hk-list-row-trailing">{slots.trailing()}</div> : null}
+        {hasActions() && (
+          <div
+            class={[
+              "hk-list-row-actions",
+              touchFirst.value
+                ? "hk-list-row-actions--touch"
+                : props.actionsMode === "persistent"
+                  ? "hk-list-row-actions--persistent"
+                  : "hk-list-row-actions--overlay",
+            ]}
+            data-revealed={revealed.value ? "" : undefined}
+            role={touchFirst.value ? undefined : "toolbar"}
+            aria-label={touchFirst.value ? undefined : props.actionsLabel}
+          >
+            {touchFirst.value ? (
+              <button
+                ref={triggerEl}
+                type="button"
+                class="hk-list-row-actions__trigger"
+                aria-haspopup="menu"
+                aria-expanded={menuOpen.value}
+                aria-label={props.actionsMenuLabel ?? props.actionsLabel}
+                onClick={() => (menuOpen.value = !menuOpen.value)}
+              >
+                <MoreHorizontal size={14} />
+              </button>
+            ) : (
+              (props.actions ?? []).map((a) => (
+                <HkTooltip text={a.name} placement="top">
+                  {() => (
+                    <button
+                      type="button"
+                      class="hk-list-row-actions__btn"
+                      data-danger={a.danger || undefined}
+                      disabled={a.disabled}
+                      aria-label={a.name}
+                      onClick={() => a.onSelect()}
+                    >
+                      {a.icon ? h(a.icon, { size: 14 }) : null}
+                    </button>
+                  )}
+                </HkTooltip>
+              ))
+            )}
+          </div>
+        )}
+        {menuOpen.value && (
+          <HkMenu
+            variant="popup"
+            items={menuItems.value}
+            open
+            anchorRef={triggerEl.value}
+            placement="top-end"
+            title={props.actionsMenuLabel ?? props.actionsLabel ?? ""}
+            onSelect={(key: string) => {
+              menuOpen.value = false;
+              (props.actions ?? []).find((a) => a.name === key)?.onSelect();
+            }}
+            onUpdate:open={(v: boolean) => (menuOpen.value = v)}
+          />
+        )}
       </div>
     );
   },

package/src/index.ts

@@ -938,6 +938,7 @@ export type { HkPillToggleGroupOption } from "./components/HkPillToggleGroup";
 export { HkIconChip as HkIconChip } from "./components/HkIconChip";
 export { HkIconChip as HIconChip } from "./components/HkIconChip";
 export { HkCardList, HkListRow } from "./components/HkCardList";
+export type { HkListRowAction, HkListRowActionsMode } from "./components/HkCardList";
 export { HkCardList as HCardList, HkListRow as HListRow } from "./components/HkCardList";
 export { HkSectionHeader, type SectionHeaderVariant } from "./components/HkSectionHeader";
 export { HkSectionHeader as HSectionHeader } from "./components/HkSectionHeader";

package/src/plugins/boot-recovery.d.mts

@@ -64,6 +64,28 @@ export interface BootRecoveryCopyOptions {
   message?: string;
   /** Retry button label. */
   retry?: string;
+  /**
+   * Host translations of the panel copy, keyed by BCP 47-ish locale tags
+   * (`"en-US"`, `"zh-CN"`, `"zh-TW"`, …). Keys are normalised at config
+   * time (trimmed, lowercased, `_` → `-`); insertion order is preserved and
+   * breaks ties when several keys share a primary subtag (`zh-CN` listed
+   * before `zh-TW` means a `zh-HK` request resolves to the zh-CN entry).
+   * Every entry must carry non-empty `message` and `retry` strings —
+   * anything else fails the build loudly, as does two keys normalising to
+   * the same tag. Omitting the table (or passing it empty) keeps the
+   * single-copy script — byte-identical to the pre-locale implementation
+   * apart from the panel stylesheet, so a host that hashes the script into
+   * its CSP only needs to refresh the hash it already owns.
+   */
+  locales?: Record<string, { message: string; retry: string }>;
+  /**
+   * `localStorage` key that holds the host's saved UI locale tag (WoWSP
+   * uses `"wowsp-ui-locale"`). Consulted FIRST — the user's explicit
+   * in-app choice outranks the shell's OS preference and the navigator
+   * list. Only meaningful together with `locales`: configuring it without
+   * a table fails at config time.
+   */
+  storageKey?: string;
 }
 
 /** Options for {@link bootRecoveryPlugin} / {@link bootRecoveryScript}. */
@@ -88,6 +110,13 @@ export interface BootRecoveryPluginOptions {
   deadlineMs?: number;
   /** Absolute http(s) app origin (default `http://tauri.localhost`). */
   canonicalOrigin?: string;
+  /**
+   * Name of the `window` global carrying the shell's OS locale preference
+   * (`{ locale: string }`). Default `"__CELESTIA_OS_PREFS__"` — the
+   * boot-chrome family global; an explicit empty string `""` disables the
+   * OS-preference source. Only embedded when `copy.locales` is configured.
+   */
+  osPrefsGlobal?: string;
   /**
    * Custom mangled-origin predicate. It runs in the PAGE, so it is embedded
    * by source text: pass a self-contained ES2017-safe function expression or

package/src/plugins/boot-recovery.mjs

@@ -70,6 +70,33 @@
  *   self-contained — every value it formats comes from the options, so a
  *     crafted URL cannot steer the heal target or the copy.
  *
+ * LOCALE SELECTION (opt-in via `copy.locales`): a host that ships a locale
+ * table gets a failure panel whose copy is picked at PAGE runtime, before any
+ * framework (and any app i18n) exists. The generated script consults, in
+ * order — mirroring the boot-chrome family's stored → OS prefs → navigator →
+ * English fallback:
+ *
+ *   1. `copy.storageKey` — the host's saved UI locale tag in `localStorage`
+ *      (the user's explicit in-app choice outranks everything; WoWSP stores
+ *      `wowsp-ui-locale`);
+ *   2. the shell's OS preference, read from `window[osPrefsGlobal]` (default
+ *      `__CELESTIA_OS_PREFS__`, the boot-chrome family global; an explicit
+ *      `""` disables the source);
+ *   3. `navigator.languages`, then `navigator.language`;
+ *   4. none of the above matched: the English fallback copy.
+ *
+ * Each candidate tag is matched against the table exactly first, then with
+ * trailing subtags progressively stripped (`zh-hant-cn` → `zh-hant` →
+ * `zh`), then by its primary subtag alone. When several table keys share a
+ * primary subtag, the FIRST key in the host's insertion order wins
+ * (`zh-CN` listed before `zh-TW` means a `zh-HK` request resolves to the
+ * zh-CN entry).
+ *
+ * BYTE-COMPAT: a host that does NOT configure `copy.locales` gets a script
+ * byte-identical to the pre-locale implementation — none of the selection
+ * code is emitted, so a host that hashed the single-copy script into its CSP
+ * keeps its old hash.
+ *
  * Usage (the `/plugins/boot-recovery` subpath is the ONLY supported import for
  * consumers — it resolves to this file, not to the package's TypeScript
  * sources):
@@ -152,6 +179,42 @@ function jsonAscii(value) {
     .replace(/</g, "\\u003c");
 }
 
+/**
+ * Serialise the locale table as the generated script's `COPY_TABLE` literal:
+ * a JSON array of `[tag, message, retry]` triples, every string through
+ * `jsonAscii` (CJK becomes \uXXXX escapes, no `</script` can survive), so
+ * the generated script stays ASCII-only and byte-deterministic.
+ *
+ * @param {Array<[string, string, string]>} triples
+ * @returns {string}
+ */
+function copyTableLiteral(triples) {
+  const rows = [];
+  for (const triple of triples) {
+    rows.push(
+      "[" +
+        jsonAscii(triple[0]) +
+        "," +
+        jsonAscii(triple[1]) +
+        "," +
+        jsonAscii(triple[2]) +
+        "]",
+    );
+  }
+  return "[" + rows.join(",") + "]";
+}
+
+/**
+ * JSON literal for a nullable string option: a bare `null`, not the string
+ * `"null"` (`jsonAscii` stringifies).
+ *
+ * @param {string | null} value
+ * @returns {string}
+ */
+function jsonLiteral(value) {
+  return value === null ? "null" : jsonAscii(value);
+}
+
 /**
  * Hostname of an absolute http(s) canonical origin.
  *
@@ -287,6 +350,103 @@ function normaliseCopy(input) {
   };
 }
 
+/**
+ * Normalise the host's optional locale table.
+ *
+ * Keys are BCP 47-ish tags; each is trimmed, lowercased and has `_` turned
+ * into `-` (so `"zh_CN"` and `"zh-cn"` collide loudly instead of one of
+ * them silently shadowing the other). Each entry must be an object carrying
+ * non-empty `message` and `retry` strings — a typo must fail the build at
+ * config time, not paint an empty panel on a dead boot. The result is an
+ * array of `[tag, message, retry]` triples in the host's insertion order
+ * (which is the tie-break order for shared primary subtags), or `null`
+ * when no table was configured — the single-copy mode keeps the
+ * byte-identical script a host may have hashed into its CSP.
+ *
+ * @param {unknown} locales
+ * @returns {Array<[string, string, string]> | null}
+ */
+function normaliseLocales(locales) {
+  if (locales === undefined || locales === null) return null;
+  const triples = [];
+  const seen = new Map();
+  for (const rawKey in locales) {
+    if (!Object.prototype.hasOwnProperty.call(locales, rawKey)) continue;
+    const tag = String(rawKey).trim().replace(/_/g, "-").toLowerCase();
+    if (!tag) {
+      throw new Error(
+        "[hikari boot-recovery] copy.locales key " +
+          JSON.stringify(rawKey) +
+          " normalises to an empty locale tag",
+      );
+    }
+    const previous = seen.get(tag);
+    if (previous !== undefined) {
+      throw new Error(
+        "[hikari boot-recovery] copy.locales keys " +
+          JSON.stringify(previous) +
+          " and " +
+          JSON.stringify(rawKey) +
+          " normalise to the same locale tag " +
+          JSON.stringify(tag),
+      );
+    }
+    const entry = locales[rawKey];
+    if (
+      !entry ||
+      typeof entry !== "object" ||
+      typeof entry.message !== "string" ||
+      !entry.message ||
+      typeof entry.retry !== "string" ||
+      !entry.retry
+    ) {
+      throw new Error(
+        "[hikari boot-recovery] copy.locales[" +
+          JSON.stringify(tag) +
+          "]: copy.locales entries must carry non-empty message and retry strings",
+      );
+    }
+    seen.set(tag, rawKey);
+    triples.push([tag, entry.message, entry.retry]);
+  }
+  return triples.length ? triples : null;
+}
+
+/**
+ * Normalise `copy.storageKey`: the localStorage key holding the host's
+ * saved UI locale tag. It is the FIRST locale source (the user's explicit
+ * in-app choice outranks the OS preference and the navigator), so
+ * configuring it without a table to consult is a config error, not a silent
+ * no-op. An empty/whitespace value is treated as absent.
+ *
+ * @param {unknown} value
+ * @param {boolean} hasTable
+ * @returns {string | null}
+ */
+function normaliseStorageKey(value, hasTable) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  if (!hasTable) {
+    throw new Error(
+      "[hikari boot-recovery] copy.storageKey requires copy.locales",
+    );
+  }
+  return value.trim();
+}
+
+/**
+ * Normalise `osPrefsGlobal`: the name of the `window` global carrying the
+ * shell's OS locale preference (`{ locale: string }`). Defaults to the
+ * boot-chrome family global; an explicit empty string disables the source
+ * (for a host that publishes no such global and does not want one probed).
+ *
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+function normaliseOsPrefsGlobal(value) {
+  if (value === "") return null;
+  return typeof value === "string" ? value : "__CELESTIA_OS_PREFS__";
+}
+
 /**
  * Normalise the loading-screen half: `false` disables it entirely (heal-only
  * mode); an object customises the element selector and the dismissed class.
@@ -324,6 +484,9 @@ function normaliseLoadingScreen(input) {
  *   predicateSource: string | null,
  *   loadingScreen: { selector: string, dismissedClass: string } | null,
  *   copy: { message: string, retry: string },
+ *   copyTable: Array<[string, string, string]> | null,
+ *   storageKey: string | null,
+ *   osPrefsGlobal: string | null,
  *   injectTo: "head" | "head-prepend",
  * }}
  */
@@ -333,6 +496,9 @@ function resolveOptions(options) {
     typeof input.canonicalOrigin === "string" && input.canonicalOrigin.trim()
       ? input.canonicalOrigin.trim()
       : BOOT_RECOVERY_CANONICAL_ORIGIN;
+  const copyRaw =
+    input.copy && typeof input.copy === "object" ? input.copy : {};
+  const copyTable = normaliseLocales(copyRaw.locales);
   return {
     canonicalOrigin: canonicalOrigin,
     canonicalHostname: canonicalHostname(canonicalOrigin),
@@ -343,6 +509,9 @@ function resolveOptions(options) {
         : null,
     loadingScreen: normaliseLoadingScreen(input.loadingScreen),
     copy: normaliseCopy(input.copy),
+    copyTable: copyTable,
+    storageKey: normaliseStorageKey(copyRaw.storageKey, copyTable !== null),
+    osPrefsGlobal: normaliseOsPrefsGlobal(input.osPrefsGlobal),
     injectTo: normaliseInjectTo(input.injectTo),
   };
 }
@@ -422,17 +591,23 @@ function htmlFileMatches(filename, htmlFiles) {
  * CSS for the failure panel, injected as one inline `<style>` next to the panel
  * itself. Deliberately SELF-CONTAINED: it styles only hikari's own panel
  * classes, never the host's loading element, so a custom `selector` cannot
- * break out of a stylesheet. `color` starts from the light-scheme value and
- * flips under `prefers-color-scheme: dark` — the host's loading screen owns the
- * backdrop, but hikari can at least keep the panel text legible before any
- * theme has loaded. The button derives every colour from `currentColor`.
+ * break out of a stylesheet. The values are hikari's seed tokens written out
+ * literally (packages/vue/src/styles/theme/channels.scss + scale.scss): the
+ * primary 122 162 247 with its 82%-black hover mix and button shadow, the
+ * elevated card shadow, the md/lg radii, the `--font-sans` stack and the
+ * text seed 30 30 30. The card carries its own surface — white in the light
+ * scheme, the Nord surface rgb(46 52 64) under `prefers-color-scheme: dark`
+ * — so the panel stays legible on any backdrop (WoWSP's dark loader paints
+ * #0b1220) before any theme engine has loaded.
  */
 const FAILURE_PANEL_CSS = [
-  ".hk-boot-recovery{display:flex;flex-direction:column;align-items:center;gap:1rem;max-width:32rem;padding:1.5rem;text-align:center;font-family:system-ui,sans-serif;color:#1e2837}",
-  ".hk-boot-recovery__message{margin:0;font-size:.95rem;line-height:1.5}",
-  ".hk-boot-recovery__retry{font:inherit;font-size:.85rem;padding:.5rem 1.25rem;border:1px solid currentColor;border-radius:6px;background:transparent;color:inherit;cursor:pointer}",
-  ".hk-boot-recovery__retry:hover{background:rgba(127,127,127,.15)}",
-  "@media (prefers-color-scheme:dark){.hk-boot-recovery{color:#cfe3ff}}",
+  ".hk-boot-recovery{display:flex;flex-direction:column;align-items:center;gap:1.25rem;max-width:32rem;padding:2rem 2.5rem;text-align:center;background:#fff;border:1px solid rgb(30 30 30 / 8%);border-radius:12px;box-shadow:0 8px 32px rgb(0 0 0 / 15%);font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,'PingFang SC','Hiragino Sans GB','Microsoft YaHei','Noto Sans CJK SC',sans-serif;color:rgb(30 30 30)}",
+  ".hk-boot-recovery__message{margin:0;font-size:.875rem;line-height:1.6}",
+  ".hk-boot-recovery__retry{appearance:none;font:inherit;font-size:.875rem;font-weight:600;padding:.5rem 1.5rem;border:0;border-radius:8px;background:rgb(122 162 247);color:#fff;cursor:pointer;box-shadow:0 4px 14px rgb(122 162 247 / 35%);transition:background .15s cubic-bezier(.4,0,.2,1),box-shadow .15s cubic-bezier(.4,0,.2,1)}",
+  ".hk-boot-recovery__retry:hover{background:rgb(100 133 203)}",
+  ".hk-boot-recovery__retry:active{background:rgb(83 111 167)}",
+  ".hk-boot-recovery__retry:focus-visible{outline:none;box-shadow:0 0 0 3px rgb(122 162 247 / 25%)}",
+  "@media (prefers-color-scheme:dark){.hk-boot-recovery{background:rgb(46 52 64);border-color:rgb(255 255 255 / 8%);box-shadow:0 8px 32px rgb(0 0 0 / 45%);color:rgb(216 222 233)}}",
 ].join("\n");
 
 /**
@@ -486,6 +661,18 @@ export function bootRecoveryScript(options = {}) {
     );
     lines.push("  var COPY_MESSAGE = " + jsonAscii(resolved.copy.message) + ";");
     lines.push("  var COPY_RETRY = " + jsonAscii(resolved.copy.retry) + ";");
+    if (resolved.copyTable) {
+      lines.push("  var COPY_FALLBACK = [COPY_MESSAGE, COPY_RETRY];");
+      lines.push(
+        "  var COPY_TABLE = " + copyTableLiteral(resolved.copyTable) + ";",
+      );
+      lines.push(
+        "  var STORAGE_KEY = " + jsonLiteral(resolved.storageKey) + ";",
+      );
+      lines.push(
+        "  var OS_PREFS_GLOBAL = " + jsonLiteral(resolved.osPrefsGlobal) + ";",
+      );
+    }
     lines.push("  var PANEL_CSS = " + jsonAscii(FAILURE_PANEL_CSS) + ";");
   }
   lines.push("");
@@ -572,6 +759,79 @@ export function bootRecoveryScript(options = {}) {
     lines.push("    location.reload();");
     lines.push("  }");
     lines.push("");
+    if (resolved.copyTable) {
+      lines.push("  /* Panel copy locale sources, first match wins (mirrors boot-chrome's");
+      lines.push("     stored -> OS prefs -> navigator -> English fallback order):");
+      lines.push("     1. localStorage[STORAGE_KEY] - the host's saved UI locale, the");
+      lines.push("        user's explicit in-app choice, outranks everything;");
+      lines.push("     2. window[OS_PREFS_GLOBAL].locale - the shell's OS preference;");
+      lines.push("     3. navigator.languages, then navigator.language;");
+      lines.push("     4. no match - the English fallback pair (COPY_FALLBACK).");
+      lines.push("     Each candidate tag is matched against COPY_TABLE exactly, then");
+      lines.push("     with trailing subtags progressively stripped, then by its");
+      lines.push("     primary subtag alone; entries sharing a primary subtag resolve");
+      lines.push("     to the FIRST one the host listed. The winning entry is returned");
+      lines.push("     as its [message, retry] pair, like COPY_FALLBACK. */");
+      lines.push("  function localeKey(tag, drop) {");
+      lines.push('    var parts = String(tag).replace(/_/g, "-").toLowerCase().split("-");');
+      lines.push("    if (drop >= parts.length) return null;");
+      lines.push('    return parts.slice(0, parts.length - drop).join("-");');
+      lines.push("  }");
+      lines.push("  function tableHit(key) {");
+      lines.push("    for (var i = 0; i < COPY_TABLE.length; i++) {");
+      lines.push("      if (COPY_TABLE[i][0] === key) return COPY_TABLE[i];");
+      lines.push("    }");
+      lines.push("    return null;");
+      lines.push("  }");
+      lines.push("  function primaryHit(tag) {");
+      lines.push('    var primary = String(tag).replace(/_/g, "-").toLowerCase().split("-")[0];');
+      lines.push("    for (var i = 0; i < COPY_TABLE.length; i++) {");
+      lines.push('      if (COPY_TABLE[i][0].split("-")[0] === primary) return COPY_TABLE[i];');
+      lines.push("    }");
+      lines.push("    return null;");
+      lines.push("  }");
+      lines.push("  function pickCopy() {");
+      lines.push("    var candidates = [];");
+      lines.push("    if (STORAGE_KEY) {");
+      lines.push("      try {");
+      lines.push("        var stored = localStorage.getItem(STORAGE_KEY);");
+      lines.push('        if (typeof stored === "string" && stored) candidates.push(stored);');
+      lines.push("      } catch (e) {}");
+      lines.push("    }");
+      lines.push('    if (OS_PREFS_GLOBAL && typeof window !== "undefined") {');
+      lines.push("      try {");
+      lines.push("        var prefs = window[OS_PREFS_GLOBAL];");
+      lines.push('        if (prefs && typeof prefs.locale === "string") candidates.push(prefs.locale);');
+      lines.push("      } catch (e) {}");
+      lines.push("    }");
+      lines.push('    if (typeof navigator !== "undefined") {');
+      lines.push("      try {");
+      lines.push("        if (navigator.languages && navigator.languages.length) {");
+      lines.push("          for (var i = 0; i < navigator.languages.length; i++) {");
+      lines.push('            if (typeof navigator.languages[i] === "string" && navigator.languages[i]) {');
+      lines.push("              candidates.push(navigator.languages[i]);");
+      lines.push("            }");
+      lines.push("          }");
+      lines.push("        }");
+      lines.push('        if (typeof navigator.language === "string" && navigator.language) {');
+      lines.push("          candidates.push(navigator.language);");
+      lines.push("        }");
+      lines.push("      } catch (e) {}");
+      lines.push("    }");
+      lines.push("    for (var c = 0; c < candidates.length; c++) {");
+      lines.push("      var hit = tableHit(localeKey(candidates[c], 0));");
+      lines.push("      if (hit) return [hit[1], hit[2]];");
+      lines.push('      var parts = String(candidates[c]).replace(/_/g, "-").toLowerCase().split("-");');
+      lines.push("      for (var drop = 1; drop < parts.length; drop++) {");
+      lines.push("        hit = tableHit(localeKey(candidates[c], drop));");
+      lines.push("        if (hit) return [hit[1], hit[2]];");
+      lines.push("      }");
+      lines.push("      hit = primaryHit(candidates[c]);");
+      lines.push("      if (hit) return [hit[1], hit[2]];");
+      lines.push("    }");
+      lines.push("    return null;");
+      lines.push("  }");
+    }
     lines.push(
       "  /* Replace the loader's contents with the failure panel. Built from",
     );
@@ -588,11 +848,20 @@ export function bootRecoveryScript(options = {}) {
     lines.push('    box.setAttribute("role", "alert");');
     lines.push('    var message = document.createElement("p");');
     lines.push('    message.className = "hk-boot-recovery__message";');
-    lines.push("    message.textContent = COPY_MESSAGE;");
+    if (resolved.copyTable) {
+      lines.push("    var copy = pickCopy() || COPY_FALLBACK;");
+      lines.push("    message.textContent = copy[0];");
+    } else {
+      lines.push("    message.textContent = COPY_MESSAGE;");
+    }
     lines.push('    var button = document.createElement("button");');
     lines.push('    button.type = "button";');
     lines.push('    button.className = "hk-boot-recovery__retry";');
-    lines.push("    button.textContent = COPY_RETRY;");
+    lines.push(
+      resolved.copyTable
+        ? "    button.textContent = copy[1];"
+        : "    button.textContent = COPY_RETRY;",
+    );
     lines.push('    button.addEventListener("click", retry);');
     lines.push("    box.appendChild(message);");
     lines.push("    box.appendChild(button);");
@@ -630,8 +899,14 @@ export function bootRecoveryScript(options = {}) {
  *   loadingScreen?: { selector?: string, dismissedClass?: string } | false,
  *   deadlineMs?: number,
  *   canonicalOrigin?: string,
+ *   osPrefsGlobal?: string,
  *   isMangledOrigin?: (protocol: string, hostname: string) => boolean,
- *   copy?: { message?: string, retry?: string },
+ *   copy?: {
+ *     message?: string,
+ *     retry?: string,
+ *     locales?: Record<string, { message: string, retry: string }>,
+ *     storageKey?: string,
+ *   },
  *   injectTo?: "head" | "head-prepend",
  *   }} [options]
  * @returns {import("vite").Plugin}

package/src/plugins/boot-recovery.test.ts

@@ -131,9 +131,22 @@ function tags(
 }
 
 // ── fake page harness ──────────────────────────────────────────────────────
-// The generated script only reaches for three globals. Passing fakes as
-// Function parameters shadows Node's (absent) globals, so the REAL shipped
-// script runs unmodified — no copied logic, no drift.
+// The generated script only reaches for three globals on every page
+// (location / document / setTimeout); locale-aware variants additionally
+// read localStorage / navigator / window. Passing fakes as Function
+// parameters shadows Node's globals (Node exposes a real `navigator`!), so
+// the REAL shipped script runs unmodified — no copied logic, no drift.
+
+/** Minimal stand-in for the `localStorage` the locale-aware copy reads. */
+interface FakeLocalStorage {
+  getItem: (key: string) => string | null;
+}
+
+/** Minimal stand-in for the `navigator` the locale-aware copy reads. */
+interface FakeNavigator {
+  languages?: string[];
+  language?: string;
+}
 
 interface FakeNode {
   tag: string;
@@ -217,6 +230,12 @@ interface FakePage {
   replaceThrows?: boolean;
   /** The script to execute (default: the shipped default script). */
   script?: string;
+  /** `localStorage` backing the host's saved UI locale (locale-aware scripts). */
+  localStorage?: FakeLocalStorage;
+  /** `navigator` (locale-aware scripts; absent = the script must not see one). */
+  navigator?: FakeNavigator;
+  /** `window` global bag, e.g. the shell's OS prefs (locale-aware scripts). */
+  window?: Record<string, unknown>;
 }
 
 /**
@@ -268,13 +287,28 @@ function runRecovery(page: FakePage = {}): RecoveryRun {
     "location",
     "document",
     "setTimeout",
+    "localStorage",
+    "navigator",
+    "window",
     script,
   ) as (
     location: FakeLocation,
     document: FakeDocument,
     setTimeout: FakeSetTimeout,
+    localStorage: FakeLocalStorage | undefined,
+    navigator: FakeNavigator | undefined,
+    window: Record<string, unknown> | undefined,
   ) => void;
-  run(location, fakeDocument, fakeSetTimeout);
+  // Passing undefined shadows Node's own globals: a locale-aware script run
+  // without a fake navigator must not see Node's real one.
+  run(
+    location,
+    fakeDocument,
+    fakeSetTimeout,
+    page.localStorage,
+    page.navigator,
+    page.window,
+  );
 
   return {
     replaced,
@@ -294,6 +328,26 @@ function panelButton(run: RecoveryRun): FakeNode {
   return mustFind(panel.children, "button");
 }
 
+/** The panel's message <p>, if a panel was painted into the fake loader. */
+function panelMessage(run: RecoveryRun): FakeNode {
+  const panel = mustFind(run.loading?.children ?? [], "div");
+  return mustFind(panel.children, "p");
+}
+
+/** Fake localStorage backed by a plain record. */
+function fakeStorage(entries: Record<string, string> = {}): FakeLocalStorage {
+  return {
+    getItem: (key) => (key in entries ? entries[key] : null),
+  };
+}
+
+/** Fake navigator with a languages list (and an optional explicit language). */
+function fakeNavigator(languages: string[], language?: string): FakeNavigator {
+  return language === undefined
+    ? { languages, language: languages[0] ?? "" }
+    : { languages, language };
+}
+
 /** Click every listener the button carries (the generated script registers one). */
 function clickButton(button: FakeNode): void {
   for (const listener of button.listeners.click ?? []) listener();
@@ -566,9 +620,12 @@ describe("the recovery script's runtime behaviour (executed against a fake page)
     const style = mustFind(run.loading?.children ?? [], "style");
     // Colour-scheme aware and self-contained: the panel must not flip to light
     // colours on a dark desktop (or vice versa) before the app's theme loads.
+    // The card carries its own seed-token surface (white / Nord rgb(46 52 64)),
+    // so it stays legible on a dark loader backdrop (WoWSP paints #0b1220).
     expect(style.textContent).toContain("prefers-color-scheme:dark");
-    expect(style.textContent).toContain("#1e2837");
-    expect(style.textContent).toContain("#cfe3ff");
+    expect(style.textContent).toContain("rgb(30 30 30)");
+    expect(style.textContent).toContain("rgb(216 222 233)");
+    expect(style.textContent).toContain("rgb(122 162 247)");
     expect(style.textContent).toContain(".hk-boot-recovery");
 
     const panel = mustFind(run.loading?.children ?? [], "div");
@@ -735,6 +792,280 @@ describe("the recovery script's runtime behaviour (executed against a fake page)
   });
 });
 
+// ── locale-aware copy (copy.locales) ──────────────────────────────────────
+
+/** A WoWSP-shaped table: English fallback + two Chinese scripts, in the order
+ * the host lists them — zh-CN BEFORE zh-TW, which is the tie-break order. */
+const LOCALE_TABLE = {
+  "en-US": { message: "EN message", retry: "Reload" },
+  "zh-CN": { message: "简体中文消息", retry: "重新加载" },
+  "zh-TW": { message: "繁體中文訊息", retry: "重新載入" },
+};
+
+const WITH_TABLE = bootRecoveryScript({
+  copy: { locales: LOCALE_TABLE, storageKey: "wowsp-ui-locale" },
+});
+
+/** Fire the watchdog and return the painted panel's message and button. */
+function paint(page: FakePage): { message: FakeNode; button: FakeNode } {
+  const run = runRecovery(page);
+  run.timers[0].callback();
+  return { message: panelMessage(run), button: panelButton(run) };
+}
+
+describe("the locale-aware script's content contract", () => {
+  it("embeds the table, the storage key and the OS-prefs global", () => {
+    // The table is an ARRAY of [tag, message, retry] triples in the host's
+    // insertion order — the tie-break order for shared primary subtags.
+    expect(WITH_TABLE).toContain(
+      'var COPY_TABLE = [["en-us","EN message","Reload"],["zh-cn",',
+    );
+    // CJK rides through jsonAscii as \uXXXX escapes (ASCII-only script).
+    expect(WITH_TABLE).toContain('"\\u7b80\\u4f53\\u4e2d\\u6587\\u6d88\\u606f"');
+    expect(WITH_TABLE).toContain(
+      '["zh-tw","\\u7e41\\u9ad4\\u4e2d\\u6587\\u8a0a\\u606f","\\u91cd\\u65b0\\u8f09\\u5165"]',
+    );
+    expect(WITH_TABLE).toContain(
+      'var COPY_FALLBACK = [COPY_MESSAGE, COPY_RETRY];',
+    );
+    expect(WITH_TABLE).toContain('var STORAGE_KEY = "wowsp-ui-locale";');
+    expect(WITH_TABLE).toContain(
+      'var OS_PREFS_GLOBAL = "__CELESTIA_OS_PREFS__";',
+    );
+    // showFailure resolves the pair at paint time.
+    expect(WITH_TABLE).toContain("var copy = pickCopy() || COPY_FALLBACK;");
+    // Insertion order is preserved in the emitted literal.
+    expect(WITH_TABLE.indexOf('"en-us"')).toBeLessThan(
+      WITH_TABLE.indexOf('"zh-cn"'),
+    );
+    expect(WITH_TABLE.indexOf('"zh-cn"')).toBeLessThan(
+      WITH_TABLE.indexOf('"zh-tw"'),
+    );
+  });
+
+  it("stays ASCII-only, deterministic and tag-safe with a locale table", () => {
+    const foreign = [...WITH_TABLE].filter((char) => {
+      const code = char.charCodeAt(0);
+      return code !== 9 && code !== 10 && (code < 32 || code > 126);
+    });
+    expect(foreign).toEqual([]);
+    expect(
+      bootRecoveryScript({
+        copy: { locales: LOCALE_TABLE, storageKey: "wowsp-ui-locale" },
+      }),
+    ).toBe(WITH_TABLE); // deterministic: byte-identical regeneration
+    expect(WITH_TABLE.toLowerCase()).not.toContain("</script");
+    // No template-literal hole sequence may leak into the generated text
+    // (built by concatenation so THIS file stays grep-safe).
+    expect(WITH_TABLE).not.toContain(String.fromCharCode(36) + "{");
+  });
+
+  it("keeps single-copy scripts free of every locale machinery string", () => {
+    // Byte-compat for hosts that hash the script into their CSP: without
+    // copy.locales NONE of the selection code is emitted.
+    for (const script of [
+      bootRecoveryScript(),
+      bootRecoveryScript({ copy: { message: "Boot failed", retry: "Retry" } }),
+    ]) {
+      expect(script).not.toContain("COPY_TABLE");
+      expect(script).not.toContain("COPY_FALLBACK");
+      expect(script).not.toContain("localStorage");
+      expect(script).not.toContain("OS_PREFS");
+      expect(script).not.toContain("pickCopy");
+      expect(script).not.toContain("STORAGE_KEY");
+    }
+  });
+});
+
+describe("copy locale selection (executed against a fake page)", () => {
+  it("paints the whole panel in the navigator locale (zh-CN)", () => {
+    const painted = paint({
+      script: WITH_TABLE,
+      navigator: fakeNavigator(["zh-CN", "en-US"]),
+    });
+    expect(painted.message.textContent).toBe(LOCALE_TABLE["zh-CN"].message);
+    expect(painted.button.textContent).toBe(LOCALE_TABLE["zh-CN"].retry);
+  });
+
+  it("prefers the host storage key over the OS preference and the navigator", () => {
+    // The user's explicit in-app choice outranks everything.
+    const painted = paint({
+      script: WITH_TABLE,
+      localStorage: fakeStorage({ "wowsp-ui-locale": "zh-TW" }),
+      window: { __CELESTIA_OS_PREFS__: { locale: "zh-CN" } },
+      navigator: fakeNavigator(["en-US"]),
+    });
+    expect(painted.message.textContent).toBe(LOCALE_TABLE["zh-TW"].message);
+    expect(painted.button.textContent).toBe(LOCALE_TABLE["zh-TW"].retry);
+  });
+
+  it("prefers the OS preference over the navigator list", () => {
+    const painted = paint({
+      script: WITH_TABLE,
+      window: { __CELESTIA_OS_PREFS__: { locale: "zh-CN" } },
+      navigator: fakeNavigator(["en-US"]),
+    });
+    expect(painted.message.textContent).toBe(LOCALE_TABLE["zh-CN"].message);
+  });
+
+  it("matches an exact navigator tag (ja-JP style)", () => {
+    const table = { "ja-JP": { message: "日本語メッセージ", retry: "再読み込み" } };
+    const painted = paint({
+      script: bootRecoveryScript({ copy: { locales: table } }),
+      navigator: fakeNavigator(["ja-JP"]),
+    });
+    expect(painted.message.textContent).toBe("日本語メッセージ");
+    expect(painted.button.textContent).toBe("再読み込み");
+  });
+
+  it("strips trailing subtags progressively (zh-Hant-CN -> zh-Hant)", () => {
+    const table = { "zh-Hant": { message: "繁體訊息", retry: "重新載入" } };
+    const painted = paint({
+      script: bootRecoveryScript({ copy: { locales: table } }),
+      navigator: fakeNavigator(["zh-Hant-CN"]),
+    });
+    expect(painted.message.textContent).toBe("繁體訊息");
+  });
+
+  it("resolves a shared primary subtag to the FIRST listed entry (zh-HK)", () => {
+    // zh-HK hits no key exactly; the primary subtag zh matches zh-CN first
+    // because the host listed it before zh-TW.
+    const painted = paint({
+      script: WITH_TABLE,
+      navigator: fakeNavigator(["zh-HK"]),
+    });
+    expect(painted.message.textContent).toBe(LOCALE_TABLE["zh-CN"].message);
+    expect(painted.button.textContent).toBe(LOCALE_TABLE["zh-CN"].retry);
+  });
+
+  it("falls back to the English copy when nothing matches", () => {
+    const script = bootRecoveryScript({
+      copy: { locales: { "zh-CN": LOCALE_TABLE["zh-CN"] } },
+    });
+    const painted = paint({
+      script,
+      navigator: fakeNavigator(["fr-FR", "de-DE"]),
+    });
+    expect(painted.message.textContent).toBe(BOOT_RECOVERY_MESSAGE);
+    expect(painted.button.textContent).toBe(BOOT_RECOVERY_RETRY);
+  });
+
+  it("resolves from the storage key alone (no window, no navigator)", () => {
+    const painted = paint({
+      script: WITH_TABLE,
+      localStorage: fakeStorage({ "wowsp-ui-locale": "zh-CN" }),
+    });
+    expect(painted.message.textContent).toBe(LOCALE_TABLE["zh-CN"].message);
+  });
+
+  it("still reloads via the button after painting a locale row", () => {
+    const run = runRecovery({
+      script: WITH_TABLE,
+      navigator: fakeNavigator(["zh-CN"]),
+    });
+    run.timers[0].callback();
+    clickButton(panelButton(run));
+    expect(run.reloads).toBe(1);
+    expect(run.replaced).toEqual([]);
+  });
+});
+
+describe("copy.locales / osPrefsGlobal validation", () => {
+  it("rejects two keys that normalise to the same locale tag", () => {
+    expect(() =>
+      bootRecoveryScript({
+        copy: {
+          locales: {
+            "zh-CN": LOCALE_TABLE["zh-CN"],
+            zh_cn: LOCALE_TABLE["zh-TW"],
+          },
+        },
+      }),
+    ).toThrow(/same locale tag/);
+    // Plugin creation fails equally loudly (config-time validation).
+    expect(() =>
+      bootRecoveryPlugin({
+        copy: {
+          locales: {
+            "en-US": LOCALE_TABLE["en-US"],
+            "en_us": LOCALE_TABLE["en-US"],
+          },
+        },
+      }),
+    ).toThrow(/same locale tag/);
+  });
+
+  it("rejects a malformed entry, naming the tag", () => {
+    expect(() =>
+      bootRecoveryScript({
+        copy: { locales: { "zh-CN": { message: "消息", retry: "" } } },
+      }),
+    ).toThrow(/must carry non-empty message and retry strings/);
+    expect(() =>
+      bootRecoveryScript({
+        copy: { locales: { "zh_CN": invalidInput("oops") } },
+      }),
+    ).toThrow(/must carry non-empty message and retry strings/);
+    // The thrown error names the normalised tag.
+    try {
+      bootRecoveryScript({
+        copy: { locales: { "zh_CN": invalidInput("oops") } },
+      });
+      expect.unreachable("validation must throw");
+    } catch (err) {
+      expect(String(err)).toContain("zh-cn");
+    }
+  });
+
+  it("rejects storageKey without a locales table", () => {
+    expect(() =>
+      bootRecoveryScript({ copy: { storageKey: "wowsp-ui-locale" } }),
+    ).toThrow(/copy\.storageKey requires copy\.locales/);
+    expect(() =>
+      bootRecoveryPlugin({ copy: { storageKey: "wowsp-ui-locale" } }),
+    ).toThrow(/copy\.storageKey requires copy\.locales/);
+    // An empty storageKey is absent, not a misconfiguration: single-copy mode.
+    expect(bootRecoveryScript({ copy: { storageKey: "" } })).toBe(SCRIPT);
+  });
+});
+
+describe("osPrefsGlobal", () => {
+  it("disables the OS-prefs source when set to an empty string", () => {
+    const script = bootRecoveryScript({
+      copy: { locales: LOCALE_TABLE, storageKey: "wowsp-ui-locale" },
+      osPrefsGlobal: "",
+    });
+    expect(script).toContain("var OS_PREFS_GLOBAL = null;");
+    expect(script).not.toContain("__CELESTIA_OS_PREFS__");
+    // The OS preference is now ignored: the navigator list decides.
+    const painted = paint({
+      script,
+      window: { __CELESTIA_OS_PREFS__: { locale: "zh-CN" } },
+      navigator: fakeNavigator(["en-US"]),
+    });
+    expect(painted.message.textContent).toBe(LOCALE_TABLE["en-US"].message);
+    // A navigator-only environment still resolves.
+    const zhPainted = paint({ script, navigator: fakeNavigator(["zh-CN"]) });
+    expect(zhPainted.message.textContent).toBe(LOCALE_TABLE["zh-CN"].message);
+  });
+
+  it("reads a renamed OS-prefs global (WoWSP's real wiring)", () => {
+    const script = bootRecoveryScript({
+      copy: { locales: LOCALE_TABLE, storageKey: "wowsp-ui-locale" },
+      osPrefsGlobal: "__WOWSP_OS_PREFS__",
+    });
+    expect(script).toContain('"__WOWSP_OS_PREFS__"');
+    expect(script).not.toContain('"__CELESTIA_OS_PREFS__"');
+    const painted = paint({
+      script,
+      window: { __WOWSP_OS_PREFS__: { locale: "zh-TW" } },
+      navigator: fakeNavigator(["en-US"]),
+    });
+    expect(painted.message.textContent).toBe(LOCALE_TABLE["zh-TW"].message);
+    expect(painted.button.textContent).toBe(LOCALE_TABLE["zh-TW"].retry);
+  });
+});
+
 // ── the plugin: injection face ────────────────────────────────────────────
 
 describe("bootRecoveryPlugin injection", () => {