@celestia-island/hikari 0.55.188 → 0.55.189

package/package.json

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

package/src/components/HkMenuActionItem.tsx

@@ -21,6 +21,11 @@ export default defineComponent({
     /** Destructive styling (logout, delete…). */
     danger: { type: Boolean, default: false },
     disabled: { type: Boolean, default: false },
+    /** Selected/current row — the unified menu-item grammar's [data-active]
+     *  face (primary wash + strong border + primary text; see
+     *  _menu-item.scss). For lists that mark "you are here", e.g. the
+     *  modal-breadcrumb layer picker highlighting the current layer. */
+    active: { type: Boolean, default: false },
   },
   emits: {
     click: (_e: MouseEvent) => true,
@@ -31,6 +36,7 @@ export default defineComponent({
         type="button"
         class={["hk-menu-action-item", props.danger ? "hk-menu-action-item--danger" : ""]}
         data-danger={props.danger || undefined}
+        data-active={props.active || undefined}
         disabled={props.disabled}
         role="menuitem"
         onClick={(e: MouseEvent) => emit("click", e)}

package/src/components/HkModalBreadcrumb.overflow.contract.test.ts

@@ -95,7 +95,7 @@ describe("HkModalBreadcrumb overflow fence", () => {
     expect(offset).toBeGreaterThan(clearance);
   });
 
-  it("routes the hidden-layers menu through the shared form-factor rule", () => {
+  it("routes the all-layers menu through the shared form-factor rule", () => {
     // HkPopover owns "anchored under the trigger on desktop, bottom-up
     // sheet on mobile" and registers the surface with the popup manager;
     // a bespoke panel here would fork that behaviour.

package/src/components/HkModalBreadcrumb.scss

@@ -109,9 +109,22 @@
   inset: calc(-1 * var(--space-8, 0.5rem));
 }
 
-.hk-modal-breadcrumb-more:hover {
-  background: var(--hk-breadcrumb-more-hover, rgba(0, 0, 0, 0.06));
-  color: var(--hi-color-text, #1f2328);
+/* Hover AND the open state (aria-expanded — on a phone the tap leaves
+ * :hover stuck on the trigger, so the two must share one legible face).
+ * Both colors ride tokens that exist in every theme: the wash is the
+ * menu-item grammar's own primary-subtle (a raw rgba(0,0,0,…) fallback
+ * vanished on dark surfaces), and the text is --hi-color-text-primary —
+ * the token family defines NO --hi-color-text, so the old fallback
+ * (#1f2328, light-theme ink) used to repaint the glyph near-black on a
+ * dark strip, i.e. unreadable exactly after the tap (2026-10-18 report).
+ * The host knob --hk-breadcrumb-more-hover still wins if declared. */
+.hk-modal-breadcrumb-more:hover,
+.hk-modal-breadcrumb-more[aria-expanded="true"] {
+  background: var(
+    --hk-breadcrumb-more-hover,
+    var(--c-primary-subtle, rgb(var(--color-primary, 122 162 247) / 8%))
+  );
+  color: var(--hi-color-text-primary, rgb(var(--color-text, 30 30 30)));
 }
 
 .hk-modal-breadcrumb-more:focus-visible {
@@ -119,7 +132,7 @@
   outline-offset: 1px;
 }
 
-/* The hidden-layers menu rides HkPopover, so it inherits the family's
+/* The all-layers menu rides HkPopover, so it inherits the family's
    dropdown chrome and mobile-sheet form. Only the inset is re-anchored:
    the popover panel already pads 4px, and HkMenuPanel's drawer-scale 12px
    inset on top of it read as a double margin. */
@@ -128,7 +141,7 @@
 }
 
 /* A visible-but-cut label is tappable: it opens the whole name in the same
-   popover family as the hidden-layers menu. The strip is pointer-
+   popover family as the all-layers menu. The strip is pointer-
    transparent, so only these buttons (and the "…" trigger) take the click. */
 .hk-modal-breadcrumb-item-reveal {
   /* No padding: the strip's ruler measures a plain item, so a padded
@@ -160,8 +173,14 @@
 
 .hk-modal-breadcrumb-item-reveal:hover,
 .hk-modal-breadcrumb-item-reveal[aria-expanded="true"] {
-  background: var(--hk-breadcrumb-more-hover, rgba(0, 0, 0, 0.06));
-  color: var(--hi-color-text, #1f2328);
+  /* Same token contract as the "…" trigger above (see there): sticky
+   * touch hover makes this face linger after the tap, so it must stay
+   * legible on dark surfaces too. */
+  background: var(
+    --hk-breadcrumb-more-hover,
+    var(--c-primary-subtle, rgb(var(--color-primary, 122 162 247) / 8%))
+  );
+  color: var(--hi-color-text-primary, rgb(var(--color-text, 30 30 30)));
 }
 
 .hk-modal-breadcrumb-item-reveal:focus-visible {
@@ -170,7 +189,9 @@
 }
 
 /* The revealed name itself: the strip's own type, wrapping instead of
-   cutting, and selectable (the strip around it is not). */
+   cutting, and selectable (the strip around it is not). Same token
+   contract as the trigger faces above — --hi-color-text does not exist
+   in any theme, and its light-ink fallback was unreadable on dark. */
 .hk-modal-breadcrumb-reveal {
   margin: 0;
   padding: var(--space-8, 0.5rem) var(--space-12, 0.75rem);
@@ -178,7 +199,7 @@
   font-size: var(--text-xs, 0.75rem);
   font-weight: 600;
   line-height: 1.5;
-  color: var(--hi-color-text, #1f2328);
+  color: var(--hi-color-text-primary, rgb(var(--color-text, 30 30 30)));
   overflow-wrap: anywhere;
   user-select: text;
 }

package/src/components/HkModalBreadcrumb.test.tsx

@@ -483,7 +483,7 @@ describe("HkModalBreadcrumb label budget", () => {
     expect(document.body.querySelector(".hk-modal-breadcrumb-reveal")).toBeNull();
   });
 
-  it("opens the reveal instead of the hidden-layers menu", async () => {
+  it("opens the reveal instead of the all-layers menu", async () => {
     // The two surfaces are never open together: tapping a crumb closes the
     // menu it was opened from (its leave plays out, so the logical state is
     // what the assertion reads).
@@ -905,34 +905,52 @@ describe("HkModalBreadcrumb overflow fold", () => {
   });
 });
 
-describe("HkModalBreadcrumb hidden-layers menu", () => {
+describe("HkModalBreadcrumb all-layers menu", () => {
   function registerStack(extraTitle: string): void {
     STACK_TITLES.forEach((title) => manager.register("modal", true, title));
     manager.register("modal", true, extraTitle);
   }
 
-  it("lists the folded layers with their full names", async () => {
+  it("lists every layer reversed, full names, current row selected", async () => {
     setViewport(360);
     registerStack("细节");
     await mountStrip();
     const allTitles = [...STACK_TITLES, "细节"];
-    // The tail that stays on the strip before the menu opens: the menu
-    // snapshots exactly the layers this run folds away.
-    const tailBefore = labels();
     expect(more()).not.toBeNull();
-    expect(tailBefore.length).toBeGreaterThan(0);
-    expect(tailBefore.length).toBeLessThan(allTitles.length);
 
     more()!.click();
     await nextTick();
     await nextTick();
     const rows = menuRows();
-    // Full names, in stack order — the strip's clamp never reaches here.
+    // EVERY layer, topmost first (reverse stack order) — not just the
+    // folded prefix — with full names: the strip's clamp never reaches
+    // here.
     expect(rows.map((row) => row.textContent)).toEqual(
-      allTitles.slice(0, allTitles.length - tailBefore.length),
+      allTitles.slice().reverse(),
     );
-    expect(rows.map((row) => row.textContent)).not.toContain(LONG_TAIL);
     expect(rows.some((row) => row.textContent?.includes("…"))).toBe(false);
+    // The current layer is marked with the unified menu-item grammar's
+    // selected face (HkMenuActionItem `active` → [data-active]), and it
+    // is the ONLY selected row.
+    const selected = rows.filter((row) => row.hasAttribute("data-active"));
+    expect(selected).toHaveLength(1);
+    expect(selected[0].textContent).toBe("细节");
+  });
+
+  it("never lists the menu's own sheet among the layers", async () => {
+    setViewport(360);
+    registerStack("细节");
+    await mountStrip();
+    more()!.click();
+    await nextTick();
+    await nextTick();
+    // The sheet form registered as a blocking layer (the strip itself
+    // lists it as a crumb — see the docking test below), yet the menu's
+    // rows stay the WINDOWS only: selecting "the menu" is not a place
+    // to go.
+    const rows = menuRows();
+    expect(rows.map((row) => row.textContent)).not.toContain("All layers");
+    expect(rows).toHaveLength(STACK_TITLES.length + 1);
   });
 
   it("docks the menu as a bottom-up sheet on mobile", async () => {
@@ -950,12 +968,12 @@ describe("HkModalBreadcrumb hidden-layers menu", () => {
     // window layer — it is named, and it counts as a layer of the stack it
     // was opened from.
     const blocking = [...manager.registry.value.values()].filter((entry) => entry.blocking);
-    expect(blocking.map((entry) => entry.title)).toContain("Hidden layers");
+    expect(blocking.map((entry) => entry.title)).toContain("All layers");
     // It is a window layer in every sense — including naming itself as the
     // current crumb of the very strip it was opened from.
     expect(
       strip()!.querySelector(".hk-modal-breadcrumb-item-current")!.textContent,
-    ).toBe("Hidden layers");
+    ).toBe("All layers");
   });
 
   it("drops the trigger and the menu once the stack stops folding", async () => {
@@ -971,8 +989,9 @@ describe("HkModalBreadcrumb hidden-layers menu", () => {
     expect(more()!.getAttribute("aria-expanded")).toBe("true");
 
     // Wide enough for the whole stack, still the same form factor (so the
-    // popover's own breakpoint rule is not what closes it): nothing is left
-    // to list, and the trigger the menu is anchored to must go with it.
+    // popover's own breakpoint rule is not what closes it): the strip now
+    // shows every layer itself, and the trigger the menu is anchored to
+    // goes with it.
     setViewport(760);
     await until(
       () =>
@@ -993,7 +1012,7 @@ describe("HkModalBreadcrumb hidden-layers menu", () => {
     const panel = document.body.querySelector<HTMLElement>(".hk-popover-panel")!;
     expect(panel).toBeTruthy();
     expect(panel.classList.contains("hk-is-sheet")).toBe(false);
-    expect(panel.getAttribute("aria-label")).toBe("Hidden layers");
+    expect(panel.getAttribute("aria-label")).toBe("All layers");
     expect(document.body.querySelector(".hk-popover-scrim")).toBeNull();
     // Anchored = a hidden level: nothing new joins the window stack.
     expect([...manager.registry.value.values()].filter((entry) => entry.blocking)).toHaveLength(0);
@@ -1015,15 +1034,19 @@ describe("HkModalBreadcrumb hidden-layers menu", () => {
     await nextTick();
     const rows = menuRows();
     expect(rows.length).toBeGreaterThan(1);
-    expect(rows[0].textContent).toBe(LONG);
+    // Reversed order: the topmost layer (the no-close-channel one) leads.
+    expect(rows[0].textContent).toBe("没有关闭通道的层级占位文本");
 
-    // Pick the SECOND folded layer: everything above it closes, it and
+    // Rows are reverse stack order: past the no-channel topmost (row 0),
+    // rows[k] is STACK_TITLES[STACK_TITLES.length - k] — pick k = 3,
+    // i.e. STACK_TITLES[5]; everything above it closes, it and
     // everything below it stay.
-    rows[1].click();
+    rows[3].click();
     await nextTick();
-    expect(closes[0]).not.toHaveBeenCalled();
-    expect(closes[1]).not.toHaveBeenCalled();
-    for (let i = 2; i < closes.length; i++) {
+    for (let i = 0; i <= 5; i++) {
+      expect(closes[i]).not.toHaveBeenCalled();
+    }
+    for (let i = 6; i < closes.length; i++) {
       expect(closes[i]).toHaveBeenCalledTimes(1);
     }
     expect(manager.registry.value.has(noChannel.id)).toBe(true);

package/src/components/HkModalBreadcrumb.tokens.contract.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Source contract for the strip's trigger/reveal interaction face.
+ *
+ * The behavioural suite runs in happy-dom, which resolves no theme
+ * custom properties — a rule that falls back to a WRONG literal paints
+ * fine in the suite and breaks only in a real theme. That is exactly
+ * what shipped: the hover/open faces colored their glyphs with a
+ * var() reference to --hi-color-text (fallback #1f2328) — a token NO
+ * theme defines (the family spells it --hi-color-text-primary), so the
+ * light-theme ink #1f2328 won
+ * — and on a phone the tap leaves :hover stuck, making the "…" trigger
+ * near-invisible on every dark theme right after the tap (2026-10-18
+ * user report). The pins live here, next to the reason each exists.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const scss = readFileSync(join(here, "HkModalBreadcrumb.scss"), "utf-8");
+
+function rule(selector: string): string {
+  return scss.match(new RegExp(`${selector}\\s*{[^}]*}`, "m"))?.[0] ?? "";
+}
+
+describe("HkModalBreadcrumb trigger face tokens", () => {
+  it("never references the nonexistent --hi-color-text alias", () => {
+    // The alias family defines --hi-color-text-primary; --hi-color-text
+    // does not exist, so any var() use silently takes its light-theme
+    // fallback. (Matched as var() usage so prose in comments about the
+    // alias itself stays legal.)
+    expect(scss).not.toMatch(/var\(\s*--hi-color-text[,)]/);
+  });
+
+  it("paints the trigger's hover AND open face from live theme tokens", () => {
+    // One legible face for both states: the tap on a phone leaves :hover
+    // stuck on the trigger, so aria-expanded must share the rule.
+    const group = scss.match(
+      /\.hk-modal-breadcrumb-more:hover,\s*\n\.hk-modal-breadcrumb-more\[aria-expanded="true"\]\s*{[^}]*}/,
+    )?.[0];
+    expect(group).toBeTruthy();
+    expect(group).toContain("var(--hi-color-text-primary");
+    // The wash falls back to the menu-item grammar's own primary-subtle —
+    // a raw rgba(0,0,0,…) fallback vanished on dark surfaces.
+    expect(group).toContain("var(--c-primary-subtle");
+    expect(group).not.toContain("rgba(0, 0, 0");
+    // The host knob still wins when declared.
+    expect(group).toContain("--hk-breadcrumb-more-hover");
+  });
+
+  it("gives the cut-label reveal button the same token contract", () => {
+    const group = scss.match(
+      /\.hk-modal-breadcrumb-item-reveal:hover,\s*\n\.hk-modal-breadcrumb-item-reveal\[aria-expanded="true"\]\s*{[^}]*}/,
+    )?.[0];
+    expect(group).toBeTruthy();
+    expect(group).toContain("var(--hi-color-text-primary");
+    expect(group).toContain("var(--c-primary-subtle");
+    expect(group).not.toContain("rgba(0, 0, 0");
+  });
+
+  it("keeps the base faces on the tokens the strip already used", () => {
+    // Untouched by the fix, pinned so a refactor cannot quietly
+    // reintroduce a raw literal here either.
+    expect(rule(".hk-modal-breadcrumb-more")).toContain(
+      "color: var(--hi-color-text-secondary",
+    );
+    expect(rule(".hk-modal-breadcrumb-item")).toContain(
+      "color: var(--hi-color-text-secondary",
+    );
+  });
+
+  it("colors the revealed full name from a live token too", () => {
+    // The reveal body text rode the same broken alias — near-black ink
+    // on every dark theme.
+    expect(rule(".hk-modal-breadcrumb-reveal")).toContain(
+      "color: var(--hi-color-text-primary",
+    );
+  });
+});

package/src/components/HkModalBreadcrumb.tsx

@@ -71,7 +71,7 @@ export default defineComponent({
      * both viewport edges (2026-09-16 report). The ellipsis counts inside the
      * budget: a 10-unit cap renders ten ideographs, or nine plus the
      * ellipsis. Full names stay in the DOM for assistive tech and in the
-     * hidden-layers menu.
+     * all-layers menu.
      */
     maxLabelUnits: { type: Number, default: 10 },
     /**
@@ -287,16 +287,40 @@ export default defineComponent({
     const tail = computed(() => crumbs.value.slice(hiddenCount.value));
     const folded = computed(() => hidden.value.length > 0);
 
-    // ── Hidden-layers menu ────────────────────────────────────────────
-    // The trigger lists the layers it folded away, in stack order, with
-    // their FULL names — the strip's clamp never reaches this menu.
-    // HkPopover owns the form-factor rules (anchored under the trigger on
-    // desktop, bottom-up sheet on mobile) and registers the surface with
-    // the popup manager, so the menu is a first-class layer of the very
-    // stack it lists.
+    // ── All-layers menu ──────────────────────────────────────────────
+    // The trigger lists EVERY layer of the stack, topmost first, with
+    // their FULL names — the strip's clamp never reaches this menu. The
+    // layer the user is currently on is marked with the menu row's own
+    // selected face (HkMenuActionItem `active` → the unified menu-item
+    // grammar's [data-active] box). HkPopover owns the form-factor rules
+    // (anchored under the trigger on desktop, bottom-up sheet on mobile)
+    // and registers the surface with the popup manager, so the menu is a
+    // first-class layer of the very stack it lists — and must not list
+    // ITSELF: the popover's `registered` handle tells this strip which
+    // layer to drop from the rows.
     const menuOpen = ref(false);
-    const menuItems = ref<{ id: string; label: string }[]>([]);
-    const menuLabel = computed(() => t("hikari::modal.hiddenLayers", "Hidden layers"));
+    const menuSheetId = ref<string | null>(null);
+    const menuLabel = computed(() => t("hikari::modal.allLayers", "All layers"));
+
+    /** Live rows: every stack layer but the menu's own surface, topmost
+     *  first (reverse stack order — the current layer leads the list).
+     *  Live, not a snapshot, so an anchored desktop menu keeps agreeing
+     *  with a stack that changed underneath it. */
+    const menuItems = computed<{ id: string; label: string; current: boolean }[]>(() => {
+      const layers = stackEntries.value.filter((entry) => entry.id !== menuSheetId.value);
+      return layers
+        .slice()
+        .reverse()
+        .map((entry, i) => ({
+          id: entry.id,
+          label:
+            entry.title ||
+            (entry.kind === "dropdown"
+              ? t("hikari::modal.unnamedSheet", "Menu")
+              : t("hikari::modal.unnamedWindow", "Window")),
+          current: i === 0,
+        }));
+    });
 
     /** The trigger must stay mounted while its menu is open (the popover
      *  anchors to it); a stack change that unfolds everything mid-menu
@@ -304,29 +328,37 @@ export default defineComponent({
     const triggerShown = computed(() => folded.value || menuOpen.value);
 
     function openMenu(): void {
-      if (!hidden.value.length) return;
+      if (!crumbs.value.length) return;
       // The two surfaces are never open together — and the symmetric close
       // matters on a phone: the strip paints above the sheet's scrim, so
       // its trigger stays tappable while a reveal is docked (review round
       // two), and a menu opening underneath it would leave the pair
       // fighting over one Escape.
       revealed.value = null;
-      menuItems.value = hidden.value.map(({ id, label }) => ({ id, label }));
       menuOpen.value = true;
     }
 
-    /** Jump back to a folded layer: the menu closes and everything stacked
+    /** Jump to a listed layer: the menu closes and everything stacked
      *  ABOVE the chosen level is asked to close, top-down. The close rides
      *  the popup manager's per-entry close channel, so a layer whose owner
      *  registered none simply stays — the strip never guesses at foreign
-     *  state. */
+     *  state. The CURRENT layer sits on top with nothing above it, so
+     *  picking it just dismisses the menu. */
     function selectLayer(id: string): void {
       menuOpen.value = false;
       manager.closeAbove(id);
     }
 
-    // Unfolding everything while the menu is open leaves nothing to list:
-    // drop the menu rather than keep a stale snapshot on screen.
+    // The menu's own sheet id is only meaningful while that surface lives;
+    // drop it when the surface goes so a FUTURE popover registration is
+    // never mistaken for "the menu".
+    function onMenuClosed(): void {
+      menuSheetId.value = null;
+    }
+
+    // Unfolding everything while the menu is open dissolves the trigger's
+    // reason to exist — the strip itself now shows every layer, so the
+    // anchored pair steps aside instead of duplicating it.
     watch(folded, (stillFolded) => {
       if (!stillFolded) menuOpen.value = false;
     });
@@ -702,12 +734,20 @@ export default defineComponent({
             sheetOnMobile
             title={menuLabel.value}
             class="hk-modal-breadcrumb-menu"
+            // The menu's own registry handle: while the sheet form blocks,
+            // it is a layer of the very stack this menu lists — the rows
+            // must skip it (selecting "the menu" is not a place to go).
+            onRegistered={(handle: { id: string }) => {
+              menuSheetId.value = handle.id;
+            }}
+            onClosed={onMenuClosed}
           >
             <HkMenuPanel label={menuLabel.value}>
               {menuItems.value.map((item) => (
                 <HkMenuActionItem
                   key={item.id}
                   label={item.label}
+                  active={item.current}
                   onClick={() => selectLayer(item.id)}
                 />
               ))}

package/src/components/HkPopover.tsx

@@ -85,6 +85,12 @@ export default defineComponent({
   },
   emits: {
     "update:modelValue": (_v: boolean) => true,
+    /** Fired when the surface joins the popup registry — the handle
+     *  (id + zIndex) is the surface's identity as a stack layer. Hosts
+     *  that reason about the WINDOW STACK (the modal breadcrumb listing
+     *  every layer but its own sheet) use this edge to tell the
+     *  popover's layer apart from the windows it floats above. */
+    registered: (_handle: PopupHandle) => true,
     /** Fired once the close has fully settled (the leave transition
      * completed and the panel left the DOM) — the moment focus that
      * lived inside the closing panel falls back to <body>. Hosts that
@@ -169,13 +175,15 @@ export default defineComponent({
           // they govern accidental DISMISSAL GESTURES, not closability, and
           // the sheet always renders its own ✕ (this popover has no
           // `closable` to mirror HkModal's).
-          handle.value = manager.register(
+          const registered = manager.register(
             "dropdown",
             false,
             props.title || undefined,
             sheetMode.value,
             close,
           );
+          handle.value = registered;
+          emit("registered", registered);
           if (sheetMode.value) {
             // Bottom sheet: nothing to anchor-measure; the scrim handles
             // dismissal (the outside-click shield is desktop-only).

package/src/components/HkThemeToggle.scss

@@ -96,7 +96,12 @@
   cursor: pointer;
   user-select: none;
   -webkit-user-select: none;
-  -webkit-tap-highlight-color: transparent;
+  /* Same policy as the canonical reset; keeps standalone component styles
+     working and lets the document-level native escape hatch through. */
+  -webkit-tap-highlight-color: var(--hk-tap-highlight-color, transparent);
+  html[data-hk-tap-highlight='native'] & {
+    -webkit-tap-highlight-color: revert;
+  }
   appearance: none;
   transition: color 0.15s ease, background 0.15s ease, transform 0.12s ease;
 }

package/src/components/_menu-item.scss

@@ -133,7 +133,13 @@
   appearance: none;
   user-select: none;
   -webkit-user-select: none;
-  -webkit-tap-highlight-color: transparent;
+  /* Ride the canonical reset policy: this component sheet is also exported
+     standalone, so it keeps the token fallback (transparent) and honours the
+     document-level native escape hatch. */
+  -webkit-tap-highlight-color: var(--hk-tap-highlight-color, transparent);
+  html[data-hk-tap-highlight='native'] & {
+    -webkit-tap-highlight-color: revert;
+  }
   transition: background-color 0.12s ease, border-color 0.12s ease, color 0.12s ease;
 
   &:hover:not(:disabled):not([data-disabled]):not([data-active]):not([data-checked]) {

package/src/demo.ts

@@ -3,8 +3,9 @@ import { createApp } from 'vue'
 import { initTheme } from './theme/useTheme'
 import * as hikari from './index'
 
-// Mobile UX contract (viewport zoom never refused; tap-highlight lives in
-// foundation.scss). Applied at bootstrap before mount, per the hook contract.
+// Mobile UX contract (viewport zoom never refused; the tap-highlight reset
+// lives in the canonical host reset, styles/reset.scss). Applied at
+// bootstrap before mount, per the hook contract.
 hikari.applyViewportPolicy({ allowZoomOut: true })
 
 localStorage.setItem('hikari-theme', 'default')

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

@@ -240,7 +240,7 @@
   "hikari::tagInput.remove": "إزالة",
   "hikari::tagInput.addCustom": "استخدام \"{q}\"",
   "hikari::tagInput.reorder": "إعادة الترتيب — {label}",
-  "hikari::modal.hiddenLayers": "الطبقات المخفية",
+  "hikari::modal.allLayers": "جميع الطبقات",
   "hikari::theme.modeTabHint": "هذه التبويبات تختار لوحة الألوان التي تحرّرها؛ لتبديل الوضع الفاتح/الداكن للتطبيق كله استخدم شريط الأوضاع أعلى نافذة السمة",
   "hikari::theme.defaultThemeName": "افتراضي",
   "hikari::emptyState.loading": "جارٍ التحميل",

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

@@ -240,7 +240,7 @@
   "hikari::tagInput.remove": "Entfernen",
   "hikari::tagInput.addCustom": "„{q}“ verwenden",
   "hikari::tagInput.reorder": "Neu anordnen — {label}",
-  "hikari::modal.hiddenLayers": "Verdeckte Ebenen",
+  "hikari::modal.allLayers": "Alle Ebenen",
   "hikari::theme.modeTabHint": "Diese Reiter wählen die zu bearbeitende Palette; die appweite Hell/Dunkel-Umschaltung liegt im Modusstreifen des Themen-Popups",
   "hikari::theme.defaultThemeName": "Standard",
   "hikari::emptyState.loading": "Wird geladen",

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

@@ -240,7 +240,7 @@
   "hikari::tagInput.remove": "Remove",
   "hikari::tagInput.addCustom": "Use “{q}”",
   "hikari::tagInput.reorder": "Reorder {label}",
-  "hikari::modal.hiddenLayers": "Hidden layers",
+  "hikari::modal.allLayers": "All layers",
   "hikari::theme.modeTabHint": "These tabs pick which palette you are EDITING; to switch the app-wide light/dark, use the mode strip at the top of the theme popup",
   "hikari::theme.defaultThemeName": "Default",
   "hikari::emptyState.loading": "Loading",

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

@@ -240,7 +240,7 @@
   "hikari::tagInput.remove": "Quitar",
   "hikari::tagInput.addCustom": "Usar «{q}»",
   "hikari::tagInput.reorder": "Reordenar — {label}",
-  "hikari::modal.hiddenLayers": "Capas ocultas",
+  "hikari::modal.allLayers": "Todas las capas",
   "hikari::theme.modeTabHint": "Estas pestañas eligen la paleta que estás EDITANDO; para cambiar el modo claro/oscuro de toda la app, usa la franja de modos de la parte superior del panel de temas",
   "hikari::theme.defaultThemeName": "Predeterminado",
   "hikari::emptyState.loading": "Cargando",

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

@@ -240,7 +240,7 @@
   "hikari::tagInput.remove": "Retirer",
   "hikari::tagInput.addCustom": "Utiliser « {q} »",
   "hikari::tagInput.reorder": "Réorganiser — {label}",
-  "hikari::modal.hiddenLayers": "Couches masquées",
+  "hikari::modal.allLayers": "Toutes les couches",
   "hikari::theme.modeTabHint": "Ces onglets choisissent la palette éditée ; pour basculer clair/sombre dans toute l’app, utilisez la barre de mode du menu de thème",
   "hikari::theme.defaultThemeName": "Par défaut",
   "hikari::emptyState.loading": "Chargement",

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

@@ -240,7 +240,7 @@
   "hikari::tagInput.remove": "削除",
   "hikari::tagInput.addCustom": "「{q}」を使用",
   "hikari::tagInput.reorder": "並べ替え — {label}",
-  "hikari::modal.hiddenLayers": "非表示の階層",
+  "hikari::modal.allLayers": "すべての階層",
   "hikari::theme.modeTabHint": "このタブは編集対象のパレットを選ぶだけです。アプリ全体の明/暗はテーマポップアップ上部のモードストリップで切り替えてください",
   "hikari::theme.defaultThemeName": "デフォルト",
   "hikari::emptyState.loading": "読み込み中",

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

@@ -240,7 +240,7 @@
   "hikari::tagInput.remove": "제거",
   "hikari::tagInput.addCustom": "\"{q}\" 사용",
   "hikari::tagInput.reorder": "순서 변경 — {label}",
-  "hikari::modal.hiddenLayers": "숨겨진 레이어",
+  "hikari::modal.allLayers": "모든 레이어",
   "hikari::theme.modeTabHint": "이 탭은 편집할 팔레트를 고를 뿐입니다. 앱 전체 밝기/어둠은 테마 팝업 상단의 모드 스트립에서 바꾸세요",
   "hikari::theme.defaultThemeName": "기본값",
   "hikari::emptyState.loading": "불러오는 중",

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

@@ -240,7 +240,7 @@
   "hikari::tagInput.remove": "Remover",
   "hikari::tagInput.addCustom": "Usar \"{q}\"",
   "hikari::tagInput.reorder": "Reordenar — {label}",
-  "hikari::modal.hiddenLayers": "Camadas ocultas",
+  "hikari::modal.allLayers": "Todas as camadas",
   "hikari::theme.modeTabHint": "Estas abas escolhem a paleta que você está EDITANDO; para alternar o claro/escuro do app inteiro, use a faixa de modos no topo do painel de temas",
   "hikari::theme.defaultThemeName": "Padrão",
   "hikari::emptyState.loading": "Carregando",

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

@@ -240,7 +240,7 @@
   "hikari::tagInput.remove": "Удалить",
   "hikari::tagInput.addCustom": "Использовать «{q}»",
   "hikari::tagInput.reorder": "Изменить порядок — {label}",
-  "hikari::modal.hiddenLayers": "Скрытые слои",
+  "hikari::modal.allLayers": "Все слои",
   "hikari::theme.modeTabHint": "Вкладки выбирают редактируемую палитру; общесистемное переключение светлой/тёмной — в полосе режимов вверху меню темы",
   "hikari::theme.defaultThemeName": "По умолчанию",
   "hikari::emptyState.loading": "Загрузка",

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

@@ -244,7 +244,7 @@
   "hikari::tagInput.remove": "移除",
   "hikari::tagInput.addCustom": "使用「{q}」",
   "hikari::tagInput.reorder": "拖动排序 — {label}",
-  "hikari::modal.hiddenLayers": "隐藏层级",
+  "hikari::modal.allLayers": "所有层级",
   "hikari::theme.modeTabHint": "切换这里编辑的是对应模式的调色板；要切换应用整体深/浅，请用主题弹窗顶部的模式条",
   "hikari::theme.defaultThemeName": "默认",
   "hikari::emptyState.loading": "加载中",

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

@@ -244,7 +244,7 @@
   "hikari::tagInput.remove": "移除",
   "hikari::tagInput.addCustom": "使用「{q}」",
   "hikari::tagInput.reorder": "拖曳排序 — {label}",
-  "hikari::modal.hiddenLayers": "隱藏層級",
+  "hikari::modal.allLayers": "所有層級",
   "hikari::theme.modeTabHint": "切換這裡編輯的是對應模式的調色盤；要切換應用整體深/淺，請用主題彈窗頂部的模式條",
   "hikari::theme.defaultThemeName": "預設",
   "hikari::emptyState.loading": "載入中",

package/src/i18n/modalKeys.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
 
 /**
  * The `hikari::modal.*` family is the window chrome's own vocabulary
- * (stack label, unnamed-window/sheet fallbacks, the hidden-layers menu),
+ * (stack label, unnamed-window/sheet fallbacks, the all-layers menu),
  * referenced from source by literal key with an English fallback.
  *
  * flatKeyParity.test.ts proves the locales AGREE with en — but it takes
@@ -23,7 +23,7 @@ const REQUIRED_KEYS = [
   "hikari::modal.stackLabel",
   "hikari::modal.unnamedSheet",
   "hikari::modal.unnamedWindow",
-  "hikari::modal.hiddenLayers",
+  "hikari::modal.allLayers",
 ];
 
 describe("hikari::modal locale keys", () => {

package/src/index.ts

@@ -391,6 +391,9 @@ export {
   type HkTooltipBridgeOptions,
   installHkImageFallback,
   type HkImageFallbackOptions,
+  installHkTapHighlight,
+  type HkTapHighlightOptions,
+  type HkTapHighlightColor,
   reportHkRuntime,
   getHkRuntimeEntry,
   listHkRuntime,

package/src/runtime/index.ts

@@ -12,6 +12,11 @@ export {
   installHkImageFallback,
   type HkImageFallbackOptions,
 } from "./imageFallback";
+export {
+  installHkTapHighlight,
+  type HkTapHighlightOptions,
+  type HkTapHighlightColor,
+} from "./tapHighlight";
 export {
   tooltipPositionStyle,
   applyTooltipPosition,

package/src/runtime/mobileViewport.ts

@@ -84,9 +84,11 @@ function clampOutScale(scale: number): string {
  * Normalize the document's viewport meta so mobile browsers never refuse
  * user zoom. Idempotent; safe to call during app bootstrap before mount.
  *
- * The tap-highlight half of the mobile UX contract lives in the stylesheet
- * foundation (`foundation.scss` clears `-webkit-tap-highlight-color`
- * globally) and needs no JS.
+ * The tap-highlight half of the mobile UX contract lives in the canonical
+ * host reset (`styles/reset.scss`, composed first by `styles/index.scss`):
+ * it clears `-webkit-tap-highlight-color` at the root, and
+ * `installHkTapHighlight()` is the runtime policy layer for hosts that
+ * need a themed tint or the iOS :active enabler.
  */
 export function applyViewportPolicy(
   options: ApplyViewportPolicyOptions = {},

package/src/runtime/tapHighlight.test.ts

@@ -0,0 +1,134 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { getHkRuntimeEntry, readHkRuntime } from "./registry";
+import { installHkTapHighlight } from "./tapHighlight";
+
+/**
+ * installHkTapHighlight contract tests:
+ * - default policy clears the UA overlay at the root
+ * - a CSS colour keeps the mechanism and tints it
+ * - "native" restores the browser default through the data attribute
+ * - invalid colours fall back to transparent instead of the UA default
+ * - the iOS :active enabler is a passive document touchstart, removable
+ * - install is idempotent per document; uninstall restores prior inline
+ *   state and disposes the registry entry
+ */
+
+const TOKEN = "--hk-tap-highlight-color";
+const NATIVE_ATTR = "data-hk-tap-highlight";
+
+const uninstalls: Array<() => void> = [];
+
+function install(options?: Parameters<typeof installHkTapHighlight>[0]) {
+  const uninstall = installHkTapHighlight(options);
+  uninstalls.push(uninstall);
+  return uninstall;
+}
+
+function root(): HTMLElement {
+  return document.documentElement;
+}
+
+afterEach(() => {
+  for (const uninstall of uninstalls.splice(0)) uninstall();
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  root().removeAttribute("style");
+  root().removeAttribute(NATIVE_ATTR);
+});
+
+describe("installHkTapHighlight", () => {
+  it("clears the UA overlay at the root by default", () => {
+    install();
+    expect(root().style.getPropertyValue(TOKEN)).toBe("transparent");
+    expect(root().hasAttribute(NATIVE_ATTR)).toBe(false);
+  });
+
+  it("keeps a themed tint when a colour is given", () => {
+    install({ color: "rgb(47 111 237 / 12%)" });
+    expect(root().style.getPropertyValue(TOKEN)).toBe(
+      "rgb(47 111 237 / 12%)",
+    );
+  });
+
+  it("restores the UA default through the native escape hatch", () => {
+    install({ color: "native" });
+    expect(root().getAttribute(NATIVE_ATTR)).toBe("native");
+    expect(root().style.getPropertyValue(TOKEN)).toBe("");
+  });
+
+  it("falls back to transparent for an invalid colour", () => {
+    vi.stubGlobal("CSS", { supports: () => false });
+    install({ color: "not-a-colour" });
+    expect(root().style.getPropertyValue(TOKEN)).toBe("transparent");
+  });
+
+  it("adds a passive touchstart enabler and removes it on uninstall", () => {
+    const add = vi.spyOn(document, "addEventListener");
+    const remove = vi.spyOn(document, "removeEventListener");
+    const uninstall = install();
+    expect(add).toHaveBeenCalledWith("touchstart", expect.any(Function), {
+      passive: true,
+    });
+    uninstall();
+    expect(remove).toHaveBeenCalledWith("touchstart", expect.any(Function));
+  });
+
+  it("can opt out of the active-state enabler", () => {
+    const add = vi.spyOn(document, "addEventListener");
+    install({ enableActiveState: false });
+    expect(add).not.toHaveBeenCalledWith(
+      "touchstart",
+      expect.any(Function),
+      expect.anything(),
+    );
+  });
+
+  it("restores a pre-existing inline token and attribute on uninstall", () => {
+    root().style.setProperty(TOKEN, "red");
+    root().setAttribute(NATIVE_ATTR, "native");
+    const uninstall = install({ color: "blue" });
+    expect(root().style.getPropertyValue(TOKEN)).toBe("blue");
+    expect(root().hasAttribute(NATIVE_ATTR)).toBe(false);
+    uninstall();
+    expect(root().style.getPropertyValue(TOKEN)).toBe("red");
+    expect(root().getAttribute(NATIVE_ATTR)).toBe("native");
+  });
+
+  it("is idempotent per document (second install keeps the first policy)", () => {
+    install({ color: "red" });
+    install({ color: "blue" });
+    expect(root().style.getPropertyValue(TOKEN)).toBe("red");
+  });
+
+  it("treats an uninstaller from a replaced install as a no-op", () => {
+    const first = install({ color: "red" });
+    first();
+    install({ color: "blue" });
+    first();
+    expect(root().style.getPropertyValue(TOKEN)).toBe("blue");
+  });
+
+  it("reports the effective colour and disposes the registry entry", () => {
+    vi.stubGlobal("CSS", { supports: () => false });
+    const uninstall = install({
+      color: "not-a-colour",
+      enableActiveState: false,
+    });
+    expect(readHkRuntime("tapHighlight")).toMatchObject({
+      color: "none",
+      requestedColor: "not-a-colour",
+    });
+    expect(getHkRuntimeEntry("tapHighlight")?.status).toBe("active");
+    uninstall();
+    expect(getHkRuntimeEntry("tapHighlight")?.status).toBe("disposed");
+    expect(readHkRuntime("tapHighlight")).toBeUndefined();
+  });
+
+  it("no-ops without a DOM", () => {
+    vi.stubGlobal("document", undefined);
+    const uninstall = installHkTapHighlight();
+    expect(typeof uninstall).toBe("function");
+    expect(() => uninstall()).not.toThrow();
+  });
+});

package/src/runtime/tapHighlight.ts

@@ -0,0 +1,169 @@
+// installHkTapHighlight — document-level policy for the UA tap highlight.
+//
+// Blink/WebKit paint a platform-owned translucent overlay over the tapped
+// node (Android Chrome measures rgba(51, 181, 229, 0.4) in mobile
+// emulation). The canonical host reset (styles/reset.scss) already clears
+// it at the root and exposes two declarative knobs:
+//
+//   --hk-tap-highlight-color: transparent   → no overlay (the default)
+//   --hk-tap-highlight-color: <CSS color>   → keep the feedback, tint it
+//   html[data-hk-tap-highlight="native"]    → restore the UA default
+//
+// This hook is the runtime policy layer on top of that contract. It also
+// enables `:active` on iOS Safari: WebKit only applies the pseudo-class
+// when a touch listener exists (WebKit bug 138816), so clearing the UA
+// overlay must not leave taps without a pressed state.
+//
+// Lifecycle mirrors installHkImageFallback: idempotent per document,
+// returns the uninstaller, restores the previous inline token/attribute,
+// and reports itself to the runtime registry.
+
+import { reportHkRuntime } from "./registry";
+import type { HkRuntimeHandle } from "./registry";
+
+export type HkTapHighlightColor = "none" | "native" | (string & {});
+
+export interface HkTapHighlightOptions {
+  /**
+   * "none" clears the UA overlay (the app convention); "native" restores
+   * the browser default; any other valid CSS color keeps the feedback but
+   * tints it — e.g. `rgb(var(--color-primary) / 12%)`.
+   */
+  color?: HkTapHighlightColor;
+  /**
+   * Enable `:active` on iOS Safari with a passive document touchstart
+   * listener (default true). Removing the UA highlight makes the pressed
+   * state the only feedback, so this is on by default; hosts with their
+   * own touch handling may opt out.
+   */
+  enableActiveState?: boolean;
+}
+
+const TOKEN = "--hk-tap-highlight-color";
+const NATIVE_ATTR = "data-hk-tap-highlight";
+const TRANSPARENT = "transparent";
+
+interface TapHighlightState {
+  doc: Document;
+  root: HTMLElement;
+  previousToken: string;
+  previousNative: string | null;
+  enableActiveState: boolean;
+  onTouchStart: EventListener;
+  installedColor: HkTapHighlightColor;
+  requestedColor: HkTapHighlightColor;
+  runtime?: HkRuntimeHandle;
+}
+
+const INSTALLS = new WeakMap<Document, TapHighlightState>();
+
+function noop(): void {}
+
+function normalizeColor(color: HkTapHighlightColor | undefined): {
+  token: string | null;
+  native: boolean;
+  effective: HkTapHighlightColor;
+} {
+  if (color === undefined || color === "none") {
+    return { token: TRANSPARENT, native: false, effective: "none" };
+  }
+  if (color === "native") {
+    return { token: null, native: true, effective: "native" };
+  }
+  // Validate against the property so a bad host value cannot become an
+  // "invalid at computed-value time" flash of the UA default colour.
+  const supported =
+    typeof CSS === "undefined" ||
+    typeof CSS.supports !== "function" ||
+    CSS.supports("-webkit-tap-highlight-color", color);
+  return supported
+    ? { token: color, native: false, effective: color }
+    : { token: TRANSPARENT, native: false, effective: "none" };
+}
+
+function uninstall(state: TapHighlightState): void {
+  // A teardown from a previous install must not clear the policy that
+  // replaced it (uninstall → reinstall → call the old uninstaller).
+  if (INSTALLS.get(state.doc) !== state) return;
+  INSTALLS.delete(state.doc);
+  if (state.enableActiveState) {
+    state.doc.removeEventListener("touchstart", state.onTouchStart);
+  }
+  if (state.previousToken) {
+    state.root.style.setProperty(TOKEN, state.previousToken);
+  } else {
+    state.root.style.removeProperty(TOKEN);
+  }
+  if (state.previousNative === null) {
+    state.root.removeAttribute(NATIVE_ATTR);
+  } else {
+    state.root.setAttribute(NATIVE_ATTR, state.previousNative);
+  }
+  state.runtime?.dispose();
+}
+
+/**
+ * Install the document-level tap-highlight policy. Returns the
+ * uninstaller; idempotent per document (a second call returns the
+ * existing teardown). No-op outside a DOM.
+ */
+export function installHkTapHighlight(
+  options: HkTapHighlightOptions = {},
+): () => void {
+  if (typeof document === "undefined") return () => undefined;
+  const doc = document;
+  const existing = INSTALLS.get(doc);
+  if (existing) return () => uninstall(existing);
+
+  const root = doc.documentElement;
+  const { token, native, effective } = normalizeColor(options.color);
+  const enableActiveState = options.enableActiveState ?? true;
+  const requestedColor = options.color ?? "none";
+  const state: TapHighlightState = {
+    doc,
+    root,
+    previousToken: root.style.getPropertyValue(TOKEN),
+    previousNative: root.getAttribute(NATIVE_ATTR),
+    enableActiveState,
+    onTouchStart: noop,
+    installedColor: effective,
+    requestedColor,
+  };
+
+  if (token === null) {
+    root.style.removeProperty(TOKEN);
+  } else {
+    root.style.setProperty(TOKEN, token);
+  }
+  if (native) {
+    root.setAttribute(NATIVE_ATTR, "native");
+  } else {
+    root.removeAttribute(NATIVE_ATTR);
+  }
+
+  if (enableActiveState) {
+    doc.addEventListener("touchstart", state.onTouchStart, { passive: true });
+  }
+
+  state.runtime = reportHkRuntime("tapHighlight", {
+    kind: "hook",
+    description:
+      "Document-level mobile tap-highlight policy: clears or tints the UA overlay and enables :active on iOS.",
+    meta: {
+      color: state.installedColor,
+      requestedColor: state.requestedColor,
+      activeState: enableActiveState,
+      native,
+    },
+    read: () => ({
+      installed: true,
+      color: state.installedColor,
+      requestedColor: state.requestedColor,
+      activeState: enableActiveState,
+      native,
+    }),
+  });
+
+  INSTALLS.set(doc, state);
+  return () => uninstall(state);
+}

package/src/styles/reset.scss

@@ -25,6 +25,25 @@
 
 html {
   line-height: 1.5;
+
+  /* Mobile tap highlight (UA-owned): Blink/WebKit paint a translucent
+   * overlay over the tapped node — Android Chrome measures
+   * rgba(51, 181, 229, 0.4) in mobile emulation. The property is
+   * inherited, so this root declaration covers every element (including
+   * shadow trees). Hosts opt into a themed tint with
+   * --hk-tap-highlight-color, or restore the UA default with
+   * data-hk-tap-highlight="native".
+   *
+   * This is the canonical home of the #325 tap-highlight contract. It
+   * first lived in the Gen-1 foundation sheet; #480 retired that sheet
+   * and #523/#861 replaced it with this reset, which then missed the
+   * rule — every host composing the canonical entry silently regained
+   * the blue flash. Keep it here, not in a host stylesheet. */
+  -webkit-tap-highlight-color: var(--hk-tap-highlight-color, transparent);
+}
+
+html[data-hk-tap-highlight='native'] {
+  -webkit-tap-highlight-color: revert;
 }
 
 body {

package/src/styles/resetSheet.test.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import * as sass from "sass";
 import { describe, expect, it } from "vitest";
 
 /**
@@ -31,6 +32,25 @@ describe("host reset sheet", () => {
     expect(first).toBe("./reset.scss");
   });
 
+  it("clears the UA tap highlight at the root (mobile parity)", () => {
+    // Regression guard for the #325 contract: #480 retired the Gen-1
+    // foundation sheet, and #523/#861 composed this reset without the
+    // tap rule, so chest/hydro silently re-gained the Android blue
+    // overlay. Removing either half of this contract must fail here.
+    //
+    // Assert on the COMPILED sheet (compressed drops both comment
+    // styles): raw-text matching would pass on a commented-out rule.
+    const { css } = sass.compile(resolve(stylesDir, "reset.scss"), {
+      style: "compressed",
+    });
+    expect(css).toMatch(
+      /html\s*\{[^}]*?-webkit-tap-highlight-color:\s*var\(--hk-tap-highlight-color,\s*transparent\)/,
+    );
+    expect(css).toMatch(
+      /html\[data-hk-tap-highlight=(?:"|')?native(?:"|')?\]\s*\{[^}]*?-webkit-tap-highlight-color:\s*revert/,
+    );
+  });
+
   it("normalizes the native control typography chain", () => {
     const reset = read("reset.scss");
     for (const selector of ["button,", "input,", "textarea"]) {