@hyperframes/studio 0.8.10 → 0.8.12

package/src/hooks/useRemoveBackground.ts

@@ -0,0 +1,70 @@
+import { useCallback, useEffect, useRef } from "react";
+import { waitForMediaJob } from "../components/studioMediaJobs";
+import type { BackgroundRemovalProgress } from "../components/editor/propertyPanelTypes";
+
+interface RemoveBackgroundOptions {
+  createBackgroundPlate?: boolean;
+  quality?: "fast" | "balanced" | "best";
+  onProgress?: (progress: BackgroundRemovalProgress) => void;
+}
+
+/**
+ * One removal in flight at a time: starting a second one aborts whichever job
+ * is still running, so a stale progress callback can't overwrite a newer
+ * result. Unmounting aborts too, or the job would keep running against a
+ * panel that is no longer there to show its progress.
+ */
+export function useRemoveBackground(
+  projectId: string,
+  refreshFileTree: () => Promise<void>,
+  showToast: (message: string, kind?: "info" | "error") => void,
+) {
+  const abortRef = useRef<AbortController | null>(null);
+
+  useEffect(
+    () => () => {
+      abortRef.current?.abort();
+    },
+    [],
+  );
+
+  return useCallback(
+    // fallow-ignore-next-line complexity
+    async (inputPath: string, options: RemoveBackgroundOptions) => {
+      const response = await fetch(
+        `/api/projects/${encodeURIComponent(projectId)}/media/remove-background`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            inputPath,
+            createBackgroundPlate: options.createBackgroundPlate === true,
+            quality: options.quality ?? "balanced",
+          }),
+        },
+      );
+      const data = (await response.json().catch(() => ({}))) as {
+        jobId?: string;
+        error?: string;
+      };
+      if (!response.ok || !data.jobId) {
+        throw new Error(data.error || `Background removal failed (${response.status})`);
+      }
+      showToast("Removing background...", "info");
+      abortRef.current?.abort();
+      const controller = new AbortController();
+      abortRef.current = controller;
+      try {
+        const result = await waitForMediaJob(data.jobId, options.onProgress, controller.signal);
+        await refreshFileTree();
+        showToast(`Created transparent asset: ${result.outputPath.split("/").pop()}`, "info");
+        return result;
+      } finally {
+        if (abortRef.current === controller) {
+          abortRef.current = null;
+        }
+      }
+    },
+    [projectId, refreshFileTree, showToast],
+  );
+}

package/src/hooks/useTimelineEditing.ts

@@ -20,25 +20,21 @@ import {
   syncPreviewContentDuration,
 } from "./timelineTimingSync";
 import type { PersistTimelineEditInput } from "./timelineEditingHelpers";
-import type { TimelineStackingReorderIntent } from "../player/components/timelineEditing";
 import { useSetAudioGroupAttribute } from "./timelineAudioGroupVolume";
-import { useTimelineDeleteOps } from "./useTimelineDeleteOps";
 import { useSetElementAttribute } from "./timelineElementFxAttribute";
+import { useTimelineDeleteOps } from "./useTimelineDeleteOps";
+import { useAudioGroupCarveAssignment } from "./timelineAudioGroupCreate";
 import {
-  useAudioGroupCarveAssignment,
   useTimelineElementVisibilityEditing,
   useTimelineTrackVisibilityEditing,
 } from "./timelineTrackVisibility";
 import { useTimelineGroupEditing } from "./useTimelineGroupEditing";
+import { useBlockedTimelineEditToast } from "./useBlockedTimelineEditToast";
 import { serializeZLaneGesture } from "../components/nle/zLaneGesture";
 import { cutoverCommittedOrThrow, sdkTimingPersist } from "../utils/sdkCutover";
-import type { UseTimelineEditingOptions } from "./useTimelineEditingTypes";
+import type { TimelineMoveUpdates, UseTimelineEditingOptions } from "./useTimelineEditingTypes";
 import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";
 
-type TimelineMoveUpdates = Pick<TimelineElement, "start" | "track"> & {
-  stackingReorder?: TimelineStackingReorderIntent | null;
-};
-
 export function useTimelineEditing({
   projectId,
   activeCompPath,
@@ -61,9 +57,7 @@ export function useTimelineEditing({
 }: UseTimelineEditingOptions) {
   const projectIdRef = useRef(projectId);
   projectIdRef.current = projectId;
-
   const editQueueRef = useRef(Promise.resolve());
-  const lastBlockedTimelineToastAtRef = useRef(0);
 
   const enqueueEdit = useCallback(
     (
@@ -451,15 +445,7 @@ export function useTimelineEditing({
       observeProjectFileVersion,
     });
 
-  const handleBlockedTimelineEdit = useCallback(
-    (_element: TimelineElement) => {
-      const now = Date.now();
-      if (now - lastBlockedTimelineToastAtRef.current < 1500) return;
-      lastBlockedTimelineToastAtRef.current = now;
-      showToast("This clip can't be moved or resized from the timeline yet.", "info");
-    },
-    [showToast],
-  );
+  const handleBlockedTimelineEdit = useBlockedTimelineEditToast(showToast);
 
   const { handleRazorSplit, handleRazorSplitAll } = useRazorSplit({
     projectId,

package/src/hooks/useTimelineEditingTypes.ts

@@ -1,6 +1,7 @@
 import type { MutableRefObject, RefObject } from "react";
 import type { Composition } from "@hyperframes/sdk";
 import type { TimelineElement } from "../player";
+import type { TimelineStackingReorderIntent } from "../player/components/timelineEditing";
 import type { EditHistoryKind } from "../utils/editHistory";
 import type { PublishSdkSession } from "../utils/sdkCutover";
 
@@ -55,3 +56,9 @@ export type TimelineFileDropHandler = (
   files: File[],
   placement?: { start: number; track: number },
 ) => Promise<void>;
+
+/** What a timeline move commits: the new start and track, plus the z-index
+ *  reorder a vertical drag resolves to (absent for a pure horizontal move). */
+export type TimelineMoveUpdates = Pick<TimelineElement, "start" | "track"> & {
+  stackingReorder?: TimelineStackingReorderIntent | null;
+};

package/src/player/components/AutomationSelectionMenu.tsx

@@ -41,6 +41,10 @@ export const AutomationSelectionMenu = memo(function AutomationSelectionMenu({
   return createPortal(
     <div
       ref={menuRef}
+      // z-[200] for the same reason the timeline's FX popover uses it: this is
+      // portaled to `document.body`, but the ruler's sticky header sits at z-70
+      // in the SAME root stacking context, so a z-50 menu opened near the top of
+      // the timeline is painted through by the ruler and the playhead.
       className="hf-automation-menu fixed z-[200] min-w-[140px] rounded border border-panel-border-input bg-panel-bg-2 py-1 shadow-lg"
       style={{ left: adjustedX, top: adjustedY }}
     >

package/src/player/components/LayerDisclosureRow.tsx

@@ -1,11 +1,56 @@
 import { TRACK_H } from "./timelineLayout";
 import { TrackClipCount } from "./TrackClipCount";
 
-// Layer row (Figma order: disclosure ∿, diamond, name) — the disclosure lives
+// Layer row (diamond, name, then the ∿ disclosure on the right edge) — the
+// disclosure lives
 // here, not on the clip bar, and re-expands a collapsed layer. `∿` (not a
 // caret) because a group's own row keeps the caret for its structural
 // disclosure (member rows) — this button only ever means "show this row's
 // lanes", so it needs its own distinct glyph.
+/**
+ * The `∿` that shows or hides a row's lanes.
+ *
+ * Shared, because two layouts need the identical control: the keyframe layer
+ * row below, and the plain track header — an audio track with automation keeps
+ * its own look (music glyph, indent) and gains this, rather than being
+ * re-rendered as a keyframe layer to get at the button.
+ */
+export function LaneToggleButton({
+  name,
+  isExpanded,
+  lanesId,
+  onToggle,
+}: {
+  name: string;
+  isExpanded: boolean;
+  lanesId: string;
+  onToggle: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      // ponytail: No focus id here; keyboard routing belongs to the enclosing logical row.
+      tabIndex={-1}
+      aria-expanded={isExpanded}
+      aria-controls={lanesId}
+      aria-label={`${isExpanded ? "Hide" : "Show"} ${name} lanes`}
+      title={`${isExpanded ? "Hide" : "Show"} lanes`}
+      // h-6 w-6 = the 24x24 WCAG 2.2 minimum target. The glyph stays 11px;
+      // only the hit box grows.
+      className={`ml-auto flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 text-[11px] leading-none focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC] ${
+        isExpanded ? "text-[#3CE6AC]" : "text-white/55 hover:text-white"
+      }`}
+      onPointerDown={(event) => event.stopPropagation()}
+      onClick={(event) => {
+        event.stopPropagation();
+        onToggle();
+      }}
+    >
+      <span aria-hidden="true">∿</span>
+    </button>
+  );
+}
+
 export function LayerDisclosureRow({
   name,
   clipCount,
@@ -45,37 +90,26 @@ export function LayerDisclosureRow({
         background: gutterBackground,
       }}
     >
-      <button
-        type="button"
-        // ponytail: No focus id here; keyboard routing belongs to the enclosing logical row.
-        tabIndex={-1}
-        aria-expanded={isExpanded}
-        aria-controls={lanesId}
-        aria-label={`${isExpanded ? "Hide" : "Show"} ${name} lanes`}
-        title={`${isExpanded ? "Hide" : "Show"} lanes`}
-        // h-6 w-6 = the 24x24 WCAG 2.2 minimum target. The glyph stays 11px;
-        // only the hit box grows.
-        className={`flex h-6 w-6 shrink-0 items-center justify-center rounded border-0 bg-transparent p-0 text-[11px] leading-none focus-visible:outline focus-visible:outline-1 focus-visible:outline-[#3CE6AC] ${
-          isExpanded ? "text-[#3CE6AC]" : "text-white/55 hover:text-white"
-        }`}
-        onPointerDown={(event) => event.stopPropagation()}
-        onClick={(event) => {
-          event.stopPropagation();
-          onToggleClipExpanded();
-        }}
-      >
-        <span aria-hidden="true">∿</span>
-      </button>
       {/* Decorative: the disclosure button above already names the row's keyframe
           state, and aria-label on a plain span is not exposed reliably anyway. */}
       <span aria-hidden="true" className="shrink-0 text-[13px] leading-none text-white/40">
         ◇
       </span>
-      <span className="min-w-0 flex-1 truncate font-medium" title={name}>
-        {name}
-      </span>
+      {/* Wraps rather than truncating: a truncated name needs a hover to be
+          read, which a scanned column cannot rely on. */}
+      <span className="min-w-0 flex-1 break-words font-medium leading-tight">{name}</span>
       <TrackClipCount clipCount={clipCount} />
       {children}
+      {/* Anchored right, on every header that has one: the lane toggle is the
+          row's last word about itself, and a left-hand ∿ put it where the eye
+          looks for identity instead. `ml-auto` rather than a spacer so it holds
+          the edge whatever else the row grows. */}
+      <LaneToggleButton
+        name={name}
+        isExpanded={isExpanded}
+        lanesId={lanesId}
+        onToggle={onToggleClipExpanded}
+      />
     </div>
   );
 }

package/src/player/components/PlayerControls.tsx

@@ -6,7 +6,6 @@ import { liveTime, usePlayerStore } from "../store/playerStore";
 import { trackStudioEvent } from "../../utils/studioTelemetry";
 import { Tooltip } from "../../components/ui";
 import { useMountEffect } from "../../hooks/useMountEffect";
-import { useSoloBannerText } from "../../hooks/useAudioSoloBridge";
 import { ShortcutsPanel } from "./ShortcutsPanel";
 import { SpeedMenu } from "./SpeedMenu";
 import { VolumeControl } from "./VolumeControl";
@@ -156,47 +155,12 @@ const FullscreenButton = memo(function FullscreenButton({
 
 /* ── Main component ──────────────────────────────────────────────── */
 
-/**
- * "Hearing only this" notice. Solo is a PREVIEW-only gate — it never touches an
- * attribute and never reaches the export — so the state has to say so out loud,
- * or a soloed session reads as a broken mix.
- */
-const SoloBanner = memo(function SoloBanner({
-  previewIframeRef,
-}: {
-  previewIframeRef: { current: HTMLIFrameElement | null };
-}) {
-  const bannerText = useSoloBannerText(previewIframeRef);
-  const clearSolo = usePlayerStore.getState().clearSolo;
-  if (bannerText === null) return null;
-  return (
-    <div
-      role="status"
-      className="flex h-7 items-center justify-center gap-2 border-b border-neutral-800 bg-neutral-900/90 px-3 text-[11px] text-neutral-300"
-    >
-      <span>
-        Hearing only <span className="font-medium text-neutral-100">{bannerText}</span> — your
-        export is not affected
-      </span>
-      <button
-        type="button"
-        onClick={() => clearSolo()}
-        className="rounded px-1.5 py-0.5 font-medium text-studio-accent transition-colors hover:text-white"
-      >
-        Clear
-      </button>
-    </div>
-  );
-});
-
 interface PlayerControlsProps {
   onTogglePlay: () => void;
   onSeek: (time: number) => void;
   disabled?: boolean;
   isFullscreen?: boolean;
   onToggleFullscreen?: () => void;
-  /** Needed to read the soloed clips' labels out of the preview document. */
-  previewIframeRef?: { current: HTMLIFrameElement | null };
 }
 
 export const PlayerControls = memo(function PlayerControls({
@@ -205,7 +169,6 @@ export const PlayerControls = memo(function PlayerControls({
   disabled = false,
   isFullscreen = false,
   onToggleFullscreen,
-  previewIframeRef,
 }: PlayerControlsProps) {
   const isPlaying = usePlayerStore((s) => s.isPlaying);
   const duration = usePlayerStore((s) => s.duration);
@@ -258,7 +221,6 @@ export const PlayerControls = memo(function PlayerControls({
 
   return (
     <div>
-      {previewIframeRef && <SoloBanner previewIframeRef={previewIframeRef} />}
       <div
         className="grid h-10 grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center px-3"
         aria-disabled={disabled || undefined}

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

@@ -299,6 +299,42 @@ describe("Timeline provider boundary", () => {
     act(() => root.unmount());
   });
 
+  // The same assertion, with a group present. It passed on an empty fixture
+  // while TimelineGroupRow called the THROWING context hook — one grouped clip
+  // and the whole timeline render died, not just the row.
+  it("renders without the provider even when a group row is on screen", () => {
+    const host = createSizedTimelineHost(640);
+    usePlayerStore.setState({
+      duration: 4,
+      timelineReady: true,
+      elements: [
+        {
+          id: "voice-1",
+          domId: "voice-1",
+          tag: "audio",
+          start: 0,
+          duration: 2,
+          track: 0,
+          audioGroup: "voiceover",
+        },
+        {
+          id: "voice-2",
+          domId: "voice-2",
+          tag: "audio",
+          start: 2,
+          duration: 2,
+          track: 1,
+          audioGroup: "voiceover",
+        },
+      ],
+    });
+    const root = createRoot(host);
+    act(() => root.render(React.createElement(Timeline)));
+
+    expect(host.querySelector('[role="treegrid"]')).not.toBeNull();
+    act(() => root.unmount());
+  });
+
   it("renders the complete track list while row virtualization is gated off", () => {
     const host = createSizedTimelineHost(640);
     usePlayerStore.setState({
@@ -389,7 +425,10 @@ describe("Timeline provider boundary", () => {
       button.click();
     });
 
-    const row = button.parentElement?.parentElement;
+    // Up from the rowheader rather than counting parents: the header now lays
+    // its name and its controls out on two lines, so the button sits one level
+    // deeper than it used to.
+    const row = button.closest('[role="rowheader"]')?.parentElement;
     // Row children: [TimelineTrackHeader (sticky column), time-mapped content].
     const trackContent = row?.children.item(1);
     expect(onToggleTrackHidden).toHaveBeenCalledWith(0, false, 1);

package/src/player/components/Timeline.tsx

@@ -33,7 +33,7 @@ import { useTimelinePerformanceTelemetry } from "./useTimelinePerformanceTelemet
 import {
   getEffectiveTimelineDuration,
   getTimelinePreviewElement,
-  hasKeyframedTimelineClips,
+  timelineNeedsLabelColumn,
 } from "./timelineViewModel";
 import { useTimelineSelectionLifecycle } from "./useTimelineSelectionLifecycle";
 import { useTimelineShiftModifier } from "./useTimelineShiftModifier";
@@ -115,7 +115,10 @@ export const Timeline = memo(function Timeline({
   const selectedElementIds = usePlayerStore((s) => s.selectedElementIds);
   const focusedEaseSegment = usePlayerStore((s) => s.focusedEaseSegment);
   const gsapAnimations = usePlayerStore((s) => s.gsapAnimations);
-  const labelMode = useMemo(() => hasKeyframedTimelineClips(gsapAnimations), [gsapAnimations]);
+  const labelMode = useMemo(
+    () => timelineNeedsLabelColumn(gsapAnimations, expandedElements),
+    [gsapAnimations, expandedElements],
+  );
   // The label column provides pre-t=0 space; otherwise keep TRACKS_LEFT_PAD after the gutter.
   const contentOrigin = labelMode ? LABEL_COL_W + GUTTER : GUTTER + TRACKS_LEFT_PAD;
   const contentGutter = labelMode ? GUTTER : 0;

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

@@ -1747,3 +1747,70 @@ describe("TimelineAutomationLane stretch", () => {
     expect(svg.style.cursor).not.toBe("col-resize");
   });
 });
+
+describe("TimelineAutomationLane — a read-only lane offers nothing to grab", () => {
+  /** Hover the lane the way a pointer entering it does. */
+  function hover(container: HTMLElement): SVGSVGElement {
+    const svg = container.querySelector("svg")!;
+    stubBox(svg, { left: 0, top: 0, width: 400, height: 48 });
+    // React implements onPointerEnter through the delegated `pointerover`
+    // event, not a native `pointerenter` — which does not bubble and so never
+    // reaches its listener.
+    fire(svg, "pointerover");
+    return svg as SVGSVGElement;
+  }
+
+  const handles = (container: HTMLElement) =>
+    [...container.querySelectorAll("circle[data-automation-point]")] as SVGCircleElement[];
+
+  // A grab handle raised on hover is an offer, and a carve lane cannot honour
+  // it: the analysis rewrites these envelopes on every run, so a point moved
+  // here is discarded rather than saved. Dimming alone did not say that — the
+  // handles still came up under the cursor and the drag silently did nothing.
+  it("keeps its point handles hidden on hover", () => {
+    const { container } = render(
+      <TimelineAutomationLane
+        {...laneProps({ automation: ramp, readOnly: true, readOnlyNote: "Owned by the carve." })}
+      />,
+    );
+    hover(container);
+    const drawn = handles(container);
+    expect(drawn.length).toBeGreaterThan(0);
+    for (const c of drawn) {
+      expect(c.style.opacity).toBe("0");
+      expect(c.style.cursor).toBe("default");
+    }
+  });
+
+  it("still raises them on an editable lane, so the gate is readOnly and not hover", () => {
+    const { container } = render(<TimelineAutomationLane {...laneProps({ automation: ramp })} />);
+    hover(container);
+    const drawn = handles(container);
+    expect(drawn.length).toBeGreaterThan(0);
+    for (const c of drawn) {
+      expect(c.style.opacity).toBe("1");
+      expect(c.style.cursor).toBe("grab");
+    }
+  });
+
+  it("says why, in the lane, once hovered", () => {
+    const { container } = render(
+      <TimelineAutomationLane
+        {...laneProps({ automation: ramp, readOnly: true, readOnlyNote: "Owned by the carve." })}
+      />,
+    );
+    expect(container.querySelector("[data-automation-readonly-note]")).toBeNull();
+    hover(container);
+    expect(container.querySelector("[data-automation-readonly-note]")?.textContent).toContain(
+      "Owned by the carve.",
+    );
+  });
+
+  it("says nothing when no reason was given", () => {
+    const { container } = render(
+      <TimelineAutomationLane {...laneProps({ automation: ramp, readOnly: true })} />,
+    );
+    hover(container);
+    expect(container.querySelector("[data-automation-readonly-note]")).toBeNull();
+  });
+});

package/src/player/components/TimelineAutomationLane.tsx

@@ -86,6 +86,75 @@ function pointCircleStyle(
 }
 
 /** Pointer shape: a read-only lane can only be selected, a live one edited. */
+/**
+ * Whether a point's grab handle is up.
+ *
+ * A raised handle is an offer to drag, so a read-only lane keeps them down: the
+ * carve rewrites its envelopes from the analysis on every run, and a point
+ * moved here is discarded rather than saved. Hidden rather than unmounted
+ * either way, so the hit area survives — a point dragged past the lane's edge
+ * fires pointerleave mid-gesture, and a handle that vanished then would drop
+ * the drag. A live drag and a selected range both keep them up regardless: the
+ * range is the subject of a pending Delete, and which points it caught cannot
+ * depend on where the mouse is.
+ */
+/** The svg's tooltip: what this lane's gestures actually are. */
+function laneTitle(readOnly: boolean | undefined): string {
+  return readOnly
+    ? "Drag a box to select points, which also selects this clip; then double-click to add a point"
+    : "Double-click to add a point, drag to shape, double-click a point to type a value, right-click or Shift+click to remove it. Drag the background to draw a box around points, then Delete to remove them or drag one to move them all. Alt-drag the line to curve it. Shift locks an axis mid-drag; Alt ignores the grid.";
+}
+
+/**
+ * Why this lane will not take an edit, in the lane itself.
+ *
+ * Dimming and a default cursor say "not editable" but not WHY, and the why is
+ * the part that matters: the carve rewrites these envelopes from its own
+ * analysis on every run, so a point moved here is discarded rather than saved.
+ * Only while hovered, so a stack of read-only lanes is not a stack of notices,
+ * and never over a selection the author is about to act on.
+ *
+ * Separate from the gesture `hint` slot, which belongs to handlers that do not
+ * run on a read-only lane at all.
+ */
+function ReadOnlyNote({
+  readOnly,
+  note,
+  hovered,
+  hasRange,
+  leftPx,
+  widthPx,
+}: {
+  readOnly: boolean | undefined;
+  note: string | undefined;
+  hovered: boolean;
+  /** A selection is the subject of a pending action; do not cover it. */
+  hasRange: boolean;
+  leftPx: number;
+  widthPx: number;
+}) {
+  if (!readOnly || !note || !hovered || hasRange) return null;
+  return (
+    <div
+      data-automation-readonly-note=""
+      className="hf-automation-readonly-note pointer-events-none absolute rounded-[3px] bg-black/85 px-1.5 py-0.5 text-[9px] text-white/80"
+      style={{ left: leftPx + 6, top: 2, zIndex: 3, maxWidth: Math.max(120, widthPx - 12) }}
+    >
+      {note}
+    </div>
+  );
+}
+
+function pointHandleOpacity(args: {
+  readOnly: boolean | undefined;
+  hovered: boolean;
+  dragging: boolean;
+  hasRange: boolean;
+}): number {
+  if (args.dragging || args.hasRange) return 1;
+  return !args.readOnly && args.hovered ? 1 : 0;
+}
+
 function laneCursor(readOnly: boolean | undefined, dragging: boolean, stretching: boolean): string {
   // A stretch handle wins over everything it might also sit above: the handle is
   // a few px wide and always overlaps whatever is under the selection edge, so
@@ -120,6 +189,9 @@ export interface TimelineAutomationLaneProps {
   snapTimes?: readonly number[];
   /** Editing writes to the selected element, so an unselected clip is read-only. */
   readOnly?: boolean;
+  /** Why `readOnly`, shown in the lane on hover. Without it the lane only looks
+   *  disabled; the author still has to guess what would let them edit it. */
+  readOnlyNote?: string;
   /** Called when a read-only lane is pressed: selects the clip so it goes live. */
   onSelect?(): void;
   /** Active selection box on THIS lane, or null. */
@@ -142,6 +214,7 @@ export function TimelineAutomationLane({
   onCommit,
   snapTimes,
   readOnly,
+  readOnlyNote,
   onSelect,
   rangeSelection,
   onRangeSelect,
@@ -372,11 +445,7 @@ export function TimelineAutomationLane({
         role="group"
         aria-label={`${range.label} automation`}
       >
-        <title>
-          {readOnly
-            ? "Drag a box to select points, which also selects this clip; then double-click to add a point"
-            : "Double-click to add a point, drag to shape, double-click a point to type a value, right-click or Shift+click to remove it. Drag the background to draw a box around points, then Delete to remove them or drag one to move them all. Alt-drag the line to curve it. Shift locks an axis mid-drag; Alt ignores the grid."}
-        </title>
+        <title>{laneTitle(readOnly)}</title>
         {/* No plate behind the envelope: the lane used to darken its clip's width,
             which drew a box inside the row and made a stack of lanes read as tiles
             rather than as rows of one timeline. The row background shows through, and
@@ -433,15 +502,14 @@ export function TimelineAutomationLane({
               fill={accentColor}
               stroke={stroke}
               strokeWidth={strokeWidth}
-              // Hidden rather than unmounted, so the hit area survives: a point
-              // dragged past the lane's edge fires pointerleave mid-gesture, and a
-              // handle that vanishes then would drop the drag. A drag in progress
-              // and a selected range both keep them up for the same reason — the
-              // range is the subject of a pending Delete, and which points it
-              // caught cannot depend on where the mouse is.
               style={{
                 cursor: readOnly ? "default" : "grab",
-                opacity: hovered || dragIndex !== null || rangeSelection ? 1 : 0,
+                opacity: pointHandleOpacity({
+                  readOnly,
+                  hovered,
+                  dragging: dragIndex !== null,
+                  hasRange: Boolean(rangeSelection),
+                }),
               }}
               onContextMenu={(e) => {
                 e.preventDefault();
@@ -484,6 +552,15 @@ export function TimelineAutomationLane({
         </div>
       ) : null}
 
+      <ReadOnlyNote
+        readOnly={readOnly}
+        note={readOnlyNote}
+        hovered={hovered}
+        hasRange={Boolean(rangeSelection)}
+        leftPx={leftPx}
+        widthPx={widthPx}
+      />
+
       {menuAt && rangeSelection ? (
         <AutomationSelectionMenu
           x={menuAt.x}