Skip to content

Write HTML. Render video. Built for agents.

feat(studio): enter a sub-composition from the keyboard and host its navigation (#4672)

Miguel Ángelaf7ff3b0a104
diff --git a/docs/packages/studio.mdx b/docs/packages/studio.mdx
index 7d8dbd68d2..e35c1a21f9 100644
--- a/docs/packages/studio.mdx
+++ b/docs/packages/studio.mdx
@@ -75,6 +75,7 @@ Peer dependencies are React 19, React DOM 19, and Zustand 4 or 5.
| ----------------------------------------------------------- | ----------------------------------------------------- |
| `useTimelinePlayer` | Read and control the shared player state |
| `usePlayerStore` | Access the Zustand player store |
+| `useCompositionStack` | Drill into and back out of nested compositions |
| `useElementPicker` | Select and edit an element through the preview iframe |
| `resolveSourceFile`, `applyPatch` | Locate and patch source |
| `parseStyleString`, `mergeStyleIntoTag`, `findElementBlock` | Work with inline source styles and elements |
diff --git a/packages/studio/src/components/nle/CompositionBreadcrumb.tsx b/packages/studio/src/components/nle/CompositionBreadcrumb.tsx
index 73a4fd5539..84d376fa0c 100644
--- a/packages/studio/src/components/nle/CompositionBreadcrumb.tsx
+++ b/packages/studio/src/components/nle/CompositionBreadcrumb.tsx
@@ -21,7 +21,7 @@ export function CompositionBreadcrumb({ stack, onNavigate }: CompositionBreadcru
return (
<nav
aria-label="Composition navigation"
- className="flex items-center gap-1 px-2 h-8 border-b border-neutral-800/50 bg-neutral-900/50 shrink-0"
+ className="flex items-center gap-1 px-2 h-8 border-b border-hairline bg-bg-1 shrink-0"
>
{/* Back button — always goes to parent */}
<button
@@ -33,7 +33,7 @@ export function CompositionBreadcrumb({ stack, onNavigate }: CompositionBreadcru
});
onNavigate(stack.length - 2);
}}
- className="flex items-center gap-1 px-1.5 py-0.5 rounded-sm text-xs text-neutral-400 hover:text-white hover:bg-neutral-800 active:scale-[0.98] transition-colors"
+ className="flex items-center gap-1 px-1.5 py-0.5 rounded-sm text-xs text-text-3 hover:text-text-0 hover:bg-hover active:scale-[0.98] transition-colors"
title="Back (Esc, or double-click empty timeline)"
aria-label="Back to parent composition"
>
@@ -45,9 +45,9 @@ export function CompositionBreadcrumb({ stack, onNavigate }: CompositionBreadcru
const isLast = i === stack.length - 1;
return (
<span key={level.id} className="flex items-center gap-1">
- {i > 0 && <CaretRight size={10} className="text-neutral-600 shrink-0" />}
+ {i > 0 && <CaretRight size={10} className="text-text-4 shrink-0" />}
{isLast ? (
- <span className="text-xs text-neutral-200 font-medium">{level.label}</span>
+ <span className="text-xs text-text-1 font-medium">{level.label}</span>
) : (
<button
type="button"
@@ -55,7 +55,7 @@ export function CompositionBreadcrumb({ stack, onNavigate }: CompositionBreadcru
trackStudioEvent("navigation", { action: "breadcrumb", target: level.label });
onNavigate(i);
}}
- className="text-xs text-neutral-500 hover:text-neutral-200 transition-colors"
+ className="text-xs text-text-3 hover:text-text-1 transition-colors"
>
{level.label}
</button>
diff --git a/packages/studio/src/compositionStackExport.test.ts b/packages/studio/src/compositionStackExport.test.ts
new file mode 100644
index 0000000000..a71166b255
--- /dev/null
+++ b/packages/studio/src/compositionStackExport.test.ts
@@ -0,0 +1,7 @@
+import { expect, it } from "vitest";
+import { CompositionBreadcrumb, useCompositionStack } from "@hyperframes/studio";
+
+it("exports the composition stack hook beside the breadcrumb it feeds", () => {
+ expect(typeof useCompositionStack).toBe("function");
+ expect(typeof CompositionBreadcrumb).toBe("function");
+});
diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.ts
index 9e2b81c71d..9b02856a9d 100644
--- a/packages/studio/src/index.ts
+++ b/packages/studio/src/index.ts
@@ -9,6 +9,7 @@ export { DEFAULT_SHORTCUT_SECTIONS } from "./player/components/studioShortcuts";
export type { ShortcutHint, ShortcutSection } from "./player/components/studioShortcuts";
export { CompositionBreadcrumb } from "./components/nle/CompositionBreadcrumb";
export type { CompositionLevel } from "./components/nle/CompositionBreadcrumb";
+export { useCompositionStack } from "./components/nle/useCompositionStack";
// Player (preview, timeline, playback controls)
export {
diff --git a/packages/studio/src/player/components/TimelineLanes.tsx b/packages/studio/src/player/components/TimelineLanes.tsx
index 0925a4ed96..7b7f10086a 100644
--- a/packages/studio/src/player/components/TimelineLanes.tsx
+++ b/packages/studio/src/player/components/TimelineLanes.tsx
@@ -134,9 +134,8 @@ export function TimelineLanes({
focusedTargetId,
rowGeometry,
scrollRef,
- onToggleRow: (row) => {
- if (row.elementId) toggleClipExpandedTracked(row.elementId);
- },
+ onToggleRow: (row) => row.elementId && toggleClipExpandedTracked(row.elementId),
+ onDrillDown,
});
return (
<div
diff --git a/packages/studio/src/player/components/timelineKeyboardNavigation.ts b/packages/studio/src/player/components/timelineKeyboardNavigation.ts
index 00c321d897..53f706314b 100644
--- a/packages/studio/src/player/components/timelineKeyboardNavigation.ts
+++ b/packages/studio/src/player/components/timelineKeyboardNavigation.ts
@@ -49,6 +49,7 @@ export interface TimelineLogicalItem {
elementId: string;
/** The item's time anchor. Clips use their midpoint; ease controls use the segment midpoint. */
time: number;
+ element?: TimelineElement;
keyframeTarget?: TimelineKeyframeTarget;
}
@@ -113,6 +114,7 @@ function clipItems(rowId: string, elements: readonly TimelineElement[]): Timelin
rowId,
elementId: id,
time: element.start + element.duration / 2,
+ element,
};
});
}
diff --git a/packages/studio/src/player/components/useTimelineKeyboardActor.test.tsx b/packages/studio/src/player/components/useTimelineKeyboardActor.test.tsx
index 117b0f9310..a7920d92cb 100644
--- a/packages/studio/src/player/components/useTimelineKeyboardActor.test.tsx
+++ b/packages/studio/src/player/components/useTimelineKeyboardActor.test.tsx
@@ -3,7 +3,7 @@
import React, { act, useRef } from "react";
import { createRoot } from "react-dom/client";
import { afterEach, describe, expect, it, vi } from "vitest";
-import { usePlayerStore } from "../store/playerStore";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
import { createTimelineRowGeometry } from "./timelineLayout";
import type { TimelineLogicalRow } from "./timelineKeyboardNavigation";
import { useTimelineKeyboardActor } from "./useTimelineKeyboardActor";
@@ -57,6 +57,7 @@ interface HarnessProps {
logicalRows?: readonly TimelineLogicalRow[];
rowHeights?: readonly number[];
onToggleRow?: (target: TimelineLogicalRow) => void;
+ onDrillDown?: (element: TimelineElement) => void;
}
function Harness({
@@ -64,6 +65,7 @@ function Harness({
logicalRows = rows,
rowHeights = logicalRows.map(() => 48),
onToggleRow = vi.fn(),
+ onDrillDown,
}: HarnessProps) {
const scrollRef = useRef<HTMLDivElement>(null);
const keyboard = useTimelineKeyboardActor({
@@ -75,6 +77,7 @@ function Harness({
),
scrollRef,
onToggleRow,
+ onDrillDown,
});
return (
<div ref={scrollRef} onFocus={keyboard.onFocus} onKeyDown={keyboard.onKeyDown}>
@@ -228,6 +231,26 @@ describe("useTimelineKeyboardActor", () => {
act(() => root.unmount());
});
+ it("drills into a composition clip on Enter and leaves a plain clip alone", () => {
+ const scene = { id: "scene", tag: "div", start: 0, duration: 2, track: 1 };
+ const withElements = rows.map((row, index) => ({
+ ...row,
+ items: row.items.map((item) => ({
+ ...item,
+ element: index === 0 ? { ...scene, compositionSrc: "scene.html" } : scene,
+ })),
+ }));
+ const onDrillDown = vi.fn();
+ const { host, root } = renderHarness({ logicalRows: withElements, onDrillDown });
+ const composition = host.querySelector<HTMLElement>('[data-timeline-focus-id="clip-1"]')!;
+ const plain = host.querySelector<HTMLElement>('[data-timeline-focus-id="clip-2"]')!;
+ expect(key(plain, "Enter").defaultPrevented).toBe(false);
+ expect(onDrillDown).not.toHaveBeenCalled();
+ expect(key(composition, "Enter").defaultPrevented).toBe(true);
+ expect(onDrillDown).toHaveBeenCalledWith(withElements[0]!.items[0]!.element);
+ act(() => root.unmount());
+ });
+
it("collapses expanded rows and leaves native header controls to the browser", () => {
const onToggleRow = vi.fn();
const expandedRows = [{ ...rows[0]!, expanded: true }, ...rows.slice(1)];
diff --git a/packages/studio/src/player/components/useTimelineKeyboardActor.ts b/packages/studio/src/player/components/useTimelineKeyboardActor.ts
index 3969a5f84b..1f1a17829e 100644
--- a/packages/studio/src/player/components/useTimelineKeyboardActor.ts
+++ b/packages/studio/src/player/components/useTimelineKeyboardActor.ts
@@ -1,5 +1,5 @@
import { useCallback, useMemo, type FocusEvent, type KeyboardEvent, type RefObject } from "react";
-import { usePlayerStore } from "../store/playerStore";
+import { usePlayerStore, type TimelineElement } from "../store/playerStore";
import type { TimelineRowGeometry } from "./timelineLayout";
import {
isTimelineNavigationKey,
@@ -14,6 +14,7 @@ interface TimelineKeyboardActorInput {
rowGeometry: TimelineRowGeometry;
scrollRef: RefObject<HTMLDivElement | null>;
onToggleRow: (target: TimelineLogicalRow) => void;
+ onDrillDown?: (element: TimelineElement) => void;
}
function eventTarget(event: FocusEvent | KeyboardEvent): HTMLElement | null {
@@ -70,6 +71,7 @@ export function useTimelineKeyboardActor({
rowGeometry,
scrollRef,
onToggleRow,
+ onDrillDown,
}: TimelineKeyboardActorInput) {
const rovingTargetId =
(focusedTargetId && locateTimelineLogicalTarget(logicalRows, focusedTargetId)?.target.id) ??
@@ -130,6 +132,12 @@ export function useTimelineKeyboardActor({
openContextMenu(targetElement);
return;
}
+ const composition = located.target.kind === "clip" && located.target.element;
+ if (event.key === "Enter" && composition && composition.compositionSrc && onDrillDown) {
+ event.preventDefault();
+ onDrillDown(composition);
+ return;
+ }
if (
(event.key !== "Enter" && event.key !== " ") ||
located.target.kind !== "row" ||
@@ -140,7 +148,7 @@ export function useTimelineKeyboardActor({
event.preventDefault();
onToggleRow(located.target);
},
- [logicalRowCountByTrack, logicalRows, onToggleRow, rowGeometry, scrollRef],
+ [logicalRowCountByTrack, logicalRows, onDrillDown, onToggleRow, rowGeometry, scrollRef],
);
return { rovingTargetId, onFocus, onKeyDown };