@hyperframes/studio 0.8.51 → 0.8.53-desktop.0

package/dist/index.d.ts

@@ -1,12 +1,281 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
-import { ReactNode, RefObject } from 'react';
+import { ButtonHTMLAttributes, ReactNode, ElementType, ComponentPropsWithoutRef, ReactElement, RefObject, MutableRefObject } 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';
+import { ContextMenu as ContextMenu$1 } from '@base-ui/react/context-menu';
+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 * 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';
+
+type ButtonVariant = "primary" | "secondary" | "danger" | "ghost";
+type ButtonSize = "sm" | "md" | "lg";
+/** Forces one interactive look for a gallery shot. CSS-only; see the header. */
+type PreviewState = "hover" | "active" | "focus";
+interface ButtonBaseProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    "data-preview-state"?: PreviewState;
+}
+interface ButtonProps extends ButtonBaseProps {
+    loading?: boolean;
+    icon?: ReactNode;
+}
+/**
+ * Shared by Button and IconButton. `disabled:` keeps pointer events alive so a
+ * wrapping Tooltip can still explain why the control is disabled.
+ */
+declare const buttonBase: string;
+/**
+ * One entry per variant. The `data-[preview-state=…]` half of each string
+ * repeats the `hover:` and `active:` half exactly; the test pairs them.
+ */
+declare const buttonVariants: Record<ButtonVariant, string>;
+declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+interface IconButtonProps extends ButtonBaseProps {
+    icon: ReactNode;
+    "aria-label": string;
+}
+declare const IconButton: react.ForwardRefExoticComponent<IconButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * Base UI lets `className` be a function of the part's state. Studio's parts
+ * merge a string with `cn`, so the string form is the one they accept.
+ */
+type StyledProps$1<T extends ElementType> = Omit<ComponentPropsWithoutRef<T>, "className"> & {
+    className?: string;
+};
+/**
+ * Groups a tab list with its panels. Uncontrolled by default; pass `value` and
+ * `onValueChange` for a strip whose selection lives in a store.
+ */
+declare function Tabs(props: ComponentPropsWithoutRef<typeof Tabs$1.Root>): react_jsx_runtime.JSX.Element;
+/** The strip. Give it an `aria-label`: a tablist with no name is unlabelled. */
+declare function TabsList({ className, ...props }: StyledProps$1<typeof Tabs$1.List>): react_jsx_runtime.JSX.Element;
+interface TabProps extends StyledProps$1<typeof Tabs$1.Tab> {
+    value: string;
+    "data-preview-state"?: PreviewState;
+}
+/**
+ * aria-selected drives the selected look (Base UI sets it) so assistive tech
+ * and sighted users match. data-preview-state is for gallery shots only.
+ */
+declare function Tab({ value, className, ...props }: TabProps): react_jsx_runtime.JSX.Element;
+/** The panel for one tab. Base UI wires `aria-labelledby` back to its tab. */
+declare function TabPanel({ className, ...props }: StyledProps$1<typeof Tabs$1.Panel>): react_jsx_runtime.JSX.Element;
+
+interface TooltipProps {
+    label: string;
+    /** A single element, wrapped in a box-less span so a disabled one still gets hover. */
+    children: ReactElement<{
+        "aria-describedby"?: string;
+    }>;
+    /** Hover delay in ms. */
+    delay?: number;
+    side?: "top" | "bottom" | "left" | "right";
+}
+declare function Tooltip({ label, children, delay, side }: TooltipProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Studio's tailwind-merge config: teaches it the two scales `theme.css`
+ * invents (`text-step-*`, `ctl`/`ctl-sm`/`ctl-lg`) so overrides replace, not stack.
+ */
+declare const cn: node_modules_cn_dist_types.CnFunction;
+
+/**
+ * Base UI lets `className` be a function of the part's state. Studio's parts
+ * merge a string with `cn`, so the string form is the one they accept.
+ */
+type StyledProps<T extends ElementType> = Omit<ComponentPropsWithoutRef<T>, "className"> & {
+    className?: string;
+};
+/** Forces the settled open look for a gallery shot; CSS-only, open state stays controlled. */
+type PopupPreviewState = "open";
+/** Where the portal puts the popup. `null` keeps it inline, next to its trigger. */
+type PortalContainer$1 = ComponentPropsWithoutRef<typeof Menu$1.Portal>["container"];
+/**
+ * Chrome shared by every floating panel (`Popover` too); callers add their own shadow token.
+ * `data-starting-style`/`data-ending-style` are Base UI's transition attributes.
+ */
+declare const popupSurface: string;
+type MenuItemTone = "default" | "danger";
+interface PositionedProps {
+    side?: "top" | "bottom" | "left" | "right";
+    align?: "start" | "center" | "end";
+    sideOffset?: number;
+    /** Portal target. Pass the shadow root when the trigger lives in one. */
+    container?: PortalContainer$1;
+    /** Names the popup for assistive tech. A menu with no name is unlabelled. */
+    "aria-label"?: string;
+    className?: string;
+    "data-preview-state"?: PopupPreviewState;
+}
+interface MenuProps extends PositionedProps, Omit<ComponentPropsWithoutRef<typeof Menu$1.Root>, "children"> {
+    /** A single element. It becomes the trigger; no wrapper is added around it. */
+    trigger: ReactElement;
+    /** The items: `MenuItem`, `MenuRadioGroup`, `MenuSeparator`. */
+    children: ReactNode;
+}
+/**
+ * A menu opened by its trigger. Uncontrolled by default; pass `open` and
+ * `onOpenChange` for a menu whose state lives in a store.
+ */
+declare function Menu({ trigger, children, side, align, sideOffset, container, className, "aria-label": ariaLabel, "data-preview-state": previewState, ...root }: MenuProps): react_jsx_runtime.JSX.Element;
+interface ContextMenuProps extends PositionedProps, Omit<ComponentPropsWithoutRef<typeof ContextMenu$1.Root>, "children"> {
+    /**
+     * The right-clickable area, as the caller's own element. Its children are
+     * kept: the trigger renders that element rather than wrapping it.
+     */
+    trigger: ReactElement;
+    children: ReactNode;
+}
+/** Opened by right click or long press at the pointer, so `side` and `align` are not offered. */
+declare function ContextMenu({ trigger, children, container, className, "aria-label": ariaLabel, "data-preview-state": previewState, ...root }: Omit<ContextMenuProps, "side" | "align" | "sideOffset">): react_jsx_runtime.JSX.Element;
+/** Keyboard shortcut hint, mono and tabular; exported for hints that are not a plain string. */
+declare function MenuShortcut({ className, ...props }: StyledProps<"span">): react_jsx_runtime.JSX.Element;
+interface MenuItemProps extends StyledProps<typeof Menu$1.Item> {
+    /** Rendered as a dim mono hint on the trailing edge. Decorative. */
+    shortcut?: string;
+    /** `danger` for a destructive action (Delete, Remove). */
+    tone?: MenuItemTone;
+    "data-preview-state"?: "hover";
+}
+/** One action. `disabled` items are skipped by the arrow keys, not just dimmed. */
+declare function MenuItem({ shortcut, tone, className, children, ...props }: MenuItemProps): react_jsx_runtime.JSX.Element;
+/** Single-choice group; selection is `aria-checked` on each item, which the dot indicator draws from. */
+declare function MenuRadioGroup(props: ComponentPropsWithoutRef<typeof Menu$1.RadioGroup>): react_jsx_runtime.JSX.Element;
+interface MenuRadioItemProps extends StyledProps<typeof Menu$1.RadioItem> {
+    "data-preview-state"?: "hover";
+}
+/** One choice in a `MenuRadioGroup`. The dot renders only while it is checked. */
+declare function MenuRadioItem({ className, children, ...props }: MenuRadioItemProps): react_jsx_runtime.JSX.Element;
+/** A hairline between two groups of items. */
+declare function MenuSeparator({ className, ...props }: StyledProps<typeof Menu$1.Separator>): react_jsx_runtime.JSX.Element;
+
+type PortalContainer = ComponentPropsWithoutRef<typeof Popover$1.Portal>["container"];
+interface PopoverProps extends Omit<ComponentPropsWithoutRef<typeof Popover$1.Root>, "children"> {
+    /** A single element. It becomes the trigger; no wrapper is added around it. */
+    trigger: ReactElement;
+    /** Arbitrary content. The popover owns none of its keys. */
+    children: ReactNode;
+    side?: "top" | "bottom" | "left" | "right";
+    align?: "start" | "center" | "end";
+    sideOffset?: number;
+    /** Portal target. Pass the shadow root when the trigger lives in one. */
+    container?: PortalContainer;
+    /** Names the popup for assistive tech. */
+    "aria-label"?: string;
+    /**
+     * What to focus on open. Defaults to Base UI's behaviour (the first tabbable
+     * element), which is what a rename field wants.
+     */
+    initialFocus?: ComponentPropsWithoutRef<typeof Popover$1.Popup>["initialFocus"];
+    className?: string;
+    "data-preview-state"?: PopupPreviewState;
+}
+declare function Popover({ trigger, children, side, align, sideOffset, container, className, initialFocus, "aria-label": ariaLabel, "data-preview-state": previewState, ...root }: PopoverProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Shared field look (also used by NumberField and Select). Each interactive state is written
+ * twice, real and `data-[preview-state=...]`; `valueControls.test.tsx` asserts the lists match.
+ */
+declare const fieldBase: string;
+/** The text itself, inside the box. The box owns the border and the ring. */
+declare const fieldText: string;
+interface InputProps extends Omit<ComponentPropsWithoutRef<"input">, "value" | "onChange" | "className"> {
+    /** The committed value. A draft lives inside until Enter or blur. */
+    value: string;
+    /** Called with the draft on Enter and on blur, only when it really changed. */
+    onCommit: (next: string) => void;
+    /** Called once per committed change, for design-input telemetry. */
+    onTrack?: () => void;
+    /** Marks the field invalid: red boundary and `aria-invalid`. */
+    invalid?: boolean;
+    className?: string;
+    "data-preview-state"?: PreviewState;
+}
+declare function Input({ value, onCommit, onTrack, invalid, disabled, className, "data-preview-state": previewState, ...props }: InputProps): react_jsx_runtime.JSX.Element;
+
+interface NumberFieldProps {
+    /** Accessible name. The inspector's row label is the usual one. */
+    label: string;
+    /** The committed value. */
+    value: number;
+    /** Called when a commit boundary produces a value different from `value`. */
+    onCommit: (next: number) => void;
+    /** Called once per committed change, for design-input telemetry. */
+    onTrack?: () => void;
+    /** Rendered beside the number: "px", "%", "deg". Never part of the text. */
+    unit?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    disabled?: boolean;
+    className?: string;
+    "data-preview-state"?: PreviewState;
+}
+declare function NumberField({ label, value, onCommit, onTrack, unit, min, max, step, disabled, className, "data-preview-state": previewState, }: NumberFieldProps): react_jsx_runtime.JSX.Element;
+
+interface SelectOption {
+    label: string;
+    value: string;
+}
+interface SelectProps {
+    /** Accessible name for the trigger. */
+    label: string;
+    value: string;
+    options: SelectOption[];
+    /** Called when a different option is chosen. */
+    onCommit: (next: string) => void;
+    /** Called once per committed change, for design-input telemetry. */
+    onTrack?: () => void;
+    disabled?: boolean;
+    className?: string;
+    "data-preview-state"?: PreviewState;
+}
+declare function Select({ label, value, options, onCommit, onTrack, disabled, className, "data-preview-state": previewState, }: SelectProps): react_jsx_runtime.JSX.Element;
+
+interface SliderProps {
+    /** Accessible name for the thumb. The inspector's row label is the usual one. */
+    label: string;
+    /** The committed value. */
+    value: number;
+    min: number;
+    max: number;
+    step?: number;
+    /** Every intermediate value while dragging or stepping. Not a commit. */
+    onPreview?: (next: number) => void;
+    /** Called at a commit boundary when the value really changed. */
+    onCommit: (next: number) => void;
+    /** Called once per commit boundary, for design-input telemetry. */
+    onTrack?: () => void;
+    disabled?: boolean;
+    className?: string;
+    "data-preview-state"?: PreviewState;
+}
+declare function Slider({ label, value, min, max, step, onPreview, onCommit, onTrack, disabled, className, "data-preview-state": previewState, }: SliderProps): react_jsx_runtime.JSX.Element;
+
+interface ToggleProps {
+    /** Accessible name. */
+    label: string;
+    checked: boolean;
+    /** Called on every flip. */
+    onCommit: (next: boolean) => void;
+    /** Called once per flip, for design-input telemetry. */
+    onTrack?: () => void;
+    disabled?: boolean;
+    className?: string;
+    "data-preview-state"?: PreviewState;
+}
+declare function Toggle({ label, checked, onCommit, onTrack, disabled, className, "data-preview-state": previewState, }: ToggleProps): react_jsx_runtime.JSX.Element;
 
 interface PlayerProps {
     projectId?: string;
@@ -587,10 +856,6 @@ interface BeatHistoryEntry {
 }
 declare const usePlayerStore: zustand.UseBoundStore<zustand.StoreApi<PlayerState>>;
 
-/**
- * Source Patcher — Maps visual property edits back to source HTML files.
- * Handles inline style updates, attribute changes, and text content.
- */
 interface PatchOperation {
     type: "inline-style" | "attribute" | "text-content" | "html-attribute" | "rich-text";
     property: string;
@@ -705,8 +970,179 @@ declare function buildPickerAgentPrompt({ selection, userInstruction, }: {
 }): string;
 declare function buildPickerAgentContextPreview(selection: HyperframePickerElementInfo | null): string;
 
+type EditHistoryKind = "manual" | "motion" | "timeline" | "source";
+interface EditHistoryFileSnapshot {
+    before: string;
+    after: string;
+    beforeHash: string;
+    afterHash: string;
+}
+interface EditHistoryEntry {
+    id: string;
+    projectId: string;
+    label: string;
+    kind: EditHistoryKind;
+    coalesceKey?: string;
+    /** Per-entry coalesce window override (ms). Falls back to the reducer default. */
+    coalesceMs?: number;
+    createdAt: number;
+    files: Record<string, EditHistoryFileSnapshot>;
+}
+interface EditHistoryState {
+    version: 1;
+    updatedAt: number;
+    undo: EditHistoryEntry[];
+    redo: EditHistoryEntry[];
+}
+interface BuildEditHistoryEntryInput {
+    id: string;
+    projectId: string;
+    label: string;
+    kind?: EditHistoryKind;
+    coalesceKey?: string;
+    coalesceMs?: number;
+    now: number;
+    files: Record<string, {
+        before: string;
+        after: string;
+    }>;
+}
+
+interface SdkSessionPublication {
+    candidate: Composition;
+    expectedSession: Composition;
+    targetPath: string;
+}
+type SdkSessionPublicationResult = "published" | "rejected-active-target" | "rejected-inactive-target";
+type PublishSdkSession = (publication: SdkSessionPublication) => SdkSessionPublicationResult;
+
+type TimelineLayerDropPlacement = {
+    type: "onto";
+    layerId: string;
+} | {
+    type: "between";
+    beforeLayerId: string;
+    afterLayerId: string;
+} | {
+    type: "above";
+    layerId: string;
+} | {
+    type: "below";
+    layerId: string;
+};
+interface TimelineStackingZIndexChange {
+    key: string;
+    zIndex: number;
+    domId?: string;
+    selector?: string;
+    selectorIndex?: number;
+    sourceFile?: string;
+}
+interface TimelineStackingReorderIntent {
+    contextKey: string;
+    placement: TimelineLayerDropPlacement;
+    zIndexChanges: TimelineStackingZIndexChange[];
+}
+
 type BlockedTimelineEditIntent = "move" | "resize-start" | "resize-end";
 
+/**
+ * Durability report for a patch-batches commit. `durable === false` means the
+ * server could not locate at least one patch target on disk — the preview was
+ * reloaded to reconverge, and dependent follow-up writes (the z→lane timeline
+ * mirror) must be skipped. `allMatched` retains the underlying match detail.
+ * `changed === false` means no source file was written: every patch was a
+ * byte-identical no-op, or the atomic gesture was refused before any write.
+ */
+interface DomEditPatchBatchesResult {
+    durable: boolean;
+    allMatched: boolean;
+    changed: boolean;
+}
+
+/** A host's verdict on one element: editable, or blocked with a reason to show. */
+type TimelineEditPermission = true | {
+    blocked: true;
+    reason: string;
+};
+type CanEditTimelineElement = (element: TimelineElement) => TimelineEditPermission;
+
+interface RecordEditInput$1 {
+    label: string;
+    kind: EditHistoryKind;
+    coalesceKey?: string;
+    files: Record<string, {
+        before: string;
+        after: string;
+    }>;
+}
+type TimelineZIndexReorderCommit = (entries: Array<{
+    element: HTMLElement;
+    zIndex: number;
+    id?: string;
+    selector?: string;
+    selectorIndex?: number;
+    sourceFile: string;
+    key?: string;
+}>, coalesceKey?: string) => Promise<DomEditPatchBatchesResult | undefined | void>;
+interface UseTimelineEditingOptions {
+    projectId: string | null;
+    activeCompPath: string | null;
+    timelineElements: TimelineElement[];
+    showToast: (message: string, tone?: "error" | "info") => void;
+    writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
+    observeProjectFileVersion?: (path: string, version: string | null) => void;
+    recordEdit: (input: RecordEditInput$1) => Promise<void>;
+    reloadPreview: () => void;
+    previewIframeRef: RefObject<HTMLIFrameElement | null>;
+    pendingTimelineEditPathRef: MutableRefObject<Set<string>>;
+    uploadProjectFiles: (files: Iterable<File>, dir?: string) => Promise<string[]>;
+    isRecordingRef?: RefObject<boolean>;
+    /** Stage 7 §3.2: SDK session for routing timing ops through setTiming. */
+    sdkSession?: Composition | null;
+    /** Publish a fully persisted candidate SDK session. */
+    publishSdkSession?: PublishSdkSession;
+    /** Resync the SDK session after a server-authoritative timeline write. */
+    forceReloadSdkSession?: () => void;
+    /** Reparse authored animations after a timing rewrite changes their positions. */
+    invalidateGsapCache?: () => void;
+    handleDomZIndexReorderCommitRef?: MutableRefObject<TimelineZIndexReorderCommit | null>;
+    /** Refuses a hand edit at the persist boundary when set; absent = Studio unchanged. */
+    canEdit?: CanEditTimelineElement;
+}
+/** What a timeline move commits: the new start and track, plus the z-index
+ *  reorder a vertical drag resolves to (absent for a pure horizontal move). */
+type TimelineMoveUpdates = Pick<TimelineElement, "start" | "track"> & {
+    stackingReorder?: TimelineStackingReorderIntent | null;
+};
+
+interface TimelineGroupMoveChange {
+    element: TimelineElement;
+    start: number;
+    track?: number;
+}
+interface TimelineGroupResizeChange {
+    element: TimelineElement;
+    start: number;
+    duration: number;
+    playbackStart?: number;
+}
+interface TimelineGroupCommitOptions {
+    beforeTiming?: Promise<void>;
+    coalesceKey?: string;
+    /** Per-entry undo coalesce window override (ms) — see EditHistoryEntry.coalesceMs. */
+    coalesceMs?: number;
+    /** Overrides the default "Move timeline clips" undo-history label. Coalescing
+     *  keeps the LAST entry's label (editHistory.ts), so a mechanical follow-up
+     *  move folded into another gesture's coalesceKey (e.g. the ripple after a
+     *  delete) should carry that gesture's own label, not its own. */
+    label?: string;
+    /** Skips this call's own generic failure toast (the error is still logged
+     *  to the console) — for a caller that shows its own more specific message
+     *  on the same failure, so the user isn't told about one action twice. */
+    suppressFailureToast?: boolean;
+}
+
 type TimelineMoveOperation = "timing" | "lane-reorder" | "track-insert";
 
 interface TimelineKeyframeTarget {
@@ -991,10 +1427,8 @@ type RenderClipContent = (element: TimelineElement, style: {
     label: string;
 }) => ReactNode;
 interface EditorShellProps extends TimelineEditCallbackDeps {
-    /** Left sidebar (media/library), rendered in the top row. */
-    left: ReactNode;
-    /** Right panel (inspector/design) or null when collapsed, in the top row. */
-    right: ReactNode;
+    /** Dock.Panel elements for every panel except the built-in preview and timeline. */
+    panels: ReactNode;
     timelineToolbar: ReactNode;
     renderClipContent: RenderClipContent;
     handleTimelineElementDelete: (element: TimelineElement) => Promise<void> | void;
@@ -1018,9 +1452,13 @@ interface EditorShellProps extends TimelineEditCallbackDeps {
     isGestureRecording?: boolean;
     recordingState?: GestureRecordingState;
     onToggleRecording?: () => void;
+    /**
+     * Host layer over the preview, positioned with `usePreviewCompositionRect`. Hidden in
+     * fullscreen and during a block preview; below the selection overlay past z-index 10.
+     */
     gestureOverlay?: ReactNode;
 }
-declare function EditorShell({ left, right, 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;
+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;
@@ -1054,6 +1492,21 @@ interface CompositionBreadcrumbProps {
 }
 declare function CompositionBreadcrumb({ stack, onNavigate }: CompositionBreadcrumbProps): react_jsx_runtime.JSX.Element | null;
 
+interface DomEditCompositionRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    scaleX: number;
+    scaleY: number;
+}
+
+/**
+ * Where the composition sits inside `overlayRef`, in overlay pixels, plus the scale from
+ * composition units to pixels. Follows the live preview iframe across reloads.
+ */
+declare function usePreviewCompositionRect(overlayRef: RefObject<HTMLDivElement | null>): DomEditCompositionRect;
+
 interface SourceEditorProps {
     content: string;
     filePath?: string;
@@ -1273,6 +1726,117 @@ interface AskAgentModalProps {
 }
 declare function AskAgentModal({ selectionLabel, contextPreview, anchorPoint, onSubmit, onClose, }: AskAgentModalProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * What the dev server knows about this machine's FFmpeg, as reported by
+ * `GET /api/environment/ffmpeg`. Studio asks when the Render panel opens so a
+ * missing encoder is a prompt with an install command, not a failed export an
+ * hour into the work.
+ */
+interface FfmpegStatus {
+    ok: boolean;
+    /** Short headline, e.g. "FFmpeg not found". Absent when ok. */
+    title?: string;
+    /** Why it cannot run, in the server's words. Absent when ok. */
+    detail?: string;
+    /** Prose remediation, including the manual route where one exists. */
+    hint?: string;
+    /** A single pasteable install command, when this platform has one. */
+    command?: string;
+}
+
+interface RenderJob {
+    id: string;
+    status: "rendering" | "complete" | "failed" | "cancelled";
+    progress: number;
+    stage?: string;
+    error?: string;
+    filename: string;
+    createdAt: number;
+    durationMs?: number;
+}
+type ResolutionPreset = CanvasResolution;
+interface StartRenderOptions {
+    fps?: number;
+    quality?: "draft" | "standard" | "high";
+    format?: "mp4" | "webm" | "mov";
+    /** `"auto"` (default) renders at the composition's authored dimensions. */
+    resolution?: ResolutionPreset | "auto";
+    /**
+     * Render a specific composition file. Omit it to render the composition the
+     * user currently has open — only the sidebar's per-composition Render button
+     * names one, because it renders a card the user is not looking at.
+     */
+    composition?: string;
+    /**
+     * Composition-variable overrides ({variableId: value}), forwarded to the
+     * render route and injected as window.__hfVariables — the same channel
+     * `hyperframes render --variables` uses.
+     */
+    variables?: Record<string, unknown>;
+}
+declare function useRenderQueue(projectId: string | null, activeCompPathRef: {
+    current: string | null;
+}): {
+    jobs: RenderJob[];
+    isRendering: boolean;
+    loadError: string | null;
+    actionError: string | null;
+    dismissActionError: () => void;
+    reloadRenders: () => Promise<void>;
+    deleteRender: (jobId: string) => Promise<void>;
+    cancelRender: (jobId: string) => Promise<void>;
+    clearCompleted: () => void;
+    startRender: (options: unknown) => Promise<void>;
+    ffmpeg: FfmpegStatus | null;
+    ffmpegMissing: boolean;
+    ffmpegChecking: boolean;
+    recheckFfmpeg: () => void;
+};
+
+interface CompositionDimensions {
+    width: number;
+    height: number;
+}
+type StartRenderHandler = (format: "mp4" | "webm" | "mov", quality: "draft" | "standard" | "high", resolution: ResolutionPreset | "auto", fps: 24 | 30 | 60) => void | Promise<void>;
+interface RenderQueueProps {
+    jobs: RenderJob[];
+    projectId: string;
+    onDelete: (jobId: string) => void;
+    onCancel?: (jobId: string) => void;
+    onClearCompleted: () => void;
+    onStartRender: StartRenderHandler;
+    isRendering: boolean;
+    /** History fetch failure (null when the last load succeeded). */
+    loadError?: string | null;
+    /** Retry a failed history load. */
+    onRetryLoad?: () => void;
+    /** Failure of a delete/cancel action, shown inline until dismissed. */
+    actionError?: string | null;
+    onDismissActionError?: () => void;
+    /**
+     * Authored dimensions of the active composition. Used to pick the
+     * matching preset (landscape / portrait / square) when the user selects
+     * a 1080p or 4K scale. `null` falls back to landscape (legacy default).
+     */
+    compositionDimensions?: CompositionDimensions | null;
+    /**
+     * Encoder availability, owned by useRenderQueue so the panel's Export button
+     * and the header's agree. `null` means "no answer", not "missing".
+     */
+    ffmpeg: FfmpegStatus | null;
+    ffmpegChecking: boolean;
+    onRecheckFfmpeg: () => void;
+}
+declare const RenderQueue: react.NamedExoticComponent<RenderQueueProps>;
+
+interface PersistedRenderSettings {
+    format: "mp4" | "webm" | "mov";
+    quality: "draft" | "standard" | "high";
+    fps: 24 | 30 | 60;
+}
+declare function getPersistedRenderSettings(): PersistedRenderSettings;
+declare function persistRenderSettings(format: PersistedRenderSettings["format"], quality: PersistedRenderSettings["quality"], fps: PersistedRenderSettings["fps"]): void;
+
 interface PickedElement {
     id: string | null;
     tagName: string;
@@ -1348,4 +1912,236 @@ declare function findElementBlock(html: string, elementId: string): {
     isSelfClosing: boolean;
 } | null;
 
-export { type AgentModalAnchorPoint, type AgentPromptElementInfo, AskAgentModal, type AskAgentModalProps, CompositionBreadcrumb, type CompositionLevel, CompositionThumbnail, EditorShell, FileTree, NLEPreview, type PatchOperation, type PickedElement, Player, PlayerControls, PropertyPanel, SourceEditor, StudioApp, Timeline, type TimelineElement, VideoThumbnail, applyPatch, buildPickerAgentContextPreview, buildPickerAgentPrompt, findElementBlock, formatTime, liveTime, mergeStyleIntoTag, parseStyleString, resolveIframe, resolveSourceFile, useElementPicker, usePlayerStore, useTimelinePlayer };
+interface EditHistoryStorageAdapter {
+    get(projectId: string): Promise<EditHistoryState | null>;
+    set(projectId: string, state: EditHistoryState): Promise<void>;
+    delete(projectId: string): Promise<void>;
+}
+
+interface RecordEditInput {
+    label: string;
+    kind: EditHistoryKind;
+    coalesceKey?: string;
+    coalesceMs?: number;
+    files: BuildEditHistoryEntryInput["files"];
+}
+interface ApplyCallbacks {
+    readFile: (path: string) => Promise<string>;
+    writeFile: (path: string, content: string) => Promise<void>;
+    serialize?: <T>(paths: readonly string[], task: () => Promise<T>) => Promise<T>;
+}
+interface UsePersistentEditHistoryOptions {
+    projectId: string | null;
+    storage?: EditHistoryStorageAdapter;
+    now?: () => number;
+}
+/**
+ * Per-file content the restore just applied. `restored` is the bytes written to
+ * disk (the undo/redo target); `previous` is what was on disk immediately before
+ * (the current live preview state). The undo preview-sync diffs these to decide
+ * whether the restore is soft-reloadable (attributes/style/GSAP-script only) or
+ * needs a full iframe reload.
+ */
+interface ApplyRestoredFile {
+    previous: string;
+    restored: string;
+}
+interface ApplyResult {
+    ok: boolean;
+    reason?: "empty" | "content-mismatch";
+    label?: string;
+    paths?: string[];
+    files?: Record<string, ApplyRestoredFile>;
+}
+declare function usePersistentEditHistory(options: UsePersistentEditHistoryOptions): {
+    recordEdit: (input: RecordEditInput) => Promise<void>;
+    undo: (callbacks: ApplyCallbacks) => Promise<ApplyResult>;
+    redo: (callbacks: ApplyCallbacks) => Promise<ApplyResult>;
+    canUndo: boolean;
+    canRedo: boolean;
+    undoLabel: string;
+    redoLabel: string;
+    undoPaths: string[];
+    redoPaths: string[];
+    state: EditHistoryState;
+    loaded: boolean;
+};
+
+declare function useTimelineEditing({ projectId, activeCompPath, timelineElements, showToast, writeProjectFile, observeProjectFileVersion, recordEdit, reloadPreview, previewIframeRef, pendingTimelineEditPathRef, uploadProjectFiles, isRecordingRef, sdkSession, publishSdkSession, forceReloadSdkSession, invalidateGsapCache, handleDomZIndexReorderCommitRef, canEdit, }: UseTimelineEditingOptions): {
+    handleTimelineElementMove: (element: TimelineElement, updates: TimelineMoveUpdates) => Promise<void>;
+    handleTimelineElementResize: (element: TimelineElement, updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">) => Promise<void>;
+    handleToggleTrackHidden: (track: number, hidden: boolean, displayNumber?: number | null | undefined) => Promise<void>;
+    handleToggleElementHidden: (elementKey: string | readonly string[], hidden: boolean) => Promise<void>;
+    handleAutoGroupCarveSources: (clipIds: readonly string[], groupId: string, groupLabel?: string | undefined) => Promise<void>;
+    setAudioGroupAttribute: {
+        setQuiet: (groupId: string, attr: string, value: string | null, label: string) => Promise<void>;
+        setLive: (groupId: string, attr: string, value: string | null) => void;
+    };
+    setElementFxAttribute: {
+        setQuiet: (element: TimelineElement, attr: string, value: string | null, label: string) => Promise<void>;
+        setLive: (element: TimelineElement, attr: string, value: string | null) => void;
+    };
+    handleTimelineElementDelete: (element: TimelineElement) => Promise<void>;
+    handleTimelineElementsDelete: (selection: TimelineElement[]) => Promise<void>;
+    handleTimelineElementSplit: (element: TimelineElement, splitTime: number) => Promise<void>;
+    handleRazorSplit: (element: TimelineElement, splitTime: number) => Promise<void>;
+    handleRazorSplitAll: (splitTime: number) => Promise<void>;
+    handleTimelineAssetDrop: (assetPath: string, placement: TimelineDropPlacement, durationOverride?: number | undefined) => Promise<void>;
+    handleTimelineFileDrop: (files: File[], placement?: TimelineDropPlacement | undefined) => Promise<void>;
+    handleTimelineCompositionDrop: (sourcePath: string, placement: Pick<TimelineElement, "track" | "start">) => Promise<void>;
+    handleBlockedTimelineEdit: (element: TimelineElement) => void;
+    handleTimelineGroupMove: (changes: TimelineGroupMoveChange[], options?: TimelineGroupCommitOptions | undefined) => Promise<void>;
+    handleTimelineGroupResize: (changes: TimelineGroupResizeChange[], options?: TimelineGroupCommitOptions | undefined) => Promise<void>;
+};
+
+declare class StudioSaveHttpError extends Error {
+    readonly statusCode: number;
+    readonly alreadyToasted: boolean;
+    constructor(message: string, statusCode: number, options?: {
+        alreadyToasted?: boolean;
+    });
+}
+declare class StudioFileConflictError extends StudioSaveHttpError {
+    readonly filePath: string;
+    readonly currentVersion: string | null;
+    readonly currentContent: string | null;
+    readonly attemptedContent: string;
+    constructor(input: {
+        filePath: string;
+        currentVersion: string | null;
+        currentContent: string | null;
+        attemptedContent: string;
+    });
+}
+type StudioSaveDrainResult<Failure = unknown> = {
+    status: "clean";
+} | {
+    status: "conflict";
+    error: StudioFileConflictError;
+} | {
+    status: "failed";
+    error: Failure;
+};
+
+type StudioPendingEditsDrainResult = StudioSaveDrainResult;
+declare function flushStudioPendingEdits(): Promise<StudioPendingEditsDrainResult>;
+
+interface HistoryResult {
+    ok: boolean;
+    reason?: string;
+    label?: string;
+    paths?: string[];
+    /** Per-file restored/previous content, used to soft-apply the preview. */
+    files?: Record<string, {
+        previous: string;
+        restored: string;
+    }>;
+}
+interface HistoryFileCallbacks {
+    readFile: (path: string) => Promise<string>;
+    writeFile: (path: string, content: string) => Promise<void>;
+    serialize?: <T>(paths: readonly string[], task: () => Promise<T>) => Promise<T>;
+}
+interface EditHistoryHandle {
+    undo: (cb: HistoryFileCallbacks) => Promise<HistoryResult>;
+    redo: (cb: HistoryFileCallbacks) => Promise<HistoryResult>;
+    state: {
+        undo: ReadonlyArray<{
+            createdAt: number;
+        }>;
+        redo: ReadonlyArray<{
+            createdAt: number;
+        }>;
+    };
+}
+interface UseEditHistoryActionsOptions {
+    editHistory: Pick<EditHistoryHandle, "undo" | "redo">;
+    readOptionalProjectFile: (path: string) => Promise<string>;
+    readProjectFile: (path: string) => Promise<string>;
+    writeProjectFile: (path: string, content: string) => Promise<void>;
+    showToast: (message: string, tone?: "error" | "info") => void;
+    syncHistoryPreviewAfterApply: (restore: Pick<HistoryResult, "paths" | "files">) => Promise<void>;
+    waitForPendingDomEditSaves: () => Promise<void>;
+    onAfterUndoRedo?: () => void;
+    /** Active composition path — decides whether undo/redo must resync the SDK session. */
+    activeCompPath?: string | null;
+    /** Reloads the SDK session after a revert of the active comp, past the self-write suppress window. */
+    forceReloadSdkSession?: () => void;
+}
+/** Applies one persisted file-history step: the single owner of undo/redo over project files. */
+declare function useEditHistoryActions({ editHistory, readOptionalProjectFile, readProjectFile, writeProjectFile, showToast, syncHistoryPreviewAfterApply, waitForPendingDomEditSaves, onAfterUndoRedo, activeCompPath, forceReloadSdkSession, }: UseEditHistoryActionsOptions): {
+    undo: () => Promise<void>;
+    redo: () => Promise<void>;
+};
+
+interface UseProjectFileWriterOptions {
+    projectId: string | null;
+}
+declare function useProjectFileWriter({ projectId }: UseProjectFileWriterOptions): {
+    fileVersions: Map<string, string | null>;
+    readProjectFile: (path: string) => Promise<string>;
+    writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
+    readOptionalProjectFile: (path: string) => Promise<string>;
+    observeProjectFileVersion: (path: string, version: string | null) => void;
+};
+
+type ExternalFileChangeBlockedState = {
+    status: "conflict";
+    generation: number;
+    error: StudioFileConflictError;
+    payload: unknown;
+} | {
+    status: "failed";
+    generation: number;
+    path: string;
+    error: unknown;
+    payload: unknown;
+    studioContent: string | null;
+    recovered: boolean;
+};
+interface ExternalFileChangeCoordinatorHandle {
+    blocked: ExternalFileChangeBlockedState | null;
+    retry: () => Promise<void>;
+    useExternalFile: () => Promise<void>;
+    keepStudioFile: () => Promise<void>;
+}
+
+declare function ExternalFileConflictBanner({ coordinator, }: {
+    coordinator: ExternalFileChangeCoordinatorHandle;
+}): react_jsx_runtime.JSX.Element | null;
+
+interface TimelinePaneProps {
+    /** Slot rendered above the timeline tracks (toolbar with split, delete, zoom) */
+    timelineToolbar?: ReactNode;
+    /** Slot rendered below the timeline tracks */
+    timelineFooter?: ReactNode;
+    /** Slot for a host's own overlay spanning the whole timeline area (e.g. a draft/ghost
+     *  clip), positioned absolutely the same way PreviewPane's previewOverlay is. */
+    timelineOverlay?: ReactNode;
+    /** Custom clip content renderer for timeline (thumbnails, waveforms, etc.) */
+    renderClipContent?: (element: TimelineElement, style: {
+        clip: string;
+        label: string;
+    }) => ReactNode;
+    onFileDrop?: (files: File[], placement?: Pick<TimelineElement, "start" | "track">) => Promise<void> | void;
+    onDeleteElement?: (element: TimelineElement) => Promise<void> | void;
+    onAssetDrop?: (assetPath: string, placement: Pick<TimelineElement, "start" | "track">) => Promise<void> | void;
+    onBlockDrop?: (blockName: string, placement: Pick<TimelineElement, "start" | "track">) => Promise<void> | void;
+    onCompositionDrop?: (sourcePath: string, placement: Pick<TimelineElement, "start" | "track">) => Promise<void> | void;
+    onBlockedEditAttempt?: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
+    onSelectTimelineElement?: (element: TimelineElement | 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;
+    onPasteClip?: () => Promise<void>;
+    onDuplicateClip?: () => Promise<boolean>;
+    canPasteClip?: () => boolean;
+}
+declare function TimelinePane({ timelineToolbar, timelineFooter, timelineOverlay, renderClipContent, onFileDrop, onDeleteElement, onAssetDrop, onBlockDrop, onCompositionDrop, onBlockedEditAttempt, onSelectTimelineElement, onCopyClip, onPasteClip, onDuplicateClip, canPasteClip, }: TimelinePaneProps): react_jsx_runtime.JSX.Element;
+
+declare function TimelineEditProvider({ value, children, }: {
+    value: TimelineEditCallbacks;
+    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, 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, Toggle, type ToggleProps, Tooltip, type UseEditHistoryActionsOptions, type UsePersistentEditHistoryOptions, type UseProjectFileWriterOptions, type UseTimelineEditingOptions, VideoThumbnail, applyPatch, buildPickerAgentContextPreview, buildPickerAgentPrompt, buttonBase, buttonVariants, cn, fieldBase, fieldText, findElementBlock, flushStudioPendingEdits, formatTime, getPersistedRenderSettings, liveTime, mergeStyleIntoTag, parseStyleString, persistRenderSettings, popupSurface, resolveIframe, resolveSourceFile, useEditHistoryActions, useElementPicker, usePersistentEditHistory, usePlayerStore, usePreviewCompositionRect, useProjectFileWriter, useRenderQueue, useTimelineEditing, useTimelinePlayer };