@celestia-island/hikari 0.55.277 → 0.55.279

package/package.json

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

package/src/animation/registerAnimations.ts

@@ -134,3 +134,7 @@ registerCssAnimation("hk-persistent-toast-card-in");
 // The styles/theme/mixins.scss ambient/glow/entrance keyframes were
 // retired with the legacy Gen-1 sheet vendoring (hikari #476) — their
 // registrar entries went with them.
+// components/HkScreenIdentifyCard.scss — the identify card's entrance
+// (opacity + 6px rise, plays once; the card unmounts at dwell end, so
+// no leave keyframe).
+registerCssAnimation("hk-screen-identify-in");

package/src/components/HkAmbientLayer.scss

@@ -0,0 +1,23 @@
+// HkAmbientLayer — the ambient HUD host (see HkAmbientLayer.tsx).
+//
+// The wrapper lives INSIDE #hk-hud-root (overlay/hudRoot.scss owns the
+// root's document elevation). It spans the viewport so slot children can
+// position themselves against the screen edges, but it is a ghost for
+// pointers: annotations must never block the window they annotate.
+
+.hk-ambient-layer {
+  position: fixed;
+  inset: 0;
+  z-index: var(--hk-overlay-z-hud, 1);
+  overflow: visible;
+  pointer-events: none;
+
+  // The one opt-in for a clickable HUD targets the slot CONTENT, never
+  // the wrapper: the wrapper spans the viewport, so re-enabling pointer
+  // events on it would swallow every click on the page behind an
+  // "interactive" HUD (R2 S2). Children restore their own
+  // pointer-events, the layer itself stays a ghost.
+  &[data-pointer-events="auto"] > * {
+    pointer-events: auto;
+  }
+}

package/src/components/HkAmbientLayer.styles.test.ts

@@ -0,0 +1,43 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+/**
+ * HkAmbientLayer layout contract (R2 S2): the layer spans the viewport so
+ * slot children can position themselves against the screen edges, which
+ * means the WRAPPER must never take pointer input — enabling it there
+ * would make a transparent full-screen div swallow every click on the
+ * page. The `pointerEvents="auto"` opt-in therefore targets the slot
+ * children only.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const scss = readFileSync(join(here, "HkAmbientLayer.scss"), "utf8");
+
+/** Comments stripped: a comment naming a property must not satisfy a
+ *  guard about it. */
+const declarations = scss.replace(/\/\/[^\n]*/g, "");
+
+describe("HkAmbientLayer pointer contract", () => {
+  it("spans the viewport but stays a pointer ghost", () => {
+    expect(declarations).toMatch(/position:\s*fixed;/);
+    expect(declarations).toMatch(/inset:\s*0;/);
+    expect(declarations).toMatch(/pointer-events:\s*none;/);
+  });
+
+  it("opt-in pointer events target the slot children, not the wrapper", () => {
+    // The auto declaration must live inside the CHILD-scoped block. This
+    // is the S2 footgun: a transparent full-viewport wrapper with
+    // pointer-events:auto swallows every page click.
+    const autoAt = declarations.indexOf("pointer-events: auto");
+    expect(autoAt).toBeGreaterThan(-1);
+    const blockStart = declarations.lastIndexOf('[data-pointer-events="auto"]', autoAt);
+    expect(blockStart).toBeGreaterThan(-1);
+    expect(declarations.slice(blockStart, autoAt)).toContain("> *");
+  });
+
+  it("sits on the HUD ordinal band, below its root's document elevation", () => {
+    expect(declarations).toMatch(/z-index:\s*var\(--hk-overlay-z-hud/);
+  });
+});

package/src/components/HkAmbientLayer.test.tsx

@@ -0,0 +1,124 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick } from "vue";
+
+import HkAmbientLayer from "./HkAmbientLayer";
+
+type LayerProps = {
+  pointerEvents?: "none" | "auto";
+  zIndex?: number;
+  label?: string;
+};
+
+/**
+ * HkAmbientLayer contract:
+ * - the slot teleports into #hk-hud-root (never <body> directly), which
+ *   is what makes an annotation out-paint the whole popup tree;
+ * - the wrapper is a pointer ghost by default and exposes its own
+ *   pointer-events opt-in;
+ * - zIndex orders ambient layers against each other inside the root;
+ * - the label turns the layer into a named landmark; no label keeps it
+ *   decorative (the card carries its own status role);
+ * - unmounting removes the content from the root.
+ *
+ * (Repo test convention: raw createApp + document queries.)
+ */
+
+const mounts: Array<() => void> = [];
+
+function mountLayer(props: LayerProps = {}, slotText = "HUD") {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp(
+    defineComponent({
+      setup() {
+        return () =>
+          h(
+            HkAmbientLayer,
+            props,
+            { default: () => h("span", { class: "hud-probe" }, slotText) },
+          );
+      },
+    }),
+  );
+  app.mount(container);
+  mounts.push(() => {
+    app.unmount();
+    container.remove();
+  });
+  return container;
+}
+
+afterEach(() => {
+  while (mounts.length) mounts.pop()?.();
+  // The HUD root is a module-owned singleton; leave the DOM tidy for the
+  // next case (the root itself stays, layer content must be gone).
+  document.querySelectorAll("#hk-hud-root .hk-ambient-layer").forEach((el) => el.remove());
+});
+
+describe("HkAmbientLayer", () => {
+  it("teleports the slot into the ambient HUD root", async () => {
+    mountLayer();
+    await nextTick();
+    const root = document.querySelector("#hk-hud-root");
+    expect(root).not.toBeNull();
+    const layer = root!.querySelector(".hk-ambient-layer");
+    expect(layer).not.toBeNull();
+    expect(layer!.querySelector(".hud-probe")?.textContent).toBe("HUD");
+  });
+
+  it("does not leave the slot in <body> outside the root", async () => {
+    const container = mountLayer();
+    await nextTick();
+    expect(container.querySelector(".hud-probe")).toBeNull();
+    const inRoot = document
+      .querySelector("#hk-hud-root")!
+      .querySelector(".hud-probe");
+    expect(inRoot).not.toBeNull();
+  });
+
+  it("is a pointer ghost by default and exposes the auto opt-in", async () => {
+    mountLayer();
+    await nextTick();
+    const layer = document.querySelector<HTMLElement>("#hk-hud-root .hk-ambient-layer")!;
+    expect(layer.getAttribute("data-pointer-events")).toBe("none");
+  });
+
+  it("carries the auto pointer mode when asked", async () => {
+    mountLayer({ pointerEvents: "auto" });
+    await nextTick();
+    const layer = document.querySelector<HTMLElement>("#hk-hud-root .hk-ambient-layer")!;
+    expect(layer.getAttribute("data-pointer-events")).toBe("auto");
+  });
+
+  it("orders ambient layers by the zIndex prop inside the root", async () => {
+    mountLayer({ zIndex: 7 });
+    await nextTick();
+    const layer = document.querySelector<HTMLElement>("#hk-hud-root .hk-ambient-layer")!;
+    expect(layer.style.zIndex).toBe("7");
+  });
+
+  it("labels the layer as a landmark only when a label is given", async () => {
+    mountLayer();
+    await nextTick();
+    let layer = document.querySelector<HTMLElement>("#hk-hud-root .hk-ambient-layer")!;
+    expect(layer.hasAttribute("role")).toBe(false);
+    expect(layer.hasAttribute("aria-label")).toBe(false);
+  });
+
+  it("turns a labelled layer into a named region", async () => {
+    mountLayer({ label: "Recording" });
+    await nextTick();
+    const layer = document.querySelector<HTMLElement>("#hk-hud-root .hk-ambient-layer")!;
+    expect(layer.getAttribute("role")).toBe("region");
+    expect(layer.getAttribute("aria-label")).toBe("Recording");
+  });
+
+  it("removes its content from the root on unmount", async () => {
+    mountLayer();
+    await nextTick();
+    expect(document.querySelector("#hk-hud-root .hud-probe")).not.toBeNull();
+    mounts.pop()?.();
+    await nextTick();
+    expect(document.querySelector("#hk-hud-root .hud-probe")).toBeNull();
+  });
+});

package/src/components/HkAmbientLayer.tsx

@@ -0,0 +1,74 @@
+import { defineComponent, type PropType, Teleport } from "vue";
+
+import { ensureHudRoot } from "../overlay/hudRoot";
+import "./HkAmbientLayer.scss";
+
+/**
+ * HkAmbientLayer — the shared host for always-visible, NON-INTERACTIVE
+ * annotations: a slot teleported into hikari's ambient HUD root
+ * (`#hk-hud-root`, overlay/hudRoot.ts) so it paints above EVERY popup —
+ * the modal backdrop included — without entering the popup manager's
+ * window/anchored/tooltip stack.
+ *
+ * The 2026-11-05 identify defect is the reason this exists: the
+ * screen-identify card was teleported to `<body>` with a hand-written
+ * `z-index: 5000`, so the modal tree (document band 90000) buried it and
+ * the card showed through the scrim as dimmed background. Layer
+ * selection is a LIBRARY decision, not a per-consumer number: one HUD
+ * root, one band (`--hk-z-hud`), and a single reviewable floor
+ * (`--hk-overlay-z-hud`) for layers inside it.
+ *
+ * Non-interactive by default: the wrapper spans the viewport but lets
+ * every pointer through (`pointer-events: none`). Pass
+ * `pointerEvents="auto"` only for a HUD that really is clickable (an
+ * annotation chip with a dismiss button), and keep its footprint small so
+ * it never swallows the page.
+ *
+ * Usage:
+ *
+ * ```tsx
+ * <HkAmbientLayer>
+ *   <div class="hk-recording-dot" />
+ * </HkAmbientLayer>
+ * ```
+ *
+ * `zIndex` orders several ambient layers against each other inside the
+ * HUD root (default: the base floor). The wrapper never leaves the root,
+ * so it cannot be covered by a later-opened modal.
+ */
+export default defineComponent({
+  name: "HkAmbientLayer",
+  props: {
+    /** Whether the layer's CONTENT accepts pointer input. Default `none`
+     *  — an annotation must not block the window it annotates. `auto`
+     *  restores pointer events on the slot children only; the
+     *  viewport-spanning wrapper itself always stays a ghost, so an
+     *  interactive HUD can never swallow page clicks. */
+    pointerEvents: {
+      type: String as PropType<"none" | "auto">,
+      default: "none",
+      validator: (value: string) => value === "none" || value === "auto",
+    },
+    /** Stacking order among ambient layers (larger = nearer the user).
+     *  Local to the HUD root, never a document-space number. */
+    zIndex: { type: Number, default: 1 },
+    /** Accessible name for the layer as a landmark. Omit for purely
+     *  decorative hosts; the card inside carries its own status role. */
+    label: { type: String, default: undefined },
+  },
+  setup(props, { slots }) {
+    return () => (
+      <Teleport to={ensureHudRoot()}>
+        <div
+          class="hk-ambient-layer"
+          data-pointer-events={props.pointerEvents}
+          role={props.label ? "region" : undefined}
+          aria-label={props.label}
+          style={{ zIndex: String(props.zIndex) }}
+        >
+          {slots.default?.()}
+        </div>
+      </Teleport>
+    );
+  },
+});

package/src/components/HkScreenIdentify.barrel.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+
+import * as barrel from "../index";
+import { asIndexable } from "../utils/typing";
+
+/**
+ * Public barrel guard for the screen-identify family (R3 precedent: a
+ * forgotten index.ts line keeps the whole suite green because every
+ * other test reaches the module directly — only external consumers
+ * notice). Same shape as HkFaceShell.barrel.test.ts.
+ *
+ * This file deliberately does NOT mock "@celestia-island/hikari": the
+ * package's self-reference resolves to the very same src/index.ts module
+ * as "../index".
+ */
+describe("the screen-identify family in the public barrel", () => {
+  it("exports the card and the once-per-window host under both names", () => {
+    const card = asIndexable(barrel.HkScreenIdentifyCard);
+    const host = asIndexable(barrel.HkScreenIdentifyHost);
+    expect(card, "HkScreenIdentifyCard must be re-exported").toBeTruthy();
+    expect(card.name).toBe("HkScreenIdentifyCard");
+    expect(host.name).toBe("HkScreenIdentifyHost");
+    // The H- alias rides the HCard/HkCard family convention.
+    expect(barrel.HScreenIdentifyCard).toBe(barrel.HkScreenIdentifyCard);
+    expect(barrel.HScreenIdentifyHost).toBe(barrel.HkScreenIdentifyHost);
+  });
+
+  it("exports the ambient HUD layer primitive and its root", () => {
+    const layer = asIndexable(barrel.HkAmbientLayer);
+    expect(layer.name).toBe("HkAmbientLayer");
+    expect(barrel.HAmbientLayer).toBe(barrel.HkAmbientLayer);
+    expect(typeof barrel.ensureHudRoot).toBe("function");
+    expect(barrel.HUD_ROOT_SELECTOR).toBe("#hk-hud-root");
+    expect(barrel.HUD_ROOT_DOCUMENT_Z).toBe(90050);
+  });
+
+  it("exports the context that drives the card", () => {
+    expect(typeof barrel.useScreenIdentify).toBe("function");
+    expect(typeof barrel.showScreenIdentify).toBe("function");
+    expect(typeof barrel.dismissScreenIdentify).toBe("function");
+    expect(barrel.SCREEN_IDENTIFY_DEFAULT_MS).toBe(3000);
+    // The context accessor hands out live refs and the two verbs.
+    const identify = barrel.useScreenIdentify();
+    expect(identify.active.value).toBe(false);
+    expect(typeof identify.show).toBe("function");
+    expect(typeof identify.dismiss).toBe("function");
+  });
+});

package/src/components/HkScreenIdentifyCard.scss

@@ -0,0 +1,103 @@
+// HkScreenIdentifyCard — the numbered "which screen is this?" card.
+//
+// Grammar (user direction 2026-10-12): a LARGE SQUARE card, fixed light
+// surface, BLACK number. The card must read from across a room and look
+// identical in light and dark themes, so the surface/ink here are
+// deliberately NOT the themed tokens (a themed card would swallow the
+// number in dark mode — the reason the original card hardcoded both).
+// It is a HUD: pointer-events none, it never intercepts the window it
+// annotates.
+
+.hk-screen-identify {
+  position: fixed;
+  z-index: var(--hk-overlay-z-hud, 1);
+  // Logical side properties: the card stays in the same corner of the
+  // glass under RTL.
+  inset-inline-start: var(--space-16, 16px);
+  bottom: var(--space-16, 16px);
+  // One viewport-clamped width drives both axes, so the badge reads as a
+  // physical numbered card, not a text bubble.
+  aspect-ratio: 1;
+  width: clamp(96px, 18vw, 160px);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  // Fixed LIGHT card: the black number must read in every theme.
+  background: rgb(255 255 255 / 96%);
+  border: 1px solid rgb(0 0 0 / 18%);
+  border-radius: var(--radius-md, 8px);
+  box-shadow: var(--shadow-elevated);
+  pointer-events: none;
+  animation: hk-screen-identify-in 180ms ease-out;
+
+  // The four corners. Left/right pair mirrors under RTL (logical
+  // properties); top/bottom are the physical edges either way.
+  &[data-placement="bottom-right"] {
+    inset-inline-start: auto;
+    inset-inline-end: var(--space-16, 16px);
+  }
+
+  &[data-placement="top-left"] {
+    top: var(--space-16, 16px);
+    bottom: auto;
+  }
+
+  &[data-placement="top-right"] {
+    top: var(--space-16, 16px);
+    inset-inline-start: auto;
+    inset-inline-end: var(--space-16, 16px);
+    bottom: auto;
+  }
+
+  // Reduce-motion: the card still appears, it just does not slide in.
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+  }
+}
+
+.hk-screen-identify-num {
+  font-family: var(--font-mono, monospace);
+  // Big enough to read from across a room, scaled with the card: half the
+  // card's clamp at every viewport width. The token scale stops at
+  // heading sizes, so this one numeral is intentionally a clamp().
+  font-size: clamp(3rem, 9vw, 5rem);
+  font-weight: 700;
+  line-height: 1;
+  // BLACK, deliberately not themed (user direction 2026-10-12).
+  color: #000;
+}
+
+// The seconds left, as hikari's rolling digit: a corner badge on the
+// card, top-inline-end.
+.hk-screen-identify-count {
+  position: absolute;
+  top: var(--space-4, 4px);
+  inset-inline-end: var(--space-8, 8px);
+  font-size: var(--text-base, 0.875rem);
+  color: rgb(0 0 0 / 62%);
+}
+
+// The stable screen name: the opposite corner badge, bottom-inline-start,
+// one ellipsized line so a long window label cannot leave the card.
+.hk-screen-identify-name {
+  position: absolute;
+  inset-inline-start: var(--space-8, 8px);
+  bottom: var(--space-4, 4px);
+  max-width: calc(100% - 2 * var(--space-8, 8px));
+  overflow: hidden;
+  font-size: var(--text-xs, 0.75rem);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: rgb(0 0 0 / 62%);
+}
+
+@keyframes hk-screen-identify-in {
+  from {
+    opacity: 0;
+    transform: translateY(6px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}

package/src/components/HkScreenIdentifyCard.styles.test.ts

@@ -0,0 +1,89 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { listCssAnimations } from "../animation/registerAnimations";
+
+/**
+ * Source contract for the identify card's load-bearing look (the chest
+ * v4 wave pinned the same rules before the card was upstreamed): a
+ * LARGE SQUARE, fixed-light surface with a BLACK theme-independent
+ * number, corner badges, one viewport-clamped room-readable numeral and
+ * hikari tokens everywhere else. vitest cannot see stylesheets, so a
+ * deleted rule would leave every DOM guard green.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const scss = readFileSync(join(here, "HkScreenIdentifyCard.scss"), "utf8");
+
+/** The DECLARATIONS of a top-level class rule, comments stripped (a
+ *  comment that names a property must not satisfy a guard about it). */
+function ruleBlock(selector: string): string {
+  const escaped = selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = new RegExp(`${escaped}\\s*\\{([^}]*)\\}`).exec(scss);
+  if (!match) throw new Error(`no rule for ${selector}`);
+  return match[1]
+    .split("\n")
+    .filter((line) => !line.trim().startsWith("*") && !line.trim().startsWith("/*"))
+    .join("\n");
+}
+
+describe("HkScreenIdentifyCard layout contract", () => {
+  it("is a large square card with a viewport-clamped width", () => {
+    const card = ruleBlock(".hk-screen-identify");
+    expect(card).toMatch(/aspect-ratio:\s*1/);
+    expect(card).toMatch(/width:\s*clamp\(96px,\s*18vw,\s*160px\)/);
+    // A HUD never intercepts the window it annotates.
+    expect(card).toMatch(/pointer-events:\s*none/);
+  });
+
+  it("keeps the fixed light surface and the black number", () => {
+    const card = ruleBlock(".hk-screen-identify");
+    // A themed surface would swallow the black number in dark mode.
+    expect(card).toMatch(/background:\s*rgb\(255 255 255/);
+    const num = ruleBlock(".hk-screen-identify-num");
+    expect(num).toMatch(/color:\s*#000/);
+    expect(num).not.toMatch(/--color-/);
+  });
+
+  it("keeps the name and countdown as corner badges on the card", () => {
+    for (const badge of [".hk-screen-identify-count", ".hk-screen-identify-name"]) {
+      expect(ruleBlock(badge)).toMatch(/position:\s*absolute/);
+    }
+  });
+
+  it("parks the card in every corner through placement attributes", () => {
+    for (const placement of ["bottom-right", "top-left", "top-right"]) {
+      expect(scss).toContain(`&[data-placement="${placement}"]`);
+    }
+    // Left/right use logical properties so RTL mirrors the pair while
+    // the card stays at the same corner of the glass.
+    expect(ruleBlock(".hk-screen-identify")).toMatch(/inset-inline-start:/);
+  });
+
+  it("rides hikari text tokens for every font size except the numeral", () => {
+    const raw = [...scss.matchAll(/font-size:\s*([^;]+);/g)].map((m) => m[1].trim());
+    expect(raw.length).toBeGreaterThan(1);
+    const nonToken = raw.filter((value) => !/^var\(--text-/.test(value));
+    // The room-readable numeral is the ONE intentional clamp() beyond
+    // the token scale (which stops at heading sizes).
+    expect(nonToken).toHaveLength(1);
+    expect(nonToken[0]).toMatch(/^clamp\(/);
+    expect(ruleBlock(".hk-screen-identify-num")).toContain(nonToken[0]);
+  });
+
+  it("sits on the HUD ordinal band and honours reduced motion", () => {
+    expect(ruleBlock(".hk-screen-identify")).toMatch(
+      /z-index:\s*var\(--hk-overlay-z-hud/,
+    );
+    expect(scss).toMatch(/@media \(prefers-reduced-motion: reduce\)/);
+    expect(scss).toContain("animation: none;");
+  });
+
+  it("registers its entrance animation in the CSS animation registrar", () => {
+    const names = listCssAnimations().map((entry) => entry.name);
+    expect(names).toContain("hk-screen-identify-in");
+    expect(scss).toContain("@keyframes hk-screen-identify-in");
+  });
+});

package/src/components/HkScreenIdentifyCard.test.tsx

@@ -0,0 +1,113 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick } from "vue";
+
+import HkScreenIdentifyCard, {
+  type ScreenIdentifyPlacement,
+} from "./HkScreenIdentifyCard";
+
+type CardProps = {
+  number: number | string;
+  name?: string;
+  secondsLeft?: number;
+  placement?: ScreenIdentifyPlacement;
+  label?: string;
+};
+
+/**
+ * HkScreenIdentifyCard contract (ported from the chest card precedent,
+ * user direction 2026-10-12):
+ * - the number is the loud element; the name and countdown are corner
+ *   badges;
+ * - role="status" + an accessible label composed from the number and the
+ *   optional name (the layer must announce, not just paint);
+ * - the corner is a data attribute (CSS owns the geometry, including the
+ *   RTL mirror);
+ * - a countdown appears only while there are seconds left.
+ */
+const mounts: Array<() => void> = [];
+
+function mountCard(props: CardProps) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp(
+    defineComponent({
+      setup() {
+        return () => h(HkScreenIdentifyCard, props);
+      },
+    }),
+  );
+  app.mount(container);
+  mounts.push(() => {
+    app.unmount();
+    container.remove();
+  });
+  return container;
+}
+
+afterEach(() => {
+  while (mounts.length) mounts.pop()?.();
+});
+
+describe("HkScreenIdentifyCard", () => {
+  it("renders the number, the optional name and the countdown", async () => {
+    const container = mountCard({ number: 7, name: "Kiosk AB12", secondsLeft: 3 });
+    await nextTick();
+    const card = container.querySelector(".hk-screen-identify")!;
+    expect(card.querySelector(".hk-screen-identify-num")?.textContent).toBe("7");
+    expect(card.querySelector(".hk-screen-identify-name")?.textContent).toBe("Kiosk AB12");
+    const count = card.querySelector(".hk-screen-identify-count");
+    expect(count).not.toBeNull();
+    // The rolling digit is hikari's own component, not a hand-rolled
+    // odometer.
+    expect(count!.querySelector(".hk-countdown-digit")).not.toBeNull();
+  });
+
+  it("omits the name badge when no name is given", async () => {
+    const container = mountCard({ number: 2 });
+    await nextTick();
+    expect(container.querySelector(".hk-screen-identify-name")).toBeNull();
+  });
+
+  it("omits the countdown when there are no seconds left", async () => {
+    const container = mountCard({ number: 2, secondsLeft: 0 });
+    await nextTick();
+    expect(container.querySelector(".hk-screen-identify-count")).toBeNull();
+  });
+
+  it("accepts a string number", async () => {
+    const container = mountCard({ number: "A1" });
+    await nextTick();
+    expect(container.querySelector(".hk-screen-identify-num")?.textContent).toBe("A1");
+  });
+
+  it("announces itself with the composed label", async () => {
+    const container = mountCard({ number: 3 });
+    await nextTick();
+    const card = container.querySelector<HTMLElement>(".hk-screen-identify")!;
+    expect(card.getAttribute("role")).toBe("status");
+    expect(card.getAttribute("aria-label")).toBe("Screen 3");
+  });
+
+  it("includes the screen name in the announcement", async () => {
+    const container = mountCard({ number: 3, name: "AB12" });
+    await nextTick();
+    const card = container.querySelector<HTMLElement>(".hk-screen-identify")!;
+    expect(card.getAttribute("aria-label")).toBe("Screen 3, AB12");
+  });
+
+  it("lets the caller override the announcement", async () => {
+    const container = mountCard({ number: 3, label: "Third display" });
+    await nextTick();
+    const card = container.querySelector<HTMLElement>(".hk-screen-identify")!;
+    expect(card.getAttribute("aria-label")).toBe("Third display");
+  });
+
+  it("carries the placement as a data attribute for every corner", async () => {
+    for (const placement of ["bottom-left", "bottom-right", "top-left", "top-right"] as const) {
+      const container = mountCard({ number: 1, placement });
+      await nextTick();
+      const card = container.querySelector<HTMLElement>(".hk-screen-identify")!;
+      expect(card.getAttribute("data-placement")).toBe(placement);
+    }
+  });
+});