hyperframes 0.8.55 → 0.8.57

package/dist/studio/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;
@@ -644,10 +652,8 @@ interface TimelineElement {
     audioGroupFxChain?: string;
     audioGroupAutomation?: string;
     /**
-     * Set by useTimelineRowElements on an inline-expanded sub-composition
-     * child: the absolute master-timeline start of the sub-comp host the child
-     * lives in. Presence marks the element as expanded; edits subtract it to get
-     * the child's local (sourceFile-relative) time. Works at any nesting depth.
+     * Legacy source-coordinate marker for an inline sub-composition child. The
+     * current timeline keeps sub-compositions as single rows.
      */
     expandedParentStart?: number;
     expandedHostKey?: string;
@@ -839,8 +845,6 @@ interface PlayerState extends PlayerStoreSlices {
     clipManifest: ClipManifestClip[] | null;
     setClipManifest: (clips: ClipManifestClip[] | null) => void;
     clipParentMap: Map<string, string>;
-    topLevelIds: ReadonlySet<string> | null;
-    setTopLevelIds: (ids: ReadonlySet<string> | null) => void;
     setClipParentMap: (map: Map<string, string>) => void;
     /**
      * Sub-composition DOM descendants (groups + their children) that have no
@@ -1291,6 +1295,8 @@ interface TimelineTheme {
     tickMinor: string;
     clipBackground: string;
     clipBackgroundActive: string;
+    clipBackgroundHover: string;
+    clipBackgroundDragging: string;
     clipBorder: string;
     clipBorderHover: string;
     clipBorderActive: string;
@@ -1372,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.
  *
@@ -1406,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;
@@ -1414,10 +1443,16 @@ 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;
 };
 
 declare function formatTime(time: number): string;
@@ -1491,13 +1526,28 @@ interface EditorShellProps extends TimelineEditCallbackDeps {
      * fullscreen and during a block preview; below the selection overlay past z-index 10.
      */
     gestureOverlay?: ReactNode;
+    /** Clicks still select and report; the preview cannot move, edit or delete anything. */
+    readOnlyPreview?: boolean;
+    /** Short text shown on disabled hand-edit controls while `readOnlyPreview` is set. */
+    readOnlyPreviewReason?: string;
+}
+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;
 }
-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, }: EditorShellProps): react_jsx_runtime.JSX.Element;
 
 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;
@@ -1506,10 +1556,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 {
@@ -1537,9 +1583,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;
@@ -1744,7 +1832,13 @@ interface FileTreeProps {
 }
 declare const FileTree: react.NamedExoticComponent<FileTreeProps>;
 
-declare function StudioApp(): react_jsx_runtime.JSX.Element;
+interface StudioAppProps {
+    /** Clicks still select and report; the preview cannot move, edit or delete anything. */
+    readOnlyPreview?: boolean;
+    /** Short text shown on disabled hand-edit controls while `readOnlyPreview` is set. */
+    readOnlyPreviewReason?: string;
+}
+declare function StudioApp({ readOnlyPreview, readOnlyPreviewReason }?: StudioAppProps): react_jsx_runtime.JSX.Element;
 
 interface AgentModalAnchorPoint {
     x: number;
@@ -2179,4 +2273,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, 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 };

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