@hyperframes/studio 0.7.90 → 0.7.93

package/src/player/components/useTimelineClipRenderWindow.ts

@@ -1,10 +1,7 @@
-import { useMemo, type RefObject } from "react";
+import { useMemo } from "react";
 import { createTimelineClipIndex } from "../lib/timelineClipIndex";
-import type { TimelineElement } from "../store/playerStore";
 import { getTimelineRenderTimeRange } from "./timelineViewportGeometry";
-import type { TimelineRowGeometry } from "./timelineLayout";
 import type { TimelineScrollViewportSnapshot } from "./useTimelineScrollViewport";
-import { useTimelineRevealClip } from "./useTimelineRevealClip";
 
 interface UseTimelineClipRenderWindowInput {
   tracks: Parameters<typeof createTimelineClipIndex>[0];
@@ -14,18 +11,11 @@ interface UseTimelineClipRenderWindowInput {
   duration: number;
   selectedElementId?: string;
   draggedElementId?: string;
-  resizingElementId?: string;
-  revealElementId?: string;
+  resizingElementIds?: readonly string[];
+  focusedElementId?: string;
   focusedEaseElementId?: string;
   clipContextMenuElementId?: string;
   keyframeContextMenuElementId?: string;
-  focusedElementId?: string;
-  scrollRef: RefObject<HTMLDivElement | null>;
-  elements: readonly TimelineElement[];
-  rowGeometry: TimelineRowGeometry;
-  allowHorizontalReveal: boolean;
-  rowVirtualizationActive: boolean;
-  sessionEpoch: number;
 }
 
 export function useTimelineClipRenderWindow({
@@ -36,18 +26,11 @@ export function useTimelineClipRenderWindow({
   duration,
   selectedElementId,
   draggedElementId,
-  resizingElementId,
-  revealElementId,
+  resizingElementIds,
+  focusedElementId,
   focusedEaseElementId,
   clipContextMenuElementId,
   keyframeContextMenuElementId,
-  focusedElementId,
-  scrollRef,
-  elements,
-  rowGeometry,
-  allowHorizontalReveal,
-  rowVirtualizationActive,
-  sessionEpoch,
 }: UseTimelineClipRenderWindowInput) {
   const clipIndex = useMemo(() => createTimelineClipIndex(tracks), [tracks]);
   const renderTimeRange = useMemo(
@@ -60,12 +43,11 @@ export function useTimelineClipRenderWindow({
         [
           selectedElementId,
           draggedElementId,
-          resizingElementId,
-          revealElementId,
+          ...(resizingElementIds ?? []),
+          focusedElementId,
           focusedEaseElementId,
           clipContextMenuElementId,
           keyframeContextMenuElementId,
-          focusedElementId,
         ].filter((identity): identity is string => identity !== undefined),
       ),
     [
@@ -74,22 +56,9 @@ export function useTimelineClipRenderWindow({
       focusedEaseElementId,
       focusedElementId,
       keyframeContextMenuElementId,
-      resizingElementId,
-      revealElementId,
+      resizingElementIds,
       selectedElementId,
     ],
   );
-  useTimelineRevealClip({
-    scrollRef,
-    elements,
-    rowGeometry,
-    pixelsPerSecond,
-    contentOrigin,
-    allowHorizontal: allowHorizontalReveal,
-    deferFocusUntilViewportUpdate: rowVirtualizationActive,
-    focusedElementId,
-    viewportVersion: viewport,
-    sessionEpoch,
-  });
   return { clipIndex, renderTimeRange, pinnedClipIdentities };
 }

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

@@ -0,0 +1,174 @@
+// @vitest-environment happy-dom
+
+import React, { act, useMemo, useRef } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { usePlayerStore } from "../store/playerStore";
+import { createTimelineRowGeometry } from "./timelineLayout";
+import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
+import { timelineClipFocusId, timelineTrackRowId } from "./timelineNavigationIdentity";
+import { useTimelineFocusCoordinator } from "./useTimelineFocusCoordinator";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+const element = { id: "hero", tag: "div", start: 20, duration: 2, track: 1 };
+const elements = [element];
+const syncScrollViewport = () => {};
+const clipId = timelineClipFocusId("hero");
+const rowId = timelineTrackRowId(1);
+const rows: readonly TimelineLogicalRow[] = [
+  {
+    id: rowId,
+    kind: "row",
+    physicalTrackKey: 1,
+    logicalIndex: 0,
+    level: 1,
+    parentId: null,
+    elementId: null,
+    expandable: false,
+    expanded: false,
+    items: [{ id: clipId, kind: "clip", rowId, elementId: "hero", time: 21 }],
+  },
+];
+
+function Harness({
+  mountedId,
+  logicalRows = rows,
+  projectId = "project-a",
+}: {
+  mountedId?: string;
+  logicalRows?: readonly TimelineLogicalRow[];
+  projectId?: string;
+}) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const rowGeometry = useMemo(() => {
+    const rowKeys = [...new Set(logicalRows.map((row) => row.physicalTrackKey))];
+    return createTimelineRowGeometry(
+      rowKeys,
+      rowKeys.map(() => 48),
+    );
+  }, [logicalRows]);
+  const focus = useTimelineFocusCoordinator({
+    scrollRef,
+    logicalRows,
+    elements,
+    rowGeometry,
+    pixelsPerSecond: 100,
+    contentOrigin: 32,
+    allowHorizontal: true,
+    viewportVersion: mountedId,
+    projectId,
+    sessionEpoch: 1,
+    syncScrollViewport,
+  });
+  return (
+    <div
+      ref={(node) => {
+        scrollRef.current = node;
+        if (node) {
+          Object.defineProperty(node, "clientWidth", { configurable: true, value: 300 });
+          Object.defineProperty(node, "clientHeight", { configurable: true, value: 100 });
+        }
+      }}
+      data-focus={`${focus.focusedRowKey}:${focus.pinnedElementId}`}
+    >
+      {mountedId && <div data-timeline-focus-id={mountedId} tabIndex={-1} />}
+    </div>
+  );
+}
+
+let host: HTMLDivElement;
+let root: Root;
+beforeEach(() => {
+  usePlayerStore.setState({ timelineProjectId: "project-a", timelineSessionEpoch: 1 });
+  host = document.createElement("div");
+  document.body.append(host);
+  root = createRoot(host);
+});
+afterEach(() => {
+  act(() => root.unmount());
+  usePlayerStore.getState().reset();
+  document.body.replaceChildren();
+});
+
+describe("useTimelineFocusCoordinator", () => {
+  it("pins and scrolls from model coordinates until mount, then permits repeat reveal", async () => {
+    usePlayerStore.getState().requestTimelineFocus(clipId);
+    await act(async () => root.render(<Harness />));
+    const scroll = host.firstElementChild as HTMLDivElement;
+    expect(scroll.scrollLeft).toBe(1_944);
+    expect(scroll.dataset.focus).toBe("1:hero");
+    expect(usePlayerStore.getState().timelineFocus?.id).toBe(clipId);
+
+    await act(async () => root.render(<Harness mountedId={clipId} />));
+    const firstNonce = usePlayerStore.getState().timelineFocus?.nonce;
+    expect(usePlayerStore.getState().timelineFocus?.id).toBe(clipId);
+    expect(document.activeElement?.getAttribute("data-timeline-focus-id")).toBe(clipId);
+
+    scroll.scrollLeft = 0;
+    await act(async () => usePlayerStore.getState().requestTimelineFocus(clipId));
+    await act(async () => root.render(<Harness mountedId={clipId} />));
+    expect(scroll.scrollLeft).toBe(1_944);
+    expect(usePlayerStore.getState().timelineFocus?.nonce).toBe((firstNonce ?? 0) + 1);
+  });
+
+  it("focuses the latest request when it replaces an unmounted request", async () => {
+    usePlayerStore.getState().requestTimelineFocus(rowId);
+    usePlayerStore.getState().requestTimelineFocus(clipId);
+
+    await act(async () => root.render(<Harness mountedId={clipId} />));
+    expect(document.activeElement?.getAttribute("data-timeline-focus-id")).toBe(clipId);
+  });
+
+  it("does not retry an unchanged unmounted target on an unrelated render", async () => {
+    usePlayerStore.getState().requestTimelineFocus(clipId);
+    await act(async () => root.render(<Harness />));
+    const scroll = host.firstElementChild as HTMLDivElement;
+    const querySelector = vi.spyOn(scroll, "querySelector");
+
+    await act(async () => root.render(<Harness />));
+
+    expect(querySelector).not.toHaveBeenCalled();
+  });
+
+  it("ignores stale scope and never queries outside its own viewport", async () => {
+    usePlayerStore.getState().requestTimelineFocus(clipId);
+    await act(async () => root.render(<Harness mountedId={clipId} projectId="project-b" />));
+    expect(document.activeElement).not.toBe(host.querySelector("[data-timeline-focus-id]"));
+    expect(usePlayerStore.getState().timelineFocus?.id).toBe(clipId);
+
+    const externalTarget = document.createElement("div");
+    externalTarget.dataset.timelineFocusId = clipId;
+    externalTarget.tabIndex = -1;
+    document.body.append(externalTarget);
+    await act(async () => root.render(<Harness />));
+    expect(document.activeElement).not.toBe(externalTarget);
+  });
+
+  it("persists a deterministic parent-row fallback when a focused clip disappears", async () => {
+    usePlayerStore.getState().requestTimelineFocus(clipId);
+    await act(async () => root.render(<Harness />));
+
+    const collapsedRows: readonly TimelineLogicalRow[] = [{ ...rows[0]!, items: [] }];
+    await act(async () => root.render(<Harness logicalRows={collapsedRows} mountedId={rowId} />));
+    expect(usePlayerStore.getState().timelineFocus?.id).toBe(rowId);
+    expect(document.activeElement?.getAttribute("data-timeline-focus-id")).toBe(rowId);
+  });
+
+  it("persists the next surviving row when both a clip and its parent track disappear", async () => {
+    const nextRowId = timelineTrackRowId(2);
+    const nextRow: TimelineLogicalRow = {
+      ...rows[0]!,
+      id: nextRowId,
+      physicalTrackKey: 2,
+      items: [],
+    };
+    usePlayerStore.getState().requestTimelineFocus(clipId);
+    await act(async () => root.render(<Harness logicalRows={[...rows, nextRow]} />));
+
+    await act(async () => root.render(<Harness logicalRows={[nextRow]} mountedId={nextRowId} />));
+
+    expect(usePlayerStore.getState().timelineFocus?.id).toBe(nextRowId);
+    expect(document.activeElement?.getAttribute("data-timeline-focus-id")).toBe(nextRowId);
+  });
+});

package/src/player/components/useTimelineFocusCoordinator.ts

@@ -0,0 +1,221 @@
+import { useEffect, useLayoutEffect, useMemo, useRef, type RefObject } from "react";
+import type { TimelineElement } from "../store/playerStore";
+import { usePlayerStore } from "../store/playerStore";
+import type { TimelineFocusRequest } from "../store/timelineFocusState";
+import type { TimelineRowGeometry } from "./timelineLayout";
+import { CLIP_Y, RULER_H } from "./timelineLayout";
+import {
+  locateTimelineLogicalTarget,
+  resolveTimelineFocusFallback,
+  type TimelineLogicalRow,
+  type TimelineLogicalTarget,
+} from "./timelineKeyboardNavigation";
+import { computeRevealScroll } from "./timelineRevealScroll";
+
+interface TimelineFocusCoordinatorInput {
+  scrollRef: RefObject<HTMLDivElement | null>;
+  logicalRows: readonly TimelineLogicalRow[];
+  elements: readonly TimelineElement[];
+  rowGeometry: TimelineRowGeometry;
+  pixelsPerSecond: number;
+  contentOrigin: number;
+  allowHorizontal: boolean;
+  viewportVersion: unknown;
+  projectId: string | null;
+  sessionEpoch: number;
+  syncScrollViewport: (element: HTMLDivElement) => void;
+}
+
+export interface TimelineFocusCoordinatorState {
+  focusedTargetId: string | null;
+  focusedRowKey: number | undefined;
+  pinnedElementId: string | undefined;
+}
+
+interface ResolvedFocus {
+  target: TimelineLogicalTarget;
+  row: TimelineLogicalRow;
+}
+
+function isCurrentRequest(
+  request: TimelineFocusRequest | null,
+  projectId: string | null,
+  sessionEpoch: number,
+): request is TimelineFocusRequest {
+  return (
+    request !== null && request.projectId === projectId && request.sessionEpoch === sessionEpoch
+  );
+}
+
+function focusElement(container: HTMLDivElement, targetId: string): boolean {
+  // data-timeline-focus-id is the reserved DOM bridge between logical IDs and this actor.
+  const target = container.querySelector<HTMLElement>(
+    `[data-timeline-focus-id=${CSS.escape(targetId)}]`,
+  );
+  if (!target) return false;
+  if (target.ownerDocument.activeElement === target) return true;
+  target.setAttribute("data-reveal-highlight", "true");
+  target.focus({ preventScroll: true });
+  if (target.ownerDocument.activeElement !== target) {
+    target.removeAttribute("data-reveal-highlight");
+    return false;
+  }
+  // The reveal highlight is intentionally one-shot; ordinary refocus uses the standard focus ring.
+  target.addEventListener("blur", () => target.removeAttribute("data-reveal-highlight"), {
+    once: true,
+  });
+  return true;
+}
+
+// This is one atomic two-axis reveal calculation; each branch selects target geometry only.
+// fallow-ignore-next-line complexity
+function scrollToTarget(
+  container: HTMLDivElement,
+  resolution: ResolvedFocus,
+  elements: readonly TimelineElement[],
+  rowGeometry: TimelineRowGeometry,
+  pixelsPerSecond: number,
+  contentOrigin: number,
+  allowHorizontal: boolean,
+): boolean {
+  const rowIndex = rowGeometry.getRowIndex(resolution.row.physicalTrackKey);
+  if (rowIndex < 0) return false;
+  const elementId =
+    resolution.target.kind === "row" ? resolution.row.elementId : resolution.target.elementId;
+  const element = elementId
+    ? elements.find((candidate) => (candidate.key ?? candidate.id) === elementId)
+    : undefined;
+  const pointTime = resolution.target.kind === "row" ? null : resolution.target.time;
+  const left = element && resolution.target.kind === "clip" ? element.start : pointTime;
+  const right =
+    element && resolution.target.kind === "clip" ? element.start + element.duration : pointTime;
+  const rowTop = rowGeometry.getRowTop(rowIndex);
+  const target = computeRevealScroll({
+    scrollLeft: container.scrollLeft,
+    scrollTop: container.scrollTop,
+    viewportWidth: container.clientWidth,
+    viewportHeight: container.clientHeight,
+    clipLeft: contentOrigin + (left ?? 0) * pixelsPerSecond,
+    clipRight: contentOrigin + (right ?? 0) * pixelsPerSecond,
+    clipTop: rowTop + CLIP_Y,
+    clipBottom: rowTop + rowGeometry.getRowHeight(rowIndex) - CLIP_Y,
+    stickyLeft: contentOrigin,
+    stickyTop: RULER_H,
+    allowHorizontal: allowHorizontal && left !== null,
+  });
+  if (target.left !== null) container.scrollLeft = target.left;
+  if (target.top !== null) container.scrollTop = target.top;
+  return target.left !== null || target.top !== null;
+}
+
+/** Model-first focus actor; mounting is a consequence of its returned pins. */
+// Resolution, fallback, reveal, and focus form one ordered state machine.
+// fallow-ignore-next-line complexity
+export function useTimelineFocusCoordinator({
+  scrollRef,
+  logicalRows,
+  elements,
+  rowGeometry,
+  pixelsPerSecond,
+  contentOrigin,
+  allowHorizontal,
+  viewportVersion,
+  projectId,
+  sessionEpoch,
+  syncScrollViewport,
+}: TimelineFocusCoordinatorInput): TimelineFocusCoordinatorState {
+  const request = usePlayerStore((state) => state.timelineFocus);
+  const previousRowsRef = useRef(logicalRows);
+  const resolvedRef = useRef<{ nonce: number; id: string } | null>(null);
+  const appliedRef = useRef<{ nonce: number; id: string } | null>(null);
+  const resolution = useMemo<ResolvedFocus | null>(() => {
+    if (isCurrentRequest(request, projectId, sessionEpoch)) {
+      if (resolvedRef.current?.nonce !== request.nonce) {
+        resolvedRef.current = { nonce: request.nonce, id: request.id };
+      }
+      const resolvedId = resolvedRef.current.id;
+      let located = locateTimelineLogicalTarget(logicalRows, resolvedId);
+      if (!located) {
+        const fallback = resolveTimelineFocusFallback(
+          previousRowsRef.current,
+          logicalRows,
+          resolvedId,
+        );
+        if (fallback) {
+          // ponytail: Cache the fallback under this nonce so render-phase resolution
+          // converges before the effect persists the replacement request.
+          resolvedRef.current = { nonce: request.nonce, id: fallback.id };
+          located = locateTimelineLogicalTarget(logicalRows, fallback.id);
+        }
+      }
+      return located ? { target: located.target, row: located.row } : null;
+    }
+    resolvedRef.current = null;
+    return null;
+  }, [logicalRows, projectId, request, sessionEpoch]);
+
+  useLayoutEffect(() => {
+    previousRowsRef.current = logicalRows;
+  }, [logicalRows]);
+
+  // Apply a request exactly once after its logical target and DOM node are both ready.
+  // fallow-ignore-next-line complexity
+  useEffect(() => {
+    if (!isCurrentRequest(request, projectId, sessionEpoch)) return;
+    if (!resolution) {
+      usePlayerStore.getState().clearTimelineFocus(request.nonce);
+      return;
+    }
+    if (resolution.target.id !== request.id) {
+      usePlayerStore.getState().requestTimelineFocus(resolution.target.id);
+      return;
+    }
+    if (
+      appliedRef.current?.nonce === request.nonce &&
+      appliedRef.current.id === resolution.target.id
+    ) {
+      return;
+    }
+    const container = scrollRef.current;
+    if (!container) return;
+    if (
+      scrollToTarget(
+        container,
+        resolution,
+        elements,
+        rowGeometry,
+        pixelsPerSecond,
+        contentOrigin,
+        allowHorizontal,
+      )
+    ) {
+      syncScrollViewport(container);
+    }
+    if (!focusElement(container, resolution.target.id)) return;
+    appliedRef.current = { nonce: request.nonce, id: resolution.target.id };
+  }, [
+    allowHorizontal,
+    contentOrigin,
+    elements,
+    pixelsPerSecond,
+    projectId,
+    request,
+    resolution,
+    rowGeometry,
+    scrollRef,
+    sessionEpoch,
+    syncScrollViewport,
+    viewportVersion,
+  ]);
+
+  const pinnedElementId = resolution
+    ? resolution.target.kind === "row"
+      ? (resolution.row.elementId ?? undefined)
+      : resolution.target.elementId
+    : undefined;
+  return {
+    focusedTargetId: resolution?.target.id ?? null,
+    focusedRowKey: resolution?.row.physicalTrackKey,
+    pinnedElementId,
+  };
+}