@celestia-island/hikari 0.55.205 → 0.55.206

package/package.json

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

package/src/components/HkCrossfade.scss

@@ -39,12 +39,20 @@
  * 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. */
+ * clicks while it dissolves under the incoming one.
+ *
+ * The enter side additionally honours --hk-crossfade-enter-delay (default
+ * 0): the sequencing hook HkTransitionContainer sets per swap (2026-10-27
+ * user direction — a height-changing swap holds the new content at
+ * opacity 0 until the box is ready, so nothing is clipped by the morph).
+ * Declared as a LONGHAND after the shorthand: the `transition` shorthand
+ * resets transition-delay to 0, so the order here is load-bearing. */
 .hk-crossfade-enter-active {
   transition:
     opacity
     var(--duration-normal, 0.3s)
     var(--ease-out-expo, cubic-bezier(0.19, 1, 0.22, 1));
+  transition-delay: var(--hk-crossfade-enter-delay, 0ms);
 }
 
 .hk-crossfade-leave-active {

package/src/components/HkCrossfade.test.tsx

@@ -30,6 +30,7 @@ function mountCrossfade(opts: {
   initial?: string;
   appear?: boolean;
   disabled?: boolean;
+  enterDelay?: number;
 } = {}): Harness {
   const container = document.createElement("div");
   document.body.appendChild(container);
@@ -45,6 +46,7 @@ function mountCrossfade(opts: {
             swapKey: current.value,
             appear: opts.appear ?? false,
             disabled: opts.disabled ?? false,
+            enterDelay: opts.enterDelay ?? 0,
           },
           {
             default: () => h("p", { class: "body" }, `body-${current.value}`),
@@ -181,6 +183,27 @@ describe("HkCrossfade — DOM contract", () => {
     assertNoFrozenClasses(settled[0]!);
   });
 
+  it("enterDelay widens the watchdog budget: a delayed enter mid-flight is not 'stalled'", async () => {
+    vi.useFakeTimers();
+    freezeRaf();
+    // 300ms choreographed hold: the enter fade starts at 300 and runs to
+    // 600, so the BASE budget (450) expires mid-enter — the sweep must
+    // NOT fire there, or it would strip a live transition's classes.
+    const DELAY = 300;
+    const { container, set } = mountCrossfade({ enterDelay: DELAY });
+    await set("b");
+    await vi.advanceTimersByTimeAsync(CROSSFADE_WATCHDOG_MS + 100); // past the base, inside the extended
+    // Both generations still held by the (rAF-frozen) engine: no sweep
+    // has stripped anything.
+    expect(keys(container)).toEqual(["a", "b"]);
+    // Past the extended budget the stall sweep bites as usual.
+    await vi.advanceTimersByTimeAsync(DELAY + 200);
+    const list = items(container);
+    expect(list).toHaveLength(1);
+    expect(list[0]!.dataset.crossfadeKey).toBe("b");
+    assertNoFrozenClasses(list[0]!);
+  });
+
   it("appear dissolves the first item in; the watchdog un-freezes it under rAF starvation", async () => {
     vi.useFakeTimers();
     freezeRaf();
@@ -235,6 +258,15 @@ describe("HkCrossfade — stylesheet contract", () => {
     const enter = css.match(/\.hk-crossfade-enter-active[^{]*\{[^}]*\}/)?.[0] ?? "";
     expect(enter).toContain("transition: opacity");
     expect(enter).toContain("var(--duration-normal, 0.3s)");
+    // The choreography hook (2026-10-27): the enter side honours the
+    // per-swap delay property — as a LONGHAND declared after the
+    // shorthand (the `transition` shorthand resets transition-delay, so
+    // the order in the rule is load-bearing).
+    const enterIdx = css.indexOf(".hk-crossfade-enter-active");
+    const delayIdx = css.indexOf("transition-delay: var(--hk-crossfade-enter-delay", enterIdx);
+    const shorthandIdx = css.indexOf("transition:", enterIdx);
+    expect(delayIdx).toBeGreaterThan(-1);
+    expect(delayIdx).toBeGreaterThan(shorthandIdx);
     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");
@@ -267,7 +299,9 @@ describe("HkCrossfade — wiring contract", () => {
     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)");
+    // The report window is a per-arm provider so a choreographed enter
+    // (delayed by the host) re-reads the window wide enough each arm.
+    expect(src).toContain("const report = useReportedTransition(reportWindow);");
     expect(src).toContain("armReport(); armWatchdog();");
   });
 });

package/src/components/HkCrossfade.tsx

@@ -62,7 +62,20 @@ const REPORT_MS = CROSSFADE_WATCHDOG_MS;
  *   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.
+ *   until the next `swapKey` change re-arms the Transition fresh. The
+ *   budget scales by `enterDelay` (below) so a choreographed swap whose
+ *   enter starts late never looks stalled.
+ * - `enterDelay` (ms, default 0) holds the ENTER side at opacity 0 for a
+ *   beat before its fade runs — the sequencing hook HkTransitionContainer
+ *   drives (2026-10-27 user direction: a height-changing swap fades the
+ *   old content out first; the new content only fades in once the box is
+ *   ready, so nothing is ever clipped by the animating size). The delay
+ *   itself travels as the `--hk-crossfade-enter-delay` custom property on
+ *   an ancestor (consumed by the enter-active rule), so it can be set per
+ *   swap after the incoming content is measured; the prop exists so the
+ *   watchdog and animation-bus windows KNOW the worst case and arm wide
+ *   enough. Direct consumers who never touch the property keep the
+ *   byte-identical concurrent dissolve.
  */
 export default defineComponent({
   name: "HkCrossfade",
@@ -71,6 +84,10 @@ export default defineComponent({
     tag: { type: String, default: "div" },
     appear: { type: Boolean, default: false },
     disabled: { type: Boolean, default: false },
+    /** Enter-side hold (ms) the watchdog/report budgets must cover; the
+     *  applied delay is the CSS custom property, this only widens the
+     *  budgets. Keep it at the worst case the host can set. */
+    enterDelay: { type: Number, default: 0 },
   },
   setup(props, { slots }) {
     const hostRef = ref<HTMLElement | null>(null);
@@ -83,8 +100,11 @@ export default defineComponent({
     // ── 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);
+    // pattern). The window widens by the choreographed enter hold — read
+    // per arm, so a host that raises `enterDelay` mid-life is covered
+    // without a re-setup.
+    const reportWindow = () => REPORT_MS + Math.max(props.enterDelay, 0);
+    const report = useReportedTransition(reportWindow);
     let pending = 0;
     const armReport = () => {
       pending++;
@@ -96,13 +116,20 @@ export default defineComponent({
     };
 
     // ── Swap-stall watchdog ──────────────────────────────────────────
+    /** Budget for one arm: the base sweep window plus the choreographed
+     *  enter hold — a delayed enter is mid-flight, not stalled, when the
+     *  base budget expires. */
+    function budget(): number {
+      return CROSSFADE_WATCHDOG_MS + Math.max(props.enterDelay, 0);
+    }
+
     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);
+      watchdog = setTimeout(onWatchdog, budget());
     }
 
     function sweepFrozenClasses(el: Element): boolean {

package/src/components/HkSettingsDialog.scss

@@ -4,13 +4,21 @@
 // are the L2 scale tokens wowsp already used, so existing surfaces
 // migrate without repainting.
 //
-// Scroll ownership: inside the dialog (host class `hk-settings-host`)
-// the shell gets a STABLE height sized under the modal body scroller's
-// inner padding, so HkModal's floating overlay scrollbar stays idle and
-// the pane's own edge bar is the only scrollbar. The negative-margin
-// trick puts that edge — and its scrollbar — flush with the modal
-// window's right edge; the padding re-applies the content inset between
-// the scrollbar and the cards. A page-embedded body (no host class)
+// Scroll ownership (2026-10-27, wowsp contract upstreamed): BOTH shell
+// scrollers are HkScrollContainers — the native thin bars are gone, the
+// shared auto-hiding overlay chrome draws instead. The component
+// templates render the rail and the pane with the container class, and
+// the paired-class rules below re-anchor the shell geometry whose home
+// moved: the regions' own overflow-y is replaced by the container's
+// overflow: hidden, and the paddings/gaps now live on the VIEWPORT
+// (the slot content and rail entries are its children), so each overlay
+// track hugs its region's border edge. Inside the dialog (host class
+// `hk-settings-host`) the shell gets a STABLE height sized under the
+// modal body scroller's inner padding, so HkModal's floating overlay
+// scrollbar stays idle and the pane's track is the only scrollbar; the
+// negative-margin trick puts that track flush with the modal window's
+// right edge and the viewport padding re-applies the content inset
+// between the track and the cards. A page-embedded body (no host class)
 // skips both: plain scroll container, host-managed layout.
 
 .hk-settings {
@@ -22,12 +30,17 @@
   &__rail {
     flex: none;
     width: 10.5rem;
+    border-right: 1px solid rgb(var(--color-border) / 15%);
+  }
+
+  /* The rail's own vocabulary lives in the scroll container's viewport
+     now (scroll ownership above) — the overlay track hugs the rail's
+     border edge, flush like the native bar it replaces. */
+  &__rail.hk-scroll-container > .hk-scroll-container-viewport {
     display: flex;
     flex-direction: column;
     gap: var(--space-2);
     padding: var(--space-4) var(--space-12) var(--space-4) 0;
-    border-right: 1px solid rgb(var(--color-border) / 15%);
-    overflow-y: auto;
   }
 
   &__rail-item {
@@ -100,10 +113,14 @@
   &__pane {
     flex: 1;
     min-width: 0;
+  }
+
+  /* Same re-anchoring for the pane: the sections are viewport children,
+     so the column flow and the section gap live there. */
+  &__pane.hk-scroll-container > .hk-scroll-container-viewport {
     display: flex;
     flex-direction: column;
     gap: var(--space-16);
-    overflow-y: auto;
   }
 }
 
@@ -119,17 +136,27 @@
   height: var(--hk-settings-height, calc(70vh - 6.5rem));
 }
 
-/* Cancel the modal body's fixed right padding so the pane's scrollbar
-   sits flush at the window edge; re-apply the inset between the bar and
-   the cards. HkModal retunes the body padding to 1rem under 768px —
-   follow it or the pane overshoots the edge. */
+/* Cancel the modal body's fixed right padding so the pane's overlay
+   track sits flush at the window edge; the content inset between the
+   track and the cards is re-applied INSIDE the viewport (the scroller).
+   HkModal retunes the body padding to 1rem under 768px WITHOUT going
+   through the --hk-modal-padding-body var (a hard-coded 1rem there), so
+   the var-based margin would over-cancel by 8px and push the whole
+   track past the body's overflow clip — follow the hard-coded value or
+   the phone sheet loses its scrollbar entirely (R2 2026-10-27). */
 .hk-settings-host .hk-settings__pane {
   margin-right: calc(-1 * var(--hk-modal-padding-body, 1.5rem));
-  padding-right: var(--space-28);
 
   @media (max-width: 767px) {
     margin-right: -1rem;
-    padding-right: var(--space-20);
+  }
+
+  & > .hk-scroll-container-viewport {
+    padding-right: var(--space-28);
+
+    @media (max-width: 767px) {
+      padding-right: var(--space-20);
+    }
   }
 }
 

package/src/components/HkSettingsDialog.test.tsx

@@ -97,17 +97,63 @@ describe("HSettingsBody", () => {
       },
     });
     const { container, unmount } = mount(Probe);
+    // The pane is an HkScrollContainer: the scroller is its viewport
+    // (the root only clips), so the reset contract is read there.
     const pane = container.querySelector<HTMLElement>(".hk-settings__pane")!;
-    pane.scrollTop = 500;
+    const viewport = pane.querySelector<HTMLElement>(".hk-scroll-container-viewport")!;
+    expect(viewport).toBeTruthy();
+    viewport.scrollTop = 500;
     const items = container.querySelectorAll<HTMLButtonElement>(".hk-settings__rail-item");
     items[1].click();
     await nextTick();
     await nextTick();
-    scrolled.value = pane.scrollTop === 0;
+    scrolled.value = viewport.scrollTop === 0;
     expect(scrolled.value).toBe(true);
     unmount();
   });
 
+  it("renders the rail and the pane as HkScrollContainers (overlay scrollbar contract)", () => {
+    const { container, unmount } = mount(Host);
+    // Scroll ownership (2026-10-27): the native thin bars are gone and the
+    // shared overlay chrome draws instead — pinned at the source because
+    // happy-dom cannot exercise the cascade that hides the native bar.
+    const rail = container.querySelector(".hk-settings__rail")!;
+    const pane = container.querySelector(".hk-settings__pane")!;
+    expect(rail.classList.contains("hk-scroll-container")).toBe(true);
+    expect(pane.classList.contains("hk-scroll-container")).toBe(true);
+    expect(rail.querySelector(".hk-scroll-container-viewport")).toBeTruthy();
+    expect(pane.querySelector(".hk-scroll-container-viewport")).toBeTruthy();
+    // The rail stays a navigation landmark through the `as` prop. Without
+    // a navLabel the landmark is unnamed (the fixture passes none) — the
+    // positive naming contract is its own case below.
+    expect(rail.tagName).toBe("NAV");
+    expect(rail.getAttribute("aria-label")).toBeNull();
+    unmount();
+  });
+
+  it("lands a provided navLabel on the rail landmark (attr fallthrough)", () => {
+    // The rail is an HkScrollContainer rendered `as="nav"`: the accessible
+    // name travels through the component's attribute fallthrough onto the
+    // container root — the machinery this refactor introduced, so pin it.
+    const Named = defineComponent({
+      setup() {
+        return () => (
+          <HSettingsBody sections={SECTIONS.slice(0, 2)} navLabel="Settings sections">
+            {{
+              language: () => <div data-test="pane-language" />,
+              network: () => <div data-test="pane-network" />,
+            }}
+          </HSettingsBody>
+        );
+      },
+    });
+    const { container, unmount } = mount(Named);
+    const rail = container.querySelector(".hk-settings__rail")!;
+    expect(rail.tagName).toBe("NAV");
+    expect(rail.getAttribute("aria-label")).toBe("Settings sections");
+    unmount();
+  });
+
   it("honors an externally driven section change (deep-link landing)", async () => {
     const section = ref("language");
     const Deep = defineComponent({
@@ -222,6 +268,35 @@ describe("settings dialog SCSS host contract (source-level)", () => {
     expect(scss).toContain("margin-right: calc(-1 * var(--hk-modal-padding-body, 1.5rem));");
   });
 
+  it("re-anchors the shell vocabulary into the viewports (scroll ownership)", () => {
+    // Scroll ownership (2026-10-27): the paddings/gaps moved into the
+    // scroll containers' viewports so the overlay tracks hug the regions'
+    // border edges — the paired-class rules are the contract's home.
+    expect(scss).toContain("&__rail.hk-scroll-container > .hk-scroll-container-viewport {");
+    expect(scss).toContain("&__pane.hk-scroll-container > .hk-scroll-container-viewport {");
+    // The regions themselves must NOT scroll natively any more — scoped
+    // to their own blocks, not the whole file (a future rule elsewhere
+    // may legitimately want overflow-y: auto).
+    for (const region of ["&__rail {", "&__pane {"]) {
+      const start = scss.indexOf(region);
+      expect(start, `${region} block located`).toBeGreaterThan(-1);
+      const block = scss.slice(start, scss.indexOf("}", start));
+      expect(block, `${region} must not scroll natively`).not.toContain("overflow-y");
+    }
+    // The dialog inset lives inside the pane's viewport, not on the root.
+    expect(scss).toContain("& > .hk-scroll-container-viewport {\n    padding-right: var(--space-28);");
+  });
+
+  it("keeps the flush-edge margin width-correct (desktop var, mobile hard-coded)", () => {
+    // The desktop margin cancels the var-chained body padding; the mobile
+    // arm must exist because HkModal hard-codes 1rem under 768px without
+    // the var — dropping it over-cancels by 8px and clips the whole
+    // overlay track out of the phone sheet (R2 2026-10-27).
+    expect(scss).toContain("margin-right: calc(-1 * var(--hk-modal-padding-body, 1.5rem));");
+    const hostBlock = scss.slice(scss.indexOf(".hk-settings-host .hk-settings__pane {"));
+    expect(hostBlock).toContain("@media (max-width: 767px) {\n    margin-right: -1rem;\n  }");
+  });
+
   it("never activates a disabled section through a deep-linked prop", async () => {
     const Deep = defineComponent({
       setup() {

package/src/components/HkSettingsDialog.tsx

@@ -9,6 +9,7 @@ import {
 } from "vue";
 
 import HkTransitionContainer from "./HkTransitionContainer";
+import HkScrollContainer from "./HkScrollContainer";
 import HModal from "./HkModal";
 import "./HkSettingsDialog.scss";
 
@@ -40,9 +41,13 @@ export interface HkSettingsSection {
  *
  * Scroll ownership: the pane is the only scroller — switching sections
  * restarts it from the top (arriving on a half-scrolled pane reads as a
- * broken page). Inside the dialog the modal body's own scroller is made
- * mathematically idle by the host height rule (see the SCSS); on a page
- * the host manages its own layout.
+ * broken page). Both scrollers are HkScrollContainers (2026-10-27: the
+ * wowsp-proven contract upstreamed here — the native thin bars are gone
+ * and the shared auto-hiding overlay chrome draws instead; wowsp used to
+ * re-anchor this from outside through paired-class rules in its own
+ * SettingsShell.scss). Inside the dialog the modal body's own scroller is
+ * made mathematically idle by the host height rule (see the SCSS); on a
+ * page the host manages its own layout.
  */
 export const HkSettingsBody = defineComponent({
   name: "HkSettingsBody",
@@ -83,11 +88,17 @@ export const HkSettingsBody = defineComponent({
         ? internal.value
         : (props.sections[0]?.key ?? "");
 
-    const paneRef = ref<HTMLElement | null>(null);
-    // Section switches restart the pane from the top.
+    // The pane is an HkScrollContainer; only its consumed ref slice is
+    // typed here — the scroll reset needs the live viewport element and
+    // nothing else.
+    const paneRef = ref<{ getScrollElement(): HTMLElement | undefined } | null>(null);
+    // Section switches restart the pane from the top. Written through the
+    // public ref slice (the viewport element) rather than scrollTo so the
+    // reset stays synchronous and testable in no-layout environments.
     watch(active, () => {
       void nextTick(() => {
-        if (paneRef.value) paneRef.value.scrollTop = 0;
+        const viewport = paneRef.value?.getScrollElement();
+        if (viewport) viewport.scrollTop = 0;
       });
     });
 
@@ -100,7 +111,11 @@ export const HkSettingsBody = defineComponent({
 
     return () => (
       <div class="hk-settings">
-        <nav class="hk-settings__rail" aria-label={props.navLabel}>
+        {/* Scroll ownership (see the docblock): both scrollers are
+            HkScrollContainers — the overlay chrome replaces the native
+            bars, and the paired-class rules in the SCSS carry each
+            region's padding/gap vocabulary into its viewport. */}
+        <HkScrollContainer as="nav" class="hk-settings__rail" aria-label={props.navLabel}>
           {props.sections.map((s) => {
             const Icon = s.icon;
             const on = active() === s.key && !s.disabled;
@@ -123,8 +138,8 @@ export const HkSettingsBody = defineComponent({
               </button>
             );
           })}
-        </nav>
-        <div class="hk-settings__pane" ref={paneRef}>
+        </HkScrollContainer>
+        <HkScrollContainer class="hk-settings__pane" ref={paneRef}>
           {/* The section swap runs through the family's standard morph
               container (audit 2026-10-23): the pane's frame follows the
               incoming section's height and the contents dissolve, the
@@ -133,7 +148,7 @@ export const HkSettingsBody = defineComponent({
           <HkTransitionContainer swapKey={active()} axis="height">
             {slots[active()]?.()}
           </HkTransitionContainer>
-        </div>
+        </HkScrollContainer>
       </div>
     );
   },
@@ -142,8 +157,9 @@ export const HkSettingsBody = defineComponent({
 /**
  * HkSettingsDialog — the settings window: an HModal carrying the
  * {@link HSettingsBody} shell with a stable frame height, so the modal
- * body's floating scrollbar stays idle and the pane's edge bar is the
- * only scrollbar (the wowsp-proven contract). Width defaults to the
+ * body's floating scrollbar stays idle and the pane's own overlay
+ * scrollbar (an HkScrollContainer) is the only scrollbar (the
+ * wowsp-proven contract, upstreamed 2026-10-27). Width defaults to the
  * settings-standard 58rem; `height` styles the shell (the 70vh default
  * fits a modal with title and paddings).
  *

package/src/components/HkTransitionContainer.test.tsx

@@ -1,7 +1,10 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { createApp, defineComponent, h, ref, type App } from "vue";
+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 HkTransitionContainer from "./HkTransitionContainer";
+import HkTransitionContainer, { resolveEnterDelay } from "./HkTransitionContainer";
 import {
   DEFAULT_ANIMATION_DURATION_MS,
   animationLoopArmedCount,
@@ -95,6 +98,118 @@ describe("HkTransitionContainer", () => {
     expect(host?.style.height).not.toContain("NaN");
     t.app.unmount();
   });
+
+  it("sets the enter-delay custom property on every swap (degraded env reads 'same box')", async () => {
+    // No layout here: the incoming measurement returns null, which the
+    // choreography decision treats as "same box" — the property must
+    // still be SET (the wiring runs on every swap), reading 0ms so the
+    // plain dissolve is preserved.
+    const t = mountContainer("login");
+    t.key.value = "org";
+    await nextTick();
+    await nextTick();
+    const host = t.container.querySelector<HTMLElement>(".hk-tc");
+    expect(host?.style.getPropertyValue("--hk-crossfade-enter-delay")).toBe("0ms");
+    t.app.unmount();
+  });
+
+  it("survives hostile swapKeys (quotes) — dataset matching, no selector interpolation", async () => {
+    // A key is an opaque identity and may contain quotes; interpolating it
+    // into an attribute selector used to throw inside the post-flush
+    // callback and kill the whole choreography wiring for the swap (stale
+    // var, dead observer, unhandled rejection — R2 2026-10-27 S1).
+    const t = mountContainer('a"b');
+    t.key.value = 'c"d\\e';
+    await nextTick();
+    await nextTick();
+    // No throw above; the property is still written (no-layout → "same
+    // box" → 0ms), proving the decision wiring ran to completion.
+    const host = t.container.querySelector<HTMLElement>(".hk-tc");
+    expect(host?.style.getPropertyValue("--hk-crossfade-enter-delay")).toBe("0ms");
+    // And the DOM settled on the hostile key, crossfade untouched.
+    expect(t.container.textContent).toContain("panel-c\"d\\e");
+    t.app.unmount();
+  });
+
+  it("holds the enter (nonzero delay var) when the incoming box measures larger", async () => {
+    // The decision → var wiring on its NON-null path: mock real-layout
+    // rects so the entering generation measures 480px tall against a
+    // zero outgoing box — a size change, so the enter buys the hold.
+    const t = mountContainer("a");
+    const spy = vi
+      .spyOn(HTMLElement.prototype, "getBoundingClientRect")
+      .mockReturnValue({
+        x: 0, y: 0, top: 0, left: 0, right: 320, bottom: 480,
+        width: 320, height: 480, toJSON: () => ({}),
+      } as DOMRect);
+    try {
+      t.key.value = "b";
+      await nextTick();
+      await nextTick();
+      const host = t.container.querySelector<HTMLElement>(".hk-tc");
+      expect(host?.style.getPropertyValue("--hk-crossfade-enter-delay")).toBe(
+        `${DEFAULT_ANIMATION_DURATION_MS}ms`,
+      );
+    } finally {
+      spy.mockRestore();
+    }
+    t.app.unmount();
+  });
+
+  it("resets the hold when the swap settles (source pin)", () => {
+    // The settle callback must clear the hold: custom properties inherit
+    // down the slot subtree, so a stale delay would make every NESTED
+    // crossfade hold a full beat until the next outer swap (R2
+    // 2026-10-27 S2). happy-dom cannot drive the observer-driven settle
+    // path, so the reset line is pinned at source — the house pattern for
+    // cascade-free contracts.
+    const src = readFileSync(
+      join(dirname(fileURLToPath(import.meta.url)), "HkTransitionContainer.tsx"),
+      "utf-8",
+    ).replace(/\r\n?/g, "\n");
+    expect(src).toContain('--hk-crossfade-enter-delay", "0ms"');
+    // Inside the settle callback specifically: the reset sits between the
+    // timer's arm and the emit it guards (the callback lives in the
+    // observer setup, which precedes the decision watch in source order).
+    const settleIdx = src.indexOf("settleTimer = setTimeout(");
+    const resetIdx = src.indexOf('--hk-crossfade-enter-delay", "0ms"');
+    expect(settleIdx).toBeGreaterThan(-1);
+    expect(resetIdx).toBeGreaterThan(settleIdx);
+    // Exactly one such literal: the per-swap decision setter writes the
+    // `${delay}ms` interpolation, never this literal.
+    expect(src.split('--hk-crossfade-enter-delay", "0ms"').length - 1).toBe(1);
+  });
+});
+
+describe("swap choreography decision (resolveEnterDelay, 2026-10-27)", () => {
+  const D = DEFAULT_ANIMATION_DURATION_MS;
+  const box = (w: number, h: number) => ({ w, h });
+
+  it("holds the enter one beat when the box GROWS (grow ∥ exit, then enter)", () => {
+    expect(resolveEnterDelay(box(320, 200), box(320, 480), D)).toBe(D);
+  });
+
+  it("holds the enter one beat when the box SHRINKS (exit, then shrink ∥ enter)", () => {
+    expect(resolveEnterDelay(box(320, 480), box(320, 200), D)).toBe(D);
+  });
+
+  it("keeps the simultaneous dissolve when the box is unchanged", () => {
+    expect(resolveEnterDelay(box(320, 200), box(320, 200), D)).toBe(0);
+    // Sub-pixel noise is not a size change.
+    expect(resolveEnterDelay(box(320, 200), box(320, 200.6), D)).toBe(0);
+  });
+
+  it("reads a null measurement (no layout) as 'same box'", () => {
+    expect(resolveEnterDelay(box(320, 200), null, D)).toBe(0);
+  });
+
+  it("collapses to no hold when motion is off (0ms duration)", () => {
+    expect(resolveEnterDelay(box(320, 200), box(320, 480), 0)).toBe(0);
+  });
+
+  it("a width-only change also buys the hold (the morph axis is not always height)", () => {
+    expect(resolveEnterDelay(box(320, 200), box(480, 200), D)).toBe(D);
+  });
 });
 
 describe("useAnimationLoop (shared rAF context)", () => {

package/src/components/HkTransitionContainer.tsx

@@ -5,14 +5,54 @@ import HkCrossfade from "./HkCrossfade";
 
 import "./HkTransitionContainer.scss";
 
+/** Size delta below which a swap reads as "same box" — sub-pixel
+ *  measurement noise must not buy a sequencing beat. */
+const SIZE_EPSILON_PX = 1;
+
+/**
+ * The swap choreography decision (2026-10-27 user direction), pure so
+ * no-layout test environments can pin it directly. The ENTER side is
+ * held back one dissolve beat whenever the incoming content needs a
+ * different box than the outgoing one:
+ *
+ * - growing: the box grows WHILE the old content fades out; the new
+ *   content fades in only once the box has arrived (the morph can never
+ *   clip the incoming content from below);
+ * - shrinking: the old content fades at the full old height FIRST, then
+ *   the box shrinks while the new (shorter) content fades in — the box
+ *   never drops below the incoming height mid-morph, so nothing is
+ *   clipped there either (the ResizeObserver stream times the shrink
+ *   naturally: the stage keeps the outgoing height until the leave
+ *   completes, then collapses, and the observer pins the arrival);
+ * - same box: no morph to wait for — the classic simultaneous dissolve
+ *   stays (a sequencing beat there would only stutter tabs and labels).
+ *
+ * A null measurement (no layout: every rect reads zero) reads as "same
+ * box" so the choreography degrades to the plain dissolve, never to a
+ * broken one.
+ */
+export function resolveEnterDelay(
+  outgoing: { w: number; h: number },
+  incoming: { w: number; h: number } | null,
+  durationMs: number,
+): number {
+  if (!incoming || durationMs <= 0) return 0;
+  const changed =
+    Math.abs(incoming.h - outgoing.h) > SIZE_EPSILON_PX ||
+    Math.abs(incoming.w - outgoing.w) > SIZE_EPSILON_PX;
+  return changed ? durationMs : 0;
+}
+
 /**
  * HkTransitionContainer — the state-keyed morph container.
  *
  * HkCrossfade's height-safe dissolve, PLUS the size choreography the
- * user direction (2026-10-22) asks of every swap surface: when the
- * bound state key changes, the OLD content fades out, the container's
- * width/height smoothly animate to the incoming content's natural
- * size, and the NEW content fades in — one 300ms default, CSS-driven
+ * user directions (2026-10-22, refined 2026-10-27) ask of every swap
+ * surface: when the bound state key changes, the OLD content fades out,
+ * the container's width/height smoothly animate to the incoming
+ * content's natural size, and the NEW content fades in — with the
+ * sequencing {@link resolveEnterDelay} spells out, so a height-changing
+ * swap never clips either generation. One 300ms default, CSS-driven
  * (transition on inline size), with the animation-loop registration
  * kept for the choreography CSS cannot express.
  *
@@ -68,6 +108,17 @@ export default defineComponent({
     let observer: ResizeObserver | null = null;
     let pendingKey: string | number | null = null;
     let settleTimer: ReturnType<typeof setTimeout> | null = null;
+    /** When the current swap's whole choreography (delayed enter
+     *  included) reads as finished, in `performance.now()` time. The
+     *  settle timer derives its remaining wait from this, so a swap
+     *  whose observer fires late still settles no earlier than the
+     *  enter ends. */
+    let choreoEndsAt = 0;
+    /** The total choreography length reported to the host through the
+     *  `swap` event's `durationMs` — a delayed swap runs one beat longer
+     *  than the bare dissolve, and a scroll-glide handoff should glide
+     *  across the whole choreography, not just its fade. */
+    let choreoMs = props.duration;
 
     function readStage(): { w: number; h: number } {
       const el = stageRef.value;
@@ -75,6 +126,60 @@ export default defineComponent({
       return { w: el.offsetWidth, h: el.offsetHeight };
     }
 
+    /**
+     * The entering generation's item. Found by DATASET comparison, never
+     * by interpolating the key into a selector: a key is an opaque
+     * identity and may contain quotes — a malformed selector would throw
+     * inside this post-flush callback and kill the whole choreography
+     * wiring for the swap (stale delay var, dead observer, unhandled
+     * rejection; R2 2026-10-27 S1).
+     */
+    function enteringItem(
+      stage: HTMLElement,
+      key: string | number,
+    ): HTMLElement | null {
+      const wanted = String(key);
+      for (const el of Array.from(
+        stage.querySelectorAll<HTMLElement>(".hk-crossfade-item"),
+      )) {
+        if (el.dataset.crossfadeKey === wanted) return el;
+      }
+      return null;
+    }
+
+    /**
+     * The natural content size of the entering generation. The item
+     * itself stretches to the shared grid track (the max of the stacked
+     * generations), so during the dissolve its own box masks the
+     * incoming content — the CHILDREN carry the natural flow height.
+     * Null when nothing measurable exists (no layout: every rect reads
+     * zero), which the decision treats as "same box".
+     *
+     * Known measure blind spots, both degrade to "same box" (the exact
+     * pre-choreography dissolve) rather than to a broken swap: text-only
+     * slots (no element children to measure) and slots whose only child
+     * is height-percentage (it stretches with the track it should be
+     * measuring). Real content sections — cards, groups, forms — all
+     * measure true.
+     */
+    function measureIncomingNaturalSize(
+      stage: HTMLElement,
+      key: string | number,
+    ): { w: number; h: number } | null {
+      const item = enteringItem(stage, key);
+      if (!item) return null;
+      const itemTop = item.getBoundingClientRect().top;
+      let w = 0;
+      let h = 0;
+      for (const child of Array.from(item.children)) {
+        const r = child.getBoundingClientRect();
+        w = Math.max(w, Math.ceil(r.width));
+        h = Math.max(h, Math.ceil(r.bottom - itemTop));
+      }
+      if (w <= 0 && h <= 0) return null;
+      return { w, h };
+    }
+
     function applyPinned(): void {
       const el = hostRef.value;
       if (!el) return;
@@ -95,19 +200,28 @@ export default defineComponent({
         pinned.value = { w: Math.ceil(rect.width), h: Math.ceil(rect.height) };
         applyPinned();
         if (settleTimer !== null) clearTimeout(settleTimer);
+        // Settle no earlier than the choreography's true end (a delayed
+        // enter runs one beat past the morph), measured from NOW so an
+        // observer event that lands mid-swap still waits the right
+        // remainder.
         settleTimer = setTimeout(() => {
           pinned.value = null;
           applyPinned();
+          // The hold belongs to THIS swap alone: leaving it set would make
+          // every NESTED crossfade inside the slot inherit a full beat of
+          // delay until the next outer swap happens to rewrite the
+          // property (R2 2026-10-27 S2).
+          hostRef.value?.style.setProperty("--hk-crossfade-enter-delay", "0ms");
           const key = pendingKey;
           pendingKey = null;
           if (key !== null) {
-            emit("swap", { key, previous: previousKey, durationMs: props.duration });
+            emit("swap", { key, previous: previousKey, durationMs: choreoMs });
             // The handoff consumer reads `previous` to scroll the pane back;
             // it must be the key we just left, not the one we mounted with
             // (audit 2026-10-23: it was never reassigned).
             previousKey = key;
           }
-        }, motionDuration() + 40);
+        }, Math.max(choreoEndsAt - performance.now(), 0) + 40);
       });
       observer.observe(stageRef.value);
     }
@@ -120,7 +234,43 @@ export default defineComponent({
       pendingKey = next;
       pinned.value = readStage();
       applyPinned();
-      void nextTick(() => observe());
+      // A settle timer armed by a PREVIOUS swap that never fired (the
+      // user flipped the key again mid-choreography) must not discharge
+      // into THIS swap: it would release the just-pinned outgoing size
+      // and emit this swap as settled before its own choreography ends.
+      if (settleTimer !== null) {
+        clearTimeout(settleTimer);
+        settleTimer = null;
+      }
+      void nextTick(() => {
+        // The choreography decision (2026-10-27): hold the ENTER side one
+        // beat whenever the incoming content needs a different box. The
+        // hold must be in place before the transition STARTS: Vue adds
+        // enter-from + enter-active during the patch, and the double-rAF
+        // nextFrame removes enter-from — the style recalc where the
+        // opacity transition begins and its delay is read. This post-flush
+        // microtask always precedes that frame, so the custom property is
+        // in place in time (verified against the installed Vue 3.5
+        // runtime, R2 2026-10-27). The leave side and the size morph need
+        // no help: the observer stream naturally grows the box during the
+        // exit (the stage reads the max of both generations) and shrinks
+        // it only after the leave completes.
+        const outgoing = pinned.value ?? { w: 0, h: 0 };
+        // Without a ResizeObserver there is no morph to wait for — the
+        // box snaps to the incoming size, so a hold would only park the
+        // new content on a blind beat (R2 2026-10-27): keep master's
+        // plain dissolve on that path.
+        const measurable =
+          typeof ResizeObserver !== "undefined" && stageRef.value != null;
+        const incoming = measurable
+          ? measureIncomingNaturalSize(stageRef.value!, next)
+          : null;
+        const delay = resolveEnterDelay(outgoing, incoming, motionDuration());
+        hostRef.value?.style.setProperty("--hk-crossfade-enter-delay", `${delay}ms`);
+        choreoMs = delay + motionDuration();
+        choreoEndsAt = performance.now() + choreoMs;
+        observe();
+      });
     });
 
     /**
@@ -163,11 +313,14 @@ export default defineComponent({
           }}
         >
           {/* The stage is HkCrossfade: it owns the opacity dissolve
-            (both generations stacked in one grid cell — no exit blank,
-            no collapse flash) and the swap-stall watchdog; THIS
-            component owns the measured size morph around it. */}
+              (both generations stacked in one grid cell — no exit blank,
+              no collapse flash) and the swap-stall watchdog; THIS
+              component owns the measured size morph around it — and the
+              enter sequencing: the decision above sets the delay
+              property per swap, while this prop widens the watchdog and
+              animation-bus budgets to cover the worst-case hold. */}
           <div ref={stageRef} class="hk-tc-stage">
-            <HkCrossfade swapKey={props.swapKey}>
+            <HkCrossfade swapKey={props.swapKey} enterDelay={motionDuration()}>
               {slots.default?.()}
             </HkCrossfade>
           </div>

package/src/composables/useReportedTransition.ts

@@ -11,7 +11,12 @@ export interface ReportedTransition extends ReportedTransitionTrack {
   track(key: string): ReportedTransitionTrack;
 }
 
-export function useReportedTransition(durationMs: number): ReportedTransition {
+export function useReportedTransition(durationMs: number | (() => number)): ReportedTransition {
+  /** The live window: a static value, or a per-run provider — callers
+   *  whose CSS work can outgrow the setup-time estimate (a choreographed
+   *  swap whose enter side starts late) re-read the window on every
+   *  arm, so one composable serves both without a re-setup. */
+  const windowMs = () => (typeof durationMs === "function" ? durationMs() : durationMs);
   interface TrackState {
     handle: AnimationHandle | null;
     timer: CronHandle | null;
@@ -39,15 +44,16 @@ export function useReportedTransition(durationMs: number): ReportedTransition {
 
   function runTrack(key: string) {
     const t = getTrack(key);
+    const ms = windowMs();
     t.timer?.disconnect();
     t.timer = null;
     t.handle?.disconnect();
-    t.handle = reportTransition(durationMs);
+    t.handle = reportTransition(ms);
     t.timer = scheduleCronAfter(() => {
       t.timer = null;
       t.handle?.disconnect();
       t.handle = null;
-    }, durationMs);
+    }, ms);
   }
 
   function cancelAll() {