@celestia-island/hikari 0.55.272 → 0.55.274

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.272",
+  "version": "0.55.274",
   "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/components/HkPersistentToast.scss

@@ -65,6 +65,10 @@ button.hk-persistent-toast {
   color: rgb(var(--color-muted));
 }
 
+.hk-persistent-toast--success .hk-persistent-toast__icon {
+  color: rgb(var(--color-success));
+}
+
 .hk-persistent-toast__label {
   overflow: hidden;
   text-overflow: ellipsis;

package/src/components/HkPersistentToast.test.tsx

@@ -111,6 +111,15 @@ describe("HkPersistentToast inert default", () => {
     expect(container.querySelector(".hk-persistent-toast__spinner")).not.toBeNull();
   });
 
+  it("renders a static icon for the success tone", () => {
+    const { container } = mount({ props: { tone: "success", label: "Saved" } });
+    const c = chip(container);
+    expect(c.classList.contains("hk-persistent-toast--success")).toBe(true);
+    // Success renders a static lucide icon like the other non-loading tones.
+    expect(container.querySelector(".hk-persistent-toast__spinner")).toBeNull();
+    expect(c.querySelector("svg")).not.toBeNull();
+  });
+
   it("renders the ✕ sibling button only when dismissible", () => {
     const onDismiss = vi.fn();
     const { container } = mount({ props: { label: "x", dismissible: true }, onDismiss });

package/src/components/HkPersistentToast.tsx

@@ -1,4 +1,4 @@
-import { AlertTriangle, Info, X } from "lucide-vue-next";
+import { AlertTriangle, Check, Info, X } from "lucide-vue-next";
 import {
   computed,
   defineComponent,
@@ -15,7 +15,7 @@ import { useI18n } from "../i18n/context";
 import "./HkPersistentToast.scss";
 import { ensureOverlayRoot } from "../overlay/overlayRoot";
 
-export type PersistentToastTone = "loading" | "info" | "warning" | "error";
+export type PersistentToastTone = "loading" | "info" | "warning" | "error" | "success";
 
 /** Viewport gutter the detail card clamps into (mirror of
  *  --viewport-gutter's desktop value; the card is chrome-adjacent and
@@ -251,6 +251,8 @@ export default defineComponent({
               <span class="hk-persistent-toast__spinner" aria-hidden="true" />
             ) : props.tone === "error" || props.tone === "warning" ? (
               <AlertTriangle size={12} class="hk-persistent-toast__icon" aria-hidden="true" />
+            ) : props.tone === "success" ? (
+              <Check size={12} class="hk-persistent-toast__icon" aria-hidden="true" />
             ) : (
               <Info size={12} class="hk-persistent-toast__icon" aria-hidden="true" />
             )}

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