@hyperframes/studio 0.8.105 → 0.8.107

package/dist/index.d.ts

@@ -4,12 +4,12 @@ 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, ParsedGsap, PropertyGroupName } from '@hyperframes/core/gsap-parser';
+import { GsapAnimation as GsapAnimation$1, ArcPathSegment } from '@hyperframes/parsers/gsap-parser';
 import { Composition } from '@hyperframes/sdk';
 import * as zustand from 'zustand';
 import { StoreApi } from 'zustand';
 export { Player } from './player.js';
 import { MusicBeatAnalysis } from '@hyperframes/core/beats';
-import { GsapAnimation as GsapAnimation$1, ArcPathSegment } from '@hyperframes/parsers/gsap-parser';
 import * as _hyperframes_parsers from '@hyperframes/parsers';
 import { CanvasResolution } from '@hyperframes/parsers';
 export { SeamTransitionFrameSource, SeamTransitionLoopHandle, SeamTransitionLoopOptions, playSeamTransitionLoop } from '@hyperframes/shader-transitions';
@@ -699,6 +699,19 @@ interface DomEditSelection extends PatchTarget {
     capabilities: DomEditCapabilities;
     gsapAnimations?: GsapAnimation$1[];
 }
+interface DomEditLayerItem {
+    key: string;
+    element: HTMLElement;
+    label: string;
+    tagName: string;
+    depth: number;
+    childCount: number;
+    id?: string;
+    hfId?: string;
+    selector?: string;
+    selectorIndex?: number;
+    sourceFile: string;
+}
 interface DomEditContextOptions {
     activeCompositionPath: string | null;
     isMasterView: boolean;
@@ -797,6 +810,14 @@ interface TimelineRangeSelection {
     anchorY: number;
 }
 
+interface ImportedFontAsset {
+    family: string;
+    path: string;
+    url: string;
+    weight?: string;
+    style?: "normal" | "italic";
+}
+
 /** Durable evidence returned by the one Studio DOM persistence actor. */
 interface DomEditPersistOutcome {
     sourceFile: string;
@@ -816,6 +837,11 @@ interface DomEditPatchBatchesResult {
     allMatched: boolean;
     changed: boolean;
 }
+/** Several data-* and HTML attribute ops on one element as ONE persist and ONE undo entry. */
+type CommitDomAttributeBatch = (selection: DomEditSelection, operations: PatchOperation[], options: {
+    label: string;
+    prepareContent?: (html: string) => string;
+}) => Promise<boolean>;
 
 interface RecordEditInput$5 {
     label: string;
@@ -2182,14 +2208,6 @@ interface SourceEditorProps {
 }
 declare const SourceEditor: react.NamedExoticComponent<SourceEditorProps>;
 
-interface ImportedFontAsset {
-    family: string;
-    path: string;
-    url: string;
-    weight?: string;
-    style?: "normal" | "italic";
-}
-
 /**
  * Edit callbacks shared by GsapAnimationSection and each AnimationCard it
  * renders. Extracted so the two prop interfaces don't duplicate the (large)
@@ -2277,6 +2295,7 @@ interface PropertyPanelProps {
         changedElements: number;
     }>;
     onSetHtmlAttribute: (attr: string, value: string | null) => void | Promise<void>;
+    onSetAttributeBatch: CommitDomAttributeBatch;
     onRemoveBackground?: (inputPath: string, options: {
         createBackgroundPlate?: boolean;
         quality?: "fast" | "balanced" | "best";
@@ -2887,6 +2906,9 @@ interface AudioMeterStripProps {
 }
 declare const AudioMeterStrip: react.NamedExoticComponent<AudioMeterStripProps>;
 
+type InPlace = {
+    inPlace?: boolean;
+};
 interface RecordEditInput$3 {
     label: string;
     coalesceKey?: string;
@@ -2910,9 +2932,9 @@ interface UseClipboardOptions {
 }
 declare function useClipboard({ projectId, activeCompPath, domEditSelectionRef, showToast, writeProjectFile, recordEdit, reloadPreview, handleTimelineElementsDelete, handleDomEditElementDelete, previewIframeRef, waitForPendingDomEditSaves, }: UseClipboardOptions): {
     handleCopy: () => boolean;
-    handlePaste: () => Promise<void>;
+    handlePaste: (options?: InPlace) => Promise<void>;
     handleCut: () => Promise<boolean>;
-    handleDuplicate: () => Promise<boolean>;
+    handleDuplicate: (options?: InPlace) => Promise<boolean>;
     canPaste: () => boolean;
 };
 
@@ -3185,7 +3207,7 @@ interface UseDomEditSessionParams extends DomEditTimelineParams {
     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): {
+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: hostPreviewIframe, refreshKey, previewDocumentVersion, rightPanelTab, applyStudioManualEditsToPreviewRef, syncPreviewHotkeys, reloadPreview, openSourceForSelection, sdkSession, publishSdkSession, forceReloadSdkSession, handleTimelineElementsDelete, readOnlyPreview, }: UseDomEditSessionParams): {
     domEditSelection: DomEditSelection | null;
     domEditGroupSelections: DomEditSelection[];
     domEditHoverSelection: DomEditSelection | null;
@@ -3213,6 +3235,7 @@ declare function useDomEditSession({ projectId, activeCompPath, compIdToSrc, cap
     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>;
+    handleDomAttributeBatchCommit: CommitDomAttributeBatch;
     handleDomPathOffsetCommit: (selection: DomEditSelection, next: {
         x: number;
         y: number;
@@ -3330,6 +3353,14 @@ declare function useDomEditSession({ projectId, activeCompPath, compIdToSrc, cap
     }) => Promise<void>;
 };
 
+/** The one source for which preview is on screen: the host's iframe, then each reload promoted in its place. */
+declare function useLivePreviewIframe(host: HTMLIFrameElement | null): HTMLIFrameElement | null;
+
+type PreviewPromotion = {
+    retired: HTMLIFrameElement | null;
+    live: HTMLIFrameElement;
+};
+
 interface DomEditSaveQueue {
     enqueue: <T>(save: () => Promise<T>) => Promise<T>;
     waitForIdle: () => Promise<DomEditSaveDrainResult>;
@@ -3377,6 +3408,7 @@ declare function usePreviewPersistence({ showToast, readOptionalProjectFile: _re
         error: unknown;
     }>;
     waitForPendingDomEditSaves: () => Promise<void>;
+    settlePendingEdits: () => Promise<void>;
     domEditSaveQueuePaused: string | null;
     resetDomEditSaveQueueBreaker: () => void;
     applyCurrentStudioManualEditsToPreview: (iframe?: HTMLIFrameElement | null) => void;
@@ -3389,7 +3421,7 @@ 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, }: {
+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, handleDomAttributeBatchCommit, 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;
@@ -3629,4 +3661,339 @@ interface MarqueeOverlayProps {
  */
 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, Dock, type DockController, type DomEditCapabilities, type DomEditCommitDeclineReason, type DomEditCommitOutcome, type DomEditGroupPathOffsetCommit, DomEditOverlay, type DomEditOverlayProps, DomEditProvider, type DomEditSelection, type DomEditZOrder, type DomGeometryCommits, 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 PanelId, 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, ShortcutsButton, type ShortcutsButtonProps, 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, TRACK_H, type ThumbnailPriority, Timeline, TimelineClipMenu, type TimelineClipMenuItem, 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 TimelineTrackPadding, type TimelineZIndexReorderCommit, type UseClipboardOptions, type UseDomEditSessionParams, type UseDomGeometryCommitOptions, type UseDomStyleCommitOptions, type UseEditHistoryActionsOptions, type UsePersistentEditHistoryOptions, type UsePreviewPersistenceParams, type UseProjectFileWriterOptions, type UseRenderClipContentOptions, type UseTimelineEditingOptions, VideoThumbnail, type ZOrderAction, applyPatch, buildCompositionSnapTarget, buildGridSnapEdges, buildPickerAgentContextPreview, buildPickerAgentPrompt, collectSnapContext, extractSnapTargets, findElementBlock, flushStudioPendingEdits, formatTime, getPersistedRenderSettings, liveTime, mergeStyleIntoTag, parseStyleString, persistRenderSettings, resolveDomEditSelection, resolveEquidistanceGuides, resolveGuideLineRect, resolveIframe, resolveSnapAdjustment, resolveSourceFile, snapEngagedForTravel, useClipboard, useCompositionStack, useDockLayoutStore, useDomEditSelectionContext, useDomEditSession, useDomEditZOrder, useDomGeometryCommit, useDomStyleCommit, useEditHistoryActions, useElementPicker, useMarqueeGestures, usePersistentEditHistory, usePlayerHandle, usePlayerStore, usePreviewCompositionRect, usePreviewGuidesStore, usePreviewOverlayContext, usePreviewPersistence, useProjectFileWriter, useRenderClipContent, useRenderQueue, useTimelineContext, useTimelineEditing, useTimelinePlayer };
+/**
+ * The slice of the WebMCP browser API that Studio uses.
+ *
+ * Mirrors the WebIDL in the W3C spec (`webmachinelearning/webmcp`, `index.bs`)
+ * as of 2026-08-26. Two things worth knowing before editing this file:
+ *
+ * - The API hangs off `document`, NOT `navigator`. `navigator.modelContext` is
+ *   a polyfill compatibility shim, not a spec member, so feature-detecting it
+ *   is wrong even where an article's sample "works".
+ * - The spec is pre-stable (Origin Trial). This file and `registrar.ts` are the
+ *   only places that touch the API, so a spec change is a two-file edit. Re-read
+ *   `index.bs` rather than trusting this transcription.
+ *
+ * Only the surface Studio registers against is declared. `getTools` and
+ * `executeTool` are the consumer side; Studio registers, it does not call.
+ *
+ * These stay hand-written rather than imported from `@mcp-b/webmcp-types`,
+ * which the polyfill pulls in. That package's `registerTool` is overloaded to
+ * infer argument types from a literal `inputSchema`, which is useful when you
+ * register one tool inline and actively hostile when you register a uniform
+ * list of them, as `registerStudioTools` does. Narrower is the safe operation
+ * here. It does mean this file can drift from the spec, hence the note above.
+ */
+interface ModelContextToolAnnotations {
+    /** The tool does not change state. Lets an agent decide when calling is free. */
+    readOnlyHint?: boolean;
+    /** The tool's output contains data the page's author does not vouch for. */
+    untrustedContentHint?: boolean;
+}
+interface ToolExecuteCallbackOptions {
+    /**
+     * Aborted when the caller cancels. Studio's commit path is not cancellable
+     * once dispatched, so tools check this BEFORE dispatching and document that a
+     * late abort does not unwind a write.
+     */
+    signal: AbortSignal;
+}
+interface ModelContextTool {
+    /**
+     * Max 128 characters, ASCII alphanumeric plus `_`, `-`, `.`. Registering a
+     * name that already exists REJECTS with InvalidStateError; it does not
+     * replace.
+     */
+    name: string;
+    title?: string;
+    /** Required and non-empty; an empty string rejects with InvalidStateError. */
+    description: string;
+    /** JSON Schema. Nothing in the platform validates input against it. */
+    inputSchema?: object;
+    /**
+     * The user agent JSON-serializes whatever this resolves with, so it must
+     * return an object. Returning `undefined` fails the serialization.
+     *
+     * A rejection is NOT a usable error channel: the spec discards the reason and
+     * rejects the caller with a bare UnknownError. Resolve with a tagged failure
+     * instead. See `toolResult.ts`.
+     *
+     * `options` is optional here although the spec always passes it: the
+     * `@mcp-b/global` polyfill (through 5.1.0) calls `execute(input)` with no
+     * second argument, so a Studio handler must not depend on receiving one.
+     */
+    execute: (input: object, options?: ToolExecuteCallbackOptions) => Promise<unknown>;
+    annotations?: ModelContextToolAnnotations;
+}
+
+/**
+ * The shape every Studio tool resolves with.
+ *
+ * Tools resolve, they never reject. That is forced by the spec, not a style
+ * choice: a rejected `execute` has its reason DISCARDED and the caller is
+ * rejected with a bare `UnknownError` (`index.bs`, the execute-tool completion
+ * steps). Rejecting would therefore guarantee the agent cannot see why the edit
+ * failed, which is the one thing it needs most.
+ *
+ * There is no `outputSchema` in the platform yet, so this discriminant is
+ * invisible to the agent's schema layer. Every tool's `description` has to say
+ * that it returns `ok`.
+ */
+type ToolFailureKind = 
+/** A real state the agent can route around: save queue paused, capability off. */
+"blocked"
+/** The agent's fault: unknown handle, bad enum, out of range. */
+ | "invalid"
+/** Exogenous: the server said no, the patch target could not be resolved. */
+ | "failed"
+/** Our bug. Reported AND re-thrown, so it is findable instead of plausible. */
+ | "internal";
+interface ToolFailure {
+    ok: false;
+    kind: ToolFailureKind;
+    reason: string;
+    /** What to try instead. This is what turns a failure into a next action. */
+    hint?: string;
+}
+type ToolResult<T> = ({
+    ok: true;
+} & T) | ToolFailure;
+
+/**
+ * `studio_look`: the one call that orients an agent.
+ *
+ * Deliberately fat. Every field here is one the agent would otherwise have to
+ * spend a round trip discovering.
+ *
+ * The building is a pure function over a snapshot so it can be tested with
+ * values. Gathering the snapshot is the React layer's job.
+ */
+
+type StudioLookSceneSnapshot = {
+    status: "loading";
+} | {
+    status: "ready";
+    items: readonly DomEditLayerItem[];
+    drillInItem: DomEditLayerItem | null;
+};
+interface StudioLookSnapshot {
+    projectId: string | null;
+    compositionPath: string | null;
+    currentTime: number;
+    duration: number;
+    isPlaying: boolean;
+    elements: readonly TimelineElement[];
+    scene: StudioLookSceneSnapshot;
+    selection: DomEditSelection | null;
+    /** Live animations for the current selection arrive outside DomEditSelection. */
+    selectionAnimationCount: number;
+    /**
+     * The undo stack as Studio's shell actually exposes it.
+     *
+     * This is a weaker signal than a revision counter, and deliberately not
+     * dressed up as one: the depth lives in component-local state and is not
+     * reachable here without plumbing it through the shell context. What an agent
+     * CAN do is checkpoint `undoLabel` before a batch and notice it change to
+     * something it did not do, which means a human pressed undo and its earlier
+     * edits are gone.
+     */
+    history: {
+        canUndo: boolean;
+        canRedo: boolean;
+        undoLabel: string | null;
+        redoLabel: string | null;
+    };
+}
+/** Gather the live scene once per tool call. The response never retains DOM nodes. */
+declare function collectStudioLookScene(doc: Document | null, activeCompositionPath: string | null, activeGroupElement: HTMLElement | null): StudioLookSceneSnapshot;
+
+/**
+ * `studio_select` and `studio_seek`: pointing the human and the agent at the
+ * same thing.
+ *
+ * Selection is shared human-visible state. Element writes do not infer their
+ * target from it: they resolve an explicit source-safe handle per call. Keeping
+ * these contracts separate means a human click cannot redirect an agent write.
+ */
+
+interface SelectionToolDeps {
+    /** The preview iframe's document, or null before it mounts. */
+    getPreviewDocument: () => Document | null;
+    getCompositionPath: () => string | null;
+    getProjectId: () => string | null;
+    buildSelection: (element: HTMLElement) => Promise<DomEditSelection | null>;
+    applySelection: (selection: DomEditSelection) => void;
+    /** Out-of-loop seek. `requestSeek`, not `setCurrentTime`. */
+    requestSeek: (time: number) => void;
+    readPlayhead: () => {
+        currentTime: number;
+        duration: number;
+        isPlaying: boolean;
+    };
+}
+
+/**
+ * `studio_frame`: the eyes.
+ *
+ * Without this the tool set is a remote control. With it an agent can author a
+ * change, look at the instant it affects, judge it, and adjust. That loop is the
+ * one thing source alone cannot support, because "what does this look like at
+ * 2.4 seconds" is not a question a file can answer.
+ *
+ * Reuses Studio's existing capture endpoint (`utils/frameCapture`) rather than
+ * inventing a second one. The server renders the composition with Puppeteer, so
+ * the frame reflects the file on disk, not the live preview DOM.
+ */
+
+interface FrameToolDeps {
+    getProjectId: () => string | null;
+    getCompositionPath: () => string | null;
+    readPlayhead: () => {
+        currentTime: number;
+        duration: number;
+        isPlaying: boolean;
+    };
+    requestSeek: (time: number) => void;
+    /** Confirms the URL renders. Injected so tests need no network. */
+    probeFrame: (url: string) => Promise<{
+        ok: boolean;
+        status: number;
+    }>;
+    wait: (ms: number) => Promise<void>;
+}
+
+/**
+ * `studio_inspect`: everything about one element, in one call.
+ *
+ * The point is to prevent a failed write. Every field here either tells the
+ * agent what it can change (`can`, with `reasonIfDisabled` verbatim) or what it
+ * would be changing (the resolved styles, the text fields, the animations).
+ * An agent that reads this first should never attempt an edit the element will
+ * refuse.
+ *
+ * The GSAP diagnostics are here for the same reason: `multipleTimelines` and
+ * `unsupportedTimelinePattern` are states where animation editing is off, and
+ * learning that from a read is cheaper than learning it from a failed write.
+ */
+
+interface InspectToolDeps extends SelectionToolDeps {
+    /** What the human currently has selected, used when no handle is given. */
+    getCurrentSelection: () => DomEditSelection | null;
+    getGsapDiagnostics: () => {
+        animations: readonly GsapAnimation$1[];
+        multipleTimelines: boolean;
+        unsupportedTimelinePattern: boolean;
+    };
+}
+
+interface TargetedWriteDeps {
+    getPreviewDocument: () => Document | null;
+    getProjectId: () => string | null;
+    getWriteBlockedReason: () => string | null;
+    buildSelection: (element: HTMLElement) => Promise<DomEditSelection | null>;
+    applySelection: (selection: DomEditSelection) => void;
+}
+
+/**
+ * `studio_set_text` and `studio_set_style`: the first tools that change the file.
+ *
+ * The explicit source-safe handle is resolved to one selection per invocation.
+ * That captured selection is passed into Studio's existing commit actor; visible
+ * selection is presentation only and cannot redirect the write.
+ */
+
+interface ContentToolDeps extends TargetedWriteDeps {
+    setText: (selection: DomEditSelection, value: string, fieldKey?: string) => Promise<DomEditCommitOutcome>;
+    setStyle: (selection: DomEditSelection, property: string, value: string) => Promise<DomEditCommitOutcome>;
+}
+
+/**
+ * `studio_transform`: move, resize and rotate, as a drag would.
+ *
+ * This tool reads the element's box back after every write and reports what
+ * ACTUALLY changed. That is not belt-and-braces, it is the only thing standing
+ * between an agent and a silent lie, because two of the three handlers can do
+ * nothing and resolve:
+ *
+ * - The handlers exposed on `DomEditActionsValue` are the GSAP-AWARE wrappers
+ *   (`useDomEditSession.ts` aliases them), not the CSS ones in
+ *   `useDomGeometryCommits.ts`.
+ * - `handleGsapAwarePathOffsetCommit` and `handleGsapAwareRotationCommit` are
+ *   `if (gsapCommitMutation) { ...intercept... }` with NO else branch. In a
+ *   composition with no GSAP they return having done nothing. The adjacent
+ *   comments confirm that is deliberate: there is no CSS fallback to write to.
+ * - `handleGsapAwareBoxSizeCommit` is different. It runs through
+ *   `runGestureTransaction` with a scale route and a width/height route, so
+ *   resize works more generally than the other two.
+ *
+ * Read back, do not assume.
+ */
+
+interface ElementBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface TransformToolDeps extends TargetedWriteDeps {
+    /** The element's box as it renders right now. */
+    readBox: (selection: DomEditSelection) => ElementBox;
+    moveTo: (selection: DomEditSelection, next: {
+        x: number;
+        y: number;
+    }) => Promise<DomEditCommitOutcome | void>;
+    resizeTo: (selection: DomEditSelection, next: {
+        width: number;
+        height: number;
+    }) => Promise<DomEditCommitOutcome | void>;
+    rotateTo: (selection: DomEditSelection, next: {
+        angle: number;
+    }) => Promise<DomEditCommitOutcome | void>;
+}
+
+/**
+ * `studio_animate`: author motion.
+ *
+ * Add, update, and delete await the shared GSAP commit pipeline. Its promise is
+ * the single settlement boundary for persistence and live-preview sync, so a
+ * successful tool response never races ahead of the pixels the user sees.
+ * Keyframe writes still report dispatch because their existing actor catches
+ * its own failure instead of returning a landed signal.
+ */
+
+type GsapMethod = "to" | "from" | "set" | "fromTo";
+interface AnimationToolDeps extends TargetedWriteDeps {
+    getAnimationsForSelection: (selection: DomEditSelection) => Promise<readonly {
+        id: string;
+    }[]>;
+    readPlayhead: () => {
+        currentTime: number;
+        duration: number;
+        isPlaying: boolean;
+    };
+    addAnimation: (selection: DomEditSelection, method: GsapMethod) => Promise<boolean>;
+    updateAnimation: (selection: DomEditSelection, animationId: string, updates: {
+        duration?: number;
+        ease?: string;
+        position?: number;
+    }) => Promise<boolean>;
+    addKeyframe: (selection: DomEditSelection, animationId: string, percent: number, properties: Record<string, number | string>) => Promise<void>;
+    deleteAnimation: (selection: DomEditSelection, animationId: string) => Promise<boolean>;
+}
+
+interface StudioAgentToolsDeps extends SelectionToolDeps, FrameToolDeps, InspectToolDeps, ContentToolDeps, TransformToolDeps, AnimationToolDeps {
+    /** Read Studio's current state. Called per tool invocation, never cached. */
+    getSnapshot: () => StudioLookSnapshot;
+}
+/**
+ * Build the tool list once.
+ *
+ * Every `execute` reads `depsRef.current` at CALL time rather than closing over
+ * a snapshot, which is what lets the list be built once and still see live
+ * state. That is the whole point of the ref: see the registration note below.
+ */
+declare function buildStudioTools(depsRef: {
+    readonly current: StudioAgentToolsDeps;
+}): ModelContextTool[];
+
+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, Dock, type DockController, type DomEditCapabilities, type DomEditCommitDeclineReason, type DomEditCommitOutcome, type DomEditGroupPathOffsetCommit, DomEditOverlay, type DomEditOverlayProps, DomEditProvider, type DomEditSelection, type DomEditZOrder, type DomGeometryCommits, 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, type ModelContextTool, NLEPreview, type PanelId, type PatchOperation, type PersistedRenderSettings, type PickedElement, PlayerControls, type PlayerHandle, type PlayerHandleElement, type PlayerHandleListener, type PlayerHandleTimeListener, type DomEditCompositionRect as PreviewCompositionRect, PreviewGuides, PreviewOverlayProvider, type PreviewOverlayProviderProps, type PreviewPromotion, PreviewReadOnlyProvider, type PreviewSnapPreferences, PropertyPanel, type RenderJob, RenderQueue, type RenderQueueProps, type ResolutionPreset, SNAP_THRESHOLD_PX, type ShortcutHint, type ShortcutSection, ShortcutsButton, type ShortcutsButtonProps, 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, type StudioAgentToolsDeps, StudioApp, StudioFileConflictError, type StudioLookSnapshot, type StudioPendingEditsDrainResult, TRACK_H, type ThumbnailPriority, Timeline, TimelineClipMenu, type TimelineClipMenuItem, 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 TimelineTrackPadding, type TimelineZIndexReorderCommit, type ToolResult, type UseClipboardOptions, type UseDomEditSessionParams, type UseDomGeometryCommitOptions, type UseDomStyleCommitOptions, type UseEditHistoryActionsOptions, type UsePersistentEditHistoryOptions, type UsePreviewPersistenceParams, type UseProjectFileWriterOptions, type UseRenderClipContentOptions, type UseTimelineEditingOptions, VideoThumbnail, type ZOrderAction, applyPatch, buildCompositionSnapTarget, buildGridSnapEdges, buildPickerAgentContextPreview, buildPickerAgentPrompt, buildStudioTools, collectSnapContext, collectStudioLookScene, extractSnapTargets, findElementBlock, flushStudioPendingEdits, formatTime, getPersistedRenderSettings, liveTime, mergeStyleIntoTag, parseStyleString, persistRenderSettings, resolveDomEditSelection, resolveEquidistanceGuides, resolveGuideLineRect, resolveIframe, resolveSnapAdjustment, resolveSourceFile, snapEngagedForTravel, useClipboard, useCompositionStack, useDockLayoutStore, useDomEditSelectionContext, useDomEditSession, useDomEditZOrder, useDomGeometryCommit, useDomStyleCommit, useEditHistoryActions, useElementPicker, useLivePreviewIframe, useMarqueeGestures, usePersistentEditHistory, usePlayerHandle, usePlayerStore, usePreviewCompositionRect, usePreviewGuidesStore, usePreviewOverlayContext, usePreviewPersistence, useProjectFileWriter, useRenderClipContent, useRenderQueue, useTimelineContext, useTimelineEditing, useTimelinePlayer };

package/dist/index.html

@@ -5,8 +5,17 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>HyperFrames Studio</title>
-    <script type="module" crossorigin src="/assets/index-DEDhPmPD.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-Cre9X4RS.css">
+    <script>
+      // Before the first paint: the theme the toggle saved, else light (owner: src/utils/studioTheme.ts).
+      try {
+        if (JSON.parse(localStorage.getItem("hf-studio-ui-preferences") || "{}").theme !== "dark")
+          document.documentElement.dataset.theme = "paper";
+      } catch (e) {
+        document.documentElement.dataset.theme = "paper";
+      }
+    </script>
+    <script type="module" crossorigin src="/assets/index-CM1xA_jD.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-lrT-gfHa.css">
   </head>
   <body>
     <div data-hf-id="hf-aph5" id="root"></div>