@hyperframes/studio 0.8.122 → 0.8.124

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.122",
+  "version": "0.8.124",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/parsers": "0.8.122",
-    "@hyperframes/sdk": "0.8.122",
-    "@hyperframes/core": "0.8.122",
-    "@hyperframes/shader-transitions": "0.8.122",
-    "@hyperframes/studio-server": "0.8.122",
-    "@hyperframes/player": "0.8.122"
+    "@hyperframes/core": "0.8.124",
+    "@hyperframes/player": "0.8.124",
+    "@hyperframes/sdk": "0.8.124",
+    "@hyperframes/parsers": "0.8.124",
+    "@hyperframes/shader-transitions": "0.8.124",
+    "@hyperframes/studio-server": "0.8.124"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -81,7 +81,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.122"
+    "@hyperframes/producer": "0.8.124"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/FrameyGlyph.tsx

@@ -0,0 +1,52 @@
+import type { Ref } from "react";
+
+// Framey, the desktop app's cursor mascot, as hyperframes-internal packages/nib draws it: a rounded triangle with a
+// white rim and one eye. The viewBox frames the body with its rim; the tip points up and left like a cursor.
+const BODY = "M77.55 48.44 L122.77 65.85 L99.3 89.41 Z";
+const EYE = { cx: 111.6, cy: 68.2, r: 11.5 };
+
+/** `eyeRef` moves the pupils (a translate of a few px) without re-rendering. */
+export function FrameyGlyph({
+  size,
+  className,
+  eyeRef,
+}: {
+  size: number;
+  className?: string;
+  eyeRef?: Ref<SVGGElement>;
+}) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="58 30 82 76"
+      aria-hidden="true"
+      className={className}
+      overflow="visible"
+    >
+      <path
+        d={BODY}
+        fill="var(--color-white)"
+        stroke="var(--color-white)"
+        strokeWidth={24}
+        strokeLinejoin="round"
+      />
+      <path
+        d={BODY}
+        fill="var(--color-framey)"
+        stroke="var(--color-framey)"
+        strokeWidth={19}
+        strokeLinejoin="round"
+      />
+      <circle cx={EYE.cx} cy={EYE.cy} r={EYE.r} fill="var(--color-white)" />
+      <g ref={eyeRef} className="hf-framey-eye">
+        <path
+          d={`M${EYE.cx - 2.6} ${EYE.cy - 2} V${EYE.cy + 2} M${EYE.cx + 2.6} ${EYE.cy - 2} V${EYE.cy + 2}`}
+          stroke="var(--color-framey-ink)"
+          strokeWidth={2.4}
+          strokeLinecap="round"
+        />
+      </g>
+    </svg>
+  );
+}

package/src/components/OpenInDesktopButton.dom.test.tsx

@@ -0,0 +1,130 @@
+// @vitest-environment happy-dom
+
+/**
+ * "Edit with Framey": shown where the preview server has the app or its download to offer; a press opens the project in the app,
+ * or introduces Framey with the download while the app cannot take it or is missing.
+ */
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const showToast = vi.fn();
+vi.mock("../contexts/StudioContext", () => ({ useStudioShellContext: () => ({ showToast }) }));
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
+const { OpenInDesktopButton } = await import("./OpenInDesktopButton");
+
+const DOWNLOAD = "https://hyperframes.dev/studio/download";
+let mounted: { root: Root; host: HTMLElement } | null = null;
+let posts: number;
+
+function serve(get: Response | null, post?: unknown) {
+  posts = 0;
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (_url: string, init?: RequestInit) => {
+      if (init?.method === "POST") {
+        posts += 1;
+        return Response.json(post);
+      }
+      return get ?? new Response("Not found", { status: 404 });
+    }),
+  );
+}
+
+async function mount(): Promise<HTMLElement> {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  mounted = { root, host };
+  await act(async () => root.render(<OpenInDesktopButton />));
+  return host;
+}
+
+const downloadHref = () =>
+  [...document.querySelectorAll("a")]
+    .find((a) => a.textContent?.includes("Get the desktop app"))
+    ?.getAttribute("href");
+
+const button = () =>
+  document.querySelector<HTMLButtonElement>('[data-testid="header-open-in-desktop"]');
+
+beforeEach(() => showToast.mockReset());
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  if (!mounted) return;
+  const { root, host } = mounted;
+  mounted = null;
+  act(() => root.unmount());
+  host.remove();
+});
+
+it("stays hidden where the server has no hand-off (the desktop's own Studio)", async () => {
+  serve(null);
+  await mount();
+  expect(button()).toBeNull();
+});
+
+it("stays hidden when the app has no build for this machine (Windows)", async () => {
+  serve(Response.json({ available: false, handoff: true, downloadUrl: null }));
+  await mount();
+  expect(button()).toBeNull();
+});
+
+it("with the app installed but no download (Windows), shows only once the app can take the project", async () => {
+  serve(Response.json({ available: true, handoff: false, downloadUrl: null }));
+  await mount();
+  expect(button()).toBeNull();
+});
+
+it("opens the project in an installed app that has no download (Windows)", async () => {
+  serve(Response.json({ available: true, handoff: true, downloadUrl: null }), {
+    opened: true,
+    app: "the HyperFrames desktop app",
+  });
+  await mount();
+  await act(async () => button()!.click());
+  expect(posts).toBe(1);
+});
+
+it("while the app cannot take a project yet, introduces Framey with the download and opens nothing", async () => {
+  const linux = `${DOWNLOAD}?os=linux`;
+  serve(Response.json({ available: true, handoff: false, downloadUrl: linux }), { opened: true });
+  await mount();
+  await act(async () => button()!.click());
+  expect(posts).toBe(0);
+  expect(document.body.textContent).toContain("Meet Framey");
+  expect(downloadHref()).toBe(linux);
+});
+
+it("opens the project in the app and says so", async () => {
+  serve(Response.json({ available: true, handoff: true, downloadUrl: DOWNLOAD }), {
+    opened: true,
+    app: "the HyperFrames desktop app",
+  });
+  await mount();
+  await act(async () => button()!.click());
+  expect(posts).toBe(1);
+  expect(showToast).toHaveBeenCalledWith(
+    "Framey is opening this project in the HyperFrames desktop app",
+    "info",
+  );
+  expect(button()!.dataset.opening).toBe("true");
+  expect(document.body.textContent).not.toContain("Meet Framey");
+});
+
+it("introduces Framey and offers the download when the app is missing", async () => {
+  serve(Response.json({ available: true, handoff: true, downloadUrl: DOWNLOAD }), {
+    opened: false,
+    reason: "not-installed",
+    downloadUrl: DOWNLOAD,
+  });
+  await mount();
+  await act(async () => button()!.click());
+  expect(showToast).not.toHaveBeenCalled();
+  expect(document.body.textContent).toContain("Meet Framey");
+  expect(downloadHref()).toBe(DOWNLOAD);
+});

package/src/components/OpenInDesktopButton.tsx

@@ -0,0 +1,160 @@
+import { useEffect, useRef, useState } from "react";
+import { useStudioShellContext } from "../contexts/StudioContext";
+import { studioApiFetch } from "../utils/studioApiFetch";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+import { FrameyGlyph } from "./FrameyGlyph";
+import { Button, buttonBase, buttonSizes, buttonVariants, cn, Popover } from "./ui";
+
+// "Edit with Framey": the preview server (`/api/open-in-desktop`) says whether to show it and whether the app can
+// take the project yet (its gate is the CLI's HANDOFF_READY); until then a press introduces Framey with the download.
+const ROUTE = "/api/open-in-desktop";
+/** How far the pupils travel towards the pointer, in the glyph's own units. */
+const GAZE = 2.2;
+/** Long enough for the flight to finish before the label comes back. */
+const OPENING_MS = 1600;
+
+type OpenResult = { opened: true } | { opened: false; reason: string; downloadUrl: string };
+
+type DesktopRoute = { handoff: boolean; downloadUrl: string | null };
+
+/** Null hides the button: no route (the app's own Studio), or nothing here to open or download. */
+function useDesktopRoute(): DesktopRoute | null {
+  const [route, setRoute] = useState<DesktopRoute | null>(null);
+  useEffect(() => {
+    let live = true;
+    studioApiFetch(ROUTE)
+      .then((res) => (res.ok ? res.json() : null))
+      .then((body: { available?: unknown; handoff?: unknown; downloadUrl?: unknown } | null) => {
+        if (!live || body?.available !== true) return;
+        const handoff = body.handoff === true;
+        const downloadUrl = typeof body.downloadUrl === "string" ? body.downloadUrl : null;
+        if (handoff || downloadUrl) setRoute({ handoff, downloadUrl });
+      })
+      .catch(() => {});
+    return () => {
+      live = false;
+    };
+  }, []);
+  return route;
+}
+
+/** Framey looks at the pointer: one listener, one write per frame, no re-render. */
+function useGaze(
+  anchor: React.RefObject<HTMLElement | null>,
+  eye: React.RefObject<SVGGElement | null>,
+) {
+  useEffect(() => {
+    let frame = 0;
+    const look = (event: PointerEvent) => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(() => {
+        const box = anchor.current?.getBoundingClientRect();
+        if (!box || !eye.current) return;
+        const dx = event.clientX - (box.left + box.height / 2);
+        const dy = event.clientY - (box.top + box.height / 2);
+        const distance = Math.hypot(dx, dy) || 1;
+        eye.current.style.transform = `translate(${(dx / distance) * GAZE}px, ${(dy / distance) * GAZE}px)`;
+      });
+    };
+    window.addEventListener("pointermove", look);
+    return () => {
+      cancelAnimationFrame(frame);
+      window.removeEventListener("pointermove", look);
+    };
+  }, [anchor, eye]);
+}
+
+export function OpenInDesktopButton() {
+  const { showToast } = useStudioShellContext();
+  const route = useDesktopRoute();
+  const [opening, setOpening] = useState(false);
+  // The card under the button, introducing Framey with the app's download.
+  const [downloadUrl, setDownloadUrl] = useState<string | null>(null);
+  const trigger = useRef<HTMLButtonElement>(null);
+  const eye = useRef<SVGGElement>(null);
+  useGaze(trigger, eye);
+  if (!route) return null;
+
+  const open = async () => {
+    if (!route.handoff) {
+      trackStudioEvent("toolbar_action", { action: "open_in_desktop" });
+      setDownloadUrl(route.downloadUrl);
+      return;
+    }
+    if (opening) return;
+    setOpening(true);
+    trackStudioEvent("toolbar_action", { action: "open_in_desktop" });
+    try {
+      const res = await studioApiFetch(ROUTE, { method: "POST" });
+      const result = (await res.json()) as OpenResult;
+      if (result.opened) {
+        showToast("Framey is opening this project in the HyperFrames desktop app", "info");
+        await new Promise((done) => setTimeout(done, OPENING_MS));
+      } else setDownloadUrl(result.downloadUrl);
+    } catch {
+      showToast("Couldn't reach the preview server to open the app", "error");
+    } finally {
+      setOpening(false);
+    }
+  };
+
+  return (
+    <Popover
+      open={downloadUrl !== null}
+      // The popover owns the trigger's press: a press runs the hand-off, and the card shows only when there is
+      // something to say (the download). A second handler on the button raced this one.
+      onOpenChange={(next) => {
+        if (next) void open();
+        else setDownloadUrl(null);
+      }}
+      side="bottom"
+      align="end"
+      arrow
+      aria-label="Meet Framey"
+      className="w-72"
+      trigger={
+        <Button
+          ref={trigger}
+          variant="ghost"
+          data-testid="header-open-in-desktop"
+          data-opening={opening || undefined}
+          title="Open this project in the HyperFrames desktop app and edit it with Framey"
+          className="hf-framey-trigger gap-1.5 border border-accent/40 bg-accent/10 pl-1 font-semibold text-text-0 enabled:hover:bg-accent/20"
+          icon={<FrameyGlyph size={24} className="hf-framey" eyeRef={eye} />}
+        >
+          {opening ? "Opening in the app…" : "Edit with Framey"}
+          {!opening && (
+            <span className="rounded-full bg-accent px-1.5 text-[10px] leading-4 font-bold text-on-accent">
+              New
+            </span>
+          )}
+        </Button>
+      }
+    >
+      <div className="flex items-center gap-2.5">
+        <FrameyGlyph size={36} />
+        <p className="text-step-12 font-medium text-text-0">Meet Framey</p>
+      </div>
+      <p className="mt-2 text-balance text-text-3">I live in the free HyperFrames desktop app:</p>
+      <ul className="mt-1.5 grid gap-1 text-text-1">
+        <li>Chat to change anything in the video</li>
+        <li>Draw on a frame to point at it</li>
+        <li>Watch me act out each edit</li>
+      </ul>
+      <div className="mt-3 flex items-center justify-end gap-2 whitespace-nowrap">
+        <Button variant="ghost" onClick={() => setDownloadUrl(null)}>
+          Not now
+        </Button>
+        <a
+          href={downloadUrl ?? undefined}
+          target="_blank"
+          rel="noopener noreferrer"
+          className={cn(buttonBase, buttonVariants.primary, buttonSizes.md)}
+          onClick={() => trackStudioEvent("toolbar_action", { action: "get_desktop_app" })}
+        >
+          Get the desktop app
+        </a>
+      </div>
+    </Popover>
+  );
+}

package/src/components/StudioHeader.dom.test.tsx

@@ -40,6 +40,8 @@ vi.mock("../contexts/PanelLayoutContext", () => ({
 }));
 
 vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+// Probes the preview server on mount; covered in OpenInDesktopButton.dom.test.tsx.
+vi.mock("./OpenInDesktopButton", () => ({ OpenInDesktopButton: () => null }));
 
 const { StudioHeader } = await import("./StudioHeader");
 const { ShowThemeToggle } = await import("./ThemeToggle");

package/src/components/StudioHeader.tsx

@@ -6,6 +6,7 @@ import { trackStudioEvent } from "../utils/studioTelemetry";
 import { Button, buttonBase, buttonSizes, buttonVariants, cn, Tooltip } from "./ui";
 import { Dock } from "./dock/Dock";
 import { InspectorIcon } from "./icons/InspectorIcon";
+import { OpenInDesktopButton } from "./OpenInDesktopButton";
 import { HyperframesLogo } from "./ui/HyperframesLogo";
 import { ShowThemeToggle, ThemeToggle } from "./ThemeToggle";
 
@@ -151,6 +152,7 @@ export const StudioHeader = memo(function StudioHeader({
         </div>
         {showThemeToggle && <ThemeToggle />}
         <Dock.WindowMenu />
+        <OpenInDesktopButton />
         <Tooltip
           label={
             ffmpegMissing

package/src/player/components/AudibleVideoClipContent.test.tsx

@@ -0,0 +1,67 @@
+// @vitest-environment happy-dom
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { act, type ReactNode } from "react";
+import { compile } from "tailwindcss";
+import { describe, expect, it } from "vitest";
+import { createHappyDomRootHarness } from "./testRootHarness";
+import { AudibleVideoClipContent } from "./AudibleVideoClipContent";
+
+const harness = createHappyDomRootHarness();
+const STYLES_DIR = path.resolve(__dirname, "../../styles");
+const TAILWIND_DIR = path.dirname(
+  createRequire(import.meta.url).resolve("tailwindcss/package.json"),
+);
+
+async function studioCss() {
+  const load = async (id: string, base: string) => {
+    const file =
+      id === "tailwindcss" ? path.join(TAILWIND_DIR, "index.css") : path.resolve(base, id);
+    return { path: file, base: path.dirname(file), content: readFileSync(file, "utf8") };
+  };
+  const compiled = await compile(readFileSync(path.join(STYLES_DIR, "studio.css"), "utf8"), {
+    base: STYLES_DIR,
+    loadStylesheet: load,
+  });
+  return compiled.build([]);
+}
+
+async function renderStrip(wave: ReactNode) {
+  const host = document.createElement("div");
+  document.body.appendChild(host);
+  await act(async () => {
+    harness
+      .mount(host)
+      .render(<AudibleVideoClipContent thumbnail={<span>frames</span>} waveform={wave} />);
+  });
+  return host;
+}
+
+describe("AudibleVideoClipContent", () => {
+  it("draws the sound on the audio clip's own surface, under half the clip", async () => {
+    const host = await renderStrip(<span>wave</span>);
+    const strip = host.querySelector<HTMLElement>('[data-testid="audible-video-wave"]');
+    expect(strip?.textContent).toBe("wave");
+    expect(strip?.style.backgroundColor).toBe("var(--timeline-clip-audio-bg)");
+    expect(strip?.style.height).toBe("50%");
+    expect(strip?.previousElementSibling?.getAttribute("style")).toContain("bottom: 50%");
+  });
+
+  it("keeps only the peak mark in the strip, above the waveform canvas layer", async () => {
+    const style = document.createElement("style");
+    style.textContent = await studioCss();
+    document.head.appendChild(style);
+    const host = await renderStrip(
+      <span data-peak-badge>
+        ▲<span data-peak-text> peaks +0.7 dBFS</span>
+      </span>,
+    );
+    const badge = host.querySelector<HTMLElement>("[data-peak-badge]")!;
+    const text = host.querySelector<HTMLElement>("[data-peak-text]")!;
+    expect(getComputedStyle(text).display).toBe("none");
+    // The waveform canvas sits in a z-index 10 layer (AudioWaveform).
+    expect(Number(getComputedStyle(badge).zIndex)).toBeGreaterThan(10);
+    style.remove();
+  });
+});

package/src/player/components/AudibleVideoClipContent.tsx

@@ -1,7 +1,8 @@
 import type { ReactNode } from "react";
 
-/** Share of the clip height the sound strip takes under a video's thumbnails. */
-const AUDIBLE_VIDEO_WAVE_SHARE = 0.38;
+/** Share of the clip height the sound strip takes under a video's thumbnails: tall enough for the bars to read. */
+const AUDIBLE_VIDEO_WAVE_SHARE = 0.5;
+const AUDIO_CLIP_SURFACE = "var(--timeline-clip-audio-bg)";
 
 /** A video that carries sound: thumbnails on top, its waveform strip along the bottom. */
 export function AudibleVideoClipContent({
@@ -18,9 +19,9 @@ export function AudibleVideoClipContent({
         {thumbnail}
       </div>
       <div
-        className="absolute inset-x-0 bottom-0 bg-black/30"
+        className="audible-video-wave absolute inset-x-0 bottom-0"
         data-testid="audible-video-wave"
-        style={{ height: waveHeight }}
+        style={{ height: waveHeight, backgroundColor: AUDIO_CLIP_SURFACE }}
       >
         {waveform}
       </div>

package/src/player/components/AudioWaveform.tsx

@@ -26,6 +26,7 @@ const BAR_STEP = 3;
 
 export const rendersWaveform = (el: { tag: string }) => el.tag === "audio";
 const FADE_GHOST_OPACITY = 0.27;
+export const WAVEFORM_LAYER_Z = 10;
 
 type BarGeometry = { x: number; width: number; height: number; gain: number };
 
@@ -236,7 +237,7 @@ export const AudioWaveform = memo(function AudioWaveform({
 
   return (
     <div ref={rootRef} className="absolute inset-0">
-      <div className="absolute inset-0 overflow-hidden" style={{ zIndex: 10 }}>
+      <div className="absolute inset-0 overflow-hidden" style={{ zIndex: WAVEFORM_LAYER_Z }}>
         <canvas
           ref={setCanvasRef}
           className="absolute inset-x-0 bottom-0 w-full"

package/src/player/components/ClipPeakMarks.tsx

@@ -49,8 +49,11 @@ export function ClipPeakMarks({
               }}
             />
           ))}
-          <span className="absolute top-0 right-1 font-mono text-[9px] leading-none text-red-400">
-            ▲ peaks {dbText(peakDbfs)}
+          <span
+            className="absolute top-0 right-1 font-mono text-[9px] leading-none text-red-400"
+            data-peak-badge
+          >
+            ▲<span data-peak-text> peaks {dbText(peakDbfs)}</span>
           </span>
         </div>
       )}

package/src/player/components/OutOfSyncBadge.tsx

@@ -105,7 +105,7 @@ export const OutOfSyncBadge = memo(function OutOfSyncBadge({ el }: { el: Timelin
         aria-label={`Out of sync with ${partnerName} by ${label} frames`}
         title={`Out of sync with ${partnerName} by ${label} — click for Move or Slip into Sync`}
         data-testid="out-of-sync-badge"
-        className="absolute bottom-0.5 left-1 z-[7] cursor-pointer rounded-[3px] bg-red-600 px-1 font-mono text-[9px] leading-[14px] text-white tabular-nums"
+        className="absolute bottom-0.5 left-1 z-[12] cursor-pointer rounded-[3px] bg-red-600 px-1 font-mono text-[9px] leading-[14px] text-white tabular-nums"
         onPointerDown={stop}
         onDoubleClick={stop}
         onClick={open}

package/src/player/components/Timeline.trackPadding.test.tsx

@@ -99,9 +99,7 @@ describe("Timeline trackPadding", () => {
     const clip = host.querySelector('[data-clip][data-el-id="c0"]')!;
     pointer(clip, "pointerdown", RULER_H + TRACK_H / 2);
     pointer(window, "pointermove", ROW1_MID);
-    const ghost = Array.from(
-      host.querySelectorAll<HTMLElement>(".absolute.pointer-events-none"),
-    ).find((el) => el.style.zIndex === "30" && !el.dataset.testid);
+    const ghost = host.querySelector<HTMLElement>('[data-testid="timeline-drag-landing"]');
     expect(top(ghost)).toBe(`${RULER_H + TRACK_H + CLIP_Y}px`);
     pointer(window, "pointermove", RULER_H + 3 * TRACK_H + TRACK_H / 2);
     const lane = host.querySelector<HTMLElement>("[data-timeline-new-track-lane]");

package/src/player/components/TimelineCanvas.tsx

@@ -134,6 +134,7 @@ export const TimelineCanvas = memo(function TimelineCanvas() {
           lane + snapped start), parallel to the ghost. Hidden in insert mode. */}
       {draggedClip?.started && draggedClip.insertRow == null && draggedRowIndex >= 0 && (
         <div
+          data-testid="timeline-drag-landing"
           className="absolute pointer-events-none"
           style={{
             top: props.rowGeometry.getRowTop(draggedRowIndex) + CLIP_Y,

package/src/player/components/TimelineClip.filmstrip.test.tsx

@@ -6,6 +6,7 @@ import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 import { loadStylesheet, STYLES_DIR } from "../../styles/styleSources";
 import { cleanupMounted, trackedRoot } from "../../components/ui/mountHost.testHelpers";
 import { TimelineClip } from "./TimelineClip";
+import { WAVEFORM_LAYER_Z } from "./AudioWaveform";
 import { renderClipChildren } from "./timelineClipChildren";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 
@@ -23,6 +24,7 @@ beforeAll(async () => {
 afterEach(() => {
   cleanupMounted();
   usePlayerStore.getState().setLintFindingsByElement(new Map());
+  usePlayerStore.getState().setElements([]);
   document.body.innerHTML = "";
 });
 
@@ -153,4 +155,29 @@ describe("Filmstrip clips", () => {
     );
     expect(css).toMatch(/\.timeline-clip:not\(\.is-audio\)\s*\{\s*border-width:\s*0;/);
   });
+
+  const audioPillZ = () =>
+    Number(
+      css.match(/\.timeline-clip\.is-audio \.timeline-clip__label\s*\{[^}]*z-index:\s*(\d+)/)?.[1],
+    );
+
+  it("draws an audio clip's name pill over its waveform", () => {
+    expect(audioPillZ()).toBeGreaterThan(WAVEFORM_LAYER_Z);
+  });
+
+  it("keeps the out-of-sync badge over the audio name pill", () => {
+    const audio = {
+      id: "clip",
+      domId: "clip",
+      label: "City",
+      tag: "audio",
+      start: 1.7,
+      duration: 4,
+    };
+    const synced = { ...audio, track: 1, playbackStart: 0, syncOrigin: "lk-1" };
+    const video = { ...synced, id: "talk", domId: "talk", tag: "video", start: 1, track: 0 };
+    usePlayerStore.getState().setElements([video, synced]);
+    const badge = render("audio", synced, false).querySelector('[data-testid="out-of-sync-badge"]');
+    expect(Number(badge?.className.match(/\bz-\[(\d+)\]/)?.[1])).toBeGreaterThan(audioPillZ());
+  });
 });

package/src/player/components/TimelineClipFades.test.tsx

@@ -3,6 +3,7 @@
 import React, { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { WAVEFORM_LAYER_Z } from "./AudioWaveform";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { TimelineClipFades, useClipFadeDraft } from "./TimelineClipFades";
 import { TimelineEditProvider } from "../../contexts/TimelineEditContext";
@@ -298,7 +299,7 @@ describe("TimelineClipFades", () => {
   it("paints the handles above the clip's waveform and thumbnail layers", () => {
     const { host } = render(clip);
     const layer = host.querySelector<HTMLElement>('[data-testid="clip"]')?.firstElementChild;
-    expect(Number((layer as HTMLElement).style.zIndex)).toBeGreaterThan(10);
+    expect(Number((layer as HTMLElement).style.zIndex)).toBeGreaterThan(WAVEFORM_LAYER_Z);
   });
 
   it("splits a clip narrower than two targets between the handles", () => {

package/src/player/components/timelineClipDragPreview.test.ts

@@ -321,6 +321,20 @@ describe("guideIfSaved — a guide only where the clip saves", () => {
     expect(guideIfSaved(el, { start: 2.217 }, edge, 1440)).toBeNull();
   });
 
+  it("keeps the pointer's start when a move's snap would save off the target", () => {
+    // 1440 px/s: a 31/30 s clip whose end snaps to 3.25s would save at 2.22s and jump 4px on release.
+    const el = clip("a", 0, 1, 31 / 30, 0, "div");
+    const { drag } = horizontalDrag(el, 0.5, 0);
+    const context = {
+      ...ctx(undefined, [el]),
+      pps: 1440,
+      buildSnapTargets: () => [{ time: 3.25, type: "clip-edge" as const }],
+    };
+    const x = drag.originClientX + 1.22 * 1440;
+    const next = computeDragPreview(drag, x, drag.originClientY, context);
+    expect(next).toMatchObject({ previewStart: 2.22, snapTime: null, snapType: null });
+  });
+
   it("draws no guide for a move whose saved start misses the target", () => {
     const nested = { ...moodboard, parentCompositionStart: 1 / 30 };
     const { drag } = horizontalDrag(nested, 0.5, 0);
@@ -388,6 +402,23 @@ describe("computeResizePreview — composition source continuity", () => {
     expect(result).toMatchObject({ previewStart: 1.03, snapTime: null, snapType: null });
   });
 
+  it("keeps the pointer's end when a tail snap would save off the target", () => {
+    // 1440 px/s: snapping 1.125s + 2.12s to 3.25s needs a 2.125s duration, which saves 7px off.
+    const result = computeResizePreview(
+      {
+        element: clip("a", 0, 1.125, 2, 0, "div"),
+        edge: "end",
+        originClientX: 0,
+        previewStart: 1.125,
+        previewDuration: 2,
+        started: true,
+      },
+      173,
+      { scroll: fakeScroll(), pps: 1440, buildSnapTargets: () => [{ time: 3.25, type: "grid" }] },
+    );
+    expect(result).toMatchObject({ previewDuration: 2.12, snapTime: null, snapType: null });
+  });
+
   it("does not let a tail snap shrink a clip below the drag's minimum duration", () => {
     const result = computeResizePreview(
       {