Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.mdxindex 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.tsxindex 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 }: CompositionBreadcrureturn (<navaria-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 }: CompositionBreadcruconst 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>) : (<buttontype="button"@@ -55,7 +55,7 @@ export function CompositionBreadcrumb({ stack, onNavigate }: CompositionBreadcrutrackStudioEvent("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.tsnew file mode 100644index 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.tsindex 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.tsxindex 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 (<divdiff --git a/packages/studio/src/player/components/timelineKeyboardNavigation.ts b/packages/studio/src/player/components/timelineKeyboardNavigation.tsindex 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[]): TimelinrowId,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.tsxindex 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.tsindex 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 };