@celestia-island/hikari 0.55.37 → 0.55.38

package/package.json

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

package/src/components/HkStepFlow.phonesnap.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Source contract for the phone step-swap snap (2026-09-21 chest field
+ * report, AddProviderWizard Prev/Next "content blinks once").
+ *
+ * On ≤767px the step body's slide+fade must be inert: inside the mobile
+ * bottom sheet the frame's own size morph already carries the spatial
+ * feedback, and the slide's transient layer promotion/demotion costs a
+ * one-frame raster gap at both ends on phone GPUs. Desktop keeps the
+ * directional slide; reduced motion already snaps globally.
+ *
+ * Pinned here so a refactor cannot silently restore the phone slide —
+ * the class names are the same, so only the media-scoped rule proves it.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const src = readFileSync(join(here, "HkStepFlow.scss"), "utf-8");
+
+/** Brace-aware `@media <query>` block extractor: a naive slice at the
+ *  first `}` would cut at the first nested rule's closing brace. */
+function mediaBlocks(source: string, query: string): string[] {
+  const blocks: string[] = [];
+  let from = 0;
+  for (;;) {
+    const at = source.indexOf(`@media ${query}`, from);
+    if (at < 0) break;
+    const open = source.indexOf("{", at);
+    let depth = 0;
+    let i = open;
+    for (; i < source.length; i++) {
+      if (source[i] === "{") depth++;
+      else if (source[i] === "}") {
+        depth--;
+        if (depth === 0) break;
+      }
+    }
+    blocks.push(source.slice(at, i + 1));
+    from = i + 1;
+  }
+  return blocks;
+}
+
+const PHONE_QUERY = "(max-width: 767px)";
+/** The four transition-class selectors Vue's <Transition> toggles. */
+const ACTIVE_SELECTORS = [
+  ".hk-stepflow-fwd-enter-active",
+  ".hk-stepflow-back-enter-active",
+  ".hk-stepflow-fwd-leave-active",
+  ".hk-stepflow-back-leave-active",
+];
+
+/** The single ≤767px block, asserted present IN the test that needs it
+ *  (a beforeAll assertion would downgrade a missing block to "skipped"
+ *  instead of a hard failure). */
+function phoneBlock(): string {
+  const blocks = mediaBlocks(src, PHONE_QUERY);
+  expect(blocks.length).toBe(1);
+  return blocks[0]!;
+}
+
+describe("HkStepFlow phone snap contract", () => {
+  it("disables the slide/fade transition on ≤767px", () => {
+    const block = phoneBlock();
+    for (const selector of ACTIVE_SELECTORS) {
+      expect(block).toContain(selector);
+    }
+    // transition:none on every active class — the whole point: no
+    // property animates, so no promotion window exists to blink.
+    expect(block).toMatch(/transition:\s*none\s*;/);
+    // …and it must be the ONLY transition declaration in the block
+    // (a stray `transition: opacity …` would re-open the blink).
+    const declarations = block.match(/transition:\s*[^;]+;/g) ?? [];
+    expect(declarations).toHaveLength(1);
+  });
+
+  it("keeps the desktop slide outside the phone block", () => {
+    // Mutation guard: the phone rule must be ADDITIVE. The base
+    // (desktop) enter/leave rules still carry the opacity+transform
+    // transition, so deleting them fails here instead of passing
+    // vacuously.
+    const baseEnter = src.match(
+      /\.hk-stepflow-fwd-enter-active\s*,\s*\n\.hk-stepflow-back-enter-active\s*\{[^}]*\}/,
+    );
+    expect(baseEnter).not.toBeNull();
+    expect(baseEnter![0]).toContain("transition:");
+    expect(baseEnter![0]).toContain("opacity");
+    expect(baseEnter![0]).toContain("transform");
+
+    const baseLeave = src.match(
+      /\.hk-stepflow-fwd-leave-active\s*,\s*\n\.hk-stepflow-back-leave-active\s*\{[^}]*\}/,
+    );
+    expect(baseLeave).not.toBeNull();
+    expect(baseLeave![0]).toContain("opacity");
+    expect(baseLeave![0]).toContain("transform");
+  });
+
+  it("keeps the reduce-motion snap block (house pattern) intact", () => {
+    const blocks = mediaBlocks(src, "(prefers-reduced-motion: reduce)");
+    expect(blocks.length).toBe(1);
+    expect(blocks[0]).toMatch(/transition:\s*none\s*;/);
+  });
+});

package/src/components/HkStepFlow.scss

@@ -89,6 +89,22 @@
   transform: translateX(24px);
 }
 
+/* Phone (≤767px): the body snaps between steps instead of sliding. On
+ * the mobile sheet the frame's own size morph already carries the
+ * spatial feedback, and the slide's transient layer promotion/demotion
+ * costs a one-frame raster gap at both ends on phone GPUs — the
+ * "content blinks once on every step" report (2026-09-21 chest field
+ * report, AddProviderWizard Prev/Next). Same shape as the
+ * reduced-motion block below; desktop keeps the directional slide. */
+@media (max-width: 767px) {
+  .hk-stepflow-fwd-enter-active,
+  .hk-stepflow-back-enter-active,
+  .hk-stepflow-fwd-leave-active,
+  .hk-stepflow-back-leave-active {
+    transition: none;
+  }
+}
+
 /* Reduced motion: the body snaps between steps instead of sliding
  * (house pattern: HkExpansionPanel.scss / HkAffixPicker.scss). */
 @media (prefers-reduced-motion: reduce) {

package/src/components/HkTitleBar.scss

@@ -115,6 +115,15 @@
   border-radius: 8px 0 0 0;
 }
 
+/* A maximized frame has no rounded window corner to follow: Windows 11
+   squares decorated windows itself and borderless hosts square the DWM
+   corners manually, so keeping the radius would round the hover fill
+   away from the (square) frame corner. The (0,3,0) compound out-ranks
+   both the base rule and the RTL mirror above. */
+.hk-titlebar[data-maximized] .hk-titlebar-btn-close {
+  border-radius: 0;
+}
+
 .hk-titlebar-btn-close:hover {
   background: var(--hk-tb-close-hover);
   color: var(--hi-color-text-on-danger, #ffffff);

package/src/components/HkTitleBar.test.tsx

@@ -0,0 +1,127 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compile } from "sass";
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h, nextTick, ref } from "vue";
+
+import HkTitleBar from "./HkTitleBar";
+
+/**
+ * HkTitleBar maximized-state contract tests.
+ *
+ * The `maximized` prop drives three things; all are contract-tested here
+ * because the failure mode is silent (a wrong glyph, a hover fill that
+ * rounds away from a square frame corner):
+ *
+ *   1. the root carries `data-maximized` only while maximized — the
+ *      stylesheet keys the close-button radius override off it,
+ *   2. the maximize button swaps its glyph/title with the same prop, and
+ *   3. the compiled sheet squares the close corner under `[data-maximized]`.
+ *
+ * The compiled-stylesheet guard exists because vitest stubs CSS, so a
+ * runtime test can never notice the rule going missing (the HkAboutModal
+ * styles test hit exactly that class of regression).
+ *
+ * (Repo test convention: raw createApp + container queries, no
+ * @vue/test-utils dependency.)
+ */
+
+const componentDir = resolve(dirname(fileURLToPath(import.meta.url)));
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(node: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => node });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+describe("HkTitleBar", () => {
+  it("marks the root data-maximized only while maximized", () => {
+    const windowed = mount(h(HkTitleBar, { title: "App", maximized: false }));
+    expect(windowed.querySelector(".hk-titlebar")?.hasAttribute("data-maximized")).toBe(false);
+
+    const maximized = mount(h(HkTitleBar, { title: "App", maximized: true }));
+    expect(maximized.querySelector(".hk-titlebar")?.hasAttribute("data-maximized")).toBe(true);
+  });
+
+  it("follows the prop reactively, adding and removing the marker", async () => {
+    // Hosts toggle `maximized` live (resize listener → ref); the marker
+    // must come and go with it, not just latch on mount.
+    const maximized = ref(false);
+    const host = mount(
+      h(() => h(HkTitleBar, { title: "App", maximized: maximized.value })),
+    );
+    const bar = () => host.querySelector<HTMLElement>(".hk-titlebar")!;
+    expect(bar().hasAttribute("data-maximized")).toBe(false);
+
+    maximized.value = true;
+    await nextTick();
+    expect(bar().hasAttribute("data-maximized")).toBe(true);
+
+    maximized.value = false;
+    await nextTick();
+    expect(bar().hasAttribute("data-maximized")).toBe(false);
+  });
+
+  it("swaps the maximize glyph with the same prop", () => {
+    const windowed = mount(h(HkTitleBar, { title: "App", maximized: false }));
+    expect(windowed.querySelector('[title="Maximize"]')).toBeTruthy();
+
+    const maximized = mount(h(HkTitleBar, { title: "App", maximized: true }));
+    expect(maximized.querySelector('[title="Restore"]')).toBeTruthy();
+  });
+});
+
+describe("HkTitleBar stylesheet contract", () => {
+  const css = compile(resolve(componentDir, "HkTitleBar.scss"), {
+    style: "expanded",
+  }).css;
+
+  /**
+   * Body of one compiled rule, by exact selector (Sass drops the quotes
+   * around an attribute value: `[data-maximized]`).
+   *
+   * The selector is anchored to its own line: expanded Sass puts every
+   * selector of a rule (comma lists included) on its own line, so this
+   * skips compound rules that merely END with the selector (e.g. the
+   * `[data-maximized]` override) while still requiring exactly one match —
+   * a second copy, say inside a media query, would stay invisible to a
+   * looser scan while still winning the cascade.
+   */
+  function ruleBody(sheet: string, selector: string): string {
+    const escaped = selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const matches = [
+      ...sheet.matchAll(new RegExp(`(?:^|\\n)\\s*${escaped}\\s*\\{([^}]*)\\}`, "g")),
+    ];
+    expect(matches, `${selector} compiles exactly once`).toHaveLength(1);
+    return matches[0]?.[1] ?? "";
+  }
+
+  it("squares the close button corner while maximized, both directions", () => {
+    // The (0,3,0) compound must survive compilation and out-rank the base
+    // radius rule and its RTL mirror; reading the compiled declarations
+    // (not the SCSS source) means a rule that failed to compile fails here.
+    const body = ruleBody(css, ".hk-titlebar[data-maximized] .hk-titlebar-btn-close");
+    expect(body).toContain("border-radius: 0");
+  });
+
+  it("keeps the windowed radius var wired to the close button", () => {
+    const scss = readFileSync(resolve(componentDir, "HkTitleBar.scss"), "utf8");
+    expect(scss).toContain("--hk-tb-radius-close:");
+    const body = ruleBody(css, ".hk-titlebar-btn-close");
+    expect(body).toContain("border-radius: var(--hk-tb-radius-close)");
+  });
+});

package/src/components/HkTitleBar.tsx

@@ -23,7 +23,9 @@ import "./HkTitleBar.scss";
  * to the LEFT of minimize, each emitting `action` with its id.
  *
  * The maximized state is data-driven: the host passes `maximized` and the
- * component swaps the maximize/restore glyph — no shell probing inside.
+ * component swaps the maximize/restore glyph and squares the close button's
+ * window corner radius (a maximized frame has no rounded corner to follow)
+ * — no shell probing inside.
  */
 export default defineComponent({
   name: "HkTitleBar",
@@ -51,7 +53,11 @@ export default defineComponent({
   },
   setup(props, { emit, slots }) {
     return () => (
-      <div class="hk-titlebar" data-drag-region>
+      <div
+        class="hk-titlebar"
+        data-drag-region
+        data-maximized={props.maximized || undefined}
+      >
         {slots.left?.() ?? (
           <span class="hk-titlebar-title">
             {props.icon && <img class="hk-titlebar-icon" src={props.icon} alt="" />}

package/src/composables/useSizeMorph.test.ts

@@ -1,6 +1,8 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { createApp, h, nextTick, ref } from "vue";
 
+import { readHkRuntime } from "../runtime/registry";
+
 import { useSizeMorph, type SizeMorphOptions } from "./useSizeMorph";
 
 /** Injectable ResizeObserver: captures the callback so tests can fire
@@ -123,6 +125,15 @@ async function settle(): Promise<void> {
   await nextTick();
 }
 
+/** Await exactly N animation frames. The bus's one-shot pump is itself
+ *  rAF-driven and FIFO-ordered with these, so an awaited frame resolves
+ *  in the same tick the pump that ran before it did. */
+async function busFrames(n: number): Promise<void> {
+  for (let i = 0; i < n; i++) {
+    await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+  }
+}
+
 describe("useSizeMorph", () => {
   it("pins the frame to its natural height on start", () => {
     const h = mountHarness(120);
@@ -295,7 +306,61 @@ describe("useSizeMorph clip reveal", () => {
     expect(h.frame.style.willChange).toBe("");
   });
 
-  it("starts the sweep from the old visual edge (delta inset)", () => {
+  it("holds the staged clip through a two-frame warmup before the sweep starts", async () => {
+    const h = mountHarness(300);
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.start();
+
+    h.setNatural(360);
+    h.remeasure();
+    // Staged synchronously — new pin, start inset, layer promotion —
+    // but NO sweep yet: the reveal must let the promoted layer raster
+    // the resized box first (2026-09-21 chest report — a same-task
+    // sweep outran the raster thread and the revealed band composited
+    // as black tiles).
+    expect(h.frame.style.height).toBe("360px");
+    expect(h.frame.style.clipPath).toBe("inset(60px 0 0 0 round 0px 0px 0px 0px)");
+    expect(h.frame.style.willChange).toBe("clip-path");
+
+    // The hold is TWO frames, not one: after the first frame the staged
+    // start inset must still be in place (a one-frame warmup would have
+    // already opened the clip).
+    await busFrames(1);
+    expect(h.frame.style.clipPath).toBe("inset(60px 0 0 0 round 0px 0px 0px 0px)");
+
+    await settle();
+    expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
+    fireTransitionEnd(h.frame, "clip-path");
+    expect(h.frame.style.clipPath).toBe("");
+    expect(h.frame.style.willChange).toBe("");
+  });
+
+  it("reports the sweep to the animation bus only once it starts", async () => {
+    const h = mountHarness(300);
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    // Let any earlier test's report timer expire so the baseline is quiet.
+    await new Promise((resolve) => setTimeout(resolve, 220));
+    const transitions = (): number =>
+      Number(readHkRuntime("animationBus")?.transitions ?? 0);
+    const base = transitions();
+
+    h.start();
+    h.setNatural(360);
+    h.remeasure();
+    // Warmup pending: no CSS transition is running yet, nothing reported.
+    expect(transitions()).toBe(base);
+
+    // Two warmup frames start the sweep; its 150ms report is live now
+    // (well inside the report's window — do NOT use the 220ms settle,
+    // it outlives the report).
+    await busFrames(3);
+    expect(transitions()).toBe(base + 1);
+
+    fireTransitionEnd(h.frame, "clip-path");
+    expect(transitions()).toBe(base);
+  });
+
+  it("starts the sweep from the old visual edge (delta inset)", async () => {
     const h = mountHarness(300);
     h.frame.style.setProperty("--hk-sheet-morph", "clip");
     h.start();
@@ -324,6 +389,10 @@ describe("useSizeMorph clip reveal", () => {
       "inset(120px 0 0 0 round 0px 0px 0px 0px)",
     ]);
     expect(h.frame.style.height).toBe("420px");
+    // The staged start inset HOLDS through the warmup — the sweep is a
+    // bus one-shot now, never part of the staging task.
+    expect(h.frame.style.clipPath).toBe("inset(120px 0 0 0 round 0px 0px 0px 0px)");
+    await settle();
     expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
   });
 
@@ -366,18 +435,49 @@ describe("useSizeMorph clip reveal", () => {
 
     h.setNatural(380);
     h.remeasure();
+    // Staged: the sweep is still pending on the warmup.
+    expect(h.frame.style.clipPath).toBe("inset(80px 0 0 0 round 0px 0px 0px 0px)");
+    await settle();
     expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
 
-    // A second growth lands before transitionend fired: the stale clip
-    // must come off inside the new dance, then the new reveal stages.
+    // A second growth lands mid-sweep: the stale clip/listener/report
+    // must come off inside the new dance, then the new reveal stages
+    // from the NEW delta (450 − 380 = 70px).
     h.setNatural(450);
     h.remeasure();
     expect(h.frame.style.height).toBe("450px");
-    expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
+    expect(h.frame.style.clipPath).toBe("inset(70px 0 0 0 round 0px 0px 0px 0px)");
     expect(h.frame.style.willChange).toBe("clip-path");
   });
 
-  it("clears an interrupted reveal inside the next dance (no transitionend)", () => {
+  it("cancels a pending warmup when a second growth re-stages mid-warmup", async () => {
+    const h = mountHarness(300);
+    h.frame.style.setProperty("--hk-sheet-morph", "clip");
+    h.start();
+
+    h.setNatural(380);
+    h.remeasure();
+    expect(h.frame.style.clipPath).toBe("inset(80px 0 0 0 round 0px 0px 0px 0px)");
+
+    // Burn exactly one of the first warmup's two frames, then re-stage.
+    // A LEAKED first warmup would run its sweep on the next frame; the
+    // cancelled one (disconnect in stopReveal) never does.
+    await busFrames(1);
+    h.setNatural(450);
+    h.remeasure();
+    expect(h.frame.style.clipPath).toBe("inset(70px 0 0 0 round 0px 0px 0px 0px)");
+
+    // One frame later the leak would have flipped the clip open; the
+    // freshly staged start inset must still hold.
+    await busFrames(1);
+    expect(h.frame.style.clipPath).toBe("inset(70px 0 0 0 round 0px 0px 0px 0px)");
+
+    // The NEW warmup's second frame starts its own sweep.
+    await busFrames(1);
+    expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
+  });
+
+  it("clears an interrupted reveal inside the next dance (no transitionend)", async () => {
     const h = mountHarness(300);
     h.frame.style.setProperty("--hk-sheet-morph", "clip");
     h.start();
@@ -386,17 +486,22 @@ describe("useSizeMorph clip reveal", () => {
     h.remeasure();
     expect(h.frame.style.clipPath).not.toBe("");
 
-    // A SHRINK lands before the reveal's transitionend fired: unlike a
-    // follow-up growth (which restages its own clip), the height-morph
-    // branch writes no clip at all — the dance-start teardown is the
-    // only thing that returns the frame to CSS ownership (R1 mutation
-    // M1 evidence: without it the stale inset(0px) + will-change ride
-    // the shrink and linger at rest).
+    // A SHRINK lands before the reveal finished: unlike a follow-up
+    // growth (which restages its own clip), the height-morph branch
+    // writes no clip at all — the dance-start teardown is the only
+    // thing that returns the frame to CSS ownership (R1 mutation M1
+    // evidence: without it the stale inset + will-change ride the
+    // shrink and linger at rest). It must also cancel the pending
+    // warmup, or a stale sweep lands after the shrink.
     h.setNatural(310);
     h.remeasure();
     expect(h.frame.style.height).toBe("310px");
     expect(h.frame.style.clipPath).toBe("");
     expect(h.frame.style.willChange).toBe("");
+
+    await settle();
+    expect(h.frame.style.clipPath).toBe("");
+    expect(h.frame.style.willChange).toBe("");
   });
 
   it("releases the clip state on stop so the leave animation owns the frame", async () => {
@@ -412,6 +517,12 @@ describe("useSizeMorph clip reveal", () => {
     expect(h.frame.style.height).toBe("");
     expect(h.frame.style.clipPath).toBe("");
     expect(h.frame.style.willChange).toBe("");
+
+    // A leaked warmup would fire the sweep AFTER the stop and re-add
+    // the clip/promotion — disconnect() in stopReveal is the fix.
+    await settle();
+    expect(h.frame.style.clipPath).toBe("");
+    expect(h.frame.style.willChange).toBe("");
   });
 
   it("ignores transitionend events for other properties", async () => {
@@ -421,6 +532,8 @@ describe("useSizeMorph clip reveal", () => {
 
     h.setNatural(360);
     h.remeasure();
+    // The listener only exists once the warmup started the sweep.
+    await settle();
     fireTransitionEnd(h.frame, "height");
     expect(h.frame.style.clipPath).toBe("inset(0px 0 0 0 round 0px 0px 0px 0px)");
     fireTransitionEnd(h.frame, "opacity");

package/src/composables/useSizeMorph.ts

@@ -1,5 +1,11 @@
 import { onBeforeUnmount, type Ref } from "vue";
 
+import {
+  reportTransition,
+  scheduleFrame,
+  type AnimationHandle,
+} from "../runtime/animationBus";
+
 /** Chrome-allowance calibration constants (px): the floor covers a
  *  standard header+footer+borders stack (and bodies that overflow at
  *  arm time, where the resting delta goes negative and says nothing
@@ -13,6 +19,18 @@ const CHROME_ALLOWANCE_SLACK = 32;
  * layer for. */
 const REVEAL_MIN_PX = 3;
 
+/** Reveal warmup (bus frames): how long the staged clip holds before
+ *  the sweep starts. The pin + clip start + `will-change` land in one
+ *  task, so the promoted layer starts re-rastering the whole resized
+ *  box immediately; holding the sweep for two frames lets that raster
+ *  land before the moving edge reveals it. Starting the sweep in the
+ *  staging task outran the raster thread on phone GPUs and the
+ *  just-revealed band composited as black tiles (2026-09-21 chest
+ *  field report, AddProviderWizard step growth). The staged clip keeps
+ *  the new band hidden through the hold, so the visible geometry is
+ *  the pre-growth sheet while warming — the wait itself is invisible. */
+const REVEAL_WARMUP_FRAMES = 2;
+
 export interface SizeMorph {
   /** Arm the morph: observe the content and pin the frame's natural
    *  height on every change. Call once the surface finished its open
@@ -85,14 +103,28 @@ export interface SizeMorphOptions {
  * transition, same "content rides rigidly" grammar as the modal unveil,
  * but paint/compositor-level: no per-frame layout and no per-frame
  * backdrop-filter re-raster over the resizing fixed layer (the mobile
- * patchy-flicker source, 2026-09-15 chest report). Height-mode
+ * patchy-flicker source, 2026-09-15 chest report). The sweep never
+ * starts in the staging task: a two-frame warmup (REVEAL_WARMUP_FRAMES)
+ * lets the promoted layer's raster land before the edge moves
+ * (2026-09-21 chest report — same-task starts revealed black tiles).
+ * Height-mode
  * surfaces and the select sheet keep the height transition for shrinks
  * (their stylesheets list it); the phone MODAL sheet narrowed its list
  * to clip-path-only (2026-09-21 step-change shrink report — 150ms of
  * per-frame layout on the fixed layer re-rastered the moving edge), so
- * its shrinks snap: the L291-style pin flip lands instantly when the
+ * its shrinks snap: the pin flip lands instantly when the
  * stylesheet no longer transitions height.
  *
+ * Scheduling rides the shared animation context
+ * (`runtime/animationBus`): the measurement hop and the reveal warmup
+ * are bus one-shots (`scheduleFrame`), and the CSS sweep is reported
+ * (`reportTransition`) so the bus keeps beating through it and the
+ * runtime registry sees the load. The settle debounce stays a
+ * real-time timer on purpose — it gates MEASUREMENT, not motion, and a
+ * parked (reduced-motion) bus must never freeze layout by stalling it;
+ * bus one-shots fire even parked, so every frame path still completes
+ * and the motion collapse itself stays CSS-owned.
+ *
  * Reduced motion / the global animation switch stay honored: the frame's
  * transition-duration collapses to one frame under
  * `html[data-css-animations="0"]`, so the pin updates snap.
@@ -103,7 +135,7 @@ export function useSizeMorph(
   options: SizeMorphOptions = {},
 ): SizeMorph {
   let ro: ResizeObserver | null = null;
-  let raf = 0;
+  let raf: AnimationHandle | null = null;
   let settleTimer: ReturnType<typeof setTimeout> | null = null;
   let armed = false;
   /** Last pinned height (px) — the transition's "from" value. */
@@ -116,14 +148,26 @@ export function useSizeMorph(
   let chromeAllowance = CHROME_ALLOWANCE_FLOOR + CHROME_ALLOWANCE_SLACK;
   /** In-flight clip reveal (clip-mode growth morph): the frame whose
    *  inline clip-path/will-change must come off again once the sweep
-   *  lands, plus the listener that does it. */
+   *  lands, the listener that does it, the warmup one-shot that starts
+   *  the sweep, and the sweep's bus transition report. */
   let revealEl: HTMLElement | null = null;
   let revealEnd: ((ev: Event) => void) | null = null;
+  let revealWarmup: AnimationHandle | null = null;
+  let revealReport: AnimationHandle | null = null;
 
-  /** Tear down an in-flight clip reveal: drop the listener and return
-   *  the inline clip/will-change to CSS ownership. Safe to call when no
-   *  reveal is running (every dance start, stop, and unmount). */
+  /** Tear down an in-flight clip reveal: cancel the pending warmup and
+   *  the bus report, drop the listener, and return the inline
+   *  clip/will-change to CSS ownership. Safe to call when no reveal is
+   *  running (every dance start, stop, and unmount). */
   function stopReveal(): void {
+    if (revealWarmup) {
+      revealWarmup.disconnect();
+      revealWarmup = null;
+    }
+    if (revealReport) {
+      revealReport.disconnect();
+      revealReport = null;
+    }
     if (revealEl && revealEnd) {
       revealEl.removeEventListener("transitionend", revealEnd);
     }
@@ -135,6 +179,49 @@ export function useSizeMorph(
     revealEnd = null;
   }
 
+  /** The frame's computed clip-transition duration, for the bus report
+   *  at sweep start: the sweep is CSS-owned, so without a report the
+   *  bus goes quiet for its duration and starves concurrent entries
+   *  (and the runtime registry under-reports load). Max across the
+   *  duration list; falls back to the --duration-fast default when the
+   *  read fails (SSR) or carries no time token. */
+  function transitionDurationMs(f: HTMLElement): number {
+    let raw = "";
+    try {
+      raw = getComputedStyle(f).transitionDuration;
+    } catch {
+      raw = "";
+    }
+    let max = 0;
+    for (const m of raw.matchAll(/(\d+(?:\.\d+)?)(m?)s/g)) {
+      max = Math.max(max, parseFloat(m[1]!) * (m[2] ? 1 : 1000));
+    }
+    return max > 0 ? max : 150;
+  }
+
+  /** Begin the actual sweep: attach the end listener, report the CSS
+   *  transition to the bus so it keeps beating for the duration, and
+   *  flip the clip to the open state under the live transition. Only
+   *  ever called from the warmup's last frame — never synchronously
+   *  from the dance (see REVEAL_WARMUP_FRAMES). */
+  function startRevealSweep(f: HTMLElement, radii: string): void {
+    const onEnd = (ev: Event): void => {
+      // transitionend bubbles: a descendant animating its own
+      // clip-path must not end the frame's reveal early.
+      if (
+        ev.target === f &&
+        (ev as TransitionEvent).propertyName === "clip-path"
+      ) {
+        stopReveal();
+      }
+    };
+    f.addEventListener("transitionend", onEnd);
+    revealEl = f;
+    revealEnd = onEnd;
+    revealReport = reportTransition(transitionDurationMs(f));
+    f.style.clipPath = `inset(0px 0 0 0 round ${radii})`;
+  }
+
   /** Clip-mode opt-in, owned by CSS: the modal's mobile media block
    *  sets `--hk-sheet-morph: clip` inside its ≤767px query, and the
    *  select sheet sets it on its class rule directly (that class only
@@ -212,8 +299,8 @@ export function useSizeMorph(
     //    natural (CSS-capped) height in one layout flush.
     // 2. Clip-mode growth: pin the NEW height outright and stage the
     //    clip start (still transition-disabled), so the reveal that
-    //    follows sweeps a fully-laid-out box — layout happens once,
-    //    here, never per frame.
+    //    follows (after the warmup, started by the bus) sweeps a
+    //    fully-laid-out box — layout happens once, here, never per frame.
     //    Otherwise re-establish the OLD pin (still transition-disabled)
     //    and flush it, so the style history is exactly "old height" when
     //    the live CSS transition returns.
@@ -276,21 +363,29 @@ export function useSizeMorph(
     void f.offsetHeight;
     f.style.transition = inlineTransition;
     if (reveal) {
-      const onEnd = (ev: Event): void => {
-        // transitionend bubbles: a descendant animating its own
-        // clip-path must not end the frame's reveal early.
-        if (
-          ev.target === f &&
-          (ev as TransitionEvent).propertyName === "clip-path"
-        ) {
-          stopReveal();
-        }
-      };
-      f.addEventListener("transitionend", onEnd);
+      // Warmup (see REVEAL_WARMUP_FRAMES): promote the layer now and
+      // hold the staged clip; the sweep itself starts from the bus.
+      // Bus one-shots fire even while the bus is parked for reduced
+      // motion — they are scheduling primitives, not motion; the motion
+      // collapse stays CSS-owned (transition-duration → one frame), so
+      // a parked bus still lands the sweep instantly and transitionend
+      // cleans up exactly as before.
       revealEl = f;
-      revealEnd = onEnd;
       f.style.willChange = "clip-path";
-      f.style.clipPath = `inset(0px 0 0 0 round ${radii})`;
+      let framesLeft = REVEAL_WARMUP_FRAMES;
+      const armWarmup = (): void => {
+        revealWarmup = scheduleFrame(() => {
+          revealWarmup = null;
+          // Torn down mid-warmup (new dance / hold / stop / unmount).
+          if (revealEl !== f) return;
+          if (--framesLeft > 0) {
+            armWarmup();
+            return;
+          }
+          startRevealSweep(f, radii);
+        });
+      };
+      armWarmup();
     } else {
       f.style.height = `${next}px`;
     }
@@ -321,8 +416,13 @@ export function useSizeMorph(
     settleTimer = setTimeout(() => {
       settleTimer = null;
       if (raf) return;
-      raf = requestAnimationFrame(() => {
-        raf = 0;
+      // Frame work rides the shared bus; the settle debounce above
+      // deliberately stays a real-time timer — it gates MEASUREMENT,
+      // not motion, and a parked (reduced-motion) bus must never freeze
+      // the layout by stalling a bus-ridden interval. One-shots fire
+      // even parked, so this hop is safe in every motion state.
+      raf = scheduleFrame(() => {
+        raf = null;
         remeasure();
       });
     }, 150);
@@ -354,8 +454,8 @@ export function useSizeMorph(
       settleTimer = null;
     }
     if (raf) {
-      cancelAnimationFrame(raf);
-      raf = 0;
+      raf.disconnect();
+      raf = null;
     }
     // The next start() re-calibrates against whatever chrome that open
     // cycle carries.
@@ -377,7 +477,7 @@ export function useSizeMorph(
   onBeforeUnmount(() => {
     ro?.disconnect();
     if (settleTimer) clearTimeout(settleTimer);
-    if (raf) cancelAnimationFrame(raf);
+    if (raf) raf.disconnect();
     stopReveal();
   });