@celestia-island/hikari 0.55.305 → 0.55.307

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.305",
+  "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/HkRangeRibbon.scss

@@ -23,6 +23,12 @@
   // ONE label column for both surfaces: the overview paints through an
   // empty gutter of this width, so an x% bar sits at the same inline
   // position in the strip and in its lane (the strip locates segments).
+  // Wave (2026-11-06 raw-records five): the label column is JS-MEASURED —
+  // the component publishes the widest rendered label as a px value on the
+  // root (two-phase free/measure/pin). THIS fixed column is the no-JS /
+  // pre-measure fallback: a shared width keeps strip-lane x% alignment
+  // before the measurement lands (a bare max-content here would resolve
+  // 0px in the empty gutter and misalign everything).
   --hk-range-ribbon-label-col: minmax(48px, 84px);
 
   display: flex;
@@ -42,7 +48,9 @@
   min-width: 0;
 }
 
-// The empty first cell that lines the strip up with the lane tracks.
+// The empty first cell that lines the strip up with the lane tracks. Its
+// width comes from the shared var, which the component JS-measures and
+// publishes on the root (two-phase free/measure/pin).
 .hk-range-ribbon-overview-gutter {
   display: block;
   min-width: 0;
@@ -55,6 +63,29 @@
   min-width: 0;
 }
 
+.hk-range-ribbon[data-minimal] {
+  gap: 0;
+
+  /* Bare-bar layout: single column, gutter probe out of the way — the
+     strip spans the full width (its in-flow content is absolute, so
+     without this the max-content column would collapse to zero). */
+  .hk-range-ribbon-overview {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .hk-range-ribbon-overview-gutter {
+    display: none;
+  }
+}
+
+.hk-range-ribbon[data-minimal] .hk-range-ribbon-strip {
+  // Minimal mode (raw-records five): the track reads through muted-based
+  // tokens — the surface-based track read whitish inside dark phone
+  // modals. The inset hairline keeps the frame visible but quiet.
+  background: rgb(var(--color-muted) / 25%);
+  box-shadow: inset 0 0 0 1px rgb(var(--color-border) / 40%);
+}
+
 .hk-range-ribbon-strip {
   position: relative;
   display: block;