@celestia-island/hikari 0.55.335 → 0.55.337

package/package.json

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

package/src/components/HkNumberInput.test.tsx

@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h } from "vue";
+
+import HkNumberInput from "./HkNumberInput";
+
+/**
+ * HkNumberInput's label-association contract (#1206): a bare `label` prop
+ * used to render a <label> with NO programmatic association to the field
+ * (no `for`, no wrapping), so the number field announced as "spin button"
+ * to screen readers. Mirrors HkInput's contract — `for` points at the
+ * field id, which is `props.id` when given and a useId() generation
+ * otherwise — and follows the repo test convention (raw createApp +
+ * document queries, no @vue/test-utils).
+ */
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mountInput(props: Record<string, unknown>): HTMLElement {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => h(HkNumberInput, props) });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+describe("HkNumberInput label association (#1206)", () => {
+  it("associates a bare label with the field via for/id", () => {
+    const container = mountInput({ label: "Per-phone cap", modelValue: 10 });
+    console.log("HTML:", container.innerHTML.slice(0, 300));
+    const label = container.querySelector("label.hk-input-label");
+    const field = container.querySelector<HTMLInputElement>("input.hk-number-input-field");
+    expect(label).not.toBeNull();
+    expect(field).not.toBeNull();
+    expect(label!.getAttribute("for")).toBe(field!.id);
+    expect(field!.id).not.toBe("");
+  });
+
+  it("an explicit id prop wins over the generated one", () => {
+    const container = mountInput({ label: "Cap", modelValue: 1, id: "cap-field" });
+    const label = container.querySelector("label.hk-input-label");
+    const field = container.querySelector<HTMLInputElement>("input.hk-number-input-field");
+    expect(field!.id).toBe("cap-field");
+    expect(label!.getAttribute("for")).toBe("cap-field");
+  });
+
+  it("keeps field ids unique among instances of ONE app", () => {
+    // useId's counter is PER APP: two separate createApp mounts both start
+    // at v-0 (uniqueness is a within-app contract — a real host has one
+    // app). Two siblings in the same app must never share an id, or the
+    // second label's `for` would point at the FIRST field.
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    const app = createApp({
+      render: () =>
+        h("div", [
+          h(HkNumberInput, { modelValue: 1, label: "First" }),
+          h(HkNumberInput, { modelValue: 2, label: "Second" }),
+        ]),
+    });
+    app.mount(container);
+    mounts.push({ app, container });
+    const fields = [...container.querySelectorAll<HTMLInputElement>("input.hk-number-input-field")];
+    expect(fields).toHaveLength(2);
+    const ids = fields.map((f) => f.id);
+    expect(new Set(ids).size).toBe(2);
+    // Each label's `for` points at ITS OWN field, in document order.
+    const labels = [...container.querySelectorAll("label.hk-input-label")];
+    expect(labels[0]!.getAttribute("for")).toBe(ids[0]);
+    expect(labels[1]!.getAttribute("for")).toBe(ids[1]);
+  });
+});

package/src/components/HkNumberInput.tsx

@@ -1,4 +1,4 @@
-import { computed, defineComponent, ref, type PropType } from "vue";
+import { computed, defineComponent, ref, useId, type PropType } from "vue";
 import HkNumberSteppers from "./HkNumberSteppers";
 import "./HkNumberInput.scss";
 
@@ -12,6 +12,13 @@ export default defineComponent({
     disabled: { type: Boolean, default: false },
     placeholder: { type: String, default: undefined },
     label: { type: String, default: undefined },
+    /* `id` for the field element; the rendered label's `for` points here.
+       Generated via Vue's useId when omitted, so a bare `label` prop is
+       fully associated for screen readers and label clicks with zero
+       caller effort (HkInput's contract, same shape). Without this the
+       bare <label> had NO programmatic association at all — the field
+       announced as "spin button" (2026-11-10, #1206). */
+    id: { type: String, default: undefined },
     /* Affix text rendered INSIDE the field (before/after the input,
        flex-centered by the inner row). Slots of the same name take
        precedence; empty/undefined means no affix. Consumers should use
@@ -60,6 +67,13 @@ export default defineComponent({
       emitValue(props.modelValue - props.step);
     }
 
+    // Field identity: the rendered label points at this id, so a bare
+    // `label` prop gives a fully associated field (screen readers, label
+    // clicks). An explicit `id` prop wins. useId() must run synchronously
+    // in setup; it is SSR-safe (HkInput's same shape).
+    const generatedId = useId();
+    const fieldId = computed(() => props.id ?? generatedId);
+
     const wrapperClass = computed(() => [
       "hk-number-input",
       `hk-number-input-${props.size}`,
@@ -68,7 +82,7 @@ export default defineComponent({
 
     return () => (
       <div class={wrapperClass.value}>
-        {props.label && <label class="hk-input-label">{props.label}</label>}
+        {props.label && <label class="hk-input-label" for={fieldId.value}>{props.label}</label>}
         <div class="hk-number-input-inner">
           {(slots.prefix || props.prefix) ? (
             <span class="hk-number-input-prefix">
@@ -77,6 +91,7 @@ export default defineComponent({
           ) : null}
           <input
             ref={inputRef}
+            id={fieldId.value}
             type="number"
             class="hk-number-input-field"
             value={props.modelValue}

package/src/components/HkTreemap.test.tsx

@@ -139,6 +139,30 @@ afterEach(() => {
   globalThis.ResizeObserver = originalResizeObserver;
 });
 
+/** WCAG helpers for the ink assertions — an independent re-implementation of
+ *  the requirement (AA contrast), deliberately not the component's own code. */
+const srgbLinear = (channel: number) => {
+  const value = channel / 255;
+  return value <= 0.03928 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+};
+const hexChannels = (hex: string): [number, number, number] => {
+  const raw = hex.length === 4
+    ? hex.slice(1).split("").map((char) => char + char).join("")
+    : hex.slice(1);
+  return [
+    Number.parseInt(raw.slice(0, 2), 16),
+    Number.parseInt(raw.slice(2, 4), 16),
+    Number.parseInt(raw.slice(4, 6), 16),
+  ];
+};
+const luminanceOf = (rgb: readonly number[]) =>
+  0.2126 * srgbLinear(rgb[0]!) + 0.7152 * srgbLinear(rgb[1]!) + 0.0722 * srgbLinear(rgb[2]!);
+const contrastAgainst = (backgroundLuminance: number, ink: string) => {
+  const text = luminanceOf(hexChannels(ink));
+  return (Math.max(backgroundLuminance, text) + 0.05)
+    / (Math.min(backgroundLuminance, text) + 0.05);
+};
+
 describe("HkTreemap pure layout input", () => {
   it("sums nested groups from leaves and ignores caller-provided parent values", () => {
     const layout = buildHkTreemapLayout(NODES);
@@ -251,38 +275,78 @@ describe("HkTreemap pure layout input", () => {
     expect(contrastTextColor("rgb(78 121 167 / 40%)")).toBe("rgb(var(--color-text, 30 30 30))");
     expect(contrastTextColor("#4e79a780")).toBe("rgb(var(--color-text, 30 30 30))");
     expect(contrastTextColor("not-a-color")).toBe("rgb(var(--color-text, 30 30 30))");
+    // Parse strictness is part of the mirror contract: trailing garbage,
+    // inf/NaN spellings and broken hues are NOT truncated numbers — both
+    // runtimes must answer "no solid answer" identically.
+    expect(contrastTextColor("rgb(10x 20 30)")).toBe("rgb(var(--color-text, 30 30 30))");
+    expect(contrastTextColor("rgb(inf 0 0)")).toBe("rgb(var(--color-text, 30 30 30))");
+    expect(contrastTextColor("rgb(50x% 0 0)")).toBe("rgb(var(--color-text, 30 30 30))");
+    expect(contrastTextColor("hsl(10x, 50%, 50%)")).toBe("rgb(var(--color-text, 30 30 30))");
+    // The deg suffix still parses (the Rust angle channel strips it too) —
+    // in ANY case, because functional forms match on the lowercased value.
+    expect(contrastTextColor("hsl(120deg, 50%, 50%)")).toBe(contrastTextColor("hsl(120, 50%, 50%)"));
+    expect(contrastTextColor("hsl(120DEG, 50%, 50%)")).toBe(contrastTextColor("hsl(120, 50%, 50%)"));
+    // Uppercase NONE channels are filtered exactly like lowercase ones, and
+    // a BOM is whitespace on both sides of the mirror.
+    expect(contrastTextColor("rgb(NONE 1 2 3)")).toBe(contrastTextColor("rgb(1 2 3)"));
+    expect(contrastTextColor("rgb(1 2 3 / NONE)")).toBe(contrastTextColor("rgb(1 2 3)"));
+    expect(contrastTextColor("\uFEFF#fff")).toBe(contrastTextColor("#fff"));
+    expect(contrastTextColor("rgb(1\uFEFF2 3)")).toBe(contrastTextColor("rgb(1 2 3)"));
+    // The whitespace MODEL is pinned too, not just these shapes: an
+    // interleaved BOM between real spaces still trims, and U+0085 (NEL) is
+    // a control character — NOT JS whitespace — so it never parses.
+    expect(contrastTextColor("\uFEFF \uFEFF#fff")).toBe(contrastTextColor("#fff"));
+    expect(contrastTextColor("#fff\uFEFF \uFEFF")).toBe(contrastTextColor("#fff"));
+    expect(contrastTextColor("\u0085#fff")).toBe("rgb(var(--color-text, 30 30 30))");
+    expect(contrastTextColor("#fff\u0085")).toBe("rgb(var(--color-text, 30 30 30))");
+    expect(contrastTextColor("rgb(1\u00852 3)")).toBe("rgb(var(--color-text, 30 30 30))");
+    // A line terminator inside the envelope parses (the Rust mirror's
+    // strip_prefix/strip_suffix never sees it as a terminator).
+    expect(contrastTextColor("rgb(1\n2 3)")).toBe(contrastTextColor("rgb(1 2 3)"));
+    expect(contrastTextColor("rgb(1\u20282 3)")).toBe(contrastTextColor("rgb(1 2 3)"));
+    expect(contrastTextColor("rgb(\t1\n2\r3)")).toBe(contrastTextColor("rgb(1 2 3)"));
+    expect(contrastTextColor("hsl(120\u2028, 50%, 50%)")).toBe(contrastTextColor("hsl(120, 50%, 50%)"));
   });
 
   it("keeps every default palette cell AND its group band at WCAG AA", () => {
-    const linear = (channel: number) => {
-      const value = channel / 255;
-      return value <= 0.03928 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
-    };
-    const channels = (hex: string) => {
-      const raw = hex.length === 4
-        ? hex.slice(1).split("").map((char) => char + char).join("")
-        : hex.slice(1);
-      return [0, 2, 4].map((at) => Number.parseInt(raw.slice(at, at + 2), 16));
-    };
-    const luminance = (rgb: number[]) => 0.2126 * linear(rgb[0]!)
-      + 0.7152 * linear(rgb[1]!)
-      + 0.0722 * linear(rgb[2]!);
-    const ratio = (plate: number, ink: string) => {
-      const text = luminance(channels(ink));
-      return (Math.max(plate, text) + 0.05) / (Math.min(plate, text) + 0.05);
-    };
     for (const color of HK_TREEMAP_DEFAULT_COLORS) {
-      const plate = luminance(channels(color));
+      const plate = luminanceOf(hexChannels(color));
       const ink = contrastTextColor(color);
-      expect(["#fff", "#0b1220"]).toContain(ink);
-      expect(ratio(plate, ink)).toBeGreaterThanOrEqual(4.5);
+      expect(["#fff", "#0b1220", "#000"]).toContain(ink);
+      expect(contrastAgainst(plate, ink)).toBeGreaterThanOrEqual(4.5);
       // The band the group label actually sits on is the scrimmed plate —
       // pin it too, the worst palette case (#59a14f) sits at 4.506:1.
-      const band = luminance(
-        channels(color).map((channel) => channel * (1 - HK_TREEMAP_HEAD_SCRIM)),
+      const band = luminanceOf(
+        hexChannels(color).map((channel) => channel * (1 - HK_TREEMAP_HEAD_SCRIM)),
       );
       const bandInk = contrastTextColor(color, HK_TREEMAP_HEAD_SCRIM);
-      expect(ratio(band, bandInk)).toBeGreaterThanOrEqual(4.5);
+      expect(contrastAgainst(band, bandInk)).toBeGreaterThanOrEqual(4.5);
+    }
+  });
+
+  it("never leaves a solid plate under AA — black covers the mid-tone dead zone", () => {
+    // The white/near-black pair cannot reach 4.5:1 for plate luminances in
+    // (0.1833, 0.2024); pure black is the escape hatch and must appear there.
+    const deadZoneGrey = "rgb(120 120 130)";
+    expect(contrastAgainst(luminanceOf(hexChannels("#787882")), "#fff")).toBeLessThan(4.5);
+    expect(contrastAgainst(luminanceOf(hexChannels("#787882")), "#0b1220")).toBeLessThan(4.5);
+    expect(contrastTextColor(deadZoneGrey)).toBe("#000");
+    // …and only there: no default palette member is ever black.
+    for (const color of HK_TREEMAP_DEFAULT_COLORS) {
+      expect(contrastTextColor(color)).not.toBe("#000");
+    }
+    // The same grey's header band is light enough for white.
+    expect(contrastTextColor(deadZoneGrey, HK_TREEMAP_HEAD_SCRIM)).toBe("#fff");
+    // The band itself can land in the dead zone: #63a04d's plate keeps the
+    // near-black ink (5.94:1), but its scrimmed band cannot clear AA with
+    // either softer ink (white 4.49, near-black 4.17) -> black (4.68).
+    expect(contrastTextColor("#63a04d")).toBe("#0b1220");
+    expect(contrastTextColor("#63a04d", HK_TREEMAP_HEAD_SCRIM)).toBe("#000");
+    // Property: every grey step clears AA with the ink it picks.
+    for (let value = 0; value <= 255; value += 1) {
+      const color = `rgb(${value} ${value} ${value})`;
+      const plate = luminanceOf([value, value, value]);
+      expect(contrastAgainst(plate, contrastTextColor(color))).toBeGreaterThanOrEqual(4.5);
     }
   });
 

package/src/components/HkTreemap.tsx

@@ -65,15 +65,37 @@ function parseHexColor(raw: string): RgbaChannels | null {
   ];
 }
 
+/** Strict decimal/scientific numeric parse — the WHOLE string must be one
+ *  number, mirroring the Rust mirror's `str::parse::<f64>()` + `is_finite()`
+ *  gate: trailing garbage ("10x") and inf/NaN spellings are rejected, not
+ *  truncated. Returns NaN for anything that is not one number. */
+const NUMERIC_PATTERN = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
+function parseStrictNumber(raw: string): number {
+  const value = raw.trim();
+  return NUMERIC_PATTERN.test(value) ? Number(value) : Number.NaN;
+}
+
 function numericChannel(raw: string): number | null {
   if (raw.endsWith("%")) {
-    const percent = Number.parseFloat(raw.slice(0, -1));
+    const percent = parseStrictNumber(raw.slice(0, -1));
     return Number.isFinite(percent) ? Math.min(255, Math.max(0, (percent / 100) * 255)) : null;
   }
-  const value = Number.parseFloat(raw);
+  const value = parseStrictNumber(raw);
   return Number.isFinite(value) ? Math.min(255, Math.max(0, value)) : null;
 }
 
+/** An hsl hue: a strict number with the optional `deg` suffix (all trailing
+ *  repeats stripped, like the Rust mirror's `trim_end_matches("deg")`). */
+function angleChannel(raw: string): number {
+  return parseStrictNumber(raw.replace(/(?:deg)+$/, ""));
+}
+
+/** An hsl saturation/lightness: a strict number with an optional `%` suffix
+ *  (CSS requires the percent, but both forms appear in the wild). */
+function percentChannel(raw: string): number {
+  return parseStrictNumber(raw.replace(/%+$/, ""));
+}
+
 function hueToRgb(hue: number, saturation: number, lightness: number): [number, number, number] {
   const chroma = (1 - Math.abs(2 * lightness - 1)) * saturation;
   const sector = ((hue % 360) + 360) % 360 / 60;
@@ -96,17 +118,25 @@ function hueToRgb(hue: number, saturation: number, lightness: number): [number,
 function alphaComponent(raw: string | undefined): number | null {
   if (raw == null || raw === "") return 1;
   if (raw.endsWith("%")) {
-    const percent = Number.parseFloat(raw.slice(0, -1));
+    const percent = parseStrictNumber(raw.slice(0, -1));
     return Number.isFinite(percent) ? Math.min(1, Math.max(0, percent / 100)) : null;
   }
-  const value = Number.parseFloat(raw);
+  const value = parseStrictNumber(raw);
   return Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : null;
 }
 
 function parseCssColor(raw: string): RgbaChannels | null {
-  const value = raw.trim();
+  // JS trim() strips U+FEFF; the Rust mirror is taught the same character so
+  // both runtimes accept or reject a BOM-prefixed colour identically.
+  const value = raw.trim().replace(/^\uFEFF+/, "").replace(/\uFEFF+$/, "").trim();
   if (value.startsWith("#")) return parseHexColor(value);
-  const rgb = /^rgba?\((.*)\)$/i.exec(value);
+  // Functional forms are matched on the LOWERCASED value — exactly the Rust
+  // mirror's to_ascii_lowercase() — so case-insensitive CSS units (`DEG`,
+  // `NONE` channels) parse or reject identically on both sides.
+  const lower = value.toLowerCase();
+  // [\s\S] (not `.`): a line terminator inside the envelope is legal for the
+  // Rust mirror's strip_prefix/strip_suffix, so it must be legal here too.
+  const rgb = /^rgba?\(([\s\S]*)\)$/.exec(lower);
   if (rgb) {
     const parts = rgb[1]!.split(/[\s,/]+/).filter((part) => part && part !== "none");
     if (parts.length < 3) return null;
@@ -116,13 +146,13 @@ function parseCssColor(raw: string): RgbaChannels | null {
     if (alpha === null) return null;
     return [...(channels as [number, number, number]), alpha];
   }
-  const hsl = /^hsla?\((.*)\)$/i.exec(value);
+  const hsl = /^hsla?\(([\s\S]*)\)$/.exec(lower);
   if (hsl) {
     const parts = hsl[1]!.split(/[\s,/]+/).filter((part) => part && part !== "none");
     if (parts.length < 3) return null;
-    const hue = Number.parseFloat(parts[0]!);
-    const saturation = Number.parseFloat(parts[1]!);
-    const lightness = Number.parseFloat(parts[2]!);
+    const hue = angleChannel(parts[0]!);
+    const saturation = percentChannel(parts[1]!);
+    const lightness = percentChannel(parts[2]!);
     if (![hue, saturation, lightness].every(Number.isFinite)) return null;
     const alpha = alphaComponent(parts[3]);
     if (alpha === null) return null;
@@ -164,13 +194,25 @@ function contrastRatio(a: number, b: number): number {
   return (lighter + 0.05) / (darker + 0.05);
 }
 
-/** The two inks a SOLID fill can carry. The dark end is the family's
+/** The two inks a SOLID fill normally carries. The dark end is the family's
  *  near-black (a hair of blue keeps it from reading as dead #000 on the
  *  pale palette members). */
 const SOLID_LIGHT_INK = "#fff";
 const SOLID_DARK_INK = "#0b1220";
 
-/** Relative luminances of the two candidate inks (white is the reference 1). */
+/** Last-resort ink: the softer pair leaves a narrow mid-tone dead zone
+ *  (plate luminance in the open interval (0.1833, 0.2024)) where neither clears AA; there pure black
+ *  is the higher-contrast choice that can reach the floor. Outside that band
+ *  the softer pair is SELECTED even though black would beat the near-black on
+ *  raw ratio everywhere — black stays a floor escape, not the normal ink. */
+const SOLID_NEUTRAL_INK = "#000";
+
+/** WCAG AA floor for the fully-opaque cell label; the meta line and the
+ *  italic unknown label keep their pre-existing 0.85 / 0.9 opacity (a
+ *  deliberate de-emphasis, not part of this contract). */
+const AA_CONTRAST = 4.5;
+
+/** Relative luminances of the candidate inks (white is the reference 1). */
 const SOLID_DARK_INK_LUMINANCE = relativeLuminance(parseHexColor(SOLID_DARK_INK)!);
 const SOLID_LIGHT_INK_LUMINANCE = 1;
 
@@ -209,10 +251,13 @@ export function contrastTextColor(background: string, scrim = 0): string {
     1,
   ];
   const luminance = relativeLuminance(effective);
-  return contrastRatio(luminance, SOLID_DARK_INK_LUMINANCE)
-    >= contrastRatio(luminance, SOLID_LIGHT_INK_LUMINANCE)
-    ? SOLID_DARK_INK
-    : SOLID_LIGHT_INK;
+  const dark = contrastRatio(luminance, SOLID_DARK_INK_LUMINANCE);
+  const light = contrastRatio(luminance, SOLID_LIGHT_INK_LUMINANCE);
+  const best = Math.max(dark, light);
+  // Neither softer ink clears the floor -> pure black, which is strictly the
+  // higher-contrast choice inside that band (see SOLID_NEUTRAL_INK).
+  if (best < AA_CONTRAST) return SOLID_NEUTRAL_INK;
+  return dark >= light ? SOLID_DARK_INK : SOLID_LIGHT_INK;
 }
 
 export const HK_TREEMAP_DEFAULT_COLORS = [
@@ -433,7 +478,9 @@ export function createHkTreemapSummary(
  *
  * Cell ink is derived from each SOLID plate's own luminance (WCAG
  * contrast), because a big opaque block is the background that matters;
- * only a transparent/unparseable fill defers to the theme text token.
+ * only a transparent/unparseable fill defers to the theme text token. The
+ * mid-tone band where neither the white nor the family near-black clears AA
+ * falls back to pure black.
  */
 export default defineComponent({
   name: "HkTreemap",

package/src/overlay/overlayRoot.styles.test.ts

@@ -40,6 +40,33 @@ function sourcesIn(dir: string): string[] {
   return out;
 }
 
+describe("overlay root accessibility contract (#1206)", () => {
+  it("creates a root that is NOT aria-hidden", () => {
+    // The root USED to be created wholesale aria-hidden (2026-11-10
+    // a11y review). Since HkModal / HkDrawer / HkToast / every floating
+    // layer teleport INTO this root, that hid the whole popup subtree
+    // from the accessibility tree — role="dialog", aria-modal,
+    // aria-label and aria-busy never reached AT. Decorative layers
+    // declare their own aria-hidden where needed (the modal blur
+    // plate); the root itself must stay out of the hiding business,
+    // exactly like hudRoot's documented contract.
+    const root = ensureOverlayRoot();
+    if (!root) throw new Error("overlay root was not created");
+    expect(root.id).toBe("hk-overlay-root");
+    expect(root.hasAttribute("aria-hidden")).toBe(false);
+  });
+
+  it("keeps the root free of an aria-hidden writer", () => {
+    // Guard the fix at the source level too: the module must not grow a
+    // new setAttribute writer for the root's aria-hidden (the same
+    // regression the runtime assertion above catches, caught statically).
+    // The comment deliberately NAMES the attribute to explain its
+    // absence, so this matches the writer shape, not the word.
+    const source = readFileSync(resolve(overlayDir, "overlayRoot.ts"), "utf8");
+    expect(source).not.toMatch(/setAttribute\(["']aria-hidden/);
+  });
+});
+
 describe("overlay root document-space elevation contract", () => {
   const css = compile(resolve(overlayDir, "overlayRoot.scss"), {
     style: "expanded",

package/src/overlay/overlayRoot.ts

@@ -83,7 +83,16 @@ export function ensureOverlayRoot(): HTMLElement | null {
   if (!root) {
     root = document.createElement("div");
     root.id = "hk-overlay-root";
-    root.setAttribute("aria-hidden", "true");
+    // Deliberately NO aria-hidden here — the exact opposite of what the
+    // 2026-11-10 a11y review found (#1206): the root used to be created
+    // wholesale hidden, and since HkModal / HkDrawer / HkToast / every
+    // floating layer teleport INTO this root, the whole popup subtree was
+    // invisible to assistive tech (role="dialog", aria-modal, aria-label
+    // and aria-busy never reached the tree). Decorative layers declare
+    // their own aria-hidden where needed (the modal blur plate), and the
+    // root itself is a zero-size, pointer-transparent wrapper that has
+    // nothing to announce — matching hudRoot's contract.
+    root.setAttribute("data-hk-overlay-root", "");
     // Inline styles — this element is created BEFORE any stylesheet
     // loads, so it must be self-sufficient. `isolation` fences the
     // root's internal z-index space from the document's global stacking

package/src/utils/dom.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 import { clearLeaveGeometry, pinLeaveGeometry } from "./dom";
 
@@ -168,3 +168,96 @@ describe("pinLeaveGeometry", () => {
     expect(el.style.marginLeft).toBe("4px");
   });
 });
+
+/**
+ * FOCUSABLE_SELECTOR contract (#1206): every element-type branch must
+ * exclude [tabindex="-1"].
+ *
+ * The generic `[tabindex]` branch always did; the named branches did not,
+ * so a `button[tabindex="-1"]` (HkNumberSteppers' hold-to-repeat buttons
+ * are exactly that) MATCHED and could become a container's last
+ * "focusable" element. `trapFocus` only wraps when the focused element is
+ * the first/last member of the set — with a non-tab-stop as `last`, a
+ * forward Tab from the previous input walked straight out of the dialog
+ * (chest's SMS policy window was the reporter; the selector's own doc
+ * comment already claimed "excluding tabindex=-1", the implementation
+ * just never delivered it for the named branches).
+ *
+ * These tests use REAL DOM nodes appended to the document: happy-dom
+ * implements matches()/focus() on connected nodes, and the trap's wrap
+ * semantics depend on document.activeElement.
+ */
+import { FOCUSABLE_SELECTOR, getFocusableElements, trapFocus } from "./dom";
+
+describe("FOCUSABLE_SELECTOR excludes tabindex=-1 in every branch", () => {
+  let host: HTMLElement;
+
+  const tabFrom = (el: HTMLElement): boolean => {
+    el.focus();
+    const ev = new KeyboardEvent("keydown", { key: "Tab", bubbles: true, cancelable: true });
+    trapFocus(host, ev);
+    return ev.defaultPrevented;
+  };
+
+  beforeEach(() => {
+    host = document.createElement("div");
+    document.body.appendChild(host);
+  });
+
+  afterEach(() => {
+    host.remove();
+  });
+
+  it("excludes a button[tabindex=-1] that would otherwise be the trap's last", () => {
+    // The reporter's shape: switch/input, then a number field whose
+    // stepper column ends with tabindex=-1 buttons, then a disabled Save.
+    host.innerHTML = `
+      <input type="checkbox" data-name="switch" />
+      <input type="number" data-name="ttl" />
+      <button type="button" tabindex="-1" data-name="ttl-up"></button>
+      <button type="button" tabindex="-1" data-name="ttl-down"></button>
+      <input type="number" data-name="cap" />
+      <button type="button" tabindex="-1" data-name="cap-up"></button>
+      <button type="button" tabindex="-1" data-name="cap-down"></button>
+    `;
+    const focusable = getFocusableElements(host);
+    // The three real inputs; the four steppers are excluded.
+    expect(focusable).toHaveLength(3);
+    const last = focusable[focusable.length - 1]!;
+    expect(last.dataset.name).toBe("cap");
+    // The native tab order ends here too — so the trap's last IS the
+    // last real tab stop, and a forward Tab from `cap` wraps to first.
+    expect((last.nextElementSibling as HTMLElement).tabIndex).toBe(-1);
+    expect(tabFrom(last)).toBe(true);
+    expect((document.activeElement as HTMLElement).dataset.name).toBe("switch");
+  });
+
+  it("excludes tabindex=-1 in the a[href], textarea and select branches too", () => {
+    host.innerHTML = `
+      <a href="#" tabindex="-1" data-name="link"></a>
+      <a href="#" data-name="link-ok"></a>
+      <textarea tabindex="-1" data-name="ta"></textarea>
+      <textarea data-name="ta-ok"></textarea>
+      <select tabindex="-1" data-name="sel"></select>
+      <select data-name="sel-ok"></select>
+    `;
+    const names = getFocusableElements(host).map((el) => el.dataset.name);
+    expect(names).toEqual(["link-ok", "ta-ok", "sel-ok"]);
+  });
+
+  it("still counts explicit tabindex=0 as a real tab stop", () => {
+    host.innerHTML = `
+      <button type="button" data-name="first"></button>
+      <div tabindex="0" data-name="panel"></div>
+    `;
+    const names = getFocusableElements(host).map((el) => el.dataset.name);
+    expect(names).toEqual(["first", "panel"]);
+  });
+
+  it("falls back to an empty set when nothing is focusable (trap no-ops)", () => {
+    host.innerHTML = `<button type="button" tabindex="-1"></button>`;
+    expect(getFocusableElements(host)).toHaveLength(0);
+    // trapFocus with an empty set must not throw and must not move focus.
+    expect(tabFrom(document.activeElement as HTMLElement)).toBe(false);
+  });
+});

package/src/utils/dom.ts

@@ -1,5 +1,17 @@
+/**
+ * Elements a native Tab can actually reach.
+ *
+ * Every element-type branch excludes `[tabindex="-1"]` — the generic
+ * `[tabindex]` branch already did, but the named branches did not, so a
+ * `button[tabindex="-1"]` (HkNumberSteppers' hold-to-repeat buttons are
+ * exactly that) matched and could become a trap's `last`. `trapFocus`
+ * only wraps when the focused element IS the first/last member of this
+ * set; with a non-tab-stop as `last`, a forward Tab from the previous
+ * input walked straight out of the dialog (2026-11-10, #1206 — chest's
+ * SMS policy window was the reporter).
+ */
 export const FOCUSABLE_SELECTOR =
-  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+  'a[href]:not([tabindex="-1"]), button:not([disabled]):not([tabindex="-1"]), textarea:not([disabled]):not([tabindex="-1"]), input:not([disabled]):not([tabindex="-1"]), select:not([disabled]):not([tabindex="-1"]), [tabindex]:not([tabindex="-1"])';
 
 /** All focusable elements inside a container (excluding tabindex=-1). */
 export function getFocusableElements(container: HTMLElement): HTMLElement[] {