hyperframes 0.8.81 → 0.8.83

package/dist/studio/index.d.ts

@@ -1,331 +1,23 @@
-import * as react from 'react';
-import { ButtonHTMLAttributes, ReactNode, ElementType, ComponentPropsWithoutRef, ReactElement, RefObject, MutableRefObject, DragEventHandler, ComponentProps, RefCallback, MouseEvent, CSSProperties, UIEvent, PointerEvent } from 'react';
+export { Button, ButtonSize, ButtonVariant, ContextMenu, HyperframesLoader, HyperframesLoaderProps, HyperframesLogo, IconButton, Input, InputProps, Menu, MenuItem, MenuItemTone, MenuRadioGroup, MenuRadioItem, MenuSeparator, MenuShortcut, NumberField, NumberFieldProps, Popover, PopupPreviewState, PreviewState, Select, SelectOption, SelectProps, Slider, SliderProps, Tab, TabPanel, Tabs, TabsList, Toggle, ToggleProps, Tooltip, buttonBase, buttonSizes, buttonVariants, cn, fieldBase, fieldText, popupSurface } from './ui.js';
 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 * as react from 'react';
+import { RefObject, MutableRefObject, ReactNode, DragEventHandler, ComponentProps, RefCallback, MouseEvent, CSSProperties, UIEvent, PointerEvent } from 'react';
 import { RuntimeTimelineClipIdentity, HyperframePickerElementInfo } from '@hyperframes/core';
-import { GsapAnimation, PropertyGroupName } from '@hyperframes/core/gsap-parser';
+import { GsapAnimation, ParsedGsap, PropertyGroupName } from '@hyperframes/core/gsap-parser';
+export { Player } from './player.js';
+import { Composition } from '@hyperframes/sdk';
 import { MusicBeatAnalysis } from '@hyperframes/core/beats';
 import * as zustand from 'zustand';
 import { StoreApi } from 'zustand';
 import { GsapAnimation as GsapAnimation$1, ArcPathSegment } from '@hyperframes/parsers/gsap-parser';
+import * as _hyperframes_parsers from '@hyperframes/parsers';
 import { CanvasResolution } from '@hyperframes/parsers';
-import { Composition } from '@hyperframes/sdk';
 export { SeamTransitionFrameSource, SeamTransitionLoopHandle, SeamTransitionLoopOptions, playSeamTransitionLoop } from '@hyperframes/shader-transitions';
-
-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>;
-/**
- * The three control heights, 24 / 28 / 32 px, from `--spacing-ctl-*`.
- * Exported so the Capture download `<a href>` can wear the same recipe as a Button.
- */
-declare const buttonSizes: Record<ButtonSize, string>;
-declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
-
-declare function HyperframesLogo(): react_jsx_runtime.JSX.Element;
-
-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 HyperframesLoaderProps {
-    /** Status text shown below the mark. */
-    title: string;
-    /** Optional secondary detail line. */
-    detail?: string;
-    /** Optional monospace third line for IDs, counts, or percentages. */
-    mono?: string;
-    /** Pixel size of the mark itself; status text scales independently. */
-    size?: number;
-    /** Optional normalized progress value from 0 to 1. */
-    progress?: number;
-}
-declare function HyperframesLoader({ title, detail, mono, size, progress, }: HyperframesLoaderProps): 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.
- */
-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;
-    /** Offered but not choosable; the label stays visible so the reason stays visible too. */
-    disabled?: boolean;
-}
-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;
-    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;
-}
-/**
- * Renders a composition preview using the <hyperframes-player> web component.
- *
- * The web component handles iframe scaling, dimension detection, and
- * ResizeObserver internally. This wrapper bridges its inner iframe to the
- * forwarded ref so useTimelinePlayer can access it for clip manifest parsing,
- * timeline probing, and DOM inspection.
- */
-declare const Player: react.ForwardRefExoticComponent<PlayerProps & react.RefAttributes<HTMLIFrameElement>>;
+import '@base-ui/react/tabs';
+import 'node_modules/cn/dist/types';
+import '@base-ui/react/context-menu';
+import '@base-ui/react/menu';
+import '@base-ui/react/popover';
 
 interface ShortcutHint {
     key: string;
@@ -654,8 +346,9 @@ 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). */
+    /** A video with sound to mix (`data-has-audio`, or unmuted without it); `muted` silences it. */
     hasAudio?: boolean;
+    muted?: boolean;
     /** Clip-edge fades from `data-fade-in` / `data-fade-out`, seconds; absent means none. */
     fadeIn?: number;
     fadeOut?: number;
@@ -1080,6 +773,12 @@ interface TimelineRangeSelection {
     anchorY: number;
 }
 
+/** Durable evidence returned by the one Studio DOM persistence actor. */
+interface DomEditPersistOutcome {
+    sourceFile: string;
+    version: string;
+    changed: boolean;
+}
 /**
  * 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
@@ -1094,7 +793,7 @@ interface DomEditPatchBatchesResult {
     changed: boolean;
 }
 
-interface RecordEditInput$1 {
+interface RecordEditInput$4 {
     label: string;
     coalesceKey?: string;
     files: Record<string, {
@@ -1118,7 +817,7 @@ interface UseTimelineEditingOptions {
     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>;
+    recordEdit: (input: RecordEditInput$4) => Promise<void>;
     reloadPreview: () => void;
     previewIframeRef: RefObject<HTMLIFrameElement | null>;
     pendingTimelineEditPathRef: MutableRefObject<Set<string>>;
@@ -1142,6 +841,101 @@ type TimelineMoveUpdates = Pick<TimelineElement, "start" | "track"> & {
     stackingReorder?: TimelineStackingReorderIntent | null;
 };
 
+/** Value-only channels a `tl.set(...)` patch may touch. */
+interface SetPatchProps {
+    x?: number;
+    y?: number;
+    rotation?: number;
+    rotationX?: number;
+    rotationY?: number;
+    rotationZ?: number;
+    z?: number;
+    transformPerspective?: number;
+    scaleX?: number;
+    scaleY?: number;
+    scale?: number;
+    opacity?: number;
+}
+/** A single keyframe step's numeric channels (the GSAP array-keyframe form). */
+type KeyframeStep = Record<string, number>;
+type RuntimeTweenChange = {
+    kind: "set";
+    props: SetPatchProps;
+} | {
+    kind: "keyframes";
+    keyframes: KeyframeStep[];
+} | {
+    kind: "keyframe-rebuild";
+    pct: number;
+    props: KeyframeStep;
+} | {
+    kind: "global-set";
+    props: SetPatchProps;
+};
+
+interface MutationResult {
+    ok: boolean;
+    changed?: boolean;
+    parsed?: ParsedGsap;
+    before?: string;
+    after?: string;
+    scriptText?: string;
+}
+interface CommitMutationOptions {
+    label: string;
+    /** Observe the durable writer result without duplicating the request path. */
+    onResult?: (result: MutationResult) => void;
+    coalesceKey?: string;
+    coalesceMs?: number;
+    softReload?: boolean;
+    skipReload?: boolean;
+    /**
+     * Write the source but leave the preview alone; the caller renders once when it
+     * is done. For a multi-write action like a group drag, rendering after each
+     * write shows a source where the members not yet written still hold their old
+     * values, so they snap back until their own write lands. This also defers the
+     * in-place runtime patch's seek, which re-renders the whole timeline and repaints
+     * the queued members the same way. Unlike `skipReload` this changes nothing about
+     * error handling — a failed write still throws.
+     */
+    deferPreviewSync?: boolean;
+    /** Shares an in-place patch miss with the final render of one multi-write action. */
+    previewFallbackLatch?: {
+        pending: boolean;
+    };
+    beforeReload?: () => void;
+    /**
+     * Serialize this commit against others sharing the same key. Used to chain
+     * per-animationId GSAP meta updates. Every commit independently takes the
+     * project/file mutation lock, so this key only adds ordering and can never
+     * bypass whole-file serialization.
+     */
+    serializeKey?: string;
+    /**
+     * Value-only edit fast path. When present, `runCommit` first tries to patch the
+     * one changed tween in the preview's runtime timeline in place
+     * (`patchRuntimeTweenInPlace`) — instant, no composition re-run, no iframe
+     * remount. On a successful patch the reload is skipped entirely (panels still
+     * refresh); when the patch can't be confidently applied it falls back to the
+     * existing soft/full reload path. Structural edits omit this and reload as before.
+     */
+    instantPatch?: {
+        selector: string;
+        change: RuntimeTweenChange;
+    };
+    /**
+     * The same fast path for a batched commit: one patch per element the batch
+     * wrote, applied in order. All of them must land for the reload to be skipped
+     * — one that can't be applied leaves the preview half-patched, so the whole
+     * batch falls back to the reload. Only the last patch re-renders (see
+     * `deferSeek`), so a ten-element batch repaints once.
+     */
+    instantPatches?: Array<{
+        selector: string;
+        change: RuntimeTweenChange;
+    }>;
+}
+
 interface TimelineGroupMoveChange {
     element: TimelineElement;
     start: number;
@@ -1310,18 +1104,24 @@ interface TimelineTheme {
 
 type TimelineEditOverrides = Pick<TimelineEditCallbacks, "onMoveElement" | "onMoveElements" | "onResizeElement" | "onResizeElements" | "onBlockedEditAttempt" | "onSplitElement">;
 
+/** With both set, a lane move restacks the preview's z-index to match the rows; each overrides Studio's own. */
+interface TimelineStackingSyncProps {
+    previewIframeRef?: RefObject<HTMLIFrameElement | null>;
+    onZIndexReorder?: TimelineZIndexReorderCommit;
+}
+
 interface TimelineClipRenderContext {
     priority: "overscan" | "visible" | "interaction";
     rich: boolean;
 }
-interface TimelineProps extends TimelineDropCallbacks, TimelineEditOverrides {
+interface TimelineProps extends TimelineDropCallbacks, TimelineEditOverrides, TimelineStackingSyncProps {
     /** Project-scoped reset boundary; soft source refreshes retain the same epoch. */
     sessionEpoch?: number;
-    /** keepPlaying: true preserves the current play state across the seek. */
     onSeek?: (time: number, options?: {
         keepPlaying?: boolean;
     }) => void;
     onDrillDown?: (element: TimelineElement) => void;
+    /** Picture only: takes no pointer input. Interactive content goes in renderClipOverlay. */
     renderClipContent?: (element: TimelineElement, style: {
         clip: string;
         label: string;
@@ -1347,7 +1147,7 @@ interface TimelineEmptyStateProps {
 }
 declare function TimelineEmptyState({ isDragOver, onFileDrop, onDragOver, onDragLeave, onDrop, }: TimelineEmptyStateProps): react_jsx_runtime.JSX.Element;
 
-interface Rect {
+interface Rect$1 {
     left: number;
     top: number;
     width: number;
@@ -1694,7 +1494,7 @@ type TimelineCanvasState = Omit<TimelineLaneBaseProps, "setRangeSelection" | "se
     effectiveDuration: number;
     majorTickInterval: number;
     rangeSelection: TimelineRangeSelection | null;
-    marqueeRect: Rect | null;
+    marqueeRect: Rect$1 | null;
     resizingClip: ResizingClipState | null;
     isScrubbing: boolean;
     playheadRef: React.RefObject<HTMLDivElement | null>;
@@ -2448,6 +2248,7 @@ interface StudioAppProps {
 }
 declare function StudioApp({ readOnlyPreview, readOnlyPreviewReason }?: StudioAppProps): react_jsx_runtime.JSX.Element;
 
+type RightPanelTab = "layers" | "design" | "renders" | "block-params" | "slideshow" | "variables";
 interface AgentModalAnchorPoint {
     x: number;
     y: number;
@@ -2648,7 +2449,7 @@ declare function findElementBlock(html: string, elementId: string): {
     isSelfClosing: boolean;
 } | null;
 
-interface RecordEditInput {
+interface RecordEditInput$3 {
     label: string;
     coalesceKey?: string;
     coalesceMs?: number;
@@ -2694,7 +2495,7 @@ declare function usePersistentEditHistory({ projectId }: UsePersistentEditHistor
             createdAt: number;
         }[];
     };
-    recordEdit: ({ label, coalesceKey, coalesceMs, files }: RecordEditInput) => Promise<void>;
+    recordEdit: ({ label, coalesceKey, coalesceMs, files }: RecordEditInput$3) => Promise<void>;
     undo: (callbacks: ApplyCallbacks) => Promise<ApplyResult>;
     redo: (callbacks: ApplyCallbacks) => Promise<ApplyResult>;
 };
@@ -2890,4 +2691,707 @@ declare function TimelineEditProvider({ value, children, }: {
     children: ReactNode;
 }): react_jsx_runtime.JSX.Element;
 
-export { type AgentModalAnchorPoint, type AgentPromptElementInfo, AskAgentModal, type AskAgentModalProps, AudioWaveform, type AudioWaveformProps, type BlockedTimelineEditIntent, Button, type ButtonSize, type ButtonVariant, type CanEditTimelineElement, CompositionBreadcrumb, type CompositionDimensions, type CompositionLevel, CompositionThumbnail, ContextMenu, DEFAULT_SHORTCUT_SECTIONS, type EditHistoryHandle, EditorShell, type EditorShellProps, type ExternalFileChangeBlockedState, type ExternalFileChangeCoordinatorHandle, ExternalFileConflictBanner, type FfmpegStatus, FileTree, GridOverlay, HyperframesLoader, type HyperframesLoaderProps, HyperframesLogo, IconButton, ImageThumbnail, type ImageThumbnailProps, 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, type ShortcutHint, type ShortcutSection, Slider, type SliderProps, SnapToolbar, SourceEditor, type StartRenderOptions, StudioApp, StudioFileConflictError, type StudioPendingEditsDrainResult, Tab, TabPanel, Tabs, TabsList, type ThumbnailPriority, Timeline, TimelineClipMenu, type TimelineClipRenderContext, type TimelineEditCallbacks, type TimelineEditOutcome, 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 UseRenderClipContentOptions, 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, useRenderClipContent, useRenderQueue, useTimelineContext, useTimelineEditing, useTimelinePlayer };
+interface EnableKeyframesSession {
+    domEditSelection: DomEditSelection | null;
+    selectedGsapAnimations: GsapAnimation[];
+    previewIframeRef?: React.RefObject<HTMLIFrameElement | null>;
+    handleGsapAddAnimation: (method: "to" | "from" | "set" | "fromTo") => void;
+    handleGsapConvertToKeyframes: (animId: string, resolvedFromValues?: Record<string, number | string>, duration?: number, commitOverrides?: Partial<CommitMutationOptions>) => void | Promise<void>;
+    handleGsapRemoveKeyframe: (animId: string, pct: number) => void;
+    handleGsapAddKeyframeBatch?: (animId: string, pct: number, properties: Record<string, number | string>, commitOverrides?: Partial<CommitMutationOptions>) => Promise<void>;
+    commitMutation?: (mutation: Record<string, unknown>, options: CommitMutationOptions) => Promise<void>;
+}
+
+interface TimelineHistoryButtonsProps {
+    canUndo?: boolean;
+    canRedo?: boolean;
+    undoLabel?: string;
+    redoLabel?: string;
+    onUndo?: () => Promise<void> | void;
+    onRedo?: () => Promise<void> | void;
+}
+/** Undo and Redo: a host's props win, else the shell's edit history. */
+declare function TimelineHistoryButtons(props: TimelineHistoryButtonsProps): react_jsx_runtime.JSX.Element;
+
+interface DomEditSessionSlice extends EnableKeyframesSession {
+    domEditSelection: DomEditSelection | null;
+    selectedGsapAnimations: GsapAnimation[];
+}
+interface TimelineToolbarProps {
+    domEditSession?: DomEditSessionSlice;
+    onSplitElement?: (element: TimelineElement, splitTime: number) => void;
+    history?: TimelineHistoryButtonsProps;
+    showAddBeat?: boolean;
+}
+declare function TimelineToolbar({ domEditSession, onSplitElement, history, showAddBeat, }: TimelineToolbarProps): react_jsx_runtime.JSX.Element;
+
+interface AudioMeterStripProps {
+    /** Pass a stable ref (useRef): a new object each render restarts the meter loop. */
+    previewIframeRef?: RefObject<HTMLIFrameElement | null>;
+}
+declare const AudioMeterStrip: react.NamedExoticComponent<AudioMeterStripProps>;
+
+interface RecordEditInput$2 {
+    label: string;
+    coalesceKey?: string;
+    files: Record<string, {
+        before: string;
+        after: string;
+    }>;
+}
+interface UseClipboardOptions {
+    projectId: string | null;
+    activeCompPath: string | null;
+    domEditSelectionRef: React.MutableRefObject<DomEditSelection | null>;
+    showToast: (message: string, tone?: "error" | "info") => void;
+    writeProjectFile: (path: string, content: string) => Promise<void>;
+    recordEdit: (input: RecordEditInput$2) => Promise<void>;
+    reloadPreview: () => void;
+    handleTimelineElementsDelete: (elements: TimelineElement[]) => Promise<void>;
+    handleDomEditElementDelete: (selection: DomEditSelection) => Promise<void>;
+    previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
+    waitForPendingDomEditSaves: () => Promise<void>;
+}
+declare function useClipboard({ projectId, activeCompPath, domEditSelectionRef, showToast, writeProjectFile, recordEdit, reloadPreview, handleTimelineElementsDelete, handleDomEditElementDelete, previewIframeRef, waitForPendingDomEditSaves, }: UseClipboardOptions): {
+    handleCopy: () => boolean;
+    handlePaste: () => Promise<void>;
+    handleCut: () => Promise<boolean>;
+    handleDuplicate: () => Promise<boolean>;
+    canPaste: () => boolean;
+};
+
+/** The live markup to persist and the session snapshot to restore on failure. */
+interface InlineTextEditCommit {
+    /** The exact preview node that owned the edit; a reload must not retarget it. */
+    element: HTMLElement;
+    html: string;
+    previousHtml: string;
+}
+
+declare const SNAP_THRESHOLD_PX = 6;
+/** Whether a move of this size has travelled far enough for snapping to apply. */
+declare function snapEngagedForTravel(dx: number, dy: number): boolean;
+interface SnapEdge {
+    position: number;
+    source: "grid";
+    id: string;
+}
+interface SnapTarget {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    centerX: number;
+    centerY: number;
+    id: string;
+}
+interface SnapGuide {
+    axis: "x" | "y";
+    position: number;
+    /** Extent of the guide line (min of involved elements). */
+    from: number;
+    /** Extent of the guide line (max of involved elements). */
+    to: number;
+}
+interface SpacingGuide {
+    axis: "x" | "y";
+    /** Position of the gap (start of gap). */
+    position: number;
+    /** Size of the gap in pixels. */
+    size: number;
+    /** Extent for rendering the indicator. */
+    from: number;
+    /** Extent for rendering the indicator. */
+    to: number;
+}
+interface SnapResult {
+    dx: number;
+    dy: number;
+    guides: SnapGuide[];
+    spacingGuides: SpacingGuide[];
+}
+interface Rect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * Convert overlay rects to snap targets with precomputed edges & centers.
+ */
+declare function extractSnapTargets(entries: Array<{
+    rect: Rect;
+    id: string;
+}>): SnapTarget[];
+/**
+ * Create a snap target from the composition/overlay boundary.
+ */
+declare function buildCompositionSnapTarget(rect: Rect): SnapTarget;
+/**
+ * Generate grid-line snap edges.
+ * `gridSpacing` is in composition pixels; `scale` converts to overlay pixels.
+ * X edges are vertical grid lines; Y edges are horizontal grid lines.
+ */
+declare function buildGridSnapEdges(compositionRect: Rect, gridSpacing: number, scale: number): {
+    x: SnapEdge[];
+    y: SnapEdge[];
+};
+declare function resolveSnapAdjustment(input: {
+    movingRect: Rect;
+    proposedDx: number;
+    proposedDy: number;
+    targets: SnapTarget[];
+    gridEdges?: {
+        x: SnapEdge[];
+        y: SnapEdge[];
+    };
+    threshold: number;
+    disabled: boolean;
+    /** Set when the gesture has not travelled far enough for snapping yet. */
+    disabledForTravel?: boolean;
+}): SnapResult;
+/**
+ * Full-length guide line spanning the composition: a vertical line (axis "x")
+ * runs the composition's height at the snapped x position; a horizontal line
+ * (axis "y") runs the composition's width. `composition` is the composition
+ * rect in overlay space — guide positions are already overlay-space, so the
+ * line must be offset by the composition's left/top (the canvas is usually
+ * letterboxed inside the overlay).
+ */
+declare function resolveGuideLineRect(guide: SnapGuide, composition: Rect): Rect;
+declare function resolveEquidistanceGuides(input: {
+    movingRect: Rect;
+    targets: SnapTarget[];
+    threshold: number;
+}): SpacingGuide[];
+
+interface SnapContext {
+    targets: SnapTarget[];
+    compositionTarget: SnapTarget | null;
+    gridEdges: {
+        x: SnapEdge[];
+        y: SnapEdge[];
+    } | null;
+    snapEnabled: boolean;
+}
+declare function collectSnapContext(input: {
+    overlayEl: HTMLDivElement;
+    iframe: HTMLIFrameElement;
+    excludeElements: Set<HTMLElement>;
+}): SnapContext;
+
+interface SnapGuidesState {
+    guides: SnapGuide[];
+    spacingGuides: SpacingGuide[];
+}
+interface SnapGuideOverlayProps {
+    snapGuidesRef: RefObject<SnapGuidesState | null>;
+    /** Composition rect in overlay space — guide lines span exactly this rect. */
+    compositionLeft: number;
+    compositionTop: number;
+    compositionWidth: number;
+    compositionHeight: number;
+}
+declare const SnapGuideOverlay: react.NamedExoticComponent<SnapGuideOverlayProps>;
+
+interface ApplyDomSelectionOptions {
+    revealPanel?: boolean;
+    additive?: boolean;
+    preserveGroup?: boolean;
+    announce?: boolean;
+}
+interface ResolveDomSelectionOptions {
+    preferClipAncestor?: boolean;
+    skipSourceProbe?: boolean;
+    activeGroupElement?: HTMLElement | null;
+    /** Resolve this node itself instead of applying human group-capture behavior. */
+    exactTarget?: boolean;
+}
+interface DomEditTimelineParams {
+    projectId: string | null;
+    activeCompPath: string | null;
+    compIdToSrc: Map<string, string>;
+    captionEditMode: boolean;
+    previewIframeRef: MutableRefObject<HTMLIFrameElement | null>;
+    timelineElements: TimelineElement[];
+    getTimelineSelectionSet: () => ReadonlySet<string>;
+    setSelectedTimelineElementId: (id: string | null, options?: SelectElementOptions) => void;
+    /** Publishes a whole multi-selection to the timeline; the anchor is set separately. */
+    setTimelineSelectionSet: (ids: Set<string>) => void;
+    setRightCollapsed: (collapsed: boolean) => void;
+    setRightPanelTab: (tab: RightPanelTab) => void;
+}
+
+interface PreviewMouseDownOptions {
+    preferClipAncestor?: boolean;
+    hoverSelection?: DomEditSelection | null;
+}
+
+interface DomEditGroupPathOffsetCommit {
+    selection: DomEditSelection;
+    next: {
+        x: number;
+        y: number;
+    };
+}
+
+/**
+ * Why a DOM edit commit did not change the file.
+ *
+ * `runDomEditCommit` resolves on persist failure by design (see its contract
+ * above), so a caller cannot learn whether the write landed by awaiting it — a
+ * failed persist and a successful one are indistinguishable. Capture and apply
+ * bugs still reject. The human path does not need to ask about handled persist
+ * failures, because `onError` already put a toast on screen. A programmatic
+ * caller has no screen, so it has to be told.
+ */
+type DomEditCommitDeclineReason = "no-project" | "no-selection" | "geometry-property" | "styles-not-editable" | "not-text-editable" | "preview-stale" | "persist-failed";
+type DomEditCommitOutcome = {
+    ok: true;
+    persistence?: DomEditPersistOutcome;
+} | {
+    ok: false;
+    reason: DomEditCommitDeclineReason;
+};
+
+/**
+ * Which elements a delete acts on.
+ *
+ * Its own module so `useDomEditSession.ts` stays under the studio's 600-line
+ * cap; it reads only its arguments.
+ */
+
+/** One entry in the studio's edit history, as `useDomEditSession`'s caller
+ *  supplies it. */
+interface RecordEditInput$1 {
+    label: string;
+    coalesceKey?: string;
+    files: Record<string, {
+        before: string;
+        after: string;
+    }>;
+}
+
+interface UseDomEditSessionParams extends DomEditTimelineParams {
+    compositionLoading: boolean;
+    showToast: (message: string, tone?: "error" | "info") => void;
+    isRecordingRef?: React.RefObject<boolean>;
+    refreshPreviewDocumentVersion: () => void;
+    queueDomEditSave: <T>(save: () => Promise<T>) => Promise<T>;
+    readProjectFile: (path: string) => Promise<string>;
+    writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
+    updateEditingFileContent: (path: string, content: string) => void;
+    editHistory: {
+        recordEdit: (entry: RecordEditInput$1) => Promise<void>;
+    };
+    fileTree: string[];
+    importedFontAssetsRef: React.MutableRefObject<ImportedFontAsset[]>;
+    projectDir: string | null;
+    projectIdRef: React.MutableRefObject<string | null>;
+    previewIframe: HTMLIFrameElement | null;
+    refreshKey: number;
+    previewDocumentVersion: number;
+    rightPanelTab: RightPanelTab;
+    applyStudioManualEditsToPreviewRef: React.MutableRefObject<(iframe: HTMLIFrameElement) => Promise<void>>;
+    syncPreviewHotkeys: (iframe: HTMLIFrameElement | null) => void;
+    reloadPreview: () => void;
+    setRefreshKey: React.Dispatch<React.SetStateAction<number>>;
+    openSourceForSelection?: (sourceFile: string, target: PatchTarget) => void;
+    sdkSession?: Composition | null;
+    publishSdkSession?: PublishSdkSession;
+    forceReloadSdkSession?: () => void;
+    /** The timeline context menu's delete op — a canvas selection that IS a
+     *  timeline row hands off here instead of the REST remove-elements path. */
+    handleTimelineElementsDelete: (elements: TimelineElement[]) => Promise<void>;
+    readOnlyPreview: boolean;
+}
+declare function useDomEditSession({ projectId, activeCompPath, compIdToSrc, captionEditMode, compositionLoading, previewIframeRef, timelineElements, getTimelineSelectionSet, setSelectedTimelineElementId, setTimelineSelectionSet, setRightCollapsed, setRightPanelTab, showToast, isRecordingRef, refreshPreviewDocumentVersion, queueDomEditSave, readProjectFile, writeProjectFile, updateEditingFileContent, editHistory, fileTree, importedFontAssetsRef, projectDir, projectIdRef, previewIframe, refreshKey, previewDocumentVersion, rightPanelTab, applyStudioManualEditsToPreviewRef, syncPreviewHotkeys, reloadPreview, setRefreshKey: _setRefreshKey, openSourceForSelection, sdkSession, publishSdkSession, forceReloadSdkSession, handleTimelineElementsDelete, readOnlyPreview, }: UseDomEditSessionParams): {
+    domEditSelection: DomEditSelection | null;
+    domEditGroupSelections: DomEditSelection[];
+    domEditHoverSelection: DomEditSelection | null;
+    activeGroupElement: HTMLElement | null;
+    agentModalOpen: boolean;
+    agentModalAnchorPoint: AgentModalAnchorPoint | null;
+    copiedAgentPrompt: boolean;
+    agentPromptSelectionContext: string | undefined;
+    domEditSelectionRef: react.MutableRefObject<DomEditSelection | null>;
+    handleTimelineElementSelect: (element: TimelineElement | null) => Promise<void>;
+    handlePreviewCanvasMouseDown: (e: React.MouseEvent<HTMLDivElement>, options?: PreviewMouseDownOptions) => Promise<void>;
+    handlePreviewCanvasPointerMove: (e: React.PointerEvent<HTMLDivElement>, options?: {
+        preferClipAncestor?: boolean;
+    }) => Promise<DomEditSelection | null>;
+    handlePreviewCanvasPointerLeave: () => void;
+    applyDomSelection: (selection: DomEditSelection | null, options?: ApplyDomSelectionOptions) => void;
+    clearDomSelection: () => void;
+    refreshDomEditSelectionFromPreview: (selection: DomEditSelection) => Promise<void>;
+    handleDomStyleCommit: (property: string, value: string) => Promise<DomEditCommitOutcome>;
+    handleDomStyleCommitForSelection: (selection: DomEditSelection, property: string, value: string) => Promise<DomEditCommitOutcome>;
+    handleDomAttributeCommit: (attr: string, value: string) => Promise<void>;
+    handleDomAttributeLiveCommit: (attr: string, value: string | null, onSettled?: (ok: boolean) => void, live?: {
+        previewOnly?: boolean;
+    }) => Promise<void>;
+    handleDomAttributeQuietCommit: (attr: string, value: string | null) => Promise<void>;
+    handleDomHtmlAttributeCommit: (attr: string, value: string | null) => Promise<void>;
+    handleDomAttributesCommit: (selection: DomEditSelection, attrs: Record<string, string>) => Promise<void>;
+    handleDomPathOffsetCommit: (selection: DomEditSelection, next: {
+        x: number;
+        y: number;
+    }, modifiers?: {
+        altKey?: boolean;
+    }) => Promise<void>;
+    handleDomGroupPathOffsetCommit: (updates: DomEditGroupPathOffsetCommit[]) => Promise<void>;
+    handleDomZIndexReorderCommit: (entries: Array<{
+        element: HTMLElement;
+        zIndex: number;
+        id?: string;
+        selector?: string;
+        selectorIndex?: number;
+        sourceFile: string;
+        key?: string;
+    }>, gestureCoalesceKey?: string, actionKind?: string) => Promise<void> | Promise<DomEditPatchBatchesResult>;
+    handleDomBoxSizeCommit: (selection: DomEditSelection, next: {
+        width: number;
+        height: number;
+    }, offset?: {
+        x: number;
+        y: number;
+    }, restore?: () => void) => Promise<void>;
+    handleDomRotationCommit: (selection: DomEditSelection, next: {
+        angle: number;
+    }) => Promise<void>;
+    handleDomManualEditsReset: (selection: DomEditSelection) => Promise<void>;
+    handleDomTextCommit: (value: string, fieldKey?: string) => Promise<DomEditCommitOutcome>;
+    handleDomTextCommitForSelection: (selection: DomEditSelection, value: string, fieldKey?: string) => Promise<DomEditCommitOutcome>;
+    handleDomRichTextCommit: ({ element, html, previousHtml }: InlineTextEditCommit) => Promise<void>;
+    handleDomTextFieldStyleCommit: (fieldKey: string, property: string, value: string) => Promise<void>;
+    handleDomAddTextField: (afterFieldKey?: string) => Promise<string | null>;
+    handleDomRemoveTextField: (fieldKey: string) => Promise<void>;
+    getGsapAnimationsForSelection: (selection: DomEditSelection) => _hyperframes_parsers.GsapAnimation[] | Promise<_hyperframes_parsers.GsapAnimation[]>;
+    handleAskAgent: () => void;
+    handleAgentModalSubmit: (userInstruction: string) => Promise<void>;
+    handleBlockedDomMove: (selection: DomEditSelection) => void;
+    handleDomManualDragStart: () => void;
+    handleDomEditElementDelete: (selection: DomEditSelection, options?: {
+        expandGroup?: boolean;
+    }) => Promise<void>;
+    handleGroupSelection: () => void;
+    handleUngroupSelection: () => void;
+    setActiveGroupElement: (el: HTMLElement | null) => void;
+    buildDomSelectionFromTarget: (target: HTMLElement, options?: ResolveDomSelectionOptions) => Promise<DomEditSelection | null>;
+    buildDomSelectionForTimelineElement: (element: TimelineElement) => Promise<DomEditSelection | null>;
+    updateDomEditHoverSelection: (selection: DomEditSelection | null) => void;
+    applyMarqueeSelection: (selections: DomEditSelection[], additive: boolean) => void;
+    resolveImportedFontAsset: (fontFamilyValue: string) => ImportedFontAsset | null;
+    setAgentModalOpen: react.Dispatch<react.SetStateAction<boolean>>;
+    setAgentPromptSelectionContext: react.Dispatch<react.SetStateAction<string | undefined>>;
+    setAgentModalAnchorPoint: react.Dispatch<react.SetStateAction<AgentModalAnchorPoint | null>>;
+    selectedGsapAnimations: _hyperframes_parsers.GsapAnimation[];
+    gsapMultipleTimelines: boolean;
+    gsapUnsupportedTimelinePattern: boolean;
+    handleGsapUpdateProperty: (animId: string, prop: string, value: number | string) => void;
+    handleGsapUpdateMeta: (animId: string, updates: {
+        duration?: number;
+        ease?: string;
+        position?: number;
+    }, selectionOverride?: DomEditSelection | null) => Promise<boolean>;
+    handleGsapDeleteAnimation: (animId: string, selectionOverride?: DomEditSelection | null) => Promise<boolean>;
+    handleGsapDeleteAllForElement: (targetSelector: string) => void;
+    handleGsapAddAnimation: (method: "to" | "from" | "set" | "fromTo", selectionOverride?: DomEditSelection | null) => Promise<boolean>;
+    handleGsapAddProperty: (animId: string, prop: string) => void;
+    handleGsapRemoveProperty: (animId: string, prop: string) => void;
+    handleGsapUpdateFromProperty: (animId: string, prop: string, value: number | string) => void;
+    handleGsapAddFromProperty: (animId: string, prop: string) => void;
+    handleGsapRemoveFromProperty: (animId: string, prop: string) => void;
+    handleGsapAddKeyframe: (animId: string, percentage: number, property: string, value: number | string, selectionOverride?: DomEditSelection | null) => void;
+    handleGsapAddKeyframeBatch: (animId: string, percentage: number, properties: Record<string, number | string>, commitOverrides?: Partial<CommitMutationOptions>, selectionOverride?: DomEditSelection | null) => Promise<void>;
+    handleGsapRemoveKeyframe: (animId: string, percentage: number, commitOverrides?: Partial<CommitMutationOptions>, selectionOverride?: DomEditSelection | null) => void;
+    handleGsapMoveKeyframeToPlayhead: (animId: string, fromPercentage: number, selectionOverride?: DomEditSelection | null, animationOverride?: _hyperframes_parsers.GsapAnimation) => void;
+    handleGsapMoveKeyframe: (animId: string, fromPercentage: number, toPercentage: number, selectionOverride?: DomEditSelection | null) => Promise<boolean>;
+    handleGsapResizeKeyframedTween: (animId: string, position: number, duration: number, pctRemap: Array<{
+        from: number;
+        to: number;
+    }>, selectionOverride?: DomEditSelection | null) => Promise<boolean>;
+    handleGsapConvertToKeyframes: (animId: string, resolvedFromValues?: Record<string, number | string>, duration?: number, commitOverrides?: Partial<CommitMutationOptions>, selectionOverride?: DomEditSelection | null) => Promise<void>;
+    handleGsapRemoveAllKeyframes: (animId: string, selectionOverride?: DomEditSelection | null) => Promise<boolean>;
+    handleResetSelectedElementKeyframes: () => boolean;
+    handleUpdateKeyframeEase: (animationId: string, percentage: number, ease: string) => void;
+    handleUpdateSegmentEase: (targets: AnimationKeyframeTarget[], ease: string) => void;
+    handleSetAllKeyframeEases: (animationId: string, ease: string) => void;
+    commitAnimatedProperty: (selection: DomEditSelection, property: string, value: number | string) => Promise<void>;
+    commitAnimatedProperties: (selection: DomEditSelection, properties: Record<string, number | string>) => Promise<void>;
+    handleSetArcPath: (animId: string, config: Parameters<(sel: DomEditSelection, animId: string, config: {
+        enabled: boolean;
+        autoRotate?: boolean | number;
+        segments?: Array<{
+            curviness: number;
+            cp1?: {
+                x: number;
+                y: number;
+            };
+            cp2?: {
+                x: number;
+                y: number;
+            };
+        }>;
+    }) => void>[2]) => void;
+    handleUpdateArcSegment: (animId: string, segmentIndex: number, update: Parameters<(sel: DomEditSelection, animId: string, segmentIndex: number, update: {
+        curviness?: number;
+        cp1?: {
+            x: number;
+            y: number;
+        };
+        cp2?: {
+            x: number;
+            y: number;
+        };
+    }) => void>[3]) => void;
+    handleUnroll: () => void;
+    invalidateGsapCache: () => void;
+    previewIframeRef: react.MutableRefObject<HTMLIFrameElement | null>;
+    commitMutation: (mutation: Record<string, unknown>, options: {
+        label: string;
+        softReload?: boolean;
+    }) => Promise<void>;
+};
+
+interface DomEditSaveQueue {
+    enqueue: <T>(save: () => Promise<T>) => Promise<T>;
+    waitForIdle: () => Promise<DomEditSaveDrainResult>;
+    reset: () => void;
+    destroy: () => void;
+}
+type DomEditSaveDrainResult = StudioSaveDrainResult;
+
+/** One file's restore from the edit-history store: before (live) / after (target) bytes. */
+interface UndoRestoreFile {
+    previous: string;
+    restored: string;
+}
+
+/** The restore payload the undo/redo preview-sync consumes (from the history store). */
+interface HistoryPreviewRestore {
+    paths?: string[];
+    files?: Record<string, UndoRestoreFile>;
+}
+interface RecordEditInput {
+    label: string;
+    coalesceKey?: string;
+    files: Record<string, {
+        before: string;
+        after: string;
+    }>;
+}
+interface UsePreviewPersistenceParams {
+    showToast: (message: string, tone?: "error" | "info") => void;
+    readOptionalProjectFile: (path: string) => Promise<string>;
+    writeProjectFile: (path: string, content: string) => Promise<void>;
+    recordEdit: (entry: RecordEditInput) => Promise<void>;
+    previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
+    activeCompPathRef: React.MutableRefObject<string | null>;
+    /** Called to reload the preview after undo/redo or external file changes. */
+    reloadPreview: () => void;
+}
+declare function usePreviewPersistence({ showToast, readOptionalProjectFile: _readOptionalProjectFile, writeProjectFile: _writeProjectFile, recordEdit: _recordEdit, previewIframeRef, activeCompPathRef, reloadPreview, }: UsePreviewPersistenceParams): {
+    domTextCommitVersionRef: react.RefObject<number>;
+    domEditSaveQueueRef: react.RefObject<DomEditSaveQueue | null>;
+    applyStudioManualEditsToPreviewRef: react.RefObject<(iframe?: HTMLIFrameElement | null) => Promise<void>>;
+    queueDomEditSave: <T>(save: () => Promise<T>) => Promise<T>;
+    drainPendingDomEditSaves: () => Promise<{
+        status: "clean";
+    } | {
+        status: "conflict";
+        error: StudioFileConflictError;
+    } | {
+        status: "failed";
+        error: unknown;
+    }>;
+    waitForPendingDomEditSaves: () => Promise<void>;
+    domEditSaveQueuePaused: string | null;
+    resetDomEditSaveQueueBreaker: () => void;
+    applyCurrentStudioManualEditsToPreview: (iframe?: HTMLIFrameElement | null) => void;
+    applyStudioManualEditsToPreview: (iframe?: HTMLIFrameElement | null) => Promise<void>;
+    syncHistoryPreviewAfterApply: (restore: HistoryPreviewRestore) => Promise<void>;
+};
+
+type DomEditValue = ReturnType<typeof useDomEditSession>;
+interface DomEditSelectionValue extends Pick<DomEditValue, "domEditSelection" | "domEditGroupSelections" | "domEditHoverSelection" | "activeGroupElement" | "domEditSelectionRef" | "selectedGsapAnimations" | "gsapMultipleTimelines" | "gsapUnsupportedTimelinePattern" | "agentModalOpen" | "agentModalAnchorPoint" | "copiedAgentPrompt" | "agentPromptSelectionContext"> {
+}
+declare function useDomEditSelectionContext(): DomEditSelectionValue;
+declare function DomEditProvider({ value: { domEditSelection, domEditGroupSelections, domEditHoverSelection, agentModalOpen, agentModalAnchorPoint, copiedAgentPrompt, agentPromptSelectionContext, domEditSelectionRef, handleTimelineElementSelect, handlePreviewCanvasMouseDown, handlePreviewCanvasPointerMove, handlePreviewCanvasPointerLeave, applyDomSelection, clearDomSelection, refreshDomEditSelectionFromPreview, handleDomStyleCommit, handleDomStyleCommitForSelection, handleDomAttributeCommit, handleDomAttributeLiveCommit, handleDomAttributeQuietCommit, handleDomHtmlAttributeCommit, handleDomAttributesCommit, handleDomPathOffsetCommit, handleDomGroupPathOffsetCommit, handleDomZIndexReorderCommit, handleDomBoxSizeCommit, handleDomRotationCommit, handleDomManualEditsReset, handleDomTextCommit, handleDomTextCommitForSelection, handleDomRichTextCommit, handleDomTextFieldStyleCommit, handleDomAddTextField, handleDomRemoveTextField, getGsapAnimationsForSelection, handleAskAgent, handleAgentModalSubmit, handleBlockedDomMove, handleDomManualDragStart, handleDomEditElementDelete, handleGroupSelection, handleUngroupSelection, setActiveGroupElement, activeGroupElement, buildDomSelectionFromTarget, buildDomSelectionForTimelineElement, updateDomEditHoverSelection, resolveImportedFontAsset, setAgentModalOpen, setAgentPromptSelectionContext, setAgentModalAnchorPoint, selectedGsapAnimations, gsapMultipleTimelines, gsapUnsupportedTimelinePattern, handleGsapUpdateProperty, handleGsapUpdateMeta, handleGsapDeleteAnimation, handleGsapDeleteAllForElement, handleGsapAddAnimation, handleGsapAddProperty, handleGsapRemoveProperty, handleGsapUpdateFromProperty, handleGsapAddFromProperty, handleGsapRemoveFromProperty, handleGsapAddKeyframe, handleGsapAddKeyframeBatch, handleGsapRemoveKeyframe, handleGsapMoveKeyframeToPlayhead, handleGsapMoveKeyframe, handleGsapResizeKeyframedTween, handleGsapConvertToKeyframes, handleGsapRemoveAllKeyframes, handleResetSelectedElementKeyframes, commitAnimatedProperty, commitAnimatedProperties, handleSetArcPath, handleUpdateArcSegment, handleUnroll, invalidateGsapCache, previewIframeRef, commitMutation, applyMarqueeSelection, handleUpdateKeyframeEase, handleUpdateSegmentEase, handleSetAllKeyframeEases, }, children, }: {
+    value: DomEditValue;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+declare function PreviewReadOnlyProvider({ readOnly, reason, children, }: {
+    readOnly: boolean;
+    reason?: string;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pure z-order helpers for the canvas right-click context menu.
+ *
+ * Layering strategy: z-index + CSS stacking context (position ≠ static).
+ * All sibling z-index values are read from the live iframe DOM via
+ * element.style.zIndex (inline style, set by the editor) falling back to
+ * the computed value. Treat missing / "auto" as 0 for comparison purposes.
+ *
+ * "Overlapping siblings" = siblings whose bounding rects intersect the
+ * target's bounding rect AND are actually visible at the current frame.
+ * Forward/backward operate within that set; front/back operate across all
+ * siblings (full painting family, visible or not — unchanged semantics).
+ *
+ * ── Visibility ───────────────────────────────────────────────────────────────
+ * In HyperFrames compositions the nearest z-neighbor is often INVISIBLE at the
+ * paused frame: the runtime hides time-inactive clips with inline
+ * `visibility:hidden` / `display:none` (see core runtime
+ * syncTimedElementVisibility), and GSAP timelines park elements at `opacity:0`.
+ * Stepping "forward" over such a sibling looks like a silent no-op. The
+ * forward/backward comparison set therefore keeps only siblings whose
+ * element-level computed style is visible (display ≠ none, visibility ≠
+ * hidden, opacity > 0.01) — all runtime hiding signals are inline styles, so
+ * computed style covers them. Ancestor-chain checks are unnecessary here:
+ * siblings share the target's ancestors. The probe is injectable
+ * (ZOrderResolveOptions.isVisible) so the pure-module tests stay meaningful
+ * without a real style engine, mirroring how tests stub rect reading.
+ *
+ * ── Tie-awareness ────────────────────────────────────────────────────────────
+ * CSS paint order for elements that share a z-index is DOM document order:
+ * the element that comes LATER in the DOM paints ON TOP. The old resolver
+ * compared z-index alone, so a target tied with the element visually below it
+ * (equal z, target later in DOM) had an empty "below" set and silently
+ * no-op'd. This module computes true render order — sort by
+ * (zIndex asc, DOM position asc), bottom→top — moves the target one step (or
+ * to an end) in that order, then realizes the new order back into z values.
+ *
+ * The result is a MULTI-element patch: a single-element patch when a
+ * strictly-between z value can express the new order given DOM-order
+ * tie-breaking, otherwise a minimal renumber of the affected set (emitting
+ * patches only for elements whose z actually changes). z is never negative
+ * (project convention clamps z ≥ 0).
+ */
+type ZOrderAction = "bring-forward" | "send-backward" | "bring-to-front" | "send-to-back";
+/** A resolved change: set `element`'s z-index to `zIndex`. */
+interface ZOrderPatch {
+    element: HTMLElement;
+    zIndex: number;
+}
+
+interface DomEditOverlayProps {
+    iframeRef: RefObject<HTMLIFrameElement | null>;
+    activeCompositionPath: string | null;
+    selection: DomEditSelection | null;
+    groupSelections?: DomEditSelection[];
+    hoverSelection: DomEditSelection | null;
+    allowCanvasMovement?: boolean;
+    /** "host": no hover, marquee or box re-select; Enter with nothing focused still opens text. */
+    canvasInput?: "overlay" | "host";
+    onTextEditingChange?: (editing: boolean) => void;
+    /** A click on a single selection's box, in either mode; the event may be the pointerup. */
+    onSelectionBoxClick?: (event: React.MouseEvent<HTMLDivElement>, selection: DomEditSelection) => void;
+    onCanvasMouseDown: (event: React.MouseEvent<HTMLDivElement>, options?: PreviewMouseDownOptions) => void;
+    onCanvasPointerMove: (event: React.PointerEvent<HTMLDivElement>, options?: {
+        preferClipAncestor?: boolean;
+    }) => Promise<DomEditSelection | null>;
+    onCanvasPointerLeave: () => void;
+    onSelectionChange: (selection: DomEditSelection, options?: {
+        revealPanel?: boolean;
+        additive?: boolean;
+    }) => void;
+    onBlockedMove: (selection: DomEditSelection) => void;
+    onManualDragStart?: () => void;
+    onPathOffsetCommit: (selection: DomEditSelection, next: {
+        x: number;
+        y: number;
+    }, modifiers?: {
+        altKey?: boolean;
+    }) => Promise<void> | void;
+    onGroupPathOffsetCommit: (updates: DomEditGroupPathOffsetCommit[]) => Promise<void> | void;
+    onBoxSizeCommit: (selection: DomEditSelection, next: {
+        width: number;
+        height: number;
+    }, offset?: {
+        x: number;
+        y: number;
+    }, restore?: () => void) => Promise<void> | void;
+    onRotationCommit: (selection: DomEditSelection, next: {
+        angle: number;
+    }) => Promise<void> | void;
+    onStyleCommit?: (property: string, value: string) => Promise<unknown> | void;
+    recordingState?: GestureRecordingState;
+    onToggleRecording?: () => void;
+    onMarqueeSelect?: (selections: DomEditSelection[], additive: boolean) => void;
+    /**
+     * Delete the selected canvas element.
+     * Wire to handleDomEditElementDelete from useDomEditActionsContext —
+     * same handler the Delete/Backspace hotkey uses.
+     */
+    onDeleteSelection?: (selection: DomEditSelection) => void;
+    /**
+     * Called with the resolved z-order patch list and the menu action that
+     * produced it (feeds the undo coalesce key). The patch list is tie-aware and
+     * may include sibling elements (see canvasContextMenuZOrder); the live DOM is
+     * NOT yet mutated. Wire to handleDomZIndexReorderCommit from
+     * useDomEditActionsContext. See CanvasContextMenu.tsx module comment.
+     */
+    onApplyZIndex?: (selection: DomEditSelection, patches: ZOrderPatch[], action: ZOrderAction, 
+    /** Sibling a forward/backward step moved past (pre-mutation render order);
+     *  null for front/back. Feeds the timeline z-mirror's crossedKey. */
+    crossed: HTMLElement | null) => void;
+}
+declare const DomEditOverlay: react.NamedExoticComponent<DomEditOverlayProps>;
+
+type HostInputProps = Pick<ComponentProps<typeof DomEditOverlay>, "canvasInput" | "onSelectionBoxClick">;
+interface ConnectedDomEditOverlayProps extends HostInputProps {
+    activeCompositionPath: string | null;
+    showHoverSelection: boolean;
+    shouldShowSelectedDomBounds: boolean;
+    isGestureRecording?: boolean;
+    /** True when an in-place text edit opens its caret, false when it ends or unmounts. */
+    onTextEditingChange?: (editing: boolean) => void;
+}
+declare function ConnectedDomEditOverlay({ activeCompositionPath, showHoverSelection, shouldShowSelectedDomBounds, isGestureRecording, canvasInput, onTextEditingChange, onSelectionBoxClick, }: ConnectedDomEditOverlayProps): react_jsx_runtime.JSX.Element;
+
+interface MarqueeGesturesDeps<T = DomEditSelection> {
+    iframeRef: React.RefObject<HTMLIFrameElement | null>;
+    overlayRef: React.RefObject<HTMLDivElement | null>;
+    activeCompositionPathRef: React.RefObject<string | null>;
+    onMarqueeSelectRef: React.RefObject<((selections: T[], additive: boolean) => void) | undefined>;
+    /** Turns the elements a drag touched into picks; without it, Studio's edit selections. */
+    resolveHits?: (elements: HTMLElement[]) => T[] | Promise<T[]>;
+    selectionRef?: React.RefObject<DomEditSelection | null>;
+    /** Studio's pointer handling, for the events that are not part of a marquee. */
+    gestures?: {
+        onPointerMove: (event: React.PointerEvent<HTMLDivElement>) => void;
+        onPointerUp: (event: React.PointerEvent<HTMLDivElement>) => void;
+        clearPointerState: (ref: React.RefObject<DomEditSelection | null>) => void;
+    };
+}
+interface MarqueeGestures {
+    marqueeRect: Rect$1 | null;
+    candidateRects: Rect$1[];
+    /** Starts a marquee at this press; the host has decided it landed on empty canvas. */
+    begin: (event: React.PointerEvent<HTMLElement>) => void;
+    /** Drops an active marquee without selecting anything. */
+    cancel: () => void;
+    onPointerMove: (event: React.PointerEvent<HTMLDivElement>) => void;
+    onPointerUp: (event: React.PointerEvent<HTMLDivElement>) => void;
+    onPointerCancel: () => void;
+}
+declare function useMarqueeGestures(deps: MarqueeGesturesDeps): MarqueeGestures;
+declare function useMarqueeGestures<T>(deps: MarqueeGesturesDeps<T> & Required<Pick<MarqueeGesturesDeps<T>, "resolveHits">>): MarqueeGestures;
+
+interface MarqueeOverlayProps {
+    /** Elements the marquee currently intersects — outlined live before mouse-up. */
+    candidateRects: Rect$1[];
+    /** The marquee drag rectangle itself, or null when not marquee-selecting. */
+    marqueeRect: Rect$1 | null;
+}
+/**
+ * The marquee selection visuals: a live "candidate" outline on each element the
+ * box currently touches, plus the dashed drag rectangle. Extracted from
+ * DomEditOverlay to keep that file under the 600-line cap.
+ */
+declare function MarqueeOverlay({ candidateRects, marqueeRect }: MarqueeOverlayProps): react_jsx_runtime.JSX.Element;
+
+export { type AgentModalAnchorPoint, type AgentPromptElementInfo, AskAgentModal, type AskAgentModalProps, AudioMeterStrip, type AudioMeterStripProps, AudioWaveform, type AudioWaveformProps, type BlockedTimelineEditIntent, type CanEditTimelineElement, CompositionBreadcrumb, type CompositionDimensions, type CompositionLevel, CompositionThumbnail, ConnectedDomEditOverlay, type ConnectedDomEditOverlayProps, DEFAULT_SHORTCUT_SECTIONS, type DomEditCapabilities, DomEditProvider, type DomEditSelection, type EditHistoryHandle, EditorShell, type EditorShellProps, type ExternalFileChangeBlockedState, type ExternalFileChangeCoordinatorHandle, ExternalFileConflictBanner, type FfmpegStatus, FileTree, GridOverlay, ImageThumbnail, type ImageThumbnailProps, type MarqueeGestures, type MarqueeGesturesDeps, MarqueeOverlay, type MarqueeOverlayProps, type Rect$1 as MarqueeRect, NLEPreview, type PatchOperation, type PersistedRenderSettings, type PickedElement, PlayerControls, type PlayerHandle, type PlayerHandleElement, type PlayerHandleListener, type PlayerHandleTimeListener, type DomEditCompositionRect as PreviewCompositionRect, PreviewGuides, PreviewOverlayProvider, type PreviewOverlayProviderProps, PreviewReadOnlyProvider, type PreviewSnapPreferences, PropertyPanel, type RenderJob, RenderQueue, type RenderQueueProps, type ResolutionPreset, SNAP_THRESHOLD_PX, type ShortcutHint, type ShortcutSection, type SnapContext, type SnapEdge, type SnapGuide, SnapGuideOverlay, type SnapGuideOverlayProps, type SnapGuidesState, type Rect as SnapRect, type SnapResult, type SnapTarget, SnapToolbar, SourceEditor, type SpacingGuide, type StartRenderOptions, StudioApp, StudioFileConflictError, type StudioPendingEditsDrainResult, type ThumbnailPriority, Timeline, TimelineClipMenu, type TimelineClipRenderContext, type TimelineEditCallbacks, type TimelineEditOutcome, type TimelineEditPermission, TimelineEditPopover, TimelineEditProvider, type TimelineElement, TimelineEmptyStatePart, TimelineFrame, TimelineGapMenu, TimelineHistoryButtons, type TimelineHistoryButtonsProps, TimelineKeyframeMenu, TimelineLanes, TimelineOverlays, TimelinePane, type TimelinePaneProps, TimelinePlayhead, TimelineProvider, TimelineRazorGuide, TimelineRuler, TimelineShortcutHint, type TimelineTheme, type TimelineTimeRange$1 as TimelineTimeRange, TimelineToolbar, type TimelineToolbarProps, type TimelineZIndexReorderCommit, type UseClipboardOptions, type UseDomEditSessionParams, type UseEditHistoryActionsOptions, type UsePersistentEditHistoryOptions, type UsePreviewPersistenceParams, type UseProjectFileWriterOptions, type UseRenderClipContentOptions, type UseTimelineEditingOptions, VideoThumbnail, applyPatch, buildCompositionSnapTarget, buildGridSnapEdges, buildPickerAgentContextPreview, buildPickerAgentPrompt, collectSnapContext, extractSnapTargets, findElementBlock, flushStudioPendingEdits, formatTime, getPersistedRenderSettings, liveTime, mergeStyleIntoTag, parseStyleString, persistRenderSettings, resolveEquidistanceGuides, resolveGuideLineRect, resolveIframe, resolveSnapAdjustment, resolveSourceFile, snapEngagedForTravel, useClipboard, useDomEditSelectionContext, useDomEditSession, useEditHistoryActions, useElementPicker, useMarqueeGestures, usePersistentEditHistory, usePlayerHandle, usePlayerStore, usePreviewCompositionRect, usePreviewGuidesStore, usePreviewOverlayContext, usePreviewPersistence, useProjectFileWriter, useRenderClipContent, useRenderQueue, useTimelineContext, useTimelineEditing, useTimelinePlayer };