@hyperframes/studio 0.8.56 → 0.8.58

package/dist/index.d.ts

@@ -304,7 +304,15 @@ interface PlayerProps {
     projectId?: string;
     directUrl?: string;
     onLoad: () => void;
+    /** Fires once the loaded document is painted and every loader (shader, assets) has cleared. */
+    onReadyToShowChange?: (ready: boolean) => void;
+    onPreviewError?: (message: string) => void;
     onCompositionLoadingChange?: (loading: boolean) => void;
+    onPainted?: (details: {
+        iframe: HTMLIFrameElement;
+        startedAt: number;
+        loadId: number;
+    }) => void;
     portrait?: boolean;
     style?: React.CSSProperties;
     suppressLoadingOverlay?: boolean;
@@ -1370,6 +1378,23 @@ interface CompositionThumbnailProps {
 /** Server-rendered composition poster, deduplicated and budgeted by project/session. */
 declare const CompositionThumbnail: react.NamedExoticComponent<CompositionThumbnailProps>;
 
+/**
+ * React callbacks for synchronising the player store from iframe runtime data.
+ *
+ * Covers four related concerns:
+ *  - processTimelineMessage  — turn a clip-manifest postMessage into TimelineElements
+ *  - enrichMissingCompositions — fill gaps the manifest misses (element-ref starts)
+ *  - initializeAdapter        — called after iframe load: seek, set duration, read elements
+ *  - onIframeLoad             — orchestrates initializeAdapter with a message-based fallback
+ */
+
+type PreviewIframeRole = "live" | "shadow";
+interface PreviewIframeSlot {
+    gen: number;
+    role: PreviewIframeRole;
+    url?: string;
+}
+
 /**
  * Runtime iframe integration utilities.
  *
@@ -1404,7 +1429,13 @@ declare const CompositionThumbnail: react.NamedExoticComponent<CompositionThumbn
  */
 declare function resolveIframe(el: Element | null): HTMLIFrameElement | null;
 
-declare function useTimelinePlayer(): {
+interface UseTimelinePlayerOptions {
+    /** Runs right after a reloaded preview becomes the live iframe. */
+    onShadowPromoted?: () => void;
+    /** A reload was abandoned (cause in the message); the previous preview is still showing. */
+    onPreviewReloadFailed?: (message: string) => void;
+}
+declare function useTimelinePlayer({ onShadowPromoted, onPreviewReloadFailed, }?: UseTimelinePlayerOptions): {
     iframeRef: react.RefObject<HTMLIFrameElement | null>;
     play: () => void;
     pause: () => void;
@@ -1412,12 +1443,47 @@ declare function useTimelinePlayer(): {
     seek: (time: number, options?: {
         keepPlaying?: boolean;
     }) => boolean;
-    onIframeLoad: () => void;
+    onIframeLoad: (context?: number) => void;
     refreshPlayer: () => void;
     saveSeekPosition: () => void;
     resetPlayer: () => void;
+    previewSlots: PreviewIframeSlot[];
+    onShadowIframeLoad: (context?: number) => void;
+    onShadowReadyChange: (gen: number, ready: boolean) => void;
+    onShadowError: (gen: number, cause: string) => void;
+    setShadowIframeNode: (node: HTMLIFrameElement | null) => void;
+    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 {
@@ -1496,10 +1562,21 @@ interface EditorShellProps extends TimelineEditCallbackDeps {
 }
 declare function EditorShell({ panels, timelineToolbar, renderClipContent, handleTimelineElementDelete, handleTimelineAssetDrop, handleTimelineBlockDrop, handleTimelineCompositionDrop, handlePreviewBlockDrop, handleTimelineFileDrop, handleTimelineElementMove, handleTimelineElementsMove, handleTimelineElementResize, handleTimelineGroupResize, handleToggleTrackHidden, setAudioGroupAttribute, handleGroupClips, setElementFxAttribute, handleBlockedTimelineEdit, handleTimelineElementSplit, handleRazorSplit, handleRazorSplitAll, onCopyClip, onPasteClip, onDuplicateClip, canPasteClip, setCompIdToSrc, setCompositionLoading, shouldShowMotionPath, shouldShowSelectedDomBounds, isGestureRecording, recordingState, onToggleRecording, blockPreview, gestureOverlay, readOnlyPreview, readOnlyPreviewReason, }: EditorShellProps): react_jsx_runtime.JSX.Element;
 
+interface PreviewCompositionSize {
+    width: number;
+    height: number;
+}
+
 interface NLEPreviewProps {
     projectId: string;
     iframeRef: RefObject<HTMLIFrameElement | null>;
     onIframeLoad: () => void;
+    previewSlots: PreviewIframeSlot[];
+    onShadowIframeLoad: (gen: number) => void;
+    onShadowReadyChange: (gen: number, ready: boolean) => void;
+    onShadowError: (gen: number, message: string) => void;
+    setShadowIframeNode: (node: HTMLIFrameElement | null) => void;
+    resetPreviewSlots: () => void;
     onCompositionLoadingChange?: (loading: boolean) => void;
     portrait?: boolean;
     directUrl?: string;
@@ -1508,10 +1585,6 @@ interface NLEPreviewProps {
     /** Reports the authored composition size measured from the loaded preview. */
     onCompositionSizeChange?: (size: PreviewCompositionSize | null) => void;
 }
-interface PreviewCompositionSize {
-    width: number;
-    height: number;
-}
 declare const NLEPreview: react.NamedExoticComponent<NLEPreviewProps>;
 
 interface CompositionLevel {
@@ -1539,9 +1612,51 @@ interface DomEditCompositionRect {
 
 /**
  * Where the composition sits inside `overlayRef`, in overlay pixels, plus the scale from
- * composition units to pixels. Follows the live preview iframe across reloads.
+ * composition units to pixels.
  */
-declare function usePreviewCompositionRect(overlayRef: RefObject<HTMLDivElement | null>): DomEditCompositionRect;
+declare function usePreviewCompositionRect(overlayRef: RefObject<HTMLDivElement | null>, iframe: HTMLIFrameElement | null): DomEditCompositionRect;
+
+interface PreviewSnapPreferences {
+    snapEnabled: boolean;
+    gridVisible: boolean;
+    gridSpacing: number;
+    snapToGrid: boolean;
+}
+interface PreviewOverlayContextValue {
+    state: {
+        snapPrefs: PreviewSnapPreferences;
+        rulerVisible: boolean;
+        safeMarginsVisible: boolean;
+        iframeRef: RefObject<HTMLIFrameElement | null>;
+        compositionRect: DomEditCompositionRect;
+    };
+    actions: {
+        setSnapPrefs: (patch: Partial<PreviewSnapPreferences>) => void;
+        toggleRulers: () => void;
+        toggleSafeMargins: () => void;
+    };
+}
+interface PreviewOverlayProviderProps {
+    iframe?: HTMLIFrameElement | null;
+    children: ReactNode;
+}
+declare function PreviewOverlayProvider({ iframe, children }: PreviewOverlayProviderProps): react_jsx_runtime.JSX.Element;
+declare function usePreviewOverlayContext(): PreviewOverlayContextValue;
+
+/** Ruler and safe-margin boxes drawn over the preview pane, never inside the composition. */
+declare const PreviewGuides: react.NamedExoticComponent<object>;
+
+declare const GridOverlay: react.NamedExoticComponent<object>;
+
+declare const SnapToolbar: react.NamedExoticComponent<object>;
+
+type GuideKey = "rulerVisible" | "safeMarginsVisible";
+interface PreviewGuidesState {
+    rulerVisible: boolean;
+    safeMarginsVisible: boolean;
+    toggle: (key: GuideKey) => void;
+}
+declare const usePreviewGuidesStore: zustand.UseBoundStore<zustand.StoreApi<PreviewGuidesState>>;
 
 interface SourceEditorProps {
     content: string;
@@ -2187,4 +2302,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, 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, type PreviewState, PropertyPanel, type RenderJob, RenderQueue, type RenderQueueProps, type ResolutionPreset, Select, type SelectOption, type SelectProps, Slider, type SliderProps, 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, 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, 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, usePlayerHandle, usePlayerStore, usePreviewCompositionRect, usePreviewGuidesStore, usePreviewOverlayContext, useProjectFileWriter, useRenderQueue, useTimelineEditing, useTimelinePlayer };

package/dist/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-BlkJ_Axe.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-ZmBtVrEm.css">
+    <script type="module" crossorigin src="/assets/index-d8ferjRc.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DKJpHYYd.css">
   </head>
   <body>
     <div data-hf-id="hf-aph5" id="root"></div>