@oneuptime/common 13.0.5 → 13.0.7

package/Tests/UI/Rum/ReplayStage.test.tsx

@@ -14,14 +14,23 @@ import { afterEach, describe, expect, it, jest } from "@jest/globals";
 import type { SpyInstance } from "jest-mock";
 import ReplayStage, {
   REPLAY_DOCUMENT_CSP,
-  REPLAY_STAGE_MAX_HEIGHT_VH,
-  REPLAY_STAGE_MIN_HEIGHT_REM,
-  REPLAY_STAGE_THEATER_MAX_HEIGHT_VH,
+  REPLAY_STAGE_ASPECT_CSS_VAR,
+  REPLAY_STAGE_FILL_BOX_CLASS,
+  REPLAY_STAGE_FIT_OVERFLOW_CLASS,
+  REPLAY_STAGE_FLOW_MAX_HEIGHT_VH,
+  REPLAY_STAGE_FLOW_MIN_HEIGHT_REM,
+  REPLAY_STAGE_PHONE_RING_PX,
+  REPLAY_STAGE_RESPONSIVE_BOX_CLASS,
   REPLAY_TEXT_SELECTION_CSS,
+  ReplayStageFit,
+  ReplayStageFrameGeometry,
   computeContainScale,
-  computeReplayStageHeight,
+  computeReplayStageFrameGeometry,
+  computeWidthScale,
   disableReplayTextSelection,
   enableReplayTextSelection,
+  formatReplayStageAspect,
+  getReplayStageBoxClassName,
 } from "../../../../App/FeatureSet/Dashboard/src/Components/SessionReplay/ReplayStage";
 import {
   ReplayEngine,
@@ -37,10 +46,15 @@ import {
 /*
  * ReplayStage is now a thin React binding over the engine: everything
  * about WHAT plays is pinned in ReplayEngine.test.ts. What is left to pin
- * here is what needs a DOM - mounting the engine's host, contain-fit
- * scaling within the height bounds, the aspect reserved before the first
+ * here is what needs a DOM - mounting the engine's host, the box classes
+ * that take the leftover height from the player's flex column, the three
+ * fits and their frame geometry, the aspect reserved before the first
  * frame, the CSP meta on every rebuilt document, the phone frame, the
  * touch ring and the speed-aware cursor.
+ *
+ * The stage no longer measures the viewport, the page offset or the
+ * transport: its height comes from CSS, so the only measurement left is
+ * its own box.
  */
 
 function makeSnapshot(
@@ -243,11 +257,6 @@ afterEach(() => {
   document.body.innerHTML = "";
 });
 
-interface BoundingRectSpy {
-  mockReturnValue: (value: DOMRect) => unknown;
-  mockRestore: () => void;
-}
-
 describe("ReplayStage mounting", () => {
   it("attaches the engine's host into the stage on mount and detaches on unmount", () => {
     const engine: FakeEngine = new FakeEngine();
@@ -291,188 +300,245 @@ describe("ReplayStage mounting", () => {
   });
 });
 
-describe("ReplayStage sizing", () => {
-  it("reserves the measured transport height without letting a short viewport erase the recording", () => {
-    expect(computeReplayStageHeight(900, 300, 260)).toBe(340);
-    expect(computeReplayStageHeight(1100, 300, 260)).toBe(540);
-    expect(computeReplayStageHeight(600, 350, 260)).toBe(256);
-  });
-
-  it("recalculates desktop height when transport size changes and keeps normal sizing on mobile", () => {
-    const engine: FakeEngine = new FakeEngine();
-    const originalWidth: number = window.innerWidth;
-    const originalHeight: number = window.innerHeight;
-    Object.defineProperty(window, "innerWidth", {
-      configurable: true,
-      value: 1440,
-    });
-    Object.defineProperty(window, "innerHeight", {
-      configurable: true,
-      value: 900,
-    });
-
-    try {
-      const { rerender } = render(
-        <ReplayStage
-          engine={engine}
-          reservedBottomHeightPx={260}
-          viewportWidth={1200}
-          viewportHeight={760}
-        />,
-      );
-      expect(stageElement().style.maxHeight).toBe("640px");
-      expect(stageElement().style.aspectRatio).toBe("1200 / 760");
-      expect(stageElement().style.minHeight).toBe("16rem");
-
-      rerender(
-        <ReplayStage
-          engine={engine}
-          reservedBottomHeightPx={320}
-          viewportWidth={1200}
-          viewportHeight={760}
-        />,
-      );
-      expect(stageElement().style.maxHeight).toBe("580px");
+/* A ResizeObserver whose callbacks this test fires by hand. */
+interface FakeResizeObserver {
+  observed: Array<Element>;
+  trigger: () => void;
+  restore: () => void;
+}
 
-      Object.defineProperty(window, "innerWidth", {
-        configurable: true,
-        value: 390,
-      });
-      act((): void => {
-        window.dispatchEvent(new Event("resize"));
-      });
-      expect(stageElement().style.maxHeight).toBe(
-        `${REPLAY_STAGE_MAX_HEIGHT_VH}vh`,
-      );
-      expect(stageElement().style.minHeight).toBe(
-        `${REPLAY_STAGE_MIN_HEIGHT_REM}rem`,
-      );
-    } finally {
-      Object.defineProperty(window, "innerWidth", {
-        configurable: true,
-        value: originalWidth,
-      });
-      Object.defineProperty(window, "innerHeight", {
-        configurable: true,
-        value: originalHeight,
-      });
+function installResizeObserver(): FakeResizeObserver {
+  const original: PropertyDescriptor | undefined =
+    Object.getOwnPropertyDescriptor(window, "ResizeObserver");
+  const observed: Array<Element> = [];
+  const callbacks: Array<ResizeObserverCallback> = [];
+  const instances: Array<ResizeObserver> = [];
+
+  class TestResizeObserver implements ResizeObserver {
+    public constructor(callback: ResizeObserverCallback) {
+      callbacks.push(callback);
+      instances.push(this);
     }
-  });
-
-  it("refits when a header notice moves the stage without changing its own size", () => {
-    const originalObserver: PropertyDescriptor | undefined =
-      Object.getOwnPropertyDescriptor(window, "ResizeObserver");
-    const originalWidth: number = window.innerWidth;
-    const originalHeight: number = window.innerHeight;
-    const observed: Array<Element> = [];
-    const callbacks: Array<ResizeObserverCallback> = [];
-    const instances: Array<ResizeObserver> = [];
-    class TestResizeObserver implements ResizeObserver {
-      public constructor(callback: ResizeObserverCallback) {
-        callbacks.push(callback);
-        instances.push(this);
-      }
-      public observe(target: Element): void {
-        observed.push(target);
-      }
-      public unobserve(): void {
-        return;
-      }
-      public disconnect(): void {
-        return;
-      }
+    public observe(target: Element): void {
+      observed.push(target);
     }
-    Object.defineProperty(window, "ResizeObserver", {
-      configurable: true,
-      value: TestResizeObserver,
-    });
-    Object.defineProperty(window, "innerWidth", {
-      configurable: true,
-      value: 1440,
-    });
-    Object.defineProperty(window, "innerHeight", {
-      configurable: true,
-      value: 900,
-    });
+    public unobserve(): void {
+      return;
+    }
+    public disconnect(): void {
+      return;
+    }
+  }
 
-    try {
-      const engine: FakeEngine = new FakeEngine();
-      render(
-        <div data-replay-layout="true">
-          <header>Recording details</header>
-          <ReplayStage engine={engine} reservedBottomHeightPx={260} />
-        </div>,
-      );
-      const stage: HTMLElement = stageElement();
-      const header: HTMLElement = document.querySelector(
-        "header",
-      ) as HTMLElement;
-      expect(observed).toContain(header);
-      expect(observed).toContain(stage);
-      /*
-       * Named structurally rather than as jest.SpiedFunction: jest.spyOn here
-       * is the one imported from @jest/globals, whose return type is
-       * jest-mock's SpyInstance, while `jest.SpiedFunction` resolves through
-       * the global @types/jest namespace. The two declarations do not assign
-       * to each other, so name only what this test uses.
-       */
-      const rectangle: BoundingRectSpy = jest.spyOn(
-        stage,
-        "getBoundingClientRect",
-      );
-      rectangle.mockReturnValue({ top: 200 } as DOMRect);
-      act((): void => {
-        callbacks[0]?.([], instances[0] as ResizeObserver);
-      });
-      expect(stage.style.maxHeight).toBe("440px");
+  Object.defineProperty(window, "ResizeObserver", {
+    configurable: true,
+    value: TestResizeObserver,
+  });
 
-      // A clipboard fallback expands the header; no resize event is needed.
-      header.textContent = "Copy the link by hand";
-      rectangle.mockReturnValue({ top: 300 } as DOMRect);
+  return {
+    observed: observed,
+    trigger: (): void => {
       act((): void => {
-        callbacks[0]?.([], instances[0] as ResizeObserver);
+        for (let index: number = 0; index < callbacks.length; index++) {
+          callbacks[index]?.([], instances[index] as ResizeObserver);
+        }
       });
-      expect(stage.style.maxHeight).toBe("340px");
-      rectangle.mockRestore();
-    } finally {
-      if (originalObserver) {
-        Object.defineProperty(window, "ResizeObserver", originalObserver);
+    },
+    restore: (): void => {
+      if (original) {
+        Object.defineProperty(window, "ResizeObserver", original);
       } else {
         Reflect.deleteProperty(window, "ResizeObserver");
       }
-      Object.defineProperty(window, "innerWidth", {
-        configurable: true,
-        value: originalWidth,
-      });
-      Object.defineProperty(window, "innerHeight", {
-        configurable: true,
-        value: originalHeight,
-      });
-    }
-  });
+    },
+  };
+}
 
-  it("reserves the recorded aspect from the header viewport before the first frame", () => {
+describe("ReplayStage sizing", () => {
+  /*
+   * The whole point of the redesign: the box no longer computes a pixel
+   * height from the viewport minus the transport (which floored at 256px
+   * and drew a 1200x760 recording at 34%). It is a flex child that takes
+   * whatever height the player's column has left, and below xl it falls
+   * back to the recorded aspect within flow bounds.
+   */
+  it("takes the leftover height from the player's flex column, with flow bounds below xl", () => {
     const engine: FakeEngine = new FakeEngine();
 
     render(
-      <ReplayStage engine={engine} viewportWidth={1440} viewportHeight={900} />,
+      <ReplayStage engine={engine} viewportWidth={1200} viewportHeight={760} />,
     );
 
     const stage: HTMLElement = stageElement();
 
-    expect(stage.style.aspectRatio).toBe("1440 / 900");
-    expect(stage.style.minHeight).toBe(`${REPLAY_STAGE_MIN_HEIGHT_REM}rem`);
-    expect(stage.style.maxHeight).toBe(`${REPLAY_STAGE_MAX_HEIGHT_VH}vh`);
+    expect(stage).toHaveAttribute("data-replay-sizing", "responsive");
+    /* Flow (below xl): the recorded aspect, capped and floored. */
+    expect(stage.className).toContain(
+      "[aspect-ratio:var(--oneuptime-replay-aspect)]",
+    );
+    expect(stage.className).toContain(
+      `max-h-[${REPLAY_STAGE_FLOW_MAX_HEIGHT_VH}vh]`,
+    );
+    expect(stage.className).toContain(
+      `min-h-[${REPLAY_STAGE_FLOW_MIN_HEIGHT_REM}rem]`,
+    );
+    /* Fill (xl and up): the column's leftover height, no aspect, no cap. */
+    expect(stage.className).toContain("xl:flex-1");
+    expect(stage.className).toContain("xl:h-full");
+    expect(stage.className).toContain("xl:min-h-0");
+    expect(stage.className).toContain("xl:max-h-none");
+    expect(stage.className).toContain("xl:[aspect-ratio:auto]");
+
+    /* No measured pixel height, and no aspect-ratio style, is left. */
+    expect(stage.style.maxHeight).toBe("");
+    expect(stage.style.minHeight).toBe("");
+    expect(stage.style.getPropertyValue("aspect-ratio")).toBe("");
+    expect(stage.style.getPropertyValue(REPLAY_STAGE_ASPECT_CSS_VAR)).toBe(
+      "1200 / 760",
+    );
+  });
+
+  it("fills its container at every width when the shell asks for fill sizing", () => {
+    const engine: FakeEngine = new FakeEngine();
+
+    render(<ReplayStage engine={engine} sizing="fill" />);
+
+    const stage: HTMLElement = stageElement();
+
+    expect(stage).toHaveAttribute("data-replay-sizing", "fill");
+    expect(stage.className).toContain(REPLAY_STAGE_FILL_BOX_CLASS);
+    expect(stage.className).toContain("h-full");
+    expect(stage.className).toContain("min-h-0");
+    expect(stage.className).toContain("flex-1");
+    /* Nothing caps it: theater is a definite-height page of its own. */
+    expect(stage.className).not.toContain(
+      `max-h-[${REPLAY_STAGE_FLOW_MAX_HEIGHT_VH}vh]`,
+    );
+    expect(stage.className).not.toContain("aspect-ratio");
   });
 
-  it("raises the height bound to the whole viewport in theater", () => {
+  it("still fills the screen in theater when the caller has not moved to sizing yet", () => {
     const engine: FakeEngine = new FakeEngine();
 
-    render(<ReplayStage engine={engine} isTheater={true} />);
+    const { rerender } = render(
+      <ReplayStage engine={engine} isTheater={true} />,
+    );
+
+    expect(stageElement()).toHaveAttribute("data-replay-sizing", "fill");
+    expect(stageElement().className).toContain(REPLAY_STAGE_FILL_BOX_CLASS);
+
+    /* An explicit sizing always wins over the legacy flag. */
+    rerender(
+      <ReplayStage engine={engine} isTheater={true} sizing="responsive" />,
+    );
 
-    expect(stageElement().style.maxHeight).toBe(
-      `${REPLAY_STAGE_THEATER_MAX_HEIGHT_VH}vh`,
+    expect(stageElement()).toHaveAttribute("data-replay-sizing", "responsive");
+  });
+
+  it("spells the exported flow bounds and aspect variable out in the box classes", () => {
+    /*
+     * Tailwind only sees whole class names in the source, so the classes
+     * are literals. These assertions are what keeps the literals and the
+     * constants the shell's placeholder reuses from drifting apart.
+     */
+    expect(REPLAY_STAGE_RESPONSIVE_BOX_CLASS).toContain(
+      `max-h-[${REPLAY_STAGE_FLOW_MAX_HEIGHT_VH}vh]`,
     );
+    expect(REPLAY_STAGE_RESPONSIVE_BOX_CLASS).toContain(
+      `min-h-[${REPLAY_STAGE_FLOW_MIN_HEIGHT_REM}rem]`,
+    );
+    expect(REPLAY_STAGE_RESPONSIVE_BOX_CLASS).toContain(
+      `[aspect-ratio:var(${REPLAY_STAGE_ASPECT_CSS_VAR})]`,
+    );
+    expect(getReplayStageBoxClassName("responsive", "contain")).toBe(
+      `${REPLAY_STAGE_RESPONSIVE_BOX_CLASS} ${REPLAY_STAGE_FIT_OVERFLOW_CLASS.contain}`,
+    );
+    expect(getReplayStageBoxClassName("fill", "actual")).toBe(
+      `${REPLAY_STAGE_FILL_BOX_CLASS} ${REPLAY_STAGE_FIT_OVERFLOW_CLASS.actual}`,
+    );
+  });
+
+  it("scrolls according to the fit, with a reserved gutter under width fit", () => {
+    const engine: FakeEngine = new FakeEngine({
+      recordedSize: { width: 1200, height: 900 },
+    });
+
+    const { rerender } = render(<ReplayStage engine={engine} />);
+
+    expect(stageElement().className).toContain("overflow-hidden");
+
+    rerender(<ReplayStage engine={engine} fit="width" />);
+
+    expect(stageElement()).toHaveAttribute("data-replay-fit", "width");
+    expect(stageElement().className).toContain("overflow-y-auto");
+    expect(stageElement().className).toContain("overflow-x-hidden");
+    /*
+     * Without a stable gutter the scrollbar narrows the box, the narrower
+     * box scales the page down until it fits, the scrollbar goes away and
+     * the two oscillate.
+     */
+    expect(stageElement().className).toContain("[scrollbar-gutter:stable]");
+
+    rerender(<ReplayStage engine={engine} fit="actual" />);
+
+    expect(stageElement().className).toContain("overflow-auto");
+  });
+
+  it("reserves the recorded aspect from the header viewport before the first frame", () => {
+    const engine: FakeEngine = new FakeEngine();
+
+    render(
+      <ReplayStage engine={engine} viewportWidth={1440} viewportHeight={900} />,
+    );
+
+    expect(
+      stageElement().style.getPropertyValue(REPLAY_STAGE_ASPECT_CSS_VAR),
+    ).toBe("1440 / 900");
+    /* The aspect is a variable the class reads, not an inline property. */
+    expect(stageElement().style.getPropertyValue("aspect-ratio")).toBe("");
+  });
+
+  it("measures its own box only, and refits when that box changes", () => {
+    const observer: FakeResizeObserver = installResizeObserver();
+
+    try {
+      const engine: FakeEngine = new FakeEngine({
+        recordedSize: { width: 1200, height: 900 },
+      });
+
+      render(
+        <div data-replay-layout="true">
+          <header>Recording details</header>
+          <ReplayStage engine={engine} />
+        </div>,
+      );
+
+      const stage: HTMLElement = stageElement();
+
+      expect(observer.observed).toContain(stage);
+      /*
+       * The header and the layout used to be observed to recompute a
+       * viewport-derived height. The box's own height now comes from the
+       * layout above it, so a header notice resizes the box itself.
+       */
+      expect(observer.observed).toHaveLength(1);
+
+      sizeElement(stage, 600, 300);
+      observer.trigger();
+
+      expect(engine.host.style.transform).toBe(
+        `scale(${computeContainScale(600, 300, { width: 1200, height: 900 })})`,
+      );
+
+      sizeElement(stage, 900, 600);
+      observer.trigger();
+
+      expect(engine.host.style.transform).toBe(
+        `scale(${computeContainScale(900, 600, { width: 1200, height: 900 })})`,
+      );
+    } finally {
+      observer.restore();
+    }
   });
 
   it("contain-fits on the smaller of the two ratios and centres the picture", () => {
@@ -513,11 +579,13 @@ describe("ReplayStage sizing", () => {
 
     const frame: HTMLElement = frameElement();
 
+    expect(frame.style.position).toBe("absolute");
     expect(frame.style.width).toBe("400px");
     expect(frame.style.height).toBe("300px");
     /* Letterboxed: (600 - 400) / 2. */
     expect(frame.style.left).toBe("100px");
     expect(frame.style.top).toBe("0px");
+    expect(frame.style.margin).toBe("");
     expect(scales[scales.length - 1]).toBeCloseTo(expected, 6);
   });
 
@@ -529,6 +597,92 @@ describe("ReplayStage sizing", () => {
 
   it("keeps the picture at 1:1 while the box is unmeasured", () => {
     expect(computeContainScale(0, 0, { width: 1200, height: 900 })).toBe(1);
+    expect(computeWidthScale(0, { width: 1200, height: 900 })).toBe(1);
+  });
+
+  it("fills the width and scrolls the page vertically when fit is width", () => {
+    const engine: FakeEngine = new FakeEngine({
+      recordedSize: { width: 1200, height: 900 },
+    });
+    const scales: Array<number> = [];
+
+    render(
+      <ReplayStage
+        engine={engine}
+        fit="width"
+        onScaleChange={(scale: number): void => {
+          scales.push(scale);
+        }}
+      />,
+    );
+
+    sizeElement(stageElement(), 600, 300);
+
+    act((): void => {
+      window.dispatchEvent(new Event("resize"));
+    });
+
+    /* Width alone decides the scale; the 900px-tall page then scrolls. */
+    expect(engine.host.style.transform).toBe("scale(0.5)");
+    expect(scales[scales.length - 1]).toBe(0.5);
+
+    const frame: HTMLElement = frameElement();
+
+    /* In flow, so the box's scroll area is the frame's own height. */
+    expect(frame.style.position).toBe("relative");
+    expect(frame.style.left).toBe("0px");
+    expect(frame.style.top).toBe("0px");
+    expect(frame.style.width).toBe("600px");
+    expect(frame.style.height).toBe("450px");
+  });
+
+  it("centres a short recording vertically under width fit", () => {
+    const engine: FakeEngine = new FakeEngine({
+      recordedSize: { width: 1200, height: 900 },
+    });
+
+    render(<ReplayStage engine={engine} fit="width" />);
+
+    sizeElement(stageElement(), 600, 1000);
+
+    act((): void => {
+      window.dispatchEvent(new Event("resize"));
+    });
+
+    /* 450px of picture in a 1000px box: (1000 - 450) / 2. */
+    expect(frameElement().style.top).toBe("275px");
+    expect(frameElement().style.height).toBe("450px");
+  });
+
+  it("keeps the phone frame's ring inside the box when contain-fitting", () => {
+    const engine: FakeEngine = new FakeEngine({
+      recordedSize: { width: 375, height: 812 },
+    });
+
+    render(<ReplayStage engine={engine} />);
+
+    sizeElement(stageElement(), 200, 400);
+
+    act((): void => {
+      window.dispatchEvent(new Event("resize"));
+    });
+
+    const ring: number = REPLAY_STAGE_PHONE_RING_PX;
+    const inset: number = computeContainScale(200 - 2 * ring, 400 - 2 * ring, {
+      width: 375,
+      height: 812,
+    });
+
+    expect(stageElement()).toHaveAttribute("data-replay-frame", "phone");
+    /* The ring is drawn OUTSIDE the frame, so the fit reserves it. */
+    expect(engine.host.style.transform).toBe(`scale(${inset})`);
+    expect(inset).toBeLessThan(
+      computeContainScale(200, 400, { width: 375, height: 812 }),
+    );
+    expect(frameElement().style.top).toBe(`${ring}px`);
+    expect(
+      Number.parseInt(frameElement().style.left, 10),
+    ).toBeGreaterThanOrEqual(ring);
   });
 
   it("shows the recording at 1:1 in a scroll box when fit is actual", () => {
@@ -548,6 +702,205 @@ describe("ReplayStage sizing", () => {
     expect(stageElement().className).toContain("overflow-auto");
     expect(engine.host.style.transform).toBe("");
     expect(frameElement().style.width).toBe("1200px");
+    expect(frameElement().style.position).toBe("relative");
+    expect(frameElement().style.margin).toBe("");
+  });
+});
+
+describe("computeReplayStageFrameGeometry", () => {
+  const desktop: { width: number; height: number } = {
+    width: 1200,
+    height: 900,
+  };
+
+  it("centres a contain-fitted picture in the box and letterboxes the rest", () => {
+    const geometry: ReplayStageFrameGeometry = computeReplayStageFrameGeometry({
+      fit: "contain",
+      box: { width: 600, height: 300 },
+      recorded: desktop,
+      isPhoneFrame: false,
+    });
+
+    expect(geometry.scale).toBeCloseTo(1 / 3, 6);
+    expect(geometry).toMatchObject({
+      position: "absolute",
+      left: 100,
+      top: 0,
+      width: 400,
+      height: 300,
+      margin: 0,
+    });
+  });
+
+  it("reserves the phone ring on every side of a contain-fitted phone frame", () => {
+    const phone: { width: number; height: number } = {
+      width: 375,
+      height: 812,
+    };
+    const ring: number = REPLAY_STAGE_PHONE_RING_PX;
+    const geometry: ReplayStageFrameGeometry = computeReplayStageFrameGeometry({
+      fit: "contain",
+      box: { width: 200, height: 400 },
+      recorded: phone,
+      isPhoneFrame: true,
+    });
+
+    expect(geometry.scale).toBeCloseTo(
+      computeContainScale(200 - 2 * ring, 400 - 2 * ring, phone),
+      6,
+    );
+    expect(geometry.top).toBe(ring);
+    expect(geometry.left).toBeGreaterThanOrEqual(ring);
+    expect(geometry.height).toBeLessThanOrEqual(400 - 2 * ring);
+    expect(geometry.width).toBeLessThanOrEqual(200 - 2 * ring);
+  });
+
+  it("does not inset a box too small to hold the ring at all", () => {
+    const geometry: ReplayStageFrameGeometry = computeReplayStageFrameGeometry({
+      fit: "contain",
+      box: { width: 10, height: 10 },
+      recorded: { width: 375, height: 812 },
+      isPhoneFrame: true,
+    });
+
+    /* Centred, but with no ring reserved: insetting would leave nothing. */
+    expect(geometry.left).toBeLessThan(REPLAY_STAGE_PHONE_RING_PX);
+    expect(geometry.top).toBe(0);
+    expect(geometry.scale).toBeCloseTo(
+      computeContainScale(10, 10, { width: 375, height: 812 }),
+      6,
+    );
+  });
+
+  it("scales width-fit on the width alone and lets the height overflow", () => {
+    const geometry: ReplayStageFrameGeometry = computeReplayStageFrameGeometry({
+      fit: "width",
+      box: { width: 600, height: 300 },
+      recorded: desktop,
+      isPhoneFrame: false,
+    });
+
+    expect(geometry).toEqual({
+      scale: 0.5,
+      position: "relative",
+      left: 0,
+      top: 0,
+      width: 600,
+      height: 450,
+      margin: 0,
+    });
+  });
+
+  it("centres a width-fitted picture that is shorter than the box", () => {
+    expect(
+      computeReplayStageFrameGeometry({
+        fit: "width",
+        box: { width: 600, height: 1000 },
+        recorded: desktop,
+        isPhoneFrame: false,
+      }).top,
+    ).toBe(275);
+  });
+
+  it("keeps room around an in-flow phone frame so its ring is not clipped", () => {
+    const ring: number = REPLAY_STAGE_PHONE_RING_PX;
+    const width: ReplayStageFrameGeometry = computeReplayStageFrameGeometry({
+      fit: "width",
+      box: { width: 200, height: 400 },
+      recorded: { width: 375, height: 812 },
+      isPhoneFrame: true,
+    });
+
+    expect(width.margin).toBe(ring);
+    expect(width.scale).toBeCloseTo((200 - 2 * ring) / 375, 6);
+    expect(width.width).toBe(200 - 2 * ring);
+
+    const actual: ReplayStageFrameGeometry = computeReplayStageFrameGeometry({
+      fit: "actual",
+      box: { width: 200, height: 400 },
+      recorded: { width: 375, height: 812 },
+      isPhoneFrame: true,
+    });
+
+    expect(actual).toEqual({
+      scale: 1,
+      position: "relative",
+      left: 0,
+      top: 0,
+      width: 375,
+      height: 812,
+      margin: ring,
+    });
+  });
+
+  it("draws 1:1 at the recorded size whatever the box is", () => {
+    for (const box of [null, { width: 100, height: 100 }]) {
+      expect(
+        computeReplayStageFrameGeometry({
+          fit: "actual",
+          box: box,
+          recorded: desktop,
+          isPhoneFrame: false,
+        }),
+      ).toMatchObject({ scale: 1, width: 1200, height: 900, margin: 0 });
+    }
+  });
+
+  it("falls back to 16 / 9 at 1:1 while nothing is known", () => {
+    for (const fit of ["contain", "width", "actual"] as Array<ReplayStageFit>) {
+      const geometry: ReplayStageFrameGeometry =
+        computeReplayStageFrameGeometry({
+          fit: fit,
+          box: null,
+          recorded: null,
+          isPhoneFrame: false,
+        });
+
+      expect(geometry.scale).toBe(1);
+      expect(geometry.width).toBe(16);
+      expect(geometry.height).toBe(9);
+      expect(geometry.left).toBe(0);
+      expect(geometry.top).toBe(0);
+    }
+  });
+
+  it("keeps a measured-as-zero box (jsdom, display:none) at 1:1", () => {
+    expect(
+      computeReplayStageFrameGeometry({
+        fit: "contain",
+        box: { width: 0, height: 0 },
+        recorded: desktop,
+        isPhoneFrame: false,
+      }),
+    ).toMatchObject({ scale: 1, width: 1200, height: 900, left: 0, top: 0 });
+  });
+});
+
+describe("computeWidthScale", () => {
+  it("spans the box's width, up or down", () => {
+    expect(computeWidthScale(600, { width: 1200, height: 900 })).toBe(0.5);
+    expect(computeWidthScale(1500, { width: 375, height: 812 })).toBe(4);
+  });
+
+  it("stays at 1:1 when either side is unknown", () => {
+    expect(computeWidthScale(0, { width: 1200, height: 900 })).toBe(1);
+    expect(computeWidthScale(-10, { width: 1200, height: 900 })).toBe(1);
+    expect(computeWidthScale(600, { width: 0, height: 900 })).toBe(1);
+  });
+});
+
+describe("formatReplayStageAspect", () => {
+  it("formats the recorded size for the aspect-ratio variable", () => {
+    expect(formatReplayStageAspect({ width: 1200, height: 760 })).toBe(
+      "1200 / 760",
+    );
+  });
+
+  it("falls back to 16 / 9 before any size is known", () => {
+    expect(formatReplayStageAspect(null)).toBe("16 / 9");
+    expect(formatReplayStageAspect(undefined)).toBe("16 / 9");
+    expect(formatReplayStageAspect({ width: 0, height: 900 })).toBe("16 / 9");
+    expect(formatReplayStageAspect({ width: 1200, height: 0 })).toBe("16 / 9");
   });
 });
 
@@ -1281,7 +1634,10 @@ describe("ReplayStage device frame and touch", () => {
     render(<ReplayStage engine={engine} />);
 
     expect(stageElement()).toHaveAttribute("data-replay-frame", "phone");
-    expect(frameElement().className).toContain("ring-8");
+    /* The reserved inset and the drawn ring are the same 8px. */
+    expect(frameElement().className).toContain(
+      `ring-${REPLAY_STAGE_PHONE_RING_PX}`,
+    );
   });
 
   it("draws the plain frame for a desktop recording, and lets the prop override it", () => {
@@ -1320,10 +1676,19 @@ describe("ReplayStage device frame and touch", () => {
     const ring: HTMLElement | null = document.querySelector(
       '[data-testid="replay-touch-ring"]',
     );
+    /*
+     * A 400px-wide recording wears the phone frame, so the contain fit
+     * reserves the ring and the touch lands at THAT scale.
+     */
+    const scale: number = computeContainScale(
+      200 - 2 * REPLAY_STAGE_PHONE_RING_PX,
+      400 - 2 * REPLAY_STAGE_PHONE_RING_PX,
+      { width: 400, height: 800 },
+    );
 
     expect(ring).not.toBeNull();
-    expect(ring?.style.left).toBe("50px");
-    expect(ring?.style.top).toBe("100px");
+    expect(ring?.style.left).toBe(`${Math.round(100 * scale)}px`);
+    expect(ring?.style.top).toBe(`${Math.round(200 * scale)}px`);
 
     act((): void => {
       jest.advanceTimersByTime(800);
@@ -1333,6 +1698,34 @@ describe("ReplayStage device frame and touch", () => {
       document.querySelector('[data-testid="replay-touch-ring"]'),
     ).toBeNull();
   });
+
+  it("places the touch ring at the width-fit scale, not the contain one", () => {
+    const engine: FakeEngine = new FakeEngine({
+      recordedSize: { width: 400, height: 800 },
+    });
+
+    /* isMobile=false: no phone ring to reserve, so the width is the width. */
+    render(<ReplayStage engine={engine} fit="width" isMobile={false} />);
+
+    /* Width fit draws this recording at 1:1; contain would be a quarter. */
+    sizeElement(stageElement(), 400, 200);
+
+    act((): void => {
+      window.dispatchEvent(new Event("resize"));
+    });
+
+    act((): void => {
+      engine.emitReplayer({ type: "touch", x: 100, y: 200 });
+    });
+
+    const ring: HTMLElement | null = document.querySelector(
+      '[data-testid="replay-touch-ring"]',
+    );
+
+    expect(engine.host.style.transform).toBe("");
+    expect(ring?.style.left).toBe("100px");
+    expect(ring?.style.top).toBe("200px");
+  });
 });
 
 describe("ReplayStage cursor", () => {