hyperframes 0.8.57 → 0.8.59

package/dist/studio/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ButtonHTMLAttributes, ReactNode, ElementType, ComponentPropsWithoutRef, ReactElement, RefObject, MutableRefObject } from 'react';
+import { ButtonHTMLAttributes, ReactNode, ElementType, ComponentPropsWithoutRef, ReactElement, RefObject, MutableRefObject, DragEventHandler, ComponentProps, RefCallback, MouseEvent, CSSProperties, UIEvent, PointerEvent } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { Tabs as Tabs$1 } from '@base-ui/react/tabs';
 import * as node_modules_cn_dist_types from 'node_modules/cn/dist/types';
@@ -8,9 +8,9 @@ import { Menu as Menu$1 } from '@base-ui/react/menu';
 import { Popover as Popover$1 } from '@base-ui/react/popover';
 import { RuntimeTimelineClipIdentity, HyperframePickerElementInfo } from '@hyperframes/core';
 import { GsapAnimation, PropertyGroupName } from '@hyperframes/core/gsap-parser';
+import { MusicBeatAnalysis } from '@hyperframes/core/beats';
 import * as zustand from 'zustand';
 import { StoreApi } from 'zustand';
-import { MusicBeatAnalysis } from '@hyperframes/core/beats';
 import { GsapAnimation as GsapAnimation$1, ArcPathSegment } from '@hyperframes/parsers/gsap-parser';
 import { CanvasResolution } from '@hyperframes/parsers';
 import { Composition } from '@hyperframes/sdk';
@@ -336,6 +336,8 @@ interface PlayerControlsProps {
 }
 declare const PlayerControls: react.NamedExoticComponent<PlayerControlsProps>;
 
+declare function TimelineRulerPart(): react_jsx_runtime.JSX.Element;
+
 interface UserBeat {
     time: number;
     strength: number;
@@ -566,13 +568,13 @@ interface PlaybackReadinessSlice {
 }
 declare function createPlaybackReadinessSlice(set: StoreApi<PlaybackReadinessSlice>["setState"]): PlaybackReadinessSlice;
 
-interface TimelineTimeRange {
+interface TimelineTimeRange$1 {
     t0: number;
     t1: number;
 }
 interface RangeSelectionSlice {
     /** Shift-drag ruler range in seconds, normalized so t0 <= t1. */
-    rangeSelection: TimelineTimeRange | null;
+    rangeSelection: TimelineTimeRange$1 | null;
 }
 
 /**
@@ -629,6 +631,11 @@ interface TimelineElement {
     playbackRate?: number;
     sourceDuration?: number;
     volume?: number;
+    /** `data-has-audio="true"` on a video: its sound is mixed, so it takes audio affordances (fades). */
+    hasAudio?: boolean;
+    /** Clip-edge fades from `data-fade-in` / `data-fade-out`, seconds; absent means none. */
+    fadeIn?: number;
+    fadeOut?: number;
     /** Verbatim `data-fx-chain` / `data-automation`; see automationLaneData. */
     fxChain?: string;
     automation?: string;
@@ -1081,6 +1088,12 @@ interface TimelineStackingReorderIntent {
 }
 
 type BlockedTimelineEditIntent = "move" | "resize-start" | "resize-end";
+interface TimelineRangeSelection {
+    start: number;
+    end: number;
+    anchorX: number;
+    anchorY: number;
+}
 
 /**
  * Durability report for a patch-batches commit. `durable === false` means the
@@ -1280,6 +1293,12 @@ interface TimelineEditCallbacks {
     onTogglePropertyGroupKeyframe?: (element: TimelineElement, target: TimelinePropertyGroupKeyframeToggle) => Promise<void> | void;
 }
 
+interface TimelineTrackStyle {
+    clip: string;
+    accent: string;
+    label: string;
+    clipActive?: string;
+}
 interface TimelineTheme {
     shellBackground: string;
     shellBorder: string;
@@ -1332,7 +1351,7 @@ interface TimelineProps extends TimelineDropCallbacks, TimelineEditOverrides {
     onDeleteElement?: (element: TimelineElement) => Promise<void> | void;
     onSelectElement?: (element: TimelineElement | null) => void;
     /** Notification only; null when cleared. The value lives in usePlayerStore.rangeSelection. */
-    onRangeSelect?: (range: TimelineTimeRange | null) => void;
+    onRangeSelect?: (range: TimelineTimeRange$1 | null) => void;
     onCopyClip?: () => boolean;
     onPasteClip?: () => Promise<void>;
     onDuplicateClip?: () => Promise<boolean>;
@@ -1340,7 +1359,528 @@ interface TimelineProps extends TimelineDropCallbacks, TimelineEditOverrides {
     theme?: Partial<TimelineTheme>;
 }
 
-declare const Timeline: react.NamedExoticComponent<TimelineProps>;
+interface TimelineEmptyStateProps {
+    isDragOver: boolean;
+    onFileDrop?: boolean;
+    onDragOver: DragEventHandler<HTMLDivElement>;
+    onDragLeave: DragEventHandler<HTMLDivElement>;
+    onDrop: DragEventHandler<HTMLDivElement>;
+}
+declare function TimelineEmptyState({ isDragOver, onFileDrop, onDragOver, onDragLeave, onDrop, }: TimelineEmptyStateProps): react_jsx_runtime.JSX.Element;
+
+interface Rect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+
+type TimelineSnapType = "beat" | "playhead" | "clip-edge";
+interface TimelineSnapTarget {
+    time: number;
+    type: TimelineSnapType;
+}
+
+interface DraggedClipState {
+    /** Pointer captured by the stable viewport coordinator for this gesture. */
+    pointerId: number;
+    element: TimelineElement;
+    originClientX: number;
+    originClientY: number;
+    originScrollLeft: number;
+    originScrollTop: number;
+    pointerClientX: number;
+    pointerClientY: number;
+    pointerOffsetX: number;
+    pointerOffsetY: number;
+    previewStart: number;
+    previewTrack: number;
+    /**
+     * The lane the POINTER aims at (from the drag's vertical position), before
+     * collision resolution. `previewTrack` is where the clip actually LANDS —
+     * which may differ from `desiredTrack` when the aimed span is occupied and the
+     * collision rules bump the dragged clip to a free lane. The commit reads this
+     * to tell a deliberate VERTICAL lane change (pointer aimed at another lane →
+     * stacking sync allowed) from a plain HORIZONTAL drag whose clip merely got
+     * bumped sideways (never touches z). Optional: when absent the commit falls
+     * back to `previewTrack` (pre-existing behaviour).
+     */
+    desiredTrack?: number;
+    /**
+     * When non-null, the drop inserts a NEW track at this visual row boundary
+     * (0 = above the top lane, trackOrder.length = below the bottom) instead of
+     * landing on previewTrack. Drives the insertion-line indicator.
+     */
+    insertRow: number | null;
+    /** Snap target the clip will land on, for the guide highlight. */
+    snapTime: number | null;
+    snapType: TimelineSnapType | null;
+    started: boolean;
+}
+interface ResizingClipState {
+    /** Pointer captured by the stable viewport coordinator for this gesture. */
+    pointerId: number;
+    element: TimelineElement;
+    edge: "start" | "end";
+    originClientX: number;
+    /**
+     * scrollLeft at gesture start. Edge auto-scroll moves the content under a
+     * stationary pointer, so the trim math folds (current − origin) scrollLeft
+     * into the pointer x — mirroring resolveTimelineMove's scroll compensation.
+     * Optional so pre-existing constructors/tests stay valid; when absent the
+     * first preview update captures the current scrollLeft.
+     */
+    originScrollLeft?: number;
+    previewStart: number;
+    previewDuration: number;
+    previewPlaybackStart?: number;
+    /** Snap target the trimmed edge landed on, for the guide highlight. */
+    snapTime?: number | null;
+    snapType?: TimelineSnapType | null;
+    /** Coordinator-owned group projection; canonical elements change only on commit. */
+    groupPreview?: readonly {
+        key: string;
+        start: number;
+        duration: number;
+        playbackStart?: number;
+    }[];
+    started: boolean;
+}
+interface BlockedClipState {
+    pointerId: number;
+    element: TimelineElement;
+    intent: BlockedTimelineEditIntent;
+    originClientX: number;
+    originClientY: number;
+    started: boolean;
+}
+
+interface TimelineTimeRange {
+    readonly start: number;
+    readonly end: number;
+}
+interface TimelineClipInterval {
+    readonly element: TimelineElement;
+    readonly identity: string;
+    readonly ordinal: number;
+    readonly start: number;
+    readonly end: number;
+}
+interface TimelineClipRowIndex {
+    readonly byStart: readonly TimelineClipInterval[];
+    readonly treeLeafCount: number;
+    readonly maxPositiveEndTree: readonly number[];
+    readonly maxPointStartTree: readonly number[];
+    readonly byIdentity: ReadonlyMap<string, readonly TimelineClipInterval[]>;
+}
+interface TimelineClipIndex {
+    readonly rows: ReadonlyMap<number, TimelineClipRowIndex>;
+}
+
+interface TimelineRowGeometry {
+    readonly rowKeys: readonly number[];
+    readonly rowHeights: readonly number[];
+    /** Cumulative row boundaries, including the final bottom boundary. */
+    readonly rowOffsets: readonly number[];
+    readonly rowsHeight: number;
+    readonly canvasHeight: number;
+    getRowIndex(rowKey: number): number;
+    getRowHeight(row: number): number;
+    getRowTop(row: number): number;
+    getRowFromY(contentY: number): number;
+    getRowPositionFromY(contentY: number): {
+        rowFloat: number;
+        row: number;
+        fraction: number;
+        rowHeight: number;
+    };
+}
+
+type TrackVisualStyle = TimelineTrackStyle;
+
+interface TimelineVirtualRow {
+    readonly index: number;
+    readonly rowKey: number;
+}
+
+/**
+ * Pure geometry for the LIVE multi-selection drag preview.
+ *
+ * Visual model (matches main): while a selected clip is dragged, ALL selected
+ * clips move together LIVE as one rigid formation following the cursor. The
+ * GRABBED clip is drawn as the free-floating ghost; every OTHER selected member
+ * ("passenger") slides by the SAME time delta via a cheap compositor
+ * `translateX` (no re-layout). Passengers do NOT stay still, and they do NOT lag
+ * behind individually — the whole formation moves by one delta, spacing locked.
+ *
+ * That single delta is the GRABBED clip's `draggedPreviewStart − draggedOriginStart`.
+ * The preview start is ALREADY group-clamped upstream (updateDraggedClipPreview
+ * runs clampGroupMoveDelta before setting it), so this delta is the clamped delta:
+ * the instant any member would cross 0 the grabbed clip stops and every passenger
+ * stops with it — the formation never deforms. On DROP the commit shifts every
+ * selected clip by this same delta (see timelineClipDragCommit / useTimelineClipDrag).
+ *
+ * Track changes apply to the grabbed clip only (mirroring the commit); passengers
+ * keep their lanes, so only their x moves.
+ */
+interface MultiDragPreviewInput {
+    /** The drag is live (past the movement threshold). */
+    dragStarted: boolean;
+    /** Key of the clip under the pointer. */
+    draggedKey: string;
+    /** The dragged clip's committed start (pre-drag). */
+    draggedOriginStart: number;
+    /** The dragged clip's live preview start (already group-clamped upstream). */
+    draggedPreviewStart: number;
+    /** The current multi-selection (store.selectedElementIds). */
+    selectedKeys: ReadonlySet<string>;
+}
+
+/** One resolved audio group, positioned in the row order. */
+interface TimelineTrackGroupInfo {
+    id: string;
+    label: string;
+    /**
+     * Synthetic sort key for the group's own row — the same fractional-key
+     * convention sub-composition expansion already uses (see
+     * timelineTrackDisplay.ts): the first (lowest) member track's number minus
+     * 0.5, so it slots in immediately above that member.
+     */
+    anchorKey: number;
+    /** Member track numbers, ascending. */
+    memberTracks: number[];
+    /**
+     * Every clip under this group, in member-track order — INDEPENDENT of whether
+     * the group is expanded.
+     *
+     * Collapsing a group stops emitting its member rows into `tracks`, so anything
+     * that recovered member elements by looking them up there got an empty list in
+     * the default (collapsed) state — silently disabling the
+     * automation-lane count, and the bus strip's member labels. Membership is not
+     * a display concern, so it does not travel through the display list.
+     */
+    memberElements: TimelineElement[];
+    /** The group element's `data-volume`, mirrored from a member's parse (B7's slider). */
+    volume: number;
+    /** The group element's `data-hidden`, mirrored from a member's parse (B5's group mute). */
+    hidden: boolean;
+    /** The group element's serialized `data-fx-chain`, mirrored from a member's parse (C1's FX entry). */
+    fxChain?: string;
+    /** The group element's serialized `data-automation` — the group's OWN lanes,
+     *  which are what its `∿` discloses (groups doc §5). */
+    automation?: string;
+}
+
+interface TimelineLogicalItem {
+    id: string;
+    kind: "clip" | "keyframe" | "ease";
+    rowId: string;
+    elementId: string;
+    /** The item's time anchor. Clips use their midpoint; ease controls use the segment midpoint. */
+    time: number;
+    keyframeTarget?: TimelineKeyframeTarget;
+}
+interface TimelineLogicalRow {
+    id: string;
+    kind: "row";
+    physicalTrackKey: number;
+    logicalIndex: number;
+    level: 1 | 2 | 3;
+    parentId: string | null;
+    elementId: string | null;
+    /** Set only on a group's own row (level 1, no clips of its own). */
+    groupId?: string;
+    expandable: boolean;
+    expanded: boolean;
+    propertyGroup?: PropertyGroupName;
+    items: readonly TimelineLogicalItem[];
+}
+
+/**
+ * Props shared by the scroll container ({@link import("./TimelineCanvas")}) and
+ * the lane renderer ({@link import("./TimelineLanes")}). TimelineCanvas passes
+ * these straight through via spread, so they are declared once here and both
+ * prop types compose from this base — no duplicated prop list. Kept in its own
+ * module so neither side has to import the other just to name the contract.
+ */
+interface TimelineLaneBaseProps {
+    pps: number;
+    contentOrigin: number;
+    contentGutter: number;
+    trackContentWidth: number;
+    theme: TimelineTheme;
+    displayTrackOrder: number[];
+    rowHeights: readonly number[];
+    rowGeometry: TimelineRowGeometry;
+    virtualRows: readonly TimelineVirtualRow[];
+    logicalRows: readonly TimelineLogicalRow[];
+    focusedTargetId: string | null;
+    rowsVirtualized: boolean;
+    clipIndex: TimelineClipIndex;
+    renderTimeRange: TimelineTimeRange;
+    visibleTimeRange: TimelineTimeRange;
+    pinnedClipIdentities: ReadonlySet<string>;
+    trackOrder: number[];
+    tracks: [number, TimelineElement[]][];
+    trackStyles: Map<number, TrackVisualStyle>;
+    laneCounts: ReadonlyMap<string, number>;
+    selectedElementId: string | null;
+    selectedElementIds: Set<string>;
+    hoveredClip: string | null;
+    draggedClip: DraggedClipState | null;
+    blockedClipRef: React.RefObject<BlockedClipState | null>;
+    suppressClickRef: React.RefObject<boolean>;
+    scrollRef: React.RefObject<HTMLDivElement | null>;
+    renderClipContent?: (element: TimelineElement, style: {
+        clip: string;
+        label: string;
+    }, context: TimelineClipRenderContext) => ReactNode;
+    renderClipOverlay?: (element: TimelineElement) => ReactNode;
+    onDrillDown?: (element: TimelineElement) => void;
+    onSelectElement?: (element: TimelineElement | null) => void;
+    setHoveredClip: (key: string | null) => void;
+    setShowPopover: (v: boolean) => void;
+    setRangeSelection: (v: null) => void;
+    setResizingClip: (v: ResizingClipState | null) => void;
+    setDraggedClip: (v: DraggedClipState | null) => void;
+    setSelectedElementId: (id: string | null) => void;
+    shiftClickClipRef: React.RefObject<{
+        element: TimelineElement;
+        anchorX: number;
+        anchorY: number;
+    } | null>;
+    getPreviewElement: (element: TimelineElement) => TimelineElement;
+    getTrackStyle: (tag: string) => TrackVisualStyle;
+    keyframeCache?: Map<string, KeyframeCacheEntry>;
+    gsapAnimations: Map<string, GsapAnimation[]>;
+    selectedKeyframes: Set<string>;
+    currentTime: number;
+    onSeek?: (time: number) => void;
+    onSelectSegment?: (elementId: string, target: TimelineKeyframeTarget) => void;
+    onClickKeyframe?: (element: TimelineElement, target: TimelineKeyframeTarget) => void;
+    onShiftClickKeyframe?: (elementId: string, target: TimelineKeyframeTarget) => void;
+    onContextMenuKeyframe?: (e: React.MouseEvent, elementId: string, target: TimelineKeyframeTarget) => void;
+    onMoveKeyframe?: (elementId: string, keyframe: TimelineKeyframeTarget, toClipPercentage: number, propertyGroup?: string, tweenPercentage?: number, animationId?: string) => Promise<boolean>;
+    onContextMenuClip?: (e: React.MouseEvent, element: TimelineElement) => void;
+    /**
+     * Right-click on EMPTY lane space (not on a clip — those preventDefault
+     * before this fires — not the gutter/ruler, not below the lanes). `time` is
+     * the timeline time (seconds) under the pointer on that lane.
+     */
+    onContextMenuLane?: (e: React.MouseEvent, track: number, time: number) => void;
+    beatAnalysis?: MusicBeatAnalysis | null;
+    /** Resolved audio groups, positioned in row order — see useTimelineTrackDerivations. */
+    groups: readonly TimelineTrackGroupInfo[];
+}
+
+/** An empty interval on the lane, [start, end) in seconds. */
+interface TrackGapInterval {
+    start: number;
+    end: number;
+}
+
+/**
+ * One lane's gap strips for the TimelineCanvas overlay.
+ *
+ * kind "hover"    — the gap(s) a hovered "Close gap" / "Close all gaps" menu
+ *                   row would collapse: the loud affordance.
+ * kind "selected" — every empty interval on a click-selected clip's lane: the
+ *                   quiet always-on hint (single click-selection only — a
+ *                   marquee multi-select spans lanes and would paint noise).
+ */
+interface TimelineLaneGapStrips {
+    track: number;
+    intervals: TrackGapInterval[];
+    kind: "hover" | "selected";
+}
+
+interface KeyframeDiamondContextMenuState {
+    x: number;
+    y: number;
+    /** Timeline project session that created this portaled target. */
+    sessionEpoch?: number;
+    element: TimelineElement;
+    elementId: string;
+    percentage: number;
+    tweenPercentage?: number;
+    propertyGroup?: string;
+    animationId?: string;
+    currentEase?: string;
+}
+
+type TimelineCanvasState = Omit<TimelineLaneBaseProps, "setRangeSelection" | "setResizingClip" | "setDraggedClip" | "renderClipContent" | "renderClipOverlay"> & {
+    major: number[];
+    minor: number[];
+    totalH: number;
+    effectiveDuration: number;
+    majorTickInterval: number;
+    rangeSelection: TimelineRangeSelection | null;
+    marqueeRect: Rect | null;
+    resizingClip: ResizingClipState | null;
+    isScrubbing: boolean;
+    playheadRef: React.RefObject<HTMLDivElement | null>;
+    laneGapStrips: TimelineLaneGapStrips[];
+    dropPreview: TimelineDropPlacement | null;
+    setRangeSelection: (value: TimelineRangeSelection | null) => void;
+    setResizingClip: (value: ResizingClipState | null) => void;
+    setDraggedClip: (value: TimelineLaneBaseProps["draggedClip"]) => void;
+    beatDragging: boolean;
+    onResizeElement: TimelineEditCallbacks["onResizeElement"];
+    onMoveElement: TimelineEditCallbacks["onMoveElement"];
+    draggedElement: TimelineElement | null;
+    snapGuide: TimelineSnapTarget | null;
+    multiDragPreview: MultiDragPreviewInput | null;
+    onToggleTrackHidden: TimelineEditCallbacks["onToggleTrackHidden"];
+    onTogglePropertyGroupKeyframe: TimelineEditCallbacks["onTogglePropertyGroupKeyframe"];
+    onRazorSplit: TimelineEditCallbacks["onRazorSplit"];
+    onRazorSplitAll: TimelineEditCallbacks["onRazorSplitAll"];
+};
+interface ClipContextMenuState {
+    x: number;
+    y: number;
+    element: TimelineElement;
+    sessionEpoch: number;
+}
+interface TrackGapContextMenuState {
+    x: number;
+    y: number;
+    gapWidth: number | null;
+    canCloseGap: boolean;
+    canCloseAllGaps: boolean;
+    hasAnyGaps: boolean;
+}
+interface TimelineOverlaysState {
+    elements: readonly TimelineElement[];
+    elementsRef: {
+        current: readonly TimelineElement[];
+    };
+    theme: TimelineTheme;
+    showShortcutHint: boolean;
+    showPopover: boolean;
+    rangeSelection: TimelineRangeSelection | null;
+    setShowPopover: (value: boolean) => void;
+    setRangeSelection: (value: TimelineRangeSelection | null) => void;
+    kfContextMenu: KeyframeDiamondContextMenuState | null;
+    setKfContextMenu: (value: KeyframeDiamondContextMenuState | null) => void;
+    onDeleteKeyframe: TimelineEditCallbacks["onDeleteKeyframe"];
+    onDeleteAllKeyframes: TimelineEditCallbacks["onDeleteAllKeyframes"];
+    onMoveKeyframeToPlayhead: TimelineEditCallbacks["onMoveKeyframeToPlayhead"];
+    clipContextMenu: ClipContextMenuState | null;
+    setClipContextMenu: (value: ClipContextMenuState | null) => void;
+    currentTime: number;
+    onSplitElement: TimelineEditCallbacks["onSplitElement"];
+    pinZoomBeforeEdit: () => void;
+    onDeleteElement?: (element: TimelineElement) => Promise<void> | void;
+    onCopyClip?: () => boolean;
+    onPasteClip?: () => Promise<void>;
+    onDuplicateClip?: () => Promise<boolean>;
+    canPasteClip?: () => boolean;
+    gapContextMenu: TrackGapContextMenuState | null;
+    onDismissGapContextMenu: () => void;
+    onCloseTrackGap: () => void;
+    onCloseAllTrackGaps: () => void;
+    onHoverGapAction: (action: "close-gap" | "close-all" | null) => void;
+}
+interface TimelineContainerProps {
+    ref: RefCallback<HTMLDivElement>;
+    "aria-label": string;
+    "data-timeline-element-count": number;
+    className: string;
+    onMouseMove: (event: MouseEvent<HTMLDivElement>) => void;
+    onMouseLeave: () => void;
+    style: CSSProperties;
+}
+interface TimelineViewportProps {
+    ref: RefCallback<HTMLDivElement>;
+    "data-timeline-scroll-viewport": boolean;
+    "data-timeline-auto-scroll-left-inset": number;
+    tabIndex: number;
+    className: string;
+    onScroll: (event: UIEvent<HTMLDivElement>) => void;
+    onFocus: (event: React.FocusEvent<HTMLDivElement>) => void;
+    onBlur: (event: React.FocusEvent<HTMLDivElement>) => void;
+    onDragOver: (event: React.DragEvent<HTMLDivElement>) => void;
+    onDragLeave: (event: React.DragEvent<HTMLDivElement>) => void;
+    onDrop: (event: React.DragEvent<HTMLDivElement>) => void;
+    onPointerDown: (event: PointerEvent<HTMLDivElement>) => void;
+    onPointerMove: (event: PointerEvent<HTMLDivElement>) => void;
+    onPointerUp: (event: PointerEvent<HTMLDivElement>) => void;
+    onPointerCancel: (event: PointerEvent<HTMLDivElement>) => void;
+    onLostPointerCapture: (event: PointerEvent<HTMLDivElement>) => void;
+}
+interface TimelineState {
+    timelineReady: boolean;
+    elements: readonly TimelineElement[];
+    selectedElementId: string | null;
+    sessionEpoch: number;
+    keyframeCache: Map<string, KeyframeCacheEntry>;
+    canvas: TimelineCanvasState;
+    overlays: TimelineOverlaysState;
+}
+interface TimelineActions {
+    renderClipContent: TimelineLaneBaseProps["renderClipContent"];
+    renderClipOverlay: TimelineLaneBaseProps["renderClipOverlay"];
+    setFocusedEaseSegment: (target: {
+        animationId: string;
+        collidingAnimationTargets?: AnimationKeyframeTarget[];
+        tweenPercentage: number;
+        elementId: string;
+    }) => void;
+}
+interface TimelineMeta {
+    emptyState: ComponentProps<typeof TimelineEmptyState>;
+    containerProps: TimelineContainerProps;
+    viewportProps: TimelineViewportProps;
+    razorGuide: ReactNode;
+}
+interface TimelineContextValue {
+    state: TimelineState;
+    actions: TimelineActions;
+    meta: TimelineMeta;
+}
+declare function TimelineProvider({ children, ...props }: TimelineProps & {
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useTimelineContext(): TimelineContextValue;
+
+declare function TimelineOverlays(): react_jsx_runtime.JSX.Element;
+
+/** The provider-backed canvas shell. */
+declare function TimelineFrame(): react_jsx_runtime.JSX.Element;
+/** The provider-backed ruler. */
+declare const TimelineRuler: typeof TimelineRulerPart;
+/**
+ * The provider-backed lane renderer. TimelineFrame remains the composed Studio
+ * canvas; this part is exported for hosts that own the canvas arrangement.
+ */
+declare function TimelineLanes(): react_jsx_runtime.JSX.Element;
+/** The provider-backed playhead indicator. */
+declare function TimelinePlayhead(): react_jsx_runtime.JSX.Element;
+/** The provider-backed razor guide. */
+declare function TimelineRazorGuide(): react.ReactNode;
+
+declare function TimelineEmptyStatePart(): react_jsx_runtime.JSX.Element;
+declare function TimelineShortcutHint(): react_jsx_runtime.JSX.Element;
+declare function TimelineEditPopover(): react_jsx_runtime.JSX.Element;
+declare function TimelineClipMenu(): react_jsx_runtime.JSX.Element;
+declare function TimelineKeyframeMenu(): react_jsx_runtime.JSX.Element;
+declare function TimelineGapMenu(): react_jsx_runtime.JSX.Element;
+
+declare const Timeline: react.NamedExoticComponent<TimelineProps> & {
+    Provider: typeof TimelineProvider;
+    Frame: typeof TimelineFrame;
+    Ruler: typeof TimelineRulerPart;
+    Lanes: typeof TimelineLanes;
+    Playhead: typeof TimelinePlayhead;
+    RazorGuide: typeof TimelineRazorGuide;
+    ShortcutHint: typeof TimelineShortcutHint;
+    EditPopover: typeof TimelineEditPopover;
+    ClipMenu: typeof TimelineClipMenu;
+    KeyframeMenu: typeof TimelineKeyframeMenu;
+    GapMenu: typeof TimelineGapMenu;
+    EmptyState: typeof TimelineEmptyStatePart;
+    Overlays: typeof TimelineOverlays;
+};
 
 type ThumbnailPriority = "overscan" | "visible" | "interaction";
 
@@ -1455,6 +1995,35 @@ declare function useTimelinePlayer({ onShadowPromoted, onPreviewReloadFailed, }?
     resetPreviewSlots: () => void;
 };
 
+interface PlayerHandleElement {
+    id: string;
+    start: number;
+    end: number;
+    selector?: string;
+    sourceFile?: string;
+    compositionSrc?: string;
+}
+type PlayerHandleListener = () => void;
+type PlayerHandleTimeListener = (time: number) => void;
+interface PlayerHandle {
+    ready: boolean;
+    playing: boolean;
+    seek: (seconds: number) => boolean;
+    play: () => void;
+    pause: () => void;
+    togglePlay: () => void;
+    readonly currentTime: number;
+    duration: number;
+    elements: PlayerHandleElement[];
+    subscribe: (listener: PlayerHandleListener) => () => void;
+    subscribeTime: (listener: PlayerHandleTimeListener) => () => void;
+}
+/**
+ * Reads and controls the shell player. Call this under EditorShell/NLEProvider;
+ * the provider owns the mounted preview iframe and the single player instance.
+ */
+declare function usePlayerHandle(): PlayerHandle;
+
 declare function formatTime(time: number): string;
 
 interface TimelineEditCallbackDeps {
@@ -2258,7 +2827,7 @@ interface TimelinePaneProps {
     onCompositionDrop?: (sourcePath: string, placement: Pick<TimelineElement, "start" | "track">) => Promise<void> | void;
     onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
     onSelectTimelineElement?: (element: TimelineElement | null) => void;
-    onRangeSelect?: (range: TimelineTimeRange | null) => void;
+    onRangeSelect?: (range: TimelineTimeRange$1 | null) => void;
     /** Copy/paste/duplicate act on the store's own selection, not a passed
      *  element, so unlike onDeleteElement they need no composition-basis wrapper. */
     onCopyClip?: () => boolean;
@@ -2273,4 +2842,4 @@ declare function TimelineEditProvider({ value, children, }: {
     children: ReactNode;
 }): react_jsx_runtime.JSX.Element;
 
-export { type AgentModalAnchorPoint, type AgentPromptElementInfo, AskAgentModal, type AskAgentModalProps, type BlockedTimelineEditIntent, Button, type ButtonSize, type ButtonVariant, type CanEditTimelineElement, CompositionBreadcrumb, type CompositionDimensions, type CompositionLevel, CompositionThumbnail, ContextMenu, type EditHistoryHandle, EditorShell, type EditorShellProps, type ExternalFileChangeBlockedState, type ExternalFileChangeCoordinatorHandle, ExternalFileConflictBanner, type FfmpegStatus, FileTree, GridOverlay, HyperframesLoader, type HyperframesLoaderProps, HyperframesLogo, IconButton, Input, type InputProps, Menu, MenuItem, type MenuItemTone, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuShortcut, NLEPreview, NumberField, type NumberFieldProps, type PatchOperation, type PersistedRenderSettings, type PickedElement, Player, PlayerControls, Popover, type PopupPreviewState, type DomEditCompositionRect as PreviewCompositionRect, PreviewGuides, PreviewOverlayProvider, type PreviewOverlayProviderProps, type PreviewSnapPreferences, type PreviewState, PropertyPanel, type RenderJob, RenderQueue, type RenderQueueProps, type ResolutionPreset, Select, type SelectOption, type SelectProps, Slider, type SliderProps, SnapToolbar, SourceEditor, type StartRenderOptions, StudioApp, StudioFileConflictError, type StudioPendingEditsDrainResult, Tab, TabPanel, Tabs, TabsList, Timeline, type TimelineEditCallbacks, type TimelineEditPermission, TimelineEditProvider, type TimelineElement, TimelinePane, type TimelinePaneProps, type TimelineTimeRange, Toggle, type ToggleProps, Tooltip, type UseEditHistoryActionsOptions, type UsePersistentEditHistoryOptions, type UseProjectFileWriterOptions, type UseTimelineEditingOptions, VideoThumbnail, applyPatch, buildPickerAgentContextPreview, buildPickerAgentPrompt, buttonBase, buttonSizes, buttonVariants, cn, fieldBase, fieldText, findElementBlock, flushStudioPendingEdits, formatTime, getPersistedRenderSettings, liveTime, mergeStyleIntoTag, parseStyleString, persistRenderSettings, popupSurface, resolveIframe, resolveSourceFile, useEditHistoryActions, useElementPicker, usePersistentEditHistory, usePlayerStore, usePreviewCompositionRect, usePreviewGuidesStore, usePreviewOverlayContext, useProjectFileWriter, useRenderQueue, useTimelineEditing, useTimelinePlayer };
+export { type AgentModalAnchorPoint, type AgentPromptElementInfo, AskAgentModal, type AskAgentModalProps, type BlockedTimelineEditIntent, Button, type ButtonSize, type ButtonVariant, type CanEditTimelineElement, CompositionBreadcrumb, type CompositionDimensions, type CompositionLevel, CompositionThumbnail, ContextMenu, type EditHistoryHandle, EditorShell, type EditorShellProps, type ExternalFileChangeBlockedState, type ExternalFileChangeCoordinatorHandle, ExternalFileConflictBanner, type FfmpegStatus, FileTree, GridOverlay, HyperframesLoader, type HyperframesLoaderProps, HyperframesLogo, IconButton, Input, type InputProps, Menu, MenuItem, type MenuItemTone, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuShortcut, NLEPreview, NumberField, type NumberFieldProps, type PatchOperation, type PersistedRenderSettings, type PickedElement, Player, PlayerControls, type PlayerHandle, type PlayerHandleElement, type PlayerHandleListener, type PlayerHandleTimeListener, Popover, type PopupPreviewState, type DomEditCompositionRect as PreviewCompositionRect, PreviewGuides, PreviewOverlayProvider, type PreviewOverlayProviderProps, type PreviewSnapPreferences, type PreviewState, PropertyPanel, type RenderJob, RenderQueue, type RenderQueueProps, type ResolutionPreset, Select, type SelectOption, type SelectProps, Slider, type SliderProps, SnapToolbar, SourceEditor, type StartRenderOptions, StudioApp, StudioFileConflictError, type StudioPendingEditsDrainResult, Tab, TabPanel, Tabs, TabsList, Timeline, TimelineClipMenu, type TimelineEditCallbacks, type TimelineEditPermission, TimelineEditPopover, TimelineEditProvider, type TimelineElement, TimelineEmptyStatePart, TimelineFrame, TimelineGapMenu, TimelineKeyframeMenu, TimelineLanes, TimelineOverlays, TimelinePane, type TimelinePaneProps, TimelinePlayhead, TimelineProvider, TimelineRazorGuide, TimelineRuler, TimelineShortcutHint, type TimelineTheme, type TimelineTimeRange$1 as TimelineTimeRange, Toggle, type ToggleProps, Tooltip, type UseEditHistoryActionsOptions, type UsePersistentEditHistoryOptions, type UseProjectFileWriterOptions, type UseTimelineEditingOptions, VideoThumbnail, applyPatch, buildPickerAgentContextPreview, buildPickerAgentPrompt, buttonBase, buttonSizes, buttonVariants, cn, fieldBase, fieldText, findElementBlock, flushStudioPendingEdits, formatTime, getPersistedRenderSettings, liveTime, mergeStyleIntoTag, parseStyleString, persistRenderSettings, popupSurface, resolveIframe, resolveSourceFile, useEditHistoryActions, useElementPicker, usePersistentEditHistory, usePlayerHandle, usePlayerStore, usePreviewCompositionRect, usePreviewGuidesStore, usePreviewOverlayContext, useProjectFileWriter, useRenderQueue, useTimelineContext, useTimelineEditing, useTimelinePlayer };

package/dist/studio/index.html

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>HyperFrames Studio</title>
-    <script type="module" crossorigin src="/assets/index-gbOCDCuZ.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-DKJpHYYd.css">
+    <script type="module" crossorigin src="/assets/index-D1KNPijK.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DZBHG9TW.css">
   </head>
   <body>
     <div data-hf-id="hf-aph5" id="root"></div>