@celestia-island/hikari 0.45.7 → 0.45.9

package/package.json

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

package/src/components/HkAboutModal.scss

@@ -126,7 +126,7 @@
   color: rgb(var(--color-muted));
 }
 
-/* ── Credits: made-by sentence + organization blurb ────────────────────── */
+/* ── Credits: credits sentence + organization blurb ────────────────────── */
 
 .s-about-modal-credits {
   display: flex;
@@ -136,24 +136,19 @@
   margin-top: calc(-1 * var(--space-4, 0.25rem));
 }
 
-.s-about-modal-made-by {
+// Inline flow (not flex): the sentence is assembled from text runs and
+// chips, and the runs carry their own spaces around the chips.
+.s-about-modal-credits-line {
   margin: 0;
   font-size: var(--text-sm, 0.8125rem);
+  line-height: 2;
   text-align: center;
+  text-wrap: pretty;
   color: rgb(var(--color-text));
 }
 
-.s-about-modal-made-by .s-about-modal-row-link {
-  margin: 0 0.15em;
-}
-
-.s-about-modal-row-link {
-  color: rgb(var(--color-primary));
-  text-decoration: none;
-}
-
-.s-about-modal-row-link:hover {
-  text-decoration: underline;
+.s-about-modal-credit-name {
+  color: rgb(var(--color-text));
 }
 
 .s-about-modal-description {
@@ -257,8 +252,8 @@
   gap: var(--space-6, 0.375rem);
 }
 
-// Ghost pills: the chips are secondary navigation, so they carry a hairline
-// instead of a filled brand block.
+// Ghost pills: every link in this dialog is a tag, so they share one face —
+// credits names, licenses, external links and the legal filings.
 .s-about-modal-link {
   padding: var(--space-2, 0.125rem) var(--space-10, 0.625rem);
   border: 1px solid var(--border-subtle, rgb(100 100 100 / 12%));
@@ -273,6 +268,14 @@
     background var(--duration-short, 0.15s) ease;
 }
 
+// Chips inside the credits sentence sit in a text run: keep them on the
+// baseline and let the surrounding spaces do the spacing.
+.s-about-modal-credit-link {
+  display: inline-block;
+  vertical-align: middle;
+  margin: 0 0.1em;
+}
+
 .s-about-modal-link:hover {
   border-color: var(--c-primary-strong, rgb(var(--color-primary) / 40%));
   background: var(--c-primary-faint, rgb(var(--color-primary) / 5%));
@@ -292,25 +295,20 @@
 
 /* ── Legal footer: filing links + copyright ───────────────────────────── */
 
+// Filing numbers are long, so the legal chips render a notch smaller than
+// the license / link rows.
+.s-about-modal-footer-link {
+  font-size: var(--text-2xs, 0.625rem);
+}
+
 .s-about-modal-footer-links {
   display: flex;
   flex-wrap: wrap;
   justify-content: center;
-  gap: var(--space-16, 1rem);
+  gap: var(--space-6, 0.375rem);
   margin-top: calc(-1 * var(--space-4, 0.25rem));
 }
 
-.s-about-modal-footer-link {
-  font-size: var(--text-xs, 0.75rem);
-  color: rgb(var(--color-muted));
-  text-decoration: none;
-}
-
-.s-about-modal-footer-link:hover {
-  color: rgb(var(--color-primary));
-  text-decoration: underline;
-}
-
 .s-about-modal-footer {
   display: flex;
   justify-content: center;

package/src/components/HkAboutModal.test.tsx

@@ -9,8 +9,9 @@ import { setLocale } from "../i18n/context";
  * - the first-letter tile is the default identity and `logoSrc` swaps it
  *   for an image inside the identity frame
  * - version and tagline share one subtitle line
- * - description / made-by / license / copyright render the given strings,
- *   madeByNameHref turns the author name into an external link
+ * - the credits sentence assembles text runs and linked name chips, and a
+ *   name without an href stays plain text
+ * - description / license / copyright render the given strings
  * - component rows split the machine value from an optional meta pill
  * - the backdrop factory renders inside the clipped backdrop layer
  * - licenses and links render as chips under one centered block
@@ -96,27 +97,44 @@ describe("HkAboutModal branding", () => {
     expect(query<HTMLElement>(".s-about-modal-description").textContent).toBe("Save the world.");
   });
 
-  it("renders the made-by sentence with a linked author name", async () => {
+  it("renders the credits sentence with linked name chips", async () => {
     mountAbout({
-      madeByPrefix: "由",
-      madeByName: "伊欧",
-      madeByNameHref: "https://github.com/langyo",
-      madeBySuffix: " 主创，来自 Celestia Island",
+      credits: [
+        { text: "来自 " },
+        { name: "Celestia Island", href: "https://github.com/celestia-island" },
+        { text: "，由 " },
+        { name: "伊欧", href: "https://github.com/langyo" },
+        { text: " 倾力设计" },
+      ],
     });
     await flushModal();
-    const line = query<HTMLElement>(".s-about-modal-made-by");
-    expect(line.textContent).toBe("由伊欧 主创，来自 Celestia Island");
-    const link = query<HTMLAnchorElement>(".s-about-modal-row-link");
-    expect(link.textContent).toBe("伊欧");
-    expect(link.getAttribute("href")).toBe("https://github.com/langyo");
-    expect(link.getAttribute("target")).toBe("_blank");
+    const line = query<HTMLElement>(".s-about-modal-credits-line");
+    expect(line.textContent).toBe("来自 Celestia Island，由 伊欧 倾力设计");
+    const chips = [
+      ...document.body.querySelectorAll<HTMLAnchorElement>(".s-about-modal-credit-link"),
+    ];
+    expect(chips.map((chip) => chip.textContent)).toEqual(["Celestia Island", "伊欧"]);
+    // Every link in the dialog is a tag and opens in a new tab.
+    for (const chip of chips) {
+      expect(chip.classList.contains("s-about-modal-link")).toBe(true);
+      expect(chip.getAttribute("target")).toBe("_blank");
+      expect(chip.getAttribute("rel")).toContain("noopener");
+    }
+    expect(chips[0]!.getAttribute("href")).toBe("https://github.com/celestia-island");
+  });
+
+  it("keeps a credit name as plain text when no href is given", async () => {
+    mountAbout({ credits: [{ text: "由 " }, { name: "伊欧" }, { text: " 主创" }] });
+    await flushModal();
+    expect(query<HTMLElement>(".s-about-modal-credits-line").textContent).toBe("由 伊欧 主创");
+    expect(query<HTMLElement>(".s-about-modal-credit-name").textContent).toBe("伊欧");
+    expect(document.body.querySelector(".s-about-modal-credit-link")).toBeNull();
   });
 
-  it("renders the made-by sentence without a link when no href", async () => {
-    mountAbout({ madeByPrefix: "由", madeByName: "伊欧", madeBySuffix: " 主创" });
+  it("skips empty credit parts", async () => {
+    mountAbout({ credits: [{ text: "" }, { name: "" }, { text: "仅此一句。" }] });
     await flushModal();
-    expect(query<HTMLElement>(".s-about-modal-made-by").textContent).toBe("由伊欧 主创");
-    expect(document.body.querySelector(".s-about-modal-row-link")).toBeNull();
+    expect(query<HTMLElement>(".s-about-modal-credits-line").textContent).toBe("仅此一句。");
   });
 
   it("renders software-component version rows with a meta pill and tone", async () => {
@@ -234,7 +252,7 @@ describe("HkAboutModal branding", () => {
     mountAbout();
     await flushModal();
     expect(document.body.querySelectorAll(".s-about-modal-row").length).toBe(0);
-    expect(document.body.querySelector(".s-about-modal-made-by")).toBeNull();
+    expect(document.body.querySelector(".s-about-modal-credits-line")).toBeNull();
     expect(document.body.querySelector(".s-about-modal-links")).toBeNull();
     expect(document.body.querySelector(".s-about-modal-chips")).toBeNull();
     expect(document.body.querySelector(".s-about-modal-credits")).toBeNull();

package/src/components/HkAboutModal.tsx

@@ -10,6 +10,24 @@ export interface HAboutLink {
   href: string;
 }
 
+/**
+ * One piece of the credits line.
+ *
+ * The line is a sentence assembled from parts so a host can phrase (and
+ * order) it freely per locale: literal `text` runs sit between linked
+ * `name` chips (organization first, author second, …). The names render as
+ * the same chips as the license / link rows — every link in this dialog is
+ * a tag.
+ */
+export interface HAboutCredit {
+  /** Literal sentence fragment (mutually exclusive with `name`). */
+  text?: string;
+  /** Linked chip label (mutually exclusive with `text`). */
+  name?: string;
+  /** Target for a `name` chip; opens in a new tab. */
+  href?: string;
+}
+
 /**
  * One software-component version row.
  *
@@ -33,10 +51,11 @@ export interface HAboutComponentVersion {
  *
  * Layout (2026-09 redesign): a centered identity hero (haloed logo, name,
  * then version + tagline on one compact line), an optional credits block
- * (made-by sentence with a linked author name + organization blurb), a
- * bordered spec card holding the software-component versions, ghost chip
- * rows for licenses / external links, and a muted legal footer (filing
- * links + copyright). Every branding prop is optional — the modal degrades
+ * (a sentence built from text runs and linked name chips, plus the
+ * organization blurb), a
+ * bordered spec card holding the software-component versions, and the
+ * link rows — licenses, external links, legal filings and the credits
+ * names all render as the same ghost tag. Every one opens in a new tab. Every branding prop is optional — the modal degrades
  * to the plain identity card when none are given.
  */
 export const HkAboutModal = defineComponent({
@@ -53,14 +72,12 @@ export const HkAboutModal = defineComponent({
     tagline: { type: String, default: undefined },
     /** Optional centered small line under the credits (organization blurb). */
     description: { type: String, default: undefined },
-    /** Made-by sentence: text before the linked author name (e.g. "由"). */
-    madeByPrefix: { type: String, default: undefined },
-    /** Made-by sentence: the linked author name (e.g. "伊欧"). */
-    madeByName: { type: String, default: undefined },
-    /** Link applied to the author name (e.g. the GitHub profile). */
-    madeByNameHref: { type: String, default: undefined },
-    /** Made-by sentence: text after the name (e.g. " 主创，来自 …"). */
-    madeBySuffix: { type: String, default: undefined },
+    /**
+     * Credits sentence, assembled from text runs and linked name chips
+     * (e.g. 来自 <Celestia Island>，由 <伊欧> 倾力设计). Names render as the
+     * same chips as the license / link rows.
+     */
+    credits: { type: Array as PropType<HAboutCredit[]>, default: () => [] },
     /** License chips (e.g. SySL-1.0 / BUSL-1.1), rendered centered. */
     licenses: { type: Array as PropType<HAboutLink[]>, default: () => [] },
     /** Software-component version rows (WebUI / engines), label + value. */
@@ -88,25 +105,38 @@ export const HkAboutModal = defineComponent({
   setup(props, { emit }) {
     const { t } = useI18n();
 
-    const renderMadeBy = () => {
-      if (!props.madeByName) return null;
-      const name = props.madeByNameHref ? (
-        <a
-          class="s-about-modal-row-link"
-          href={props.madeByNameHref}
-          target="_blank"
-          rel="noopener noreferrer"
-        >
-          {props.madeByName}
-        </a>
-      ) : (
-        <span>{props.madeByName}</span>
-      );
+    // One chip renderer for every link in the dialog: credits names,
+    // licenses, external links and the legal filings all render as tags.
+    const renderChip = (label: string, href: string, extraClass: string) => (
+      <a
+        key={`${extraClass}:${href}`}
+        class={`s-about-modal-link ${extraClass}`}
+        href={href}
+        target="_blank"
+        rel="noopener noreferrer"
+      >
+        {label}
+      </a>
+    );
+
+    const renderCredits = () => {
+      const parts = props.credits.filter((part) => part.text || part.name);
+      if (parts.length === 0) return null;
       return (
-        <p class="s-about-modal-made-by">
-          {props.madeByPrefix}
-          {name}
-          {props.madeBySuffix}
+        <p class="s-about-modal-credits-line">
+          {parts.map((part, index) =>
+            part.name ? (
+              part.href ? (
+                renderChip(part.name, part.href, "s-about-modal-credit-link")
+              ) : (
+                <span key={`name:${index}`} class="s-about-modal-credit-name">
+                  {part.name}
+                </span>
+              )
+            ) : (
+              <span key={`text:${index}`}>{part.text}</span>
+            ),
+          )}
         </p>
       );
     };
@@ -116,17 +146,7 @@ export const HkAboutModal = defineComponent({
       return (
         <div class="s-about-modal-links" data-slot={slot}>
           <div class="s-about-modal-links-list">
-            {items.map((item) => (
-              <a
-                key={item.href}
-                href={item.href}
-                target="_blank"
-                rel="noopener noreferrer"
-                class="s-about-modal-link"
-              >
-                {item.label}
-              </a>
-            ))}
+            {items.map((item) => renderChip(item.label, item.href, ""))}
           </div>
         </div>
       );
@@ -177,9 +197,9 @@ export const HkAboutModal = defineComponent({
               </div>
             </header>
 
-            {(props.madeByName || props.description) && (
+            {(props.credits.length > 0 || props.description) && (
               <div class="s-about-modal-credits">
-                {renderMadeBy()}
+                {renderCredits()}
                 {props.description && (
                   <p class="s-about-modal-description">{props.description}</p>
                 )}
@@ -216,17 +236,9 @@ export const HkAboutModal = defineComponent({
 
             {props.footerLinks.length > 0 && (
               <div class="s-about-modal-footer-links">
-                {props.footerLinks.map((link) => (
-                  <a
-                    key={link.href}
-                    href={link.href}
-                    target="_blank"
-                    rel="noopener noreferrer"
-                    class="s-about-modal-footer-link"
-                  >
-                    {link.label}
-                  </a>
-                ))}
+                {props.footerLinks.map((link) =>
+                  renderChip(link.label, link.href, "s-about-modal-footer-link"),
+                )}
               </div>
             )}
 

package/src/components/HkCrossfade.scss

@@ -0,0 +1,61 @@
+/* HkCrossfade — same-position simultaneous dissolve host.
+ *
+ * Geometry: the host is a one-cell grid and every item occupies THAT cell
+ * (grid-area: 1/1). During a swap the leaving item keeps the cell, so old
+ * and new stack in the SAME box: no exit blank phase, no side-by-side
+ * reflow, and the host stays as tall as the taller of the two items until
+ * the leave completes — variable-height content never collapses mid-
+ * dissolve. This is the height-safe generalization of HkPickerPane's fixed
+ * stage + absolute leave (no known stage size needed, so whole pages can
+ * swap through it).
+ *
+ * Consumers size the host from the outside (width/height/flex are theirs);
+ * the component only guarantees the stacking geometry and the dissolve.
+ */
+.hk-crossfade {
+  display: grid;
+
+  > .hk-crossfade-item {
+    grid-area: 1 / 1;
+    width: 100%;
+    min-width: 0;
+  }
+}
+
+/* Dissolve curves: BOTH sides run --duration-normal so the exchange is a
+ * true cross-fade (not a fade-out-then-in), and both ease OUT (fast
+ * start) — midway through the swap the incoming layer already carries most
+ * of the opacity while the outgoing one has already shed most of its, so
+ * the composite never dips toward the background (the classic
+ * double-exposure artifact of symmetric linear fades). The leaving item
+ * also drops pointer events: it is dead content and must not intercept
+ * clicks while it dissolves under the incoming one. */
+.hk-crossfade-enter-active {
+  transition:
+    opacity
+    var(--duration-normal, 0.3s)
+    var(--ease-out-expo, cubic-bezier(0.19, 1, 0.22, 1));
+}
+
+.hk-crossfade-leave-active {
+  transition: opacity var(--duration-normal, 0.3s) ease-out;
+  pointer-events: none;
+}
+
+.hk-crossfade-enter-from,
+.hk-crossfade-leave-to {
+  opacity: 0;
+}
+
+/* Reduced motion: keep the opacity exchange (a fade carries no movement —
+ * HkPhaseTransition precedent), just shorter. Hosts driving the global
+ * animation switch (`html[data-css-animations="0"]`) already pin every
+ * transition via theme.scss's global rule, so no extra variant is needed
+ * here (that variant exists for ANIMATIONS, which the global rule pauses
+ * per-play-state; transitions die through its transition-duration clamp). */
+@media (prefers-reduced-motion: reduce) {
+  .hk-crossfade-enter-active,
+  .hk-crossfade-leave-active {
+    transition: opacity var(--duration-fast, 0.15s) ease;
+  }
+}

package/src/components/HkCrossfade.test.tsx

@@ -0,0 +1,270 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref, type App } from "vue";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as sass from "sass";
+
+import HkCrossfade, { CROSSFADE_WATCHDOG_MS } from "./HkCrossfade";
+
+/**
+ * HkCrossfade contract tests. House style: no @vue/test-utils dependency —
+ * raw createApp mounts on shared containers torn down after each case.
+ *
+ * Timing model (mirrors ModeMorphTabs.test): happy-dom resolves no CSS
+ * transition durations, so with a working (timer-driven) rAF the swap
+ * completes inside fake-timer advances. Freezing rAF via stubGlobal holds
+ * both transition generations in the DOM — which is exactly the state the
+ * simultaneous dissolve and the watchdog are about.
+ */
+
+const mounts: App[] = [];
+const containers: HTMLElement[] = [];
+
+interface Harness {
+  container: HTMLElement;
+  set: (key: string) => Promise<void>;
+}
+
+function mountCrossfade(opts: {
+  initial?: string;
+  appear?: boolean;
+  disabled?: boolean;
+} = {}): Harness {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+
+  const current = ref(opts.initial ?? "a");
+  const Wrapper = defineComponent({
+    setup() {
+      return () =>
+        h(
+          HkCrossfade,
+          {
+            swapKey: current.value,
+            appear: opts.appear ?? false,
+            disabled: opts.disabled ?? false,
+          },
+          {
+            default: () => h("p", { class: "body" }, `body-${current.value}`),
+          },
+        );
+    },
+  });
+  const app = createApp(Wrapper);
+  mounts.push(app);
+  app.mount(container);
+  return {
+    container,
+    set: async (key: string) => {
+      current.value = key;
+      await nextTick();
+    },
+  };
+}
+
+function items(host: HTMLElement): HTMLElement[] {
+  // The mount container holds the .hk-crossfade host; items are the HOST's
+  // direct children (Transition renders no DOM of its own).
+  return Array.from(
+    host.querySelectorAll<HTMLElement>(":scope > .hk-crossfade > .hk-crossfade-item"),
+  );
+}
+
+function keys(host: HTMLElement): Array<string | undefined> {
+  return items(host).map((el) => el.dataset.crossfadeKey);
+}
+
+function assertNoFrozenClasses(el: HTMLElement): void {
+  for (const cls of Array.from(el.classList)) {
+    expect(cls.startsWith("hk-crossfade-enter") || cls.startsWith("hk-crossfade-leave")).toBe(false);
+  }
+}
+
+function freezeRaf(): void {
+  vi.stubGlobal("requestAnimationFrame", (_cb: FrameRequestCallback) => 0 as unknown as number);
+  vi.stubGlobal("cancelAnimationFrame", () => {});
+}
+
+afterEach(() => {
+  for (const app of mounts) app.unmount();
+  mounts.length = 0;
+  document.body.innerHTML = "";
+  containers.length = 0;
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+describe("HkCrossfade — DOM contract", () => {
+  it("renders the active item silently on first paint (appear off)", () => {
+    vi.useFakeTimers();
+    const { container } = mountCrossfade({ initial: "a" });
+    const list = items(container);
+    expect(list).toHaveLength(1);
+    expect(list[0]!.dataset.crossfadeKey).toBe("a");
+    expect(list[0]!.textContent).toContain("body-a");
+    assertNoFrozenClasses(list[0]!);
+  });
+
+  it("healthy swap completes through the Transition and settles on the new item", async () => {
+    vi.useFakeTimers();
+    const { container, set } = mountCrossfade();
+    await set("b");
+    // Past the watchdog budget: the swap completed through the Transition
+    // long before, and the watchdog fired into a settled DOM as a no-op.
+    await vi.advanceTimersByTimeAsync(CROSSFADE_WATCHDOG_MS + 100);
+    const list = items(container);
+    expect(list).toHaveLength(1);
+    expect(list[0]!.dataset.crossfadeKey).toBe("b");
+    expect(list[0]!.textContent).toContain("body-b");
+    assertNoFrozenClasses(list[0]!);
+  });
+
+  it("dissolves SIMULTANEOUSLY: old and new share the same host mid-swap (no out-in gap)", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    const { container, set } = mountCrossfade();
+    await set("b");
+    await vi.advanceTimersByTimeAsync(200); // inside the watchdog budget
+    const list = items(container);
+    // Both generations mounted at once — the default-mode contract. With
+    // `mode="out-in"` the old item would already be gone here (blank phase);
+    // with a bare default Transition they would sit side by side instead of
+    // stacked in one host cell.
+    expect(keys(container)).toEqual(["a", "b"]);
+    expect(list[0]!.classList.contains("hk-crossfade-leave-active")).toBe(true);
+    expect(list[1]!.classList.contains("hk-crossfade-enter-from")).toBe(true);
+  });
+
+  it("watchdog completes a stalled swap: sweeps frozen classes, drops the stale item", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    const { container, set } = mountCrossfade();
+    await set("b");
+    await vi.advanceTimersByTimeAsync(CROSSFADE_WATCHDOG_MS - 100); // still wedged
+    expect(keys(container)).toEqual(["a", "b"]);
+    await vi.advanceTimersByTimeAsync(200); // past the budget
+    const list = items(container);
+    expect(list).toHaveLength(1);
+    expect(list[0]!.dataset.crossfadeKey).toBe("b");
+    assertNoFrozenClasses(list[0]!);
+  });
+
+  it("re-arms a fresh Transition on the next swap after a wedged one (dissolves resume)", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    const { container, set } = mountCrossfade();
+    await set("b");
+    await vi.advanceTimersByTimeAsync(CROSSFADE_WATCHDOG_MS + 100); // recovered once
+    expect(keys(container)).toEqual(["b"]);
+    // The next swap restores the Transition. The swept DOM left no previous
+    // child inside the fresh instance, so that one swap lands as a
+    // synchronous hard cut (the one-time cost of a stall) — settled and
+    // correct, no wedge loop.
+    await set("c");
+    const list = items(container);
+    expect(list).toHaveLength(1);
+    expect(list[0]!.dataset.crossfadeKey).toBe("c");
+    assertNoFrozenClasses(list[0]!);
+    // From there on, swaps run the dissolve again: with a previous child
+    // in the fresh Transition, the still-frozen rAF wedges this one, and
+    // the budget recovers it — every swap lands correct, at most one
+    // budget late.
+    await set("d");
+    await vi.advanceTimersByTimeAsync(200); // mid-swap: both generations
+    expect(keys(container)).toEqual(["c", "d"]);
+    await vi.advanceTimersByTimeAsync(CROSSFADE_WATCHDOG_MS); // recovered
+    const settled = items(container);
+    expect(settled).toHaveLength(1);
+    expect(settled[0]!.dataset.crossfadeKey).toBe("d");
+    assertNoFrozenClasses(settled[0]!);
+  });
+
+  it("appear dissolves the first item in; the watchdog un-freezes it under rAF starvation", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    const { container } = mountCrossfade({ initial: "a", appear: true });
+    await vi.advanceTimersByTimeAsync(50);
+    expect(items(container)[0]!.classList.contains("hk-crossfade-enter-from")).toBe(true);
+    await vi.advanceTimersByTimeAsync(CROSSFADE_WATCHDOG_MS + 100);
+    const list = items(container);
+    expect(list).toHaveLength(1);
+    expect(list[0]!.dataset.crossfadeKey).toBe("a");
+    assertNoFrozenClasses(list[0]!);
+  });
+
+  it("disabled swaps synchronously with zero transition classes", async () => {
+    vi.useFakeTimers();
+    const { container, set } = mountCrossfade({ disabled: true });
+    await set("b");
+    const list = items(container);
+    expect(list).toHaveLength(1);
+    expect(list[0]!.dataset.crossfadeKey).toBe("b");
+    assertNoFrozenClasses(list[0]!);
+  });
+
+  it("re-rendering with the same swapKey swaps nothing", async () => {
+    vi.useFakeTimers();
+    const { container, set } = mountCrossfade({ initial: "a" });
+    await set("a");
+    await vi.advanceTimersByTimeAsync(100);
+    const list = items(container);
+    expect(list).toHaveLength(1);
+    assertNoFrozenClasses(list[0]!);
+  });
+});
+
+describe("HkCrossfade — stylesheet contract", () => {
+  const here = dirname(fileURLToPath(import.meta.url));
+
+  it("stacks both generations in one grid cell — the same-position guarantee", () => {
+    const css = sass.compile(join(here, "HkCrossfade.scss")).css;
+    expect(css).toMatch(/\.hk-crossfade\s*\{[^}]*display:\s*grid/);
+    const item = css.match(/\.hk-crossfade-item[^{]*\{[^}]*\}/)?.[0] ?? "";
+    expect(item).toContain("grid-area: 1/1");
+  });
+
+  it("dissolves opacity only — no transform anywhere, dead layer drops pointer events", () => {
+    const css = sass.compile(join(here, "HkCrossfade.scss")).css;
+    expect(css).not.toContain("transform");
+    const leave = css.match(/\.hk-crossfade-leave-active[^{]*\{[^}]*\}/)?.[0] ?? "";
+    expect(leave).toContain("transition: opacity");
+    expect(leave).toContain("pointer-events: none");
+    expect(leave).toContain("var(--duration-normal, 0.3s)");
+    const enter = css.match(/\.hk-crossfade-enter-active[^{]*\{[^}]*\}/)?.[0] ?? "";
+    expect(enter).toContain("transition: opacity");
+    expect(enter).toContain("var(--duration-normal, 0.3s)");
+    for (const phase of ["enter-from", "leave-to"]) {
+      const block = css.match(new RegExp(`\\.hk-crossfade-${phase}[^{]*\\{[^}]*\\}`))?.[0] ?? "";
+      expect(block, `hk-crossfade-${phase} rule missing`).toContain("opacity: 0");
+    }
+  });
+
+  it("reduced motion keeps the opacity exchange, just shorter (fade survives, motion dies)", () => {
+    const css = sass.compile(join(here, "HkCrossfade.scss")).css;
+    const media = css.match(/@media \(prefers-reduced-motion: reduce\)\s*\{[\s\S]*\}\s*$/)?.[0] ?? "";
+    expect(media).toContain(".hk-crossfade-enter-active");
+    expect(media).toContain(".hk-crossfade-leave-active");
+    expect(media).toContain("var(--duration-fast, 0.15s)");
+  });
+});
+
+describe("HkCrossfade — wiring contract", () => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const src = readFileSync(join(here, "HkCrossfade.tsx"), "utf-8");
+
+  it("runs the Transition in default (simultaneous) mode and never overrides its duration", () => {
+    expect(src).toContain('<Transition\n            name="hk-crossfade"');
+    expect(src).not.toMatch(/<Transition[^>]*\bmode=/);
+    expect(src).not.toContain("duration={{");
+  });
+
+  it("pins the watchdog wiring and the animation-bus report", () => {
+    expect(src).toContain("export const CROSSFADE_WATCHDOG_MS = 450;");
+    expect(src).toContain("suppress.value = true;");
+    expect(src).toContain("el.remove();");
+    expect(src).toContain("useReportedTransition(REPORT_MS)");
+    expect(src).toContain("armReport(); armWatchdog();");
+  });
+});

package/src/components/HkCrossfade.tsx

@@ -0,0 +1,197 @@
+import { defineComponent, onBeforeUnmount, ref, Transition, watch, type PropType } from "vue";
+
+import { useReportedTransition } from "../composables/useReportedTransition";
+
+import "./HkCrossfade.scss";
+
+/** Swap-stall watchdog budget. Must sit above ANY healthy completion of the
+ *  dissolve (--duration-normal 0.3s; 0s under reduced motion or the global
+ *  animation switch) so the sweep only ever bites a genuinely stalled swap.
+ *  Exported for tests and budget-pinning. */
+export const CROSSFADE_WATCHDOG_MS = 450;
+
+/** Animation-bus report window — covers the watchdog budget so JS
+ *  choreography reacting to a swap outlives the CSS work under every
+ *  timing, including a stalled one. */
+const REPORT_MS = CROSSFADE_WATCHDOG_MS;
+
+/**
+ * HkCrossfade — same-position simultaneous dissolve for view/mode swaps.
+ *
+ * The library-level primitive for "the old content fades out WHILE the new
+ * content fades in, in place": a default-mode (NO `mode` prop) `<Transition>`
+ * whose enter and leave items share ONE grid cell, so the two generations
+ * stack at the same geometry for the duration of the dissolve — no exit
+ * blank phase (the `out-in` gap of HkPhaseTransition/HkStepFlow), no
+ * side-by-side reflow (a bare default-mode Transition), and no height
+ * collapse while both are mounted (the host stays as tall as the taller
+ * item until the leave completes). This is the height-safe generalization
+ * of HkPickerPane's fixed stage + absolute leave: it needs no known stage
+ * size, so whole pages (admin views, auth cards) can swap through it.
+ *
+ * Contract:
+ * - `swapKey` is the identity of the content on stage. The component owns
+ *   the keyed item wrapper (like HkPhaseTransition owns its key) so the
+ *   watchdog can tell stale items from the active one; rendering with the
+ *   same value swaps nothing.
+ * - Pure opacity — no transform, ever. Same-position means same-position.
+ *   Both sides run `--duration-normal` so the exchange is a true dissolve;
+ *   both ease out (fast start), which keeps the incoming (top) layer's
+ *   opacity ahead of the outgoing one's decay and stops the composite from
+ *   dipping toward the background mid-swap.
+ * - The leaving item drops pointer events: it is dead content and must not
+ *   intercept clicks while it dissolves under the incoming one.
+ * - `appear` dissolves the initially rendered item in; off by default —
+ *   first paint should never animate (view shells, restored state).
+ * - `disabled` renders the active item bare (synchronous swap, no watchdog):
+ *   the test escape hatch and the watchdog's degraded render path.
+ * - Reduced motion keeps the opacity exchange at `--duration-fast` (a fade
+ *   carries no movement — HkPhaseTransition precedent); hosts driving the
+ *   global animation switch (`html[data-css-animations="0"]`) already pin
+ *   these transitions via theme.scss.
+ * - Every swap is REPORTED to the runtime animation bus
+ *   (`useReportedTransition`, refcounted across the concurrent enter+leave)
+ *   so JS choreography reacting to the swap is not cut short by the CSS
+ *   work ending early.
+ * - The swap-stall watchdog bounds the rAF-starvation wedge (occluded or
+ *   backgrounded webview): Vue's Transition engine is rAF-gated, so a
+ *   starved swap freezes the leaving item on top of the new one (field
+ *   report 2026-09 in chest's ModeMorphTabs — the design this watchdog
+ *   inherits, alongside the surfaceMachine AXIOM A2 deadline rule). The
+ *   450ms budget sits above ANY healthy completion, so on healthy surfaces
+ *   the sweep fires into an already-settled DOM and is a no-op. After a
+ *   real stall it strips the frozen transition classes, removes the stale
+ *   item Vue can no longer unmount, and degrades to synchronous rendering
+ *   until the next `swapKey` change re-arms the Transition fresh.
+ */
+export default defineComponent({
+  name: "HkCrossfade",
+  props: {
+    swapKey: { type: [String, Number] as PropType<string | number>, required: true },
+    tag: { type: String, default: "div" },
+    appear: { type: Boolean, default: false },
+    disabled: { type: Boolean, default: false },
+  },
+  setup(props, { slots }) {
+    const hostRef = ref<HTMLElement | null>(null);
+    // Set after a watchdog sweep proved the Transition engine wedged; the
+    // render drops the Transition wrapper so keys apply synchronously until
+    // the next swap re-arms it (a one-tick toggle re-enters the wedged
+    // internal state otherwise — ModeMorphTabs lesson).
+    const suppress = ref(false);
+
+    // ── Animation-bus participation ──────────────────────────────────
+    // One swap runs an enter AND a leave concurrently; refcount them so
+    // the shared track stays armed until BOTH settle (HkListTransition
+    // pattern).
+    const report = useReportedTransition(REPORT_MS);
+    let pending = 0;
+    const armReport = () => {
+      pending++;
+      report.run();
+    };
+    const settleReport = () => {
+      pending = Math.max(0, pending - 1);
+      if (pending === 0) report.cancel();
+    };
+
+    // ── Swap-stall watchdog ──────────────────────────────────────────
+    let watchdog: ReturnType<typeof setTimeout> | null = null;
+
+    function armWatchdog(): void {
+      // Re-arm per swap event (enter or leave start); a healthy swap lets
+      // the timer fire into a settled DOM, where the sweep is a no-op.
+      if (watchdog !== null) clearTimeout(watchdog);
+      watchdog = setTimeout(onWatchdog, CROSSFADE_WATCHDOG_MS);
+    }
+
+    function sweepFrozenClasses(el: Element): boolean {
+      const frozenLeave = el.classList.contains("hk-crossfade-leave-active")
+        || el.classList.contains("hk-crossfade-leave-from");
+      el.classList.remove(
+        "hk-crossfade-enter-active",
+        "hk-crossfade-enter-from",
+        "hk-crossfade-enter-to",
+        "hk-crossfade-leave-active",
+        "hk-crossfade-leave-from",
+        "hk-crossfade-leave-to",
+      );
+      return frozenLeave;
+    }
+
+    function onWatchdog(): void {
+      watchdog = null;
+      const host = hostRef.value;
+      if (!host) return;
+      let wedged = false;
+      for (const el of Array.from(host.querySelectorAll<HTMLElement>(":scope > .hk-crossfade-item"))) {
+        const frozenLeave = sweepFrozenClasses(el);
+        // A stale item still holding a leave class is one Vue's rAF-gated
+        // engine can never unmount — remove it by hand and mark the engine
+        // wedged so this and future swaps render synchronously.
+        if (frozenLeave && el.dataset.crossfadeKey !== String(props.swapKey)) {
+          el.remove();
+          wedged = true;
+        }
+      }
+      if (wedged) suppress.value = true;
+    }
+
+    watch(() => props.swapKey, () => {
+      // Fresh swap: restore the Transition (the wedged one was discarded
+      // with the suppressed render). The watchdog re-arms from the
+      // beforeEnter/beforeLeave hooks of the new Transition instance.
+      suppress.value = false;
+    });
+    onBeforeUnmount(() => {
+      if (watchdog !== null) {
+        clearTimeout(watchdog);
+        watchdog = null;
+      }
+    });
+
+    return () => {
+      const Tag = props.tag as "div" | "section" | "main" | "aside";
+      const item = () => (
+        <div
+          key={props.swapKey}
+          class="hk-crossfade-item"
+          data-crossfade-key={String(props.swapKey)}
+        >
+          {slots.default?.()}
+        </div>
+      );
+
+      if (props.disabled || suppress.value) {
+        // Watchdog recovery / explicit opt-out: no Transition wrapper, so
+        // the key swap applies synchronously even with rAF frozen.
+        return (
+          <Tag ref={hostRef} class="hk-crossfade">
+            {item()}
+          </Tag>
+        );
+      }
+
+      return (
+        <Tag ref={hostRef} class="hk-crossfade">
+          {/* Deliberately NO `mode`: enter and leave run CONCURRENTLY in
+            the same grid cell — that is the whole point of this component.
+            A `mode="out-in"` here would reintroduce the exit blank phase;
+            `mode="in-out"` would double-stack full-opacity content. */}
+          <Transition
+            name="hk-crossfade"
+            appear={props.appear}
+            onBeforeEnter={() => { armReport(); armWatchdog(); }}
+            onAfterEnter={settleReport}
+            onEnterCancelled={settleReport}
+            onBeforeLeave={() => { armReport(); armWatchdog(); }}
+            onAfterLeave={settleReport}
+            onLeaveCancelled={settleReport}
+          >
+            {item()}
+          </Transition>
+        </Tag>
+      );
+    };
+  },
+});

package/src/index.ts

@@ -16,6 +16,7 @@ export { default as HColorPicker } from "./components/HkColorPicker";
 export { HColorSchemeDialog, type HCustomTheme } from "./components/HkColorSchemeDialog";
 export { HkColorSchemeEditor } from "./components/HkColorSchemeEditor";
 export { default as HConfirmDialog } from "./components/HkConfirmDialog";
+export { default as HCrossfade } from "./components/HkCrossfade";
 export { default as HDivider } from "./components/HkDivider";
 export { default as HDrawer } from "./components/HkDrawer";
 export { default as HEmptyState } from "./components/HkEmptyState";
@@ -356,6 +357,7 @@ export { HkProtocolModal as HProtocolModal } from "./components/HkProtocolModal"
 export {
   HkAboutModal as HAboutModal,
   type HAboutComponentVersion,
+  type HAboutCredit,
   type HAboutLink,
 } from "./components/HkAboutModal";
 export { HkLogWindow as HLogWindow, type HLogTab } from "./components/HkLogWindow";