@celestia-island/hikari 0.55.306 → 0.55.307

package/package.json

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

package/src/components/HkModal.enter-watchdog.test.tsx

@@ -81,7 +81,7 @@ describe("HkModal enter-class watchdog", () => {
     await vi.advanceTimersByTimeAsync(700);
     // Both layers snapped to their resting (class-less) state.
     expect(overlay!.className).toBe("hk-modal-overlay");
-    expect(content!.className).toBe("hk-modal-content");
+    expect(content!.className).toBe("hk-modal-content hk-ride");
     // …and the surface is still open and intact.
     expect(document.querySelector(".hk-modal-content")).not.toBeNull();
   });
@@ -170,7 +170,7 @@ describe("HkModal enter-class watchdog across an interrupted leave", () => {
     // (fade from visible) instead of the full-opacity pop.
     await vi.advanceTimersByTimeAsync(700);
     expect(overlay.className).toBe("hk-modal-overlay");
-    expect(content.className).toBe("hk-modal-content");
+    expect(content.className).toBe("hk-modal-content hk-ride");
     // The surface is still open, and closing it afterwards runs a NORMAL
     // leave (fade from visible) instead of the full-opacity pop.
     open.value = false;

package/src/components/HkModal.open-close-scale.test.ts

@@ -2,27 +2,23 @@
  * Behavioral contract for the DESKTOP modal open/close choreography — run
  * against the COMPILED stylesheet, not the source text.
  *
- * User direction 2026-11-07 (supersedes the 2026-11-05 content-only ride
- * and the 2026-11-06 body scales): ONLY THE HEIGHT COMPRESSES — width is
- * never scaled. The frame settles `translate(…) scaleY(0.9) →
- * translate(…) scaleY(1)` about its center, so the box grows symmetrically
- * and anything centered in it (the content region above all) stays
- * horizontally AND vertically centered at every t; the translate prefix is
- * byte-identical in every state so the ride can never re-seat the frame.
- * `.hk-modal-body` carries NO transform rule of its own: its vertical ride
- * is entirely the frame's scaleY, so its width stays exactly 100% while its
- * height follows the 0.9 → 1 compression. The retired grammars, oldest
- * first: the 2026-11-04 whole-frame `scale(1, 0.9)`, the 2026-11-05
- * body-only uniform `scale(0.9)`, the 2026-11-06 `scale(1.1, 1)` overshoot
- * and its same-day `scale(0.95, 1)` pinch.
+ * User direction 2026-11-07 (third revision, supersedes the 2026-11-05
+ * content-only ride and the 2026-11-06 body scales): ONLY THE HEIGHT MOVES,
+ * and the CHROME KEEPS ITS NATURAL SIZE. The frame's transform is the plain
+ * centering translate in EVERY state; the open/close is carried by LAYOUT
+ * HEIGHT through the family primitive (`useHeightRide` publishes
+ * `--hk-ride-chrome` / `--hk-ride-content` / `--hk-ride-factor`, and the
+ * frame maps its surface phases onto `hk-ride--from` / `hk-ride--to`):
  *
- * Why compile: a source-text scanner can be dodged by a later duplicate
- * rule, a block comment, SCSS interpolation, `@extend` or an `@use`d
- * partial, and it cannot see the cascade. This contract compiles
- * `HkModal.scss` with the repo's own sass, parses the emitted CSS into
- * ordered rules with their media context, and then asks the real cascade
- * question for each moment of the ride: which declaration WINS for the
- * frame, the chrome and the content region?
+ *   frame height  : chrome + content × 0.9   ⇄   chrome + content
+ *   content region: scaleY(0.9)              ⇄   scaleY(1)   (origin top)
+ *
+ * The retired grammars, oldest first: the 2026-11-04 whole-frame
+ * `scale(1, 0.9)`, the 2026-11-05 body-only uniform `scale(0.9)`, the
+ * 2026-11-06 `scale(1.1, 1)` overshoot, its same-day `scale(0.95, 1)`
+ * pinch, and the 2026-11-06/07 frame-level `scaleY(0.9)` ride (retired
+ * because a frame scale squashed the title glyphs and the footer buttons —
+ * the user's 2026-11-07 report on 0.55.305).
  */
 import { describe, expect, it } from "vitest";
 import { dirname, join } from "node:path";
@@ -337,10 +333,17 @@ const FRAME_TO = `${CENTERING} scaleY(1)`;
  *  R2 finding 2026-11-06 (S1): prefix `toContain` let both survive. */
 const ENTER_TRANSITION =
   "opacity var(--hk-modal-duration, 0.42s) var(--hk-modal-ease-out, cubic-bezier(0.33, 1, 0.68, 1)), " +
-  "transform var(--hk-modal-duration, 0.42s) var(--hk-modal-ease-out, cubic-bezier(0.33, 1, 0.68, 1))";
+  "height var(--hk-modal-duration, 0.42s) var(--hk-modal-ease-out, cubic-bezier(0.33, 1, 0.68, 1))";
 const LEAVE_TRANSITION =
   "opacity var(--hk-modal-duration, 0.32s) var(--hk-modal-ease-in, cubic-bezier(0.45, 0, 0.55, 1)), " +
-  "transform var(--hk-modal-duration, 0.32s) var(--hk-modal-ease-in, cubic-bezier(0.45, 0, 0.55, 1))";
+  "height var(--hk-modal-duration, 0.32s) var(--hk-modal-ease-in, cubic-bezier(0.45, 0, 0.55, 1))";
+/** The ride's own geometry lives in the shared container sheet; the modal
+ *  frame maps its phases onto these two ends. */
+const RIDE_SHEET = (() => {
+  const path = join(here, "HkRideBox.scss");
+  return compile(path, { loadPaths: [here, join(here, "..", "styles")], style: "expanded" }).css;
+})();
+const RIDE_RULES = parseRules(stripComments(RIDE_SHEET));
 
 describe("HkModal desktop open/close contract (compiled cascade, user direction 2026-11-07)", () => {
   it("compiles into a stylesheet with the ride rules present (known-positive)", () => {
@@ -352,30 +355,22 @@ describe("HkModal desktop open/close contract (compiled cascade, user direction
     expect(selectors.some((s) => s.includes("hk-modal-content-enter-from"))).toBe(true);
   });
 
-  it("rides the frame height as scaleY appended to the byte-identical centering translate", () => {
-    // 2026-11-06: the window's own height moves with the open/close. The
-    // translate prefix must be byte-identical in EVERY state (rest too) so
-    // the ride can never re-seat the frame or drop a dragged window's
-    // shift; only the appended scaleY flips 0.9 → 1.
-    expect(winner(frameWith(...RIDE[0].classes), "transform", DESKTOP), RIDE[0].name).toBe(FRAME_FROM);
-    expect(winner(frameWith(...RIDE[1].classes), "transform", DESKTOP), RIDE[1].name).toBe(FRAME_TO);
-    expect(winner(frameWith(...RIDE[2].classes), "transform", DESKTOP), RIDE[2].name).toBe(FRAME_TO);
-    expect(winner(frameWith(...RIDE[3].classes), "transform", DESKTOP), RIDE[3].name).toBe(FRAME_FROM);
-    // …and the same with the opt-in draggable flag on, where an
-    // attribute-qualified frame rule could otherwise slip past the mocks
-    // (R2 finding 2026-11-06 (S2): the body had this loop, the frame
-    // didn't — the repo's own [data-draggable] block is the natural next
-    // mutation site).
-    for (const state of RIDE) {
-      const expected = state.name === "enter-from" || state.name === "leave-to" ? FRAME_FROM : FRAME_TO;
-      expect(
-        winner(draggableFrameWith(...state.classes), "transform", DESKTOP),
-        `draggable frame ${state.name}`,
-      ).toBe(expected);
+  it("keeps the frame's transform at the plain centering translate in every state", () => {
+    // The ride is layout height, not a frame transform — that is the whole
+    // point (a frame scale squashed the chrome). So the transform must be
+    // the SAME `translate(...)` in rest and at both ride ends, and adding a
+    // scale to it in any state is the regression this pins.
+    for (const state of [...RIDE, { name: "rest", classes: [] as string[] }]) {
+      for (const [label, frame] of [
+        ["", frameWith(...state.classes)],
+        ["draggable ", draggableFrameWith(...state.classes)],
+      ] as const) {
+        expect(winner(frame, "transform", DESKTOP), `${label}${state.name}`).toBe(CENTERING);
+        for (const prop of ["scale", "zoom", "translate", "rotate", "transform-origin"]) {
+          expect(winner(frame, prop, DESKTOP), `${label}${state.name} ${prop}`).toBeUndefined();
+        }
+      }
     }
-    // …and at rest, too: the settled frame carries the translate only.
-    expect(winner(frameWith(), "transform", DESKTOP)).toBe(CENTERING);
-    expect(winner(draggableFrameWith(), "transform", DESKTOP)).toBe(CENTERING);
   });
 
   it("never lets a transform longhand creep onto the frame", () => {
@@ -421,37 +416,58 @@ describe("HkModal desktop open/close contract (compiled cascade, user direction
       "will-change",
       DESKTOP,
     );
-    expect(enterWill).toBe("opacity, transform");
+    expect(enterWill).toBe("opacity, height");
     // The close direction promotes the same pair of layers.
     const leaveWill = winner(
       frameWith("hk-modal-content-leave-to", "hk-modal-content-leave-active"),
       "will-change",
       DESKTOP,
     );
-    expect(leaveWill).toBe("opacity, transform");
+    expect(leaveWill).toBe("opacity, height");
   });
 
-  it("never scales the content region: width stays 100% at every t", () => {
-    // 2026-11-07: only the height compresses. The body must carry no
-    // transform of its own in ANY ride state — its vertical ride is the
-    // frame's scaleY inherited down the tree, so a body transform here
-    // would either re-scale the width or double the Y compression.
-    const REST_OR_RIDE = [...RIDE, { name: "rest", classes: [] as string[] }];
-    // The whole transform family, on BOTH branches (R2 finding 2026-11-07
-    // (S2): the draggable branch used to pin `transform` only, so a
-    // `[data-draggable] … { scale: … }` longhand stayed green).
-    const PROPS = ["transform", "transform-origin", "scale", "translate", "rotate", "zoom", "perspective"];
-    for (const state of REST_OR_RIDE) {
-      for (const [label, frame] of [
-        ["", frameWith(...state.classes)],
-        ["draggable ", draggableFrameWith(...state.classes)],
-      ] as const) {
-        const body = child(frame, "hk-modal-body");
-        for (const prop of PROPS) {
-          expect(winner(body, prop, DESKTOP), `${label}${state.name} body ${prop}`).toBeUndefined();
-        }
-      }
-    }
+  it("rides the HEIGHT through the shared container contract, chrome untouched", () => {
+    // The two ends of the ride are expressed as `height: calc(chrome +
+    // content × factor)` on the frame (`!important` beats the size morph's
+    // inline pin for the duration of the flight) and as a top-origin
+    // `scaleY` on the CONTENT REGION only — so the title bar and the footer
+    // keep their natural size, which is the 2026-11-07 user requirement.
+    // A selector may be declared by more than one rule (the ride's geometry
+    // pairs: the compressed height, the content's natural-height lock and the
+    // content's scale). Look the declaration up by property, not by "the
+    // first rule with this selector".
+    const rideRule = (selector: string, prop = "height"): CssRule | undefined =>
+      RIDE_RULES.find((r) => r.selector === selector && r.declarations.has(prop));
+
+    const from = rideRule(".hk-ride[data-hk-ride-ready].hk-ride--from");
+    expect(from, "compressed end rule").toBeTruthy();
+    expect(from!.declarations.get("height")).toBe(
+      "calc(var(--hk-ride-chrome, 0px) + var(--hk-ride-content, 0px) * var(--hk-ride-factor, 0.9))",
+    );
+    expect(from!.important.has("height"), "the ride outranks the morph's inline pin").toBe(true);
+
+    const to = rideRule(".hk-ride[data-hk-ride-ready].hk-ride--to");
+    expect(to, "natural end rule").toBeTruthy();
+    expect(to!.declarations.get("height")).toBe(
+      "calc(var(--hk-ride-chrome, 0px) + var(--hk-ride-content, 0px))",
+    );
+    expect(to!.important.has("height")).toBe(true);
+
+    // Only the content region is ever scaled — top origin, so the compressed
+    // paint lands exactly in the shorter slot the frame leaves for it.
+    const scaled = rideRule(".hk-ride[data-hk-ride-ready].hk-ride--from > .hk-ride-content", "transform");
+    expect(scaled, "content compress rule").toBeTruthy();
+    expect(scaled!.declarations.get("transform")).toBe(
+      "scaleY(var(--hk-ride-factor, 0.9))",
+    );
+    const origin = rideRule(".hk-ride-content", "transform-origin");
+    expect(origin!.declarations.get("transform-origin")).toBe("50% 0");
+
+    // …and the CHROME is never named by any ride rule: the modal's header,
+    // sub-header and footer must not be reachable from the ride sheet.
+    const CHROME = /hk-modal-(header|subheader|footer|title|close)\b/;
+    const offenders = RIDE_RULES.filter((r) => CHROME.test(r.selector)).map((r) => r.selector);
+    expect(offenders, "the ride container must not target modal chrome").toEqual([]);
   });
 
   it("never transforms the chrome: title bar, sub-header, footer, close button, title glyph", () => {
@@ -534,6 +550,16 @@ describe("HkModal desktop open/close contract (compiled cascade, user direction
     ).toBeUndefined();
   });
 
+  it("maps the surface states onto the ride's two ends", () => {
+    // The modal's TSX adds `hk-ride--from` for openingFrom/closingTo and
+    // `hk-ride--to` for openingTo/closingFrom; the container sheet keys off
+    // exactly those class names. A rename on either side has to fail here.
+    const names = RIDE_RULES.map((r) => r.selector).join("\n");
+    expect(names).toContain("hk-ride--from");
+    expect(names).toContain("hk-ride--to");
+    expect(names).toContain("hk-ride-content");
+  });
+
   it("never lets ANY rule put a ride transform on the content region", () => {
     // Fail-closed sweep, selector-level and media-independent (R2 finding
     // 2026-11-07 (S2): the cascade mock cannot match `:not()`, a type
@@ -662,11 +688,11 @@ describe("HkModal desktop open/close contract (compiled cascade, user direction
       expect(winner(body, "translate", DESKTOP), `body ${state.name}`).toBeUndefined();
       expect(winner(body, "zoom", DESKTOP), `body ${state.name}`).toBeUndefined();
 
+      // The FRAME never carries a scale any more — the ride is height, and
+      // the only `scaleY` in the choreography lives on the content region's
+      // shared contract (pinned by the ride test above).
       const frameTransform = winner(frame, "transform", DESKTOP) ?? "";
-      const centeringRe = CENTERING.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-      expect(frameTransform, `frame ${state.name}`).toMatch(
-        new RegExp(`^${centeringRe} scaleY\\((0\\.9|1)\\)$`),
-      );
+      expect(frameTransform, `frame ${state.name}`).toBe(CENTERING);
       expect(frameTransform, `frame ${state.name}`).not.toMatch(FRAME_ESCAPES);
       expect(winner(frame, "scale", DESKTOP), `frame ${state.name}`).toBeUndefined();
       expect(winner(frame, "zoom", DESKTOP), `frame ${state.name}`).toBeUndefined();

package/src/components/HkModal.scss

@@ -57,11 +57,11 @@
   z-index: 1;
   top: 50%;
   left: 50%;
-  // The centering translate is the frame's PERMANENT transform prefix:
-  // every state (rest, enter-from/to, leave-from/to) carries this exact
-  // translate, and the open/close ride only ever APPENDS a `scaleY()` to
-  // it (see the choreography block below) — so the ride can never re-seat
-  // the frame and dragged windows keep their shift.
+  // The centering translate is the frame's WHOLE transform, in every state
+  // (rest, enter-from/to, leave-from/to). The open/close ride is carried by
+  // the height instead (see the choreography block below), so the frame can
+  // never re-seat mid-flight, dragged windows keep their shift, and the
+  // chrome is never scaled.
   transform: translate(
         calc(-50% + var(--hk-modal-shift-x, 0px)),
         calc(-50% + var(--hk-modal-shift-y, 0px))
@@ -99,43 +99,41 @@
 // ------
 // Content enter/leave transitions (desktop ≥768px)
 //
-// Default window open/close (user direction 2026-11-06, superseding the
-// 2026-11-05 content-only ride): the window's own HEIGHT now rides the
-// open/close. The frame settles `scaleY(0.9) → scaleY(1)` about its
-// center (the default 50% 50% origin, composed AFTER the permanent
-// centering translate, which is byte-identical in every state — so the
-// box grows symmetrically up and down from its rest center and nothing
-// re-seats the frame mid-flight; dragged windows keep --hk-modal-shift-*
-// through the whole ride). Because a uniform map about the frame center
-// preserves relative geometry, anything sitting centered in the frame —
-// the content region above all — stays horizontally AND vertically
-// centered at every t. The chrome (title bar, sub-header, footer) has no
-// transform rule of its own; it inherits this single frame scale, which
-// IS the window-height motion the user asked for.
+// Default window open/close (user direction 2026-11-07, third revision):
+// the WINDOW's own height rides, the CHROME keeps its natural size, and
+// only the content region is compressed. Concretely:
 //
-// The content region does NOT ride on its own (user direction 2026-11-07,
-// superseding the body scale that shipped in 0.55.303 / 0.55.304): width
-// is never scaled, only height is. `.hk-modal-body` therefore carries NO
-// transform rule in any ride state — its vertical ride is entirely the
-// frame's `scaleY` above, so during the open/close its width stays exactly
-// 100% of the window while its height follows the 0.9 → 1 compression. Two
-// retired grammars before this one: the two-arg `scale(0.95, 1)` pinch and
-// the `scale(1.1, 1)` overshoot.
+//   frame height  : chrome + content × 0.9   ⇄   chrome + content
+//   content region: scaleY(0.9)              ⇄   scaleY(1)  (origin top)
 //
-// Hosts retune the ride through the `--hk-modal-*` tokens (duration /
-// easing) or the body padding vars — NOT by setting `transform` on
-// `.hk-modal-body` or the frame: the frame's state rules pair a matched
-// function list (`translate + scaleY`) so both ends of the interpolation
-// ride the same shape, and a host's single-class transform would be
-// overridden mid-ride and again under reduced motion.
+// Why not `transform: scaleY()` on the frame (the 2026-11-05/06 grammar):
+// a frame-level scale squashes the title glyphs, the footer buttons and the
+// corner radii along with everything else — the user reported exactly that
+// ("顶部标题和底部按钮组也跟着压缩") on 0.55.305. The ride is therefore a
+// LAYOUT-height animation driven by the family primitive `useHeightRide`,
+// which publishes the measured chrome/content split as CSS variables; this
+// sheet maps the surface states onto the ride's two ends. Chrome lives
+// outside the transform, so its type renders at natural size for the whole
+// flight, and the content region keeps its natural LAYOUT box (only its
+// paint is compressed about its own top edge), so the compressed paint
+// lands exactly in the shorter slot the frame leaves for it.
 //
-// No clip-path and no Y offset ride the open/close: the visible box IS the
-// frame at every t, so nothing is ever sliced off (the 2026-09-14 clip
-// unveil — and the #508/#512/#524 lineage before it — stays retired). All
-// compositor-level: zero layout per frame. The centering translate lives
-// on the base .hk-modal-content rule, so the frame never re-seats
-// mid-flight. Scoped to ≥768px; ≤767px keeps the sheet's translateY
-// choreography below.
+// The centering translate stays the frame's whole transform in every state
+// (byte-identical between rest and both ride ends, `--hk-modal-shift-*`
+// included), so the ride never re-seats the frame, dragged windows keep
+// their shift, and a box that grows by Δ about its center moves its top
+// edge up by Δ/2 — the symmetric growth the user asked for.
+//
+// Scroll containers are untouched by construction: `HkScrollContainer`,
+// `HkScrollPin` and the overlay scrollbar measure layout boxes, which the
+// content region's transform never changes, and nothing inside the content
+// reflows per frame. Surfaces may read `data-hk-riding` to skip work while
+// a ride is in flight.
+//
+// The `!important` on the two height ends is load-bearing: the size morph
+// pins the frame's height as an inline px value, and the ride — not the pin
+// — owns the box for the duration of the flight. Reduced motion flattens
+// both the height transition and the content scale.
 // ------
 
 @media (min-width: 768px) {
@@ -145,9 +143,9 @@
     transition:
       opacity var(--hk-modal-duration, 0.42s)
         var(--hk-modal-ease-out, cubic-bezier(0.33, 1, 0.68, 1)),
-      transform var(--hk-modal-duration, 0.42s)
+      height var(--hk-modal-duration, 0.42s)
         var(--hk-modal-ease-out, cubic-bezier(0.33, 1, 0.68, 1));
-    will-change: opacity, transform;
+    will-change: opacity, height;
   }
 
   // Close: the reveal's TRUE reverse — same chrome fade, while the window
@@ -156,32 +154,58 @@
     transition:
       opacity var(--hk-modal-duration, 0.32s)
         var(--hk-modal-ease-in, cubic-bezier(0.45, 0, 0.55, 1)),
-      transform var(--hk-modal-duration, 0.32s)
+      height var(--hk-modal-duration, 0.32s)
         var(--hk-modal-ease-in, cubic-bezier(0.45, 0, 0.55, 1));
-    will-change: opacity, transform;
+    will-change: opacity, height;
   }
 
-  // The translate prefix is byte-identical to the base rule; only the
-  // appended scaleY changes. scaleY(1) at the settled end — never `none`
-  // — keeps both ends of the interpolation on the same function shape.
+  // The frame's transform is the plain centering translate in EVERY state —
+  // the ride is carried by the shared `.hk-ride--*` contract (geometry) plus
+  // the modal's own phase mapping (the machine's states are translated into
+  // `hk-ride--from` / `hk-ride--to` on the frame), which is what keeps the
+  // chrome crisp.
   .hk-modal-content-enter-from,
   .hk-modal-content-leave-to {
     opacity: 0;
-    transform: translate(
-          calc(-50% + var(--hk-modal-shift-x, 0px)),
-          calc(-50% + var(--hk-modal-shift-y, 0px))
-        )
-        scaleY(0.9);
   }
 
   .hk-modal-content-enter-to,
   .hk-modal-content-leave-from {
     opacity: 1;
-    transform: translate(
-          calc(-50% + var(--hk-modal-shift-x, 0px)),
-          calc(-50% + var(--hk-modal-shift-y, 0px))
-        )
-        scaleY(1);
+  }
+
+  // The content region keeps its NATURAL layout height for the whole ride: it
+  // must not join the frame's flex shrink, or the slot compression and the
+  // `.hk-ride-content` scale would compound to 0.81 and leave a gap above the
+  // footer (2026-11-07 R3 finding). The footer band pins to the frame's
+  // bottom edge instead, so it stays visible while the content's natural box
+  // overflows underneath it.
+
+  // The content's compression has to ride the SAME per-direction token pair
+  // as the frame's height: the family sheet's default (0.42s) would leave a
+  // 0.1s tail on close (0.32s height) — a visible gap above the pinned
+  // footer — and would ignore a host's `--hk-modal-duration` retune.
+  .hk-modal-content-enter-active > .hk-modal-body {
+    transition: transform var(--hk-modal-duration, 0.42s)
+      var(--hk-modal-ease-out, cubic-bezier(0.33, 1, 0.68, 1));
+  }
+
+  .hk-modal-content-leave-active > .hk-modal-body {
+    transition: transform var(--hk-modal-duration, 0.32s)
+      var(--hk-modal-ease-in, cubic-bezier(0.45, 0, 0.55, 1));
+  }
+
+  .hk-modal-content[data-hk-ride-ready].hk-ride--from > .hk-modal-body,
+  .hk-modal-content[data-hk-ride-ready].hk-ride--to > .hk-modal-body {
+    flex: 0 0 auto;
+    height: var(--hk-ride-content, auto);
+  }
+
+  .hk-modal-content[data-hk-ride-ready].hk-ride--from > .hk-modal-footer,
+  .hk-modal-content[data-hk-ride-ready].hk-ride--to > .hk-modal-footer {
+    position: absolute;
+    inset-inline: 0;
+    bottom: 0;
   }
 }
 
@@ -671,10 +695,11 @@
       calc(-50% + var(--hk-modal-shift-y, 0px))
     );
   }
-  // The content region carries no transform of its own any more (width is
-  // never scaled — 2026-11-07), so only the frame needs flattening above.
-  // The body lines stay as a fail-closed guard: if a future state rule ever
-  // reintroduces a body transform, reduced motion still flattens it.
+  // The content region carries no transform of its own any more (the ride is
+  // height-only — 2026-11-07). These lines are a belt-and-braces guard only:
+  // at (0,2,0) they would NOT outrank a future ride rule at (0,4,0), so the
+  // family sheet's own reduced-motion block (which repeats the full
+  // selector) is the one that actually flattens the content scale.
   .hk-modal-content .hk-modal-body {
     transform: none;
     transition: none;

package/src/components/HkModal.tsx

@@ -2,6 +2,10 @@ import { computed, defineComponent, nextTick, onBeforeUnmount, onMounted, ref, s
 
 import { useI18n } from "../i18n/context";
 import "./HkModal.scss";
+// The ride GEOMETRY lives in the family sheet; the modal maps its phases onto
+// it, so the modal must ship it too (deep-import consumers of
+// `./components/HkModal` never touch the barrel). Idempotent with HkRideBox.
+import "./HkRideBox.scss";
 import HkFloatingLayer from "./HkFloatingLayer";
 import { focusFirst, trapFocus } from "../utils/dom";
 import { useOverlay } from "../runtime/useOverlay";
@@ -14,6 +18,7 @@ import { useSurfaceTransition } from "../composables/useSurfaceTransition";
 import { useSurfaceMachine } from "../composables/useSurfaceMachine";
 import { useSurfaceContentHold } from "../composables/useSurfaceContentHold";
 import { useSizeMorph, type RideEntry } from "../composables/useSizeMorph";
+import { useHeightRide } from "../composables/useHeightRide";
 
 import { STEPFLOW_SWAP_EVENT } from "./HkStepFlow";
 
@@ -348,6 +353,51 @@ export default defineComponent({
         );
       },
     });
+
+    // Desktop open/close: the WINDOW's own height rides, the chrome
+    // (title bar, sub-header, footer) keeps its natural size, and only the
+    // content region is visually compressed. The measurement half lives in
+    // the family primitive (useHeightRide); this sheet maps its surface
+    // states onto the ride's two ends (see the choreography block below).
+    const ride = useHeightRide(contentRef, bodyRef, { factor: 0.9 });
+
+    /** The window ride's own state, translated from the surface phases:
+     *  the open/close endpoints are the compressed end (`--from`) and the
+     *  natural end (`--to`). Between and after them no ride class is
+     *  present, so the frame keeps its laid-out height (or the morph's
+     *  px pin) and the geometry contract never leaks into the rest state. */
+    // The body element mounts with the frame on every open, and the inline
+    // variables die with the previous frame. Republish the split cached from
+    // the last rest measurement FIRST (so the first painted frame is already
+    // correct), then — if this is the very first open — measure as soon as
+    // the element lands (the sheet keeps the frame at `auto` until then, so
+    // that measurement sees honest natural geometry).
+    watch(
+      bodyRef,
+      (el) => {
+        if (!el) return;
+        // ALWAYS measure: the component instance survives a close, so a
+        // cached split may belong to different content (this modal is reused
+        // across tabs/entries). Publishing the cache first made the second
+        // and later opens ride the PREVIOUS geometry, cropping new content
+        // and then snapping when the cache expired (R5 finding).
+        void nextTick(() => ride.refresh());
+      },
+      { flush: "post" },
+    );
+
+    const rideStateClass = (): string | null => {
+      switch (machine.phase.value) {
+        case "openingFrom":
+        case "closingTo":
+          return "hk-ride--from";
+        case "openingTo":
+        case "closingFrom":
+          return "hk-ride--to";
+        default:
+          return null;
+      }
+    };
     let previouslyFocused: HTMLElement | null = null;
     let unmounted = false;
 
@@ -566,6 +616,10 @@ export default defineComponent({
       ],
       onPhase: (from, to, event) => {
         if (to === "openingFrom") {
+          // Measure BEFORE the enter classes land: the ride's `height:
+          // calc()` needs the rest chrome/content split, and a frame that is
+          // already compressed reports the compressed box.
+          ride.refresh();
           // Open-request bookkeeping (was the modelValue watcher's open
           // arm): registration, overlay registry, back-guard, focus
           // capture.
@@ -598,6 +652,9 @@ export default defineComponent({
           });
         } else if (to === "open") {
           surfTrack.cancel();
+          // Re-measure at the landed rest geometry so the NEXT ride starts
+          // from this box (content may have changed while the surface opened).
+          void nextTick(() => ride.refresh());
           onAfterEnter();
           // Idempotent re-arm for the fast paths (see openingFrom); the
           // morph is usually armed already by the enter-edge tick.
@@ -610,6 +667,9 @@ export default defineComponent({
             if (machine.phase.value === "open") morph.remeasure();
           });
         } else if (to === "closingFrom") {
+          // Same rule on the way out: the frame is at its open (natural)
+          // height right now, so this is the last honest measurement.
+          ride.refresh();
           // Close-request bookkeeping (was the watcher's close arm): the
           // registries forget the surface at request time; the finalize
           // edge below completes the teardown at leave end.
@@ -1065,7 +1125,7 @@ export default defineComponent({
             />
             <div
                   ref={contentRef}
-                  class={["hk-modal-content", props.contentClass, ...machine.classesFor("hk-modal-content")]}
+                  class={["hk-modal-content", "hk-ride", rideStateClass(), props.contentClass, ...machine.classesFor("hk-modal-content")]}
                   role="dialog"
                   aria-modal="true"
                   aria-label={resolvedSurfaceName.value}
@@ -1131,7 +1191,7 @@ export default defineComponent({
                       )}
                     </>
                   ) : null,
-                  <div ref={bodyRef} class="hk-modal-body">
+                  <div ref={bodyRef} class="hk-modal-body hk-ride-content">
                     <div
                       ref={scrollContainerRef}
                       class="hk-modal-body-scroll hk-scroll-pin-host"

package/src/components/HkRideBox.scss

@@ -0,0 +1,105 @@
+// HkRideBox.scss
+// The family-level height-ride container (see useHeightRide for the WHY).
+//
+// Contract, in one place:
+//   .hk-ride            the frame whose LAYOUT height rides
+//   .hk-ride--from      compressed end   (chrome + content × factor)
+//   .hk-ride--to        natural end      (chrome + content)
+//   .hk-ride-content    the ONLY scaled region (origin top, so the
+//                       compressed paint lands exactly in the shorter slot
+//                       the frame leaves for it)
+//   --hk-ride-chrome    px, measured by the composable
+//   --hk-ride-content   px, measured by the composable
+//   --hk-ride-factor    the content fraction (default 0.9)
+//   [data-hk-riding]    present for the whole flight; scroll features that
+//                       must skip work read it, like [data-hk-morphing] on
+//                       the mobile sheet
+//
+// At rest neither state class is present, so the frame keeps whatever
+// height its own layout gives it (`auto`, or a consumer's px pin) and the
+// ride degrades to "no ride" rather than to a wrong box if a measurement
+// is missing.
+
+// NOTE: the shared class deliberately carries GEOMETRY only. Timing,
+// easing and `overflow` belong to the consuming surface (the modal already
+// runs its own enter/leave transition list, and the phone sheet has a
+// completely different choreography), so this sheet can never clobber one.
+.hk-ride {
+  // Only meaningful while a ride class is present (the height resolves
+  // from the measured variables); at rest the box keeps its own layout
+  // height, or the consumer's px pin.
+}
+
+// The two ends of the ride. `!important` is deliberate and load-bearing: a
+// consumer's own size-morph pins `height` as an INLINE px value, and the
+// ride — not the pin — owns the box for the duration of the flight.
+.hk-ride-box {
+  position: relative;
+}
+
+// The ride's geometry is DESKTOP-only on purpose: the ≤767px sheet has its
+// own clip/translateY choreography, and a shared height override there would
+// fight the sheet's `max-height ... !important` cap.
+@media (min-width: 768px) {
+
+.hk-ride[data-hk-ride-ready].hk-ride--from {
+  height: calc(
+    var(--hk-ride-chrome, 0px) + var(--hk-ride-content, 0px) * var(--hk-ride-factor, 0.9)
+  ) !important;
+}
+
+.hk-ride[data-hk-ride-ready].hk-ride--to {
+  height: calc(var(--hk-ride-chrome, 0px) + var(--hk-ride-content, 0px)) !important;
+}
+
+// The box's OWN root class carries the positioning context: the shared
+// `.hk-ride` class is also worn by surfaces that bring their own `position`
+// (`.hk-modal-content` is `position: fixed`), and a `position: relative`
+// here would tie with it at (0,1,0) and win or lose by bundle order.
+
+
+.hk-ride-content {
+  transform-origin: 50% 0;
+  transition: transform var(--hk-ride-duration, 0.42s) var(--hk-ride-ease, cubic-bezier(0.33, 1, 0.68, 1));
+}
+
+// THE load-bearing pair of the whole primitive: while riding, the content
+// region stops participating in the flex shrink and holds its NATURAL
+// height, so its layout box is stable (scroll geometry, pins and the
+// overlay scrollbar keep reading the same numbers) and the `scaleY` below
+// is the ONLY thing that compresses it. Without this the slot shrink and the
+// transform would compound (0.9 × 0.9 = 0.81) and leave a gap above the
+// pinned chrome-end band (2026-11-07 R3 finding).
+.hk-ride[data-hk-ride-ready].hk-ride--from > .hk-ride-content,
+.hk-ride[data-hk-ride-ready].hk-ride--to > .hk-ride-content {
+  flex: 0 0 auto;
+  height: var(--hk-ride-content, auto);
+}
+
+.hk-ride[data-hk-ride-ready].hk-ride--from > .hk-ride-chrome-end,
+.hk-ride[data-hk-ride-ready].hk-ride--to > .hk-ride-chrome-end {
+  position: absolute;
+  inset-inline: 0;
+  bottom: 0;
+}
+
+.hk-ride[data-hk-ride-ready].hk-ride--from > .hk-ride-content {
+  transform: scaleY(var(--hk-ride-factor, 0.9));
+}
+
+}
+
+/* Reduced motion: the frame swaps instantly and the content is never
+ * compressed. */
+@media (prefers-reduced-motion: reduce) {
+  .hk-ride,
+  .hk-ride-content {
+    transition: none;
+  }
+  /* Repeated with the readiness gate so this flatten outranks the state
+   *  rule above (which is (0,4,0)); a bare `.hk-ride.hk-ride--from` here
+   *  would lose the cascade and the a11y contract would be a lie. */
+  .hk-ride[data-hk-ride-ready].hk-ride--from > .hk-ride-content {
+    transform: none;
+  }
+}

package/src/components/HkRideBox.test.tsx

@@ -0,0 +1,174 @@
+/**
+ * Contract for the family-level height-ride container (`HkRideBox` + the
+ * `useHeightRide` measurement primitive).
+ *
+ * Why these assertions: the motion is a LAYOUT-height animation precisely so
+ * that the chrome (title bar, footer action row) keeps its natural size — the
+ * 2026-11-07 user report was that a frame-level `transform: scaleY()` squashed
+ * the title text and the footer buttons along with everything else. The test
+ * that matters is therefore structural, not decorative:
+ *
+ *   1. the chrome bands are SIBLINGS of the content region, so no transform
+ *      can ever reach them;
+ *   2. the only scaled region is `.hk-ride-content`;
+ *   3. the geometry is published as variables (chrome / content / factor) and
+ *      the two state classes are what the sheet interpolates between;
+ *   4. an unmeasurable box (jsdom reports 0) publishes NOTHING, so the sheet
+ *      falls back to `auto` instead of collapsing the frame;
+ *   5. a second ride never shrinks an already-compressed measurement.
+ */
+import { describe, expect, it } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref, type Component } from "vue";
+
+import HkRideBox from "./HkRideBox";
+import {
+  RIDE_ATTR,
+  RIDE_CLASS,
+  RIDE_CONTENT_CLASS,
+  RIDE_FROM_CLASS,
+  RIDE_TO_CLASS,
+} from "../composables/useHeightRide";
+
+interface Harness {
+  root: () => HTMLElement;
+  setRiding: (next: boolean) => Promise<void>;
+  unmount: () => void;
+}
+
+function mountBox(
+  initial: { riding?: boolean; factor?: number } = {},
+  slots?: Record<string, () => unknown>,
+): Harness {
+  const host = document.createElement("div");
+  document.body.appendChild(host);
+  const riding = ref(Boolean(initial.riding));
+  const Host = defineComponent({
+    setup() {
+      return () =>
+        h(
+          HkRideBox as Component,
+          { riding: riding.value, factor: initial.factor ?? 0.9 },
+          slots ?? {
+            "chrome-start": () => h("header", { class: "probe-chrome-start" }, "title"),
+            default: () => h("div", { class: "probe-content" }, "body"),
+            "chrome-end": () => h("footer", { class: "probe-chrome-end" }, "actions"),
+          },
+        );
+    },
+  });
+  const app = createApp(Host);
+  app.mount(host);
+  return {
+    root: () => host.firstElementChild as HTMLElement,
+    setRiding: async (next: boolean) => {
+      riding.value = next;
+      await nextTick();
+      await nextTick();
+    },
+    unmount: () => {
+      app.unmount();
+      host.remove();
+    },
+  };
+}
+
+/** jsdom reports 0 for every layout box. The measurement deliberately never
+ *  reads the FRAME's height (that is the number the ride computes), so the
+ *  stub feeds it the two honest sources: the content region's natural scroll
+ *  extent and the chrome bands' own offsets. */
+function stubBox(root: HTMLElement, content: number, chrome: number): void {
+  const contentEl = root.querySelector(`.${RIDE_CONTENT_CLASS}`) as HTMLElement;
+  Object.defineProperty(contentEl, "scrollHeight", { configurable: true, value: content });
+  Object.defineProperty(contentEl, "offsetHeight", { configurable: true, value: content });
+  const chromeEls = Array.from(root.children).filter((el) => el !== contentEl) as HTMLElement[];
+  chromeEls.forEach((el, index) => {
+    Object.defineProperty(el, "offsetHeight", {
+      configurable: true,
+      value: index === 0 ? chrome : 0,
+    });
+  });
+}
+
+describe("HkRideBox (family height-ride container)", () => {
+  it("renders the ride contract and keeps the chrome outside the scaled region", () => {
+    const h1 = mountBox();
+    const root = h1.root();
+    expect(root.classList.contains(RIDE_CLASS)).toBe(true);
+    const content = root.querySelector(`.${RIDE_CONTENT_CLASS}`) as HTMLElement;
+    expect(content).not.toBeNull();
+    // Structural guarantee: no transform on the box can ever reach the
+    // chrome, because the chrome is not inside the content region.
+    expect(content.querySelector(".probe-chrome-start")).toBeNull();
+    expect(content.querySelector(".probe-chrome-end")).toBeNull();
+    expect(content.querySelector(".probe-content")).not.toBeNull();
+    expect(root.querySelector(".probe-chrome-start")).not.toBeNull();
+    expect(root.querySelector(".probe-chrome-end")).not.toBeNull();
+    h1.unmount();
+  });
+
+  it("stamps the compressed end plus the riding flag while riding", async () => {
+    const h2 = mountBox({ riding: true });
+    await nextTick();
+    const root = h2.root();
+    expect(root.classList.contains(RIDE_FROM_CLASS)).toBe(true);
+    expect(root.classList.contains(RIDE_TO_CLASS)).toBe(false);
+    expect(root.hasAttribute(RIDE_ATTR)).toBe(true);
+    h2.unmount();
+  });
+
+  it("swaps to the natural end and drops the riding flag at rest", async () => {
+    const h3 = mountBox({ riding: true });
+    await h3.setRiding(false);
+    const root = h3.root();
+    expect(root.classList.contains(RIDE_FROM_CLASS)).toBe(false);
+    expect(root.classList.contains(RIDE_TO_CLASS)).toBe(true);
+    expect(root.hasAttribute(RIDE_ATTR)).toBe(false);
+    h3.unmount();
+  });
+
+  it("publishes the measured chrome/content split and the factor", async () => {
+    const h4 = mountBox({ riding: false, factor: 0.9 });
+    const root = h4.root();
+    stubBox(root, 300, 100);
+    await h4.setRiding(true);
+
+    expect(root.style.getPropertyValue("--hk-ride-chrome")).toBe("100px");
+    expect(root.style.getPropertyValue("--hk-ride-content")).toBe("300px");
+    expect(root.style.getPropertyValue("--hk-ride-factor")).toBe("0.9");
+    h4.unmount();
+  });
+
+  it("publishes nothing when the box cannot be measured", async () => {
+    const h5 = mountBox({ riding: true });
+    await nextTick();
+    const root = h5.root();
+    // Not "0px": an unmeasured ride must degrade to `auto` (no ride), never
+    // to a collapsed frame.
+    expect(root.style.getPropertyValue("--hk-ride-chrome")).toBe("");
+    expect(root.style.getPropertyValue("--hk-ride-content")).toBe("");
+    h5.unmount();
+  });
+
+  it("measures the same split whether the frame is at rest or compressed", async () => {
+    // The measurement must never read the frame's height (that is the value
+    // the ride computes): a compressed frame would otherwise report a short
+    // box and every ride would shrink again on top of the last one.
+    const h6 = mountBox({ riding: false });
+    const root = h6.root();
+    stubBox(root, 300, 60);
+    await h6.setRiding(true);
+    const atRest = {
+      chrome: root.style.getPropertyValue("--hk-ride-chrome"),
+      content: root.style.getPropertyValue("--hk-ride-content"),
+    };
+
+    // Squeeze the frame as the ride would, and re-arm.
+    Object.defineProperty(root, "offsetHeight", { configurable: true, value: 2 });
+    await h6.setRiding(false);
+    await h6.setRiding(true);
+
+    expect(root.style.getPropertyValue("--hk-ride-chrome")).toBe(atRest.chrome);
+    expect(root.style.getPropertyValue("--hk-ride-content")).toBe(atRest.content);
+    h6.unmount();
+  });
+});

package/src/components/HkRideBox.tsx

@@ -0,0 +1,165 @@
+/**
+ * HkRideBox — the surface container for the family-level height ride.
+ *
+ * One job: give a surface a frame whose LAYOUT height rides between the
+ * natural height and `chrome + content × factor`, while every chrome band
+ * the caller pins keeps its natural size (see `useHeightRide` for why the
+ * motion is done on layout height instead of `transform: scaleY()` — the
+ * 2026-11-07 user report: a frame-level scale squashed the title bar and
+ * the footer buttons).
+ *
+ *   <HkRideBox :riding="isRiding" :factor="0.9">
+ *     <template #chrome-start><header/></template>
+ *     <Body/>                     <!-- the region that gets compressed -->
+ *     <template #chrome-end><footer/></template>
+ *   </HkRideBox>
+ *
+ * The chrome split is MEASURED, not declared (`chrome = boxHeight −
+ * contentHeight`), so any number of chrome bands — header, sub-header,
+ * breadcrumb strip, footer, a status row — works without the caller
+ * listing them. The default slot is the only region ever scaled.
+ *
+ * Scroll-container compatibility: the content slot keeps its natural
+ * layout box for the whole ride, so `HkScrollContainer` / `HkScrollPin` /
+ * the overlay scrollbar read stable geometry — no per-frame re-measure, no
+ * pins drifting. Surfaces that must skip work while a ride is in flight
+ * read the `data-hk-riding` attribute this box stamps (the same contract
+ * `data-hk-morphing` gives the mobile sheet).
+ */
+import { defineComponent, h, nextTick, onBeforeUnmount, onMounted, ref, watch } from "vue";
+
+import {
+  RIDE_ATTR,
+  RIDE_CLASS,
+  RIDE_CONTENT_CLASS,
+  RIDE_FROM_CLASS,
+  RIDE_TO_CLASS,
+  useHeightRide,
+} from "../composables/useHeightRide";
+
+/** Read the ride duration the sheet is using (ms), with a sane default. */
+function readRideMs(el: HTMLElement): number {
+  const raw = getComputedStyle(el).transitionDuration || "";
+  const ms = raw
+    .split(",")
+    .map((part) => part.trim())
+    .map((part) => (part.endsWith("ms") ? parseFloat(part) : parseFloat(part) * 1000))
+    .filter((n) => Number.isFinite(n) && n > 0);
+  return ms.length > 0 ? Math.max(...ms) : 420;
+}
+import "./HkRideBox.scss";
+
+export default defineComponent({
+  name: "HkRideBox",
+  props: {
+    /** True for the whole flight: the box is compressed from mount, and
+     *  drops back to natural when this goes false. */
+    riding: { type: Boolean, default: false },
+    /** Content height at the compressed extreme, as a fraction of natural. */
+    factor: { type: Number, default: 0.9 },
+    /** Root element tag. */
+    as: { type: String, default: "div" },
+  },
+  emits: {
+    /** The ride landed (its own transitionend, or immediately when there
+     *  was nothing to animate). */
+    settle: () => true,
+  },
+  setup(props, { slots, emit }) {
+    const rootRef = ref<HTMLElement | null>(null);
+    const contentRef = ref<HTMLElement | null>(null);
+    const ride = useHeightRide(rootRef, contentRef, { factor: props.factor });
+
+    /** Stamps the state class for the current phase. Called after the
+     *  measurement lands so the first painted frame is already correct. */
+    const apply = (riding: boolean): void => {
+      const el = rootRef.value;
+      if (!el) return;
+      el.classList.toggle(RIDE_CLASS, true);
+      if (riding) {
+        el.classList.add(RIDE_FROM_CLASS);
+        el.classList.remove(RIDE_TO_CLASS);
+        el.setAttribute(RIDE_ATTR, "");
+      } else if (el.classList.contains(RIDE_FROM_CLASS)) {
+        // Coming out of a ride: land through the natural end, then drop the
+        // classes (see land()) so the box returns to its own height.
+        el.classList.remove(RIDE_FROM_CLASS);
+        el.classList.add(RIDE_TO_CLASS);
+        el.removeAttribute(RIDE_ATTR);
+      }
+    };
+
+    let landTimer: ReturnType<typeof setTimeout> | null = null;
+    /** Bumped on every arm: a stale async continuation (rapid
+     *  riding→rest→riding in one tick) must not land the NEW ride. */
+    let generation = 0;
+
+    const clearLand = (): void => {
+      if (landTimer !== null) {
+        clearTimeout(landTimer);
+        landTimer = null;
+      }
+    };
+
+    /** Drop every ride state so the box returns to its own layout height
+     *  (`auto`, or the consumer's pin) instead of freezing at the measured
+     *  px value. */
+    const land = (): void => {
+      const el = rootRef.value;
+      if (!el) return;
+      el.classList.remove(RIDE_FROM_CLASS, RIDE_TO_CLASS);
+      el.removeAttribute(RIDE_ATTR);
+      emit("settle");
+    };
+
+    const armRide = async (riding: boolean): Promise<void> => {
+      const mine = ++generation;
+      clearLand();
+      // Measure at REST geometry first (a frame at the compressed end
+      // reports a short box, which would make the next ride shrink twice).
+      ride.refresh();
+      const wasRiding = rootRef.value?.classList.contains(RIDE_FROM_CLASS) ?? false;
+      apply(riding);
+      await nextTick();
+      if (mine !== generation) return;
+      if (riding) return;
+      if (!wasRiding) {
+        emit("settle");
+        return;
+      }
+      // Landing: the natural end is reached once the height transition has
+      // run; then the classes come off so the box is `auto` again. A lost
+      // transitionend (a WebView that skips it, a frame that never
+      // animated) still lands through the watchdog.
+      const el = rootRef.value;
+      const duration = el ? readRideMs(el) : 420;
+      landTimer = setTimeout(() => {
+        landTimer = null;
+        if (mine !== generation) return;
+        land();
+      }, duration + 120);
+    };
+
+    onMounted(() => void armRide(props.riding));
+    onBeforeUnmount(() => {
+      generation += 1;
+      clearLand();
+      ride.release();
+    });
+    watch(
+      () => props.riding,
+      (riding) => void armRide(riding),
+    );
+
+    return () =>
+      h(
+        props.as,
+        { ref: rootRef, class: [RIDE_CLASS, "hk-ride-box"] },
+        [
+          h("div", { class: "hk-ride-chrome-start" }, slots["chrome-start"]?.()),
+          h("div", { ref: contentRef, class: RIDE_CONTENT_CLASS }, slots.default?.()),
+          h("div", { class: "hk-ride-chrome-end" }, slots["chrome-end"]?.()),
+        ],
+      );
+  },
+});

package/src/components/paneSwap.contract.test.ts

@@ -127,6 +127,15 @@ describe("pane-swap contract", () => {
       // These are hosts that MUST render their slot keyed by state — they
       // are exactly the pane slots the rule is about, and each is either
       // wrapped by the standard above or justified here.
+      // HkRideBox renders its two CHROME slots by name
+      // (`slots["chrome-start"]`, `slots["chrome-end"]`). They are not pane
+      // slots and never swap: they are the fixed-size bands bracketing the
+      // content region, and the whole point of the box is that they stay
+      // OUTSIDE the scaled region (2026-11-07 user report: a frame-level
+      // scale squashed the title bar and the footer buttons). Routing them
+      // through HkTransitionContainer would be wrong — they must render
+      // exactly once, in place, in the same paint.
+      "HkRideBox.tsx",
       "HkTabs.tsx", // wrapped by HkTransitionContainer (pinned above)
       "HkSettingsDialog.tsx", // wrapped by HkTransitionContainer (pinned above)
       // HkStepFlow is NOT a rogue pane slot — it is a sibling mechanism

package/src/composables/useHeightRide.ts

@@ -0,0 +1,182 @@
+/**
+ * useHeightRide — the family-level "height ride" measurement primitive.
+ *
+ * Several hikari surfaces want one specific open/close motion: the SURFACE
+ * FRAME itself grows from a fraction of its natural height to the full
+ * height, while the chrome (title bar, footer action row, any pinned band)
+ * keeps its natural size and stays legible. Scaling the whole frame
+ * (`transform: scaleY()`) is the wrong tool for that — it squashes the
+ * title glyphs, the buttons and the corner radii along with everything
+ * else (2026-11-07 user report on the modal ride), and it re-rasters text
+ * for the entire ride.
+ *
+ * The ride is therefore a LAYOUT-height animation:
+ *
+ *   frame height  :  chrome + content × factor   ⇄   chrome + content
+ *   content region:  scaleY(factor)              ⇄   scaleY(1)   (origin top)
+ *
+ * The content region keeps its natural layout box (so nothing inside it
+ * reflows per frame) and is only visually compressed about its own TOP
+ * edge, which makes the compressed paint land exactly in the shorter slot
+ * the frame leaves for it: the frame's bottom edge and the content's
+ * bottom edge coincide at every t. Chrome is never inside the transform,
+ * so its type, icons and padding render at natural size throughout.
+ *
+ * This composable owns the MEASUREMENT half only: it publishes
+ *
+ *   --hk-ride-chrome    px  the part of the frame the ride must not squeeze
+ *   --hk-ride-content   px  the region that does get compressed
+ *   --hk-ride-factor    the fraction (default 0.9)
+ *
+ * on the frame, and leaves the interpolation to CSS. That split is what
+ * keeps it composable with the surfaces' existing state machines: the
+ * consumer keeps flipping its own enter/leave classes (HkModal's surface
+ * machine, HkRideBox's `riding` prop) and the sheet resolves
+ * `height: calc(chrome + content × factor)` from the published numbers.
+ * No timers, no class ownership, no fight with a consumer's own height pin
+ * — a state rule carrying `!important` legitimately outranks the inline
+ * px the size-morph pins while a ride is in flight.
+ *
+ * Scroll-container compatibility (the reason this lives upstream rather
+ * than inside HkModal): every hikari custom scroller (`HkScrollContainer`,
+ * `HkScrollPin`, the overlay scrollbar, the windowed scroller) measures
+ * LAYOUT boxes — `offsetHeight` / `clientHeight` / `scrollHeight` — which
+ * a transform never touches. Because the ride animates the FRAME's height
+ * and leaves the content box natural, those measurements, the scroll
+ * offsets, the pins and the fade bands stay coherent for the whole ride;
+ * nothing has to be re-measured per frame, and nothing drifts when the
+ * ride is interrupted.
+ */
+import { onBeforeUnmount, type Ref } from "vue";
+
+/** Class/attribute vocabulary shared by the sheet and the contract tests. */
+export const RIDE_CLASS = "hk-ride";
+export const RIDE_FROM_CLASS = "hk-ride--from";
+export const RIDE_TO_CLASS = "hk-ride--to";
+export const RIDE_CONTENT_CLASS = "hk-ride-content";
+export const RIDE_ATTR = "data-hk-riding";
+/** Present only once the chrome/content split has been measured. */
+export const RIDE_READY_ATTR = "data-hk-ride-ready";
+
+export interface HeightRideOptions {
+  /** Content height at the ride's extreme, as a fraction of natural.
+   *  Default 0.9 (a 10% vertical reveal). */
+  factor?: number;
+}
+
+export interface HeightRide {
+  /** Measure the frame's chrome/content split and publish the variables.
+   *  Safe to call at any time OUTSIDE a ride (rest geometry is what the
+   *  ride needs); calling it mid-ride re-measures the live, compressed
+   *  box and is therefore a no-op unless `force` is passed. */
+  refresh(force?: boolean): boolean;
+  /** Re-apply the LAST measured split without touching the DOM boxes.
+   *  A surface that unmounts its frame on close loses the inline variables
+   *  with it; republishing on the next mount is what makes the very first
+   *  painted frame of the next ride already correct. */
+  publish(): boolean;
+  /** The chrome height (px) from the last successful measure. */
+  chromeHeight(): number;
+  /** The content height (px) from the last successful measure. */
+  contentHeight(): number;
+  /** Drop the published variables (the sheet then falls back to `auto`,
+   *  i.e. no ride — never to a wrong box). */
+  release(): void;
+}
+
+/** Any ride class means the box is (or is heading) somewhere other than its
+ *  rest height, so a measurement taken then would poison the next ride. The
+ *  guard therefore covers BOTH ends; consumers measure at rest. */
+function isInFlight(frame: HTMLElement): boolean {
+  return (
+    frame.classList.contains(RIDE_FROM_CLASS) || frame.classList.contains(RIDE_TO_CLASS)
+  );
+}
+
+/**
+ * Wire a frame (whose height rides) to the content region it compresses.
+ *
+ * `frame` must carry `.hk-ride` (directly, or via `HkRideBox`); `content`
+ * must carry `.hk-ride-content`. Both are applied by the sheet/component,
+ * so consumers normally only supply the refs.
+ */
+export function useHeightRide(
+  frame: Ref<HTMLElement | null | undefined>,
+  content: Ref<HTMLElement | null | undefined>,
+  options: HeightRideOptions = {},
+): HeightRide {
+  // Read live: a consumer may change `factor` after mount.
+  const factorOf = (): number => options.factor ?? 0.9;
+  let chrome = 0;
+  let contentH = 0;
+
+  const release = (): void => {
+    const f = frame.value;
+    if (!f) return;
+    f.style.removeProperty("--hk-ride-chrome");
+    f.style.removeProperty("--hk-ride-content");
+    f.style.removeProperty("--hk-ride-factor");
+    f.removeAttribute(RIDE_READY_ATTR);
+  };
+
+  const refresh = (force = false): boolean => {
+    const f = frame.value;
+    const c = content.value;
+    if (!f || !c) return false;
+    // Once the split is known, re-measuring DURING a ride would read the
+    // compressed boxes and shrink again on the next flight. The first
+    // measurement is exempt: the sheet keeps the frame at `auto` until the
+    // split is published, so that one is taken on honest natural geometry.
+    if (!force && f.hasAttribute(RIDE_READY_ATTR) && isInFlight(f)) return false;
+    // Neither side reads the FRAME's height (that is the number the ride
+    // computes): the content region's own layout box, plus the frame's OTHER
+    // element children (the pinned chrome bands, always `flex-shrink: 0`).
+    // Phones/WebViews that report 0 publish nothing at all rather than a
+    // wrong box.
+    let chromeNatural = 0;
+    for (const child of Array.from(f.children)) {
+      if (child === c || !(child instanceof HTMLElement)) continue;
+      chromeNatural += child.offsetHeight;
+    }
+    // At rest the frame is at (or pinned to) its natural height, so the
+    // content region's natural height is the honest difference there; mid
+    // flight only the content's own box is trustworthy (the frame is short
+    // by design). Both branches are frame-height independent when it
+    // matters — a compressed frame never feeds the next ride.
+    const contentNatural = isInFlight(f)
+      ? c.offsetHeight
+      : Math.max(0, f.offsetHeight - chromeNatural);
+    const measured = contentNatural > 0 ? contentNatural : c.offsetHeight;
+    if (measured <= 0) return false;
+    contentH = measured;
+    chrome = chromeNatural;
+    f.style.setProperty("--hk-ride-chrome", `${chrome}px`);
+    f.style.setProperty("--hk-ride-content", `${contentH}px`);
+    f.style.setProperty("--hk-ride-factor", String(factorOf()));
+    // Readiness flag: the sheet only overrides the frame's height once the
+    // split is real, so an unmeasured ride degrades to a plain fade instead
+    // of collapsing to `calc(0px + 0px)`.
+    f.setAttribute(RIDE_READY_ATTR, "");
+    return true;
+  };
+
+  onBeforeUnmount(() => release());
+
+  const publish = (): boolean => {
+    const f = frame.value;
+    if (!f || contentH <= 0) return false;
+    f.style.setProperty("--hk-ride-chrome", `${chrome}px`);
+    f.style.setProperty("--hk-ride-content", `${contentH}px`);
+    f.style.setProperty("--hk-ride-factor", String(factorOf()));
+    f.setAttribute(RIDE_READY_ATTR, "");
+    return true;
+  };
+
+  return {
+    refresh,
+    publish,
+    chromeHeight: () => chrome,
+    contentHeight: () => contentH,
+    release,
+  };
+}

package/src/index.ts

@@ -86,6 +86,7 @@ export { default as HProgressBar } from "./components/HkProgressBar";
 export { default as HProgressDialog } from "./components/HkProgressDialog";
 export { default as HRadio } from "./components/HkRadio";
 export { default as HScrollContainer } from "./components/HkScrollContainer";
+export { default as HRideBox } from "./components/HkRideBox";
 export { default as HScreenIdentifyCard } from "./components/HkScreenIdentifyCard";
 export { default as HScreenIdentifyHost } from "./components/HkScreenIdentifyHost";
 export { default as HSearchInput } from "./components/HkSearchInput";
@@ -518,6 +519,8 @@ export type { HkScrollProgressHandle, HkScrollProgressRegistrar } from "./compon
 export type { OverlayScrollMapSegment, OverlayScrollbarMarker } from "./composables/useOverlayScrollbar";
 export { useDeferredTransition } from "./composables/useDeferredTransition";
 export { useSurfaceTransition } from "./composables/useSurfaceTransition";
+export { useHeightRide } from "./composables/useHeightRide";
+export type { HeightRide, HeightRideOptions } from "./composables/useHeightRide";
 export { useSizeMorph } from "./composables/useSizeMorph";
 export type { SizeMorph } from "./composables/useSizeMorph";
 export { useImage } from "./composables/useImage";