@hyperframes/studio 0.7.77 → 0.7.79

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

@@ -7,10 +7,15 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { TimelineClipDiamonds } from "./TimelineClipDiamonds";
 import {
   getTimelinePropertyLanes,
+  resolveAnimIdForProperty,
   TimelinePropertyLanes,
   type TimelinePropertyLanesProps,
 } from "./TimelinePropertyLanes";
 import { timelineKeyframeSelectionKey } from "./timelineKeyframeIdentity";
+import { LANE_H, getTimelineLaneTop } from "./timelineLayout";
+import { groupLabel } from "./trackHeaderLaneValues";
+import { clipTimingStart } from "../../hooks/gsapShared";
+import { resolveTimelineKeyframeTarget } from "../../components/nle/useTimelineEditCallbacks";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
@@ -121,7 +126,111 @@ const POSITION_SEGMENT_ANIMATION = animation("position-tween", "position", [
   { percentage: 50, properties: { x: 50 } },
 ]);
 
+/** A tween the parser leaves unclassified because it spans several groups. */
+function ungroupedAnimation(
+  id: string,
+  properties: Record<string, number | string>,
+): GsapAnimation {
+  return {
+    id,
+    targetSelector: "#clip-1",
+    method: "to",
+    position: 0,
+    duration: 1,
+    properties,
+  };
+}
+
 describe("TimelinePropertyLanes", () => {
+  // `{ x, opacity }` is the canonical HyperFrames entrance tween. The parser
+  // classifies it to `undefined` (two groups), which used to erase it from the
+  // lanes entirely — no caret, no reserved row, nothing to edit.
+  it("lanes a mixed-group tween once per group it animates", () => {
+    const lanes = getTimelinePropertyLanes(
+      [ungroupedAnimation("entrance", { x: 0, opacity: 1 })],
+      0,
+      1,
+    );
+
+    expect(lanes.map((lane) => lane.group).sort()).toEqual(["position", "visual"]);
+    for (const lane of lanes) {
+      expect(lane.keyframes.map((keyframe) => keyframe.percentage)).toEqual([0, 100]);
+      expect(lane.keyframes.every((keyframe) => keyframe.animationId === "entrance")).toBe(true);
+    }
+  });
+
+  it("lanes a tween whose properties are all unknown as one 'other' lane", () => {
+    const lanes = getTimelinePropertyLanes(
+      [ungroupedAnimation("rounded", { borderRadius: 12, fontSize: 24 })],
+      0,
+      1,
+    );
+
+    expect(lanes).toHaveLength(1);
+    expect(lanes[0]?.group).toBe("other");
+    expect(groupLabel("other", lanes[0]!.keyframes[0]!.properties)).toBe("BorderRadius");
+  });
+
+  // An expanded sub-composition child sits on the MASTER timeline at a
+  // host-absolute start while its tweens are parsed from its own file and are
+  // local to it. clipTimingStart is what brings the two into one frame.
+  it("keeps an expanded sub-comp child's lane percentages inside the clip", () => {
+    const child = { start: 16.5, duration: 2, expandedParentStart: 16 };
+    const local = animation("pill-tween", "position", [
+      { percentage: 0, properties: { x: 0 } },
+      { percentage: 100, properties: { x: 100 } },
+    ]);
+    local.position = 0.5;
+    local.resolvedStart = 0.5;
+    local.duration = 2;
+
+    const percentages = getTimelinePropertyLanes(
+      [local],
+      clipTimingStart(child),
+      child.duration,
+    ).flatMap((lane) => lane.keyframes.map((keyframe) => keyframe.percentage));
+
+    expect(percentages).toHaveLength(2);
+    for (const percentage of percentages) {
+      expect(percentage).toBeGreaterThanOrEqual(0);
+      expect(percentage).toBeLessThanOrEqual(100);
+    }
+    // Falsifier: the raw host-absolute start is what used to be passed.
+    expect(
+      getTimelinePropertyLanes([local], child.start, child.duration)[0]?.keyframes[0]?.percentage,
+    ).toBeLessThan(0);
+  });
+
+  it("still lanes a single-group tween exactly once", () => {
+    const lanes = getTimelinePropertyLanes(
+      [animation("position-tween", "position", [{ percentage: 0, properties: { x: 0, y: 0 } }])],
+      0,
+      1,
+    );
+
+    expect(lanes.map((lane) => lane.group)).toEqual(["position"]);
+  });
+
+  // A lane can merge several tweens, so an edit routed from it must carry the
+  // clicked keyframe's own animation identity — group matching alone is
+  // ambiguous once two tweens feed the same lane.
+  it("routes a mixed-tween lane edit to the tween that owns the keyframe", () => {
+    const mixed = ungroupedAnimation("entrance", { x: 40, opacity: 1 });
+    const sibling = animation("drift", "position", [
+      { percentage: 0, properties: { x: 0 } },
+      { percentage: 100, properties: { x: 9 } },
+    ]);
+    const lanes = getTimelinePropertyLanes([mixed, sibling], 0, 1);
+    const position = lanes.find((lane) => lane.group === "position");
+
+    expect(
+      resolveTimelineKeyframeTarget(100, position?.keyframes ?? [], [
+        { id: "entrance" },
+        { id: "drift", propertyGroup: "position" },
+      ]),
+    ).toEqual({ animId: "entrance", tweenPct: 100 });
+  });
+
   it("returns a position lane with synthesized endpoints for a flat tween", () => {
     const lanes = getTimelinePropertyLanes(
       [flatAnimation("position-tween", "position", { x: 420 })],
@@ -399,6 +508,68 @@ describe("TimelinePropertyLanes", () => {
     act(() => root.unmount());
   });
 
+  // The disclosure caret's aria-controls used to name a div in the STICKY LABEL
+  // COLUMN whose children are all absolutely positioned: it computed to 0x0 and
+  // held no diamonds. The real lanes had no wrapper at all to point at.
+  it("wraps the lanes in the identified element so aria-controls resolves to the diamonds", () => {
+    const animations = [
+      animation("position-tween", "position", [
+        { percentage: 0, properties: { x: 0 } },
+        { percentage: 100, properties: { x: 100 } },
+      ]),
+      animation("visual-tween", "visual", [
+        { percentage: 0, properties: { opacity: 0 } },
+        { percentage: 100, properties: { opacity: 1 } },
+      ]),
+    ];
+    const { host, root } = renderPropertyLanes({ id: "timeline-lanes-track-0", animations });
+    const wrapper = host.querySelector("#timeline-lanes-track-0");
+
+    expect(wrapper).not.toBeNull();
+    expect(wrapper?.querySelectorAll("[data-timeline-property-lane]")).toHaveLength(2);
+    expect(wrapper?.querySelectorAll("button[data-keyframe-percentage]").length).toBeGreaterThan(0);
+    // Load-bearing: a `position: relative` wrapper would become the containing
+    // block for the absolute lanes below and shift every one of them.
+    expect((wrapper as HTMLElement).style.position).toBe("");
+    act(() => root.unmount());
+  });
+
+  // happy-dom has no CSS engine, so measured geometry is always 0x0. The lanes'
+  // own inline offsets are what the component actually computes, so pin those.
+  it("leaves every lane's inline offsets untouched by the wrapper", () => {
+    const animations = [
+      animation("position-tween", "position", [{ percentage: 0, properties: { x: 0 } }]),
+      animation("visual-tween", "visual", [{ percentage: 0, properties: { opacity: 0 } }]),
+    ];
+    const { host, root } = renderPropertyLanes({
+      id: "timeline-lanes-track-0",
+      animations,
+      clipLeftPx: 120,
+      clipWidthPx: 200,
+    });
+
+    const lanes = Array.from(host.querySelectorAll<HTMLElement>("[data-timeline-property-lane]"));
+    expect(lanes.map((lane) => lane.style.top)).toEqual([
+      `${getTimelineLaneTop(0)}px`,
+      `${getTimelineLaneTop(1)}px`,
+    ]);
+    expect(lanes.map((lane) => lane.style.left)).toEqual(["120px", "120px"]);
+    expect(lanes.map((lane) => lane.style.width)).toEqual(["200px", "200px"]);
+    expect(lanes.map((lane) => lane.style.height)).toEqual([`${LANE_H}px`, `${LANE_H}px`]);
+    act(() => root.unmount());
+  });
+
+  // The wrapper is the aria-controls target in BOTH disclosure states, so a
+  // collapsed layer (no animations reach it) must still resolve the id.
+  it("still renders the identified wrapper when there are no lanes to show", () => {
+    const { host, root } = renderPropertyLanes({ id: "timeline-lanes-track-0", animations: [] });
+
+    const wrapper = host.querySelector("#timeline-lanes-track-0");
+    expect(wrapper).not.toBeNull();
+    expect(wrapper?.querySelectorAll("[data-timeline-property-lane]")).toHaveLength(0);
+    act(() => root.unmount());
+  });
+
   it("keeps the collapsed TimelineClipDiamonds positions and callback contract unchanged", () => {
     const onClickKeyframe = vi.fn();
     const COLLAPSED_IDENTITY = { animationId: "position-tween", propertyGroup: "position" };
@@ -448,3 +619,49 @@ describe("TimelinePropertyLanes", () => {
     act(() => root.unmount());
   });
 });
+
+describe("resolveAnimIdForProperty", () => {
+  /** A legacy mixed tween: the parser leaves propertyGroup undefined for it. */
+  const mixed = {
+    id: "mixed-1",
+    targetSelector: "#box",
+    method: "to",
+    position: 0,
+    properties: {},
+    keyframes: {
+      keyframes: [
+        { percentage: 0, properties: { x: 0, opacity: 0 } },
+        { percentage: 100, properties: { x: 40, opacity: 1 } },
+      ],
+    },
+  } as unknown as GsapAnimation;
+
+  it("routes both groups of a mixed tween to that tween, not the fallback", () => {
+    expect(mixed.propertyGroup).toBeUndefined();
+
+    expect(resolveAnimIdForProperty("x", [mixed], "fallback")).toBe("mixed-1");
+    expect(resolveAnimIdForProperty("opacity", [mixed], "fallback")).toBe("mixed-1");
+  });
+
+  it("falls back only when no tween animates the property's group", () => {
+    expect(resolveAnimIdForProperty("rotation", [mixed], "fallback")).toBe("fallback");
+    expect(resolveAnimIdForProperty("rotation", [mixed], undefined)).toBe("");
+  });
+
+  it("prefers a single-group tween that owns the lane", () => {
+    const opacityOnly = {
+      ...mixed,
+      id: "opacity-1",
+      propertyGroup: "visual",
+      keyframes: {
+        keyframes: [
+          { percentage: 0, properties: { opacity: 0 } },
+          { percentage: 100, properties: { opacity: 1 } },
+        ],
+      },
+    } as unknown as GsapAnimation;
+
+    expect(resolveAnimIdForProperty("opacity", [opacityOnly, mixed], "fallback")).toBe("opacity-1");
+    expect(resolveAnimIdForProperty("x", [opacityOnly, mixed], "fallback")).toBe("mixed-1");
+  });
+});

package/src/player/components/TimelinePropertyLanes.tsx

@@ -11,6 +11,12 @@ import { LANE_H, getTimelineLaneTop } from "./timelineLayout";
 import type { TimelineKeyframeTarget } from "./timelineKeyframeIdentity";
 
 export interface TimelinePropertyLanesProps {
+  /**
+   * Id of the wrapper below, so the layer's disclosure caret can point
+   * `aria-controls` at the lanes a sighted user sees it reveal. Minted by
+   * TimelineLanes, which owns both this subtree and the caret's.
+   */
+  id?: string;
   animations: readonly GsapAnimation[];
   clipStart: number;
   clipDuration: number;
@@ -29,11 +35,25 @@ export interface TimelinePropertyLanesProps {
   suppressClickRef?: RefObject<boolean>;
 }
 
+/**
+ * Keys that ride along in a tween's property bag without being animated: a
+ * transform modifier, Studio's internal endpoint marker, and GSAP's reserved
+ * `data`. Same exclusion list the parser's classifyTweenPropertyGroup applies —
+ * without it `{ x, transformOrigin }` would draw a spurious "Other" lane.
+ */
+const NON_ANIMATED_PROPERTIES = new Set(["transformOrigin", "_auto", "data"]);
+
+function isAnimatedProperty(property: string): boolean {
+  return !NON_ANIMATED_PROPERTIES.has(property);
+}
+
 function hasGroupProperty(
   properties: Record<string, number | string>,
   group: PropertyGroupName,
 ): boolean {
-  return Object.keys(properties).some((property) => classifyPropertyGroup(property) === group);
+  return Object.keys(properties).some(
+    (property) => isAnimatedProperty(property) && classifyPropertyGroup(property) === group,
+  );
 }
 
 /** The tween's editable keyframes: its real keyframes, or the start→end pair
@@ -42,19 +62,63 @@ function animationKeyframes(animation: GsapAnimation) {
   return animation.keyframes?.keyframes ?? synthesizeFlatTweenKeyframes(animation)?.keyframes ?? [];
 }
 
-/** A tween contributes a property lane when it has a group and at least one
- *  editable keyframe (real or synthesized). */
+/**
+ * Every property group a tween draws a lane for, classified PER PROPERTY.
+ * `animation.propertyGroup` is the parser's whole-tween verdict and is
+ * `undefined` for anything spanning more than one group — but `{ x, opacity }`
+ * is the canonical HyperFrames entrance tween, and reading that verdict gave it
+ * no caret, no reserved row and no diamonds. classifyPropertyGroup is total, so
+ * an unrecognised property still lands in "other" rather than vanishing.
+ *
+ * Single owner: the rendered lanes (sourceGroups) and the reserved row heights
+ * (computeLaneCounts) both count groups through here, or they drift.
+ */
+export function animationLaneGroups(animation: GsapAnimation): PropertyGroupName[] {
+  const groups = new Set<PropertyGroupName>();
+  for (const keyframe of animationKeyframes(animation)) {
+    for (const property of Object.keys(keyframe.properties)) {
+      if (isAnimatedProperty(property)) groups.add(classifyPropertyGroup(property));
+    }
+  }
+  return Array.from(groups);
+}
+
+/**
+ * Which tween a panel edit to `prop` belongs to.
+ *
+ * Matches on the groups the tween's KEYFRAMES animate, not on the parser's
+ * whole-tween `propertyGroup` verdict: that field is undefined for a legacy
+ * mixed tween such as `{ x, opacity }`, so matching it dropped every such
+ * tween and sent the edit to the selection's default animation instead, which
+ * is a different tween than the lane the user is looking at.
+ * {@link animationLaneGroups} is the single owner the rendered lanes count
+ * groups through, so resolving here through the same helper keeps the panel
+ * and the lanes on one answer.
+ */
+export function resolveAnimIdForProperty(
+  prop: string,
+  animations: readonly GsapAnimation[] | undefined,
+  fallbackAnimId: string | undefined,
+): string {
+  const group = classifyPropertyGroup(prop);
+  const groupAnim = animations?.find((a) => animationLaneGroups(a).includes(group));
+  return groupAnim?.id ?? fallbackAnimId ?? "";
+}
+
+/** A tween contributes a property lane when it animates at least one property
+ *  on at least one editable keyframe (real or synthesized). */
 export function animationContributesLane(animation: GsapAnimation): boolean {
-  return !!animation.propertyGroup && animationKeyframes(animation).length > 0;
+  return animationLaneGroups(animation).length > 0;
 }
 
 function sourceGroups(animations: readonly GsapAnimation[]) {
   const groups = new Map<PropertyGroupName, GsapAnimation[]>();
   for (const animation of animations) {
-    if (!animation.propertyGroup || !animationContributesLane(animation)) continue;
-    const groupAnimations = groups.get(animation.propertyGroup) ?? [];
-    groupAnimations.push(animation);
-    groups.set(animation.propertyGroup, groupAnimations);
+    for (const group of animationLaneGroups(animation)) {
+      const groupAnimations = groups.get(group) ?? [];
+      groupAnimations.push(animation);
+      groups.set(group, groupAnimations);
+    }
   }
   return groups;
 }
@@ -112,6 +176,7 @@ export function getTimelinePropertyLanes(
 }
 
 export function TimelinePropertyLanes({
+  id,
   animations,
   clipStart,
   clipDuration,
@@ -148,9 +213,13 @@ export function TimelinePropertyLanes({
     [lanes],
   );
 
-  if (laneData.length === 0) return null;
+  // One STATIC wrapper, never `relative`: a static box establishes no containing
+  // block, so every absolutely-positioned lane below still resolves against the
+  // track-content div and the rendered geometry is byte-identical to the bare
+  // fragment this replaced. It is also rendered when there are no lanes at all
+  // (collapsed layer), so `id` stays resolvable in both disclosure states.
   return (
-    <>
+    <div id={id}>
       {laneData.map(({ group, keyframesData }, laneIndex) => (
         <div
           key={group}
@@ -186,6 +255,6 @@ export function TimelinePropertyLanes({
           />
         </div>
       ))}
-    </>
+    </div>
   );
 }

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

@@ -60,12 +60,14 @@ const OPACITY = animation("opacity-tween", "visual", [
 ]);
 
 interface RenderHeaderOptions {
+  keyframeClip?: TimelineElement;
   animations?: GsapAnimation[];
   clipCount?: number;
   currentTime?: number;
   expanded?: boolean;
   onSeek?: (time: number) => void;
   onTogglePropertyGroupKeyframe?: TimelineEditCallbacks["onTogglePropertyGroupKeyframe"];
+  onToggleTrackHidden?: TimelineEditCallbacks["onToggleTrackHidden"];
 }
 
 function renderHeader(options: RenderHeaderOptions = {}): {
@@ -80,10 +82,14 @@ function renderHeader(options: RenderHeaderOptions = {}): {
     act(() => {
       root.render(
         <TimelineTrackHeader
-          trackNumber={0}
+          // A real fractional z-order sort key, so a label built from it would
+          // read out "track 0.16666666666666666".
+          trackNumber={1 / 6}
+          trackDisplayNumber={1}
           trackLabel="Hero card"
+          lanesId="timeline-lanes-track-0"
           contentOrigin={LABEL_COL_W}
-          keyframeClip={ELEMENT}
+          keyframeClip={next.keyframeClip ?? ELEMENT}
           clipCount={next.clipCount ?? 1}
           isExpanded={next.expanded !== false}
           animations={next.animations ?? [POSITION, OPACITY]}
@@ -92,7 +98,7 @@ function renderHeader(options: RenderHeaderOptions = {}): {
           isAudioTrack={false}
           theme={defaultTimelineTheme}
           onToggleClipExpanded={vi.fn()}
-          onToggleTrackHidden={vi.fn()}
+          onToggleTrackHidden={next.onToggleTrackHidden ?? vi.fn()}
           onTogglePropertyGroupKeyframe={next.onTogglePropertyGroupKeyframe}
           onSeek={next.onSeek}
         />,
@@ -110,6 +116,53 @@ function click(host: HTMLElement, label: string) {
 }
 
 describe("TimelineTrackHeader", () => {
+  // An expanded sub-composition child sits on the MASTER timeline at a
+  // host-absolute start, but its tweens are parsed from its own file and are
+  // local to it. Feeding the raw start straight into the clip-% math put every
+  // lane keyframe far outside the clip.
+  it("keeps an expanded sub-comp child's lane percentages inside the clip", () => {
+    const child: TimelineElement = {
+      id: "pill",
+      tag: "div",
+      start: 16.5,
+      duration: 2,
+      track: 0,
+      expandedParentStart: 16,
+      sourceFile: "scene.html",
+    };
+    const local: GsapAnimation = {
+      id: "pill-tween",
+      targetSelector: "#pill",
+      method: "to",
+      position: 0.5,
+      resolvedStart: 0.5,
+      duration: 2,
+      properties: {},
+      propertyGroup: "position",
+      keyframes: {
+        format: "percentage",
+        keyframes: [
+          { percentage: 0, properties: { x: 0 } },
+          { percentage: 100, properties: { x: 100 } },
+        ],
+      },
+    };
+    // Playhead at the clip's midpoint (master time), so the 100% keyframe is
+    // ahead of it. On the raw host-absolute basis every keyframe rebased to a
+    // large negative percentage and nothing was ever ahead of the playhead.
+    const view = renderHeader({
+      keyframeClip: child,
+      animations: [local],
+      currentTime: 17.5,
+    });
+
+    expect(
+      view.host.querySelector<HTMLButtonElement>('button[aria-label="Next Position keyframe"]')
+        ?.disabled,
+    ).toBe(false);
+    act(() => view.root.unmount());
+  });
+
   // The header shows one clip's lanes, so how many clips the track holds is
   // otherwise invisible from the label column. A single-clip track stays silent.
   it("shows the track's clip count only once the track holds more than one clip", () => {
@@ -125,10 +178,27 @@ describe("TimelineTrackHeader", () => {
   // in every disclosure state — a hover-gated eye is unusable by keyboard.
   it("keeps the visibility eye mounted whether the layer is expanded or collapsed", () => {
     const view = renderHeader({ expanded: true });
-    expect(view.host.querySelector('button[aria-label="Hide track 0"]')).not.toBeNull();
+    expect(view.host.querySelector('button[aria-label="Hide track 1"]')).not.toBeNull();
 
     view.rerender({ expanded: false });
-    expect(view.host.querySelector('button[aria-label="Hide track 0"]')).not.toBeNull();
+    expect(view.host.querySelector('button[aria-label="Hide track 1"]')).not.toBeNull();
+    act(() => view.root.unmount());
+  });
+
+  // trackNumber is a fractional z-order sort key, so building the label from it
+  // made screen readers announce "Hide track 0.16666666666666666". The display
+  // number is label-only; the toggle still routes by the real key.
+  it("announces the display track number but toggles with the real fractional key", () => {
+    const onToggleTrackHidden = vi.fn();
+    const view = renderHeader({ onToggleTrackHidden });
+    const eye = view.host.querySelector<HTMLButtonElement>('button[aria-label="Hide track 1"]');
+
+    expect(eye).not.toBeNull();
+    expect(eye?.title).toBe("Hide track 1");
+    expect(view.host.innerHTML).not.toContain("0.16666666666666666");
+
+    act(() => eye?.click());
+    expect(onToggleTrackHidden).toHaveBeenCalledWith(1 / 6, true);
     act(() => view.root.unmount());
   });
 

package/src/player/components/TimelineTrackHeader.tsx

@@ -4,6 +4,7 @@ import { Music } from "../../icons/SystemIcons";
 import type { TimelineElement } from "../store/playerStore";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
 import { getTimelinePropertyLanes } from "./TimelinePropertyLanes";
+import { clipTimingStart } from "../../hooks/gsapShared";
 import { LayerDisclosureRow } from "./LayerDisclosureRow";
 import { TrackClipCount } from "./TrackClipCount";
 import { LABEL_COL_W, LANE_H, getTimelineLaneTop } from "./timelineLayout";
@@ -14,10 +15,21 @@ import {
   type TimelinePropertyLane,
 } from "./trackHeaderLaneState";
 import { valueReadout } from "./trackHeaderLaneValues";
+import { trackDisplaySuffix } from "./timelineTrackDisplay";
 
 interface TimelineTrackHeaderProps {
+  /** The track's real key: a FRACTIONAL z-order sort value. Routes callbacks;
+   *  never shown or announced. */
   trackNumber: number;
+  /** The track's 1-based position in the rendered order: the only number safe
+   *  to put in a label. Announcing `trackNumber` read out "track
+   *  0.16666666666666666". Null when the key has no row, which drops the number
+   *  from the label rather than inventing one (see trackDisplayNumber). */
+  trackDisplayNumber: number | null;
   trackLabel: string;
+  /** Id of the canvas-side lanes element the disclosure caret expands. Minted by
+   *  TimelineLanes, which is the one place that sees both subtrees. */
+  lanesId: string;
   contentOrigin: number;
   /** The track's active keyframe clip (selected, else primary) — the one whose
    *  disclosure + property rows this header shows, whether expanded or not. */
@@ -39,16 +51,21 @@ interface TimelineTrackHeaderProps {
 function VisibilityButton({
   hidden,
   trackNumber,
+  trackDisplayNumber,
   visible,
   onToggle,
 }: {
   hidden: boolean;
   trackNumber: number;
+  trackDisplayNumber: number | null;
   visible: boolean;
   onToggle: TimelineEditCallbacks["onToggleTrackHidden"];
 }) {
   if (!visible) return <span aria-hidden="true" className="h-6 w-6 shrink-0" />;
-  const label = hidden ? `Show track ${trackNumber}` : `Hide track ${trackNumber}`;
+  // Display number in the text, real key in the callback. The two must not be
+  // conflated in either direction.
+  const suffix = trackDisplaySuffix(trackDisplayNumber);
+  const label = hidden ? `Show track${suffix}` : `Hide track${suffix}`;
   return (
     <button
       type="button"
@@ -76,6 +93,7 @@ function VisibilityButton({
 // count, eye. Not deprecated — it is the live path for every track without lanes.
 function PlainTrackHeader({
   trackNumber,
+  trackDisplayNumber,
   trackLabel,
   clipCount,
   showTrackLabel,
@@ -85,6 +103,7 @@ function PlainTrackHeader({
 }: Pick<
   TimelineTrackHeaderProps,
   | "trackNumber"
+  | "trackDisplayNumber"
   | "trackLabel"
   | "clipCount"
   | "isTrackHidden"
@@ -105,6 +124,7 @@ function PlainTrackHeader({
       <VisibilityButton
         hidden={isTrackHidden}
         trackNumber={trackNumber}
+        trackDisplayNumber={trackDisplayNumber}
         visible
         onToggle={onToggleTrackHidden}
       />
@@ -262,7 +282,9 @@ function PropertyGroupHeaderRow({
 
 export function TimelineTrackHeader({
   trackNumber,
+  trackDisplayNumber,
   trackLabel,
+  lanesId,
   contentOrigin,
   keyframeClip,
   clipCount,
@@ -281,13 +303,14 @@ export function TimelineTrackHeader({
     ? ((currentTime - keyframeClip.start) / keyframeClip.duration) * 100
     : 0;
   const lanes = keyframeClip
-    ? getTimelinePropertyLanes(animations, keyframeClip.start, keyframeClip.duration)
+    ? // clipTimingStart, not the raw start: an expanded sub-comp child's start is
+      // host-absolute while its tweens are local to its own file.
+      getTimelinePropertyLanes(animations, clipTimingStart(keyframeClip), keyframeClip.duration)
     : [];
   // Label mode = keyframe view; the label column stays LABEL_COL_W (Timeline.tsx
   // owns the gutter past it, so a 0% diamond isn't clipped by this panel).
   const showTrackLabel = contentOrigin >= LABEL_COL_W;
   const isKeyframeLayer = !!keyframeClip && lanes.length > 0;
-  const lanesId = `timeline-lanes-track-${trackNumber}`;
 
   return (
     <div
@@ -307,6 +330,7 @@ export function TimelineTrackHeader({
       {!keyframeClip || lanes.length === 0 ? (
         <PlainTrackHeader
           trackNumber={trackNumber}
+          trackDisplayNumber={trackDisplayNumber}
           trackLabel={trackLabel}
           clipCount={clipCount}
           showTrackLabel={showTrackLabel}
@@ -333,29 +357,35 @@ export function TimelineTrackHeader({
             <VisibilityButton
               hidden={isTrackHidden}
               trackNumber={trackNumber}
+              trackDisplayNumber={trackDisplayNumber}
               visible
               onToggle={onToggleTrackHidden}
             />
           </LayerDisclosureRow>
-          {/* Always mounted so the caret's aria-controls resolves in both states. */}
-          <div id={lanesId}>
-            {isExpanded &&
-              lanes.map((lane, laneIndex) => (
-                <PropertyGroupHeaderRow
-                  key={lane.group}
-                  lane={lane}
-                  laneIndex={laneIndex}
-                  isLastLane={laneIndex === lanes.length - 1}
-                  expandedElement={keyframeClip}
-                  currentTime={currentTime}
-                  clipPercentage={clipPercentage}
-                  gutterBackground={theme.gutterBackground}
-                  columnWidth={showTrackLabel ? LABEL_COL_W : contentOrigin}
-                  onTogglePropertyGroupKeyframe={onTogglePropertyGroupKeyframe}
-                  onSeek={onSeek}
-                />
-              ))}
-          </div>
+          {/* The caret expands TWO disjoint subtrees: these label-column rows,
+              which carry the per-lane keyframe controls, and the diamond lanes
+              on the canvas. `lanesId` names the canvas lanes (rendered by
+              TimelineLanes), because that is what a sighted user watches appear
+              and what following the reference has to land on. These rows are not
+              empty and are not the target; they are absolutely positioned inside
+              the sticky column, which is what made a wrapper HERE compute to
+              0x0 and hold no diamonds. */}
+          {isExpanded &&
+            lanes.map((lane, laneIndex) => (
+              <PropertyGroupHeaderRow
+                key={lane.group}
+                lane={lane}
+                laneIndex={laneIndex}
+                isLastLane={laneIndex === lanes.length - 1}
+                expandedElement={keyframeClip}
+                currentTime={currentTime}
+                clipPercentage={clipPercentage}
+                gutterBackground={theme.gutterBackground}
+                columnWidth={showTrackLabel ? LABEL_COL_W : contentOrigin}
+                onTogglePropertyGroupKeyframe={onTogglePropertyGroupKeyframe}
+                onSeek={onSeek}
+              />
+            ))}
         </>
       )}
     </div>