@vosjs/studio-core 0.24.0 → 0.24.1

package/dist/index.d.ts

@@ -2960,6 +2960,18 @@ declare const PIN_GAP = 24;
 /** Design px the layer keeps from the frame's edge. */
 declare const PIN_MARGIN = 24;
 type PinSideResolved = Exclude<PinSide, 'auto'>;
+/**
+ * A referent the POINTER carries: a slider thumb, a scrubber, a card being
+ * dragged. Its rect was measured at the press; through the drag it sits
+ * wherever the pointer has taken it, and it stays at the release. SOURCE
+ * seconds; `x0`/`y0` the press in normalised video fractions.
+ */
+interface PinCarry {
+    t0: number;
+    t1: number;
+    x0: number;
+    y0: number;
+}
 /** The referent's rect in normalised video fractions, and how it was found. */
 interface PinReferent {
     rect: Rect;
@@ -2968,6 +2980,8 @@ interface PinReferent {
     step?: StepSpan;
     /** SOURCE second the referent was measured at (a step's start, the press). */
     at: number | null;
+    /** Set when the press began a drag: the referent moves with the pointer. */
+    carry?: PinCarry;
 }
 /**
  * Find a pin's referent in the recording. A `step` reads the step's own
@@ -3009,7 +3023,25 @@ interface PinPlacementInput {
     base: readonly number[];
     /** The clip's own motion track, for scale, rotation and opacity. */
     motion?: KeyframeTrack<number[]> | null;
+    /**
+     * A carried referent (a drag): the rect is offset by the pointer's
+     * displacement at each sample's SOURCE moment, read from `cursor` in
+     * `space` through `rated` (output → source).
+     */
+    carry?: PinCarry | null;
+    cursor?: CursorTrack;
+    space?: {
+        w: number;
+        h: number;
+    };
+    rated?: readonly Segment[];
 }
+/**
+ * The referent's rect at OUTPUT time t: the measured rect, moved by where
+ * the pointer has carried it when the press began a drag (held at the
+ * release; nothing before the press).
+ */
+declare function pinReferentAt(referent: Rect, t: number, input: Pick<PinPlacementInput, 'carry' | 'cursor' | 'space' | 'rated'>): Rect;
 interface PinPlacement {
     side: PinSideResolved;
     /** Clip-local [x, y, scale, rotation, opacity] in frame fractions. */
@@ -4662,4 +4694,4 @@ declare function rejectSpan(rejected: RejectedSpan[] | undefined, lane: Rejected
     anchor?: StepAnchor;
 }, note?: string): RejectedSpan;
 
-export { ASPECT_RATIOS, AUDIO_PLAN_STEP, type AnchorKind, type Anim, type AnimKind, type AnimSide, type AnimStep, type AppliedTemplate, type ApplyTemplateOptions, type AspectRatioOption, type AudioClip, type AudioPlanPoint, type AudioPlanTrack, BACKGROUND_Z, BASE_FRAME_STYLE, type Backdrop, type BackgroundMedia, type BakedText3dAsset, type BakedText3dMaterial, type BrowserBarStyle, type BuildDigestInput, CAMERA_CENTRE_RAMP, CAMERA_COVER_MIN, CAMERA_FAR, CAMERA_NEAR, CAM_CHAIN_GAP, CAM_EASE, CAM_PAN, CAM_PAN_EASE, CAM_RAMP_IN, CAM_RAMP_OUT, CAM_SIZE_MAX, CAM_SIZE_MIN, CAM_SPAN_MIN, CAPTURE_COVERAGE_MIN, CARD_EDGE_OVERDRAW, CARD_ENTER_KINDS, CARD_EXIT_KINDS, CARD_FADE_SECONDS, CARD_FOV, CARD_Z, CHANNEL_SPECS_HASH, CHANNEL_SPECS_VERIFIED, CLICK_FX_INTENSITY, CLICK_FX_PRE, CLICK_HIGHLIGHT_FADE, CLICK_PAIR_MAX, CLICK_PULSE_DUR, CLICK_RECT_MAX_FRAC, CLICK_RIPPLE_DUR, CLICK_SYNTH_RELEASE, CROP_MAX_PX, CROP_MIN_FRAC, CROP_MIN_PX, CROP_PAD, CURSOR_IDLE_EPS_FRAC, CURSOR_IDLE_FADE_IN, CURSOR_IDLE_FADE_OUT, CURSOR_IDLE_HOLD, type CamBubbleRect, type CamPoseSpan, type CamStyle, type CameraModel, type CaptureNormalization, type CardLayout, type ClickFxStyle, type CopiedLayout, type CopyLayoutOptions, type CopyStyleOptions, type CursorEvent, type CursorFadeKey, type CursorIdleOptions, type CursorStyle, type CursorTrack, DARK_GROUND, DEFAULT_BROWSER_BAR, DEFAULT_CAM_POSE, DEFAULT_CAM_STYLE, DEFAULT_CLICK_FX, DEFAULT_CURSOR_STYLE, DEFAULT_DUCK, DEFAULT_FRAME_STYLE, DEFAULT_SPEED_PARAMS, DEFAULT_TILT_POSE, DEFAULT_ZOOM_LEVEL, DEFAULT_ZOOM_STYLE, DESIGN_FRAME_WIDTH, DESTINATIONS, DIGEST_CROP_MAX, DIGEST_FULL_MAX, DIGEST_VERSION, DOC_SCHEMA_VERSION, DRAG_FIT_LEVEL, DRAG_MIN_S, DRAG_MIN_TRAVEL_FRAC, type Destination, type Digest, type DigestImageRef, type DigestPlan, type DigestTakeFacts, type DocSegment, type Drag, type DuckOptions, END_CARD_FROM, END_CARD_RECEDE, END_CARD_SECONDS, ENTRANCE_SECONDS, EXPORT_RESOLUTION_OPTIONS, EXPORT_SHORT_EDGE, type EndCard, type EnvelopePoint, type ExportResolution, type ExtractClickOptions, FOLLOW_RECENTER, FOLLOW_SAFE_RATIO, FRAME_BORDER_COLOR_DEFAULT, FRAME_BORDER_DEFAULT, FRAME_BORDER_WIDTH_DEFAULT, FREEZE_DEFAULT_SECONDS, FREEZE_SECONDS_MAX, FREEZE_SECONDS_MIN, type FocusBounds, type FollowEvent, type FollowOptions, type FrameEntrance, type FrameGeometry, type FrameStyle, type FreezeExtent, type FreezeSpan, HOUSE_GRADIENT, HTML_LAYER_FOREIGN_FIELDS, HTML_LAYER_MAX_BYTES, HTML_LAYER_SVG_CODE, HTML_LAYER_WARN_BYTES, HTML_STARTERS, type HtmlLayerFace, type HtmlLayerInlineFace, type HtmlLayerPayload, type HtmlLayerProblem, type HtmlLayerProblemCode, type HtmlLayerSource, type HtmlOverlayClip, type HtmlOverlayFont, type HtmlStarter, IDLE_KINDS, type IdleKind, type IngestOptions, LAYER_CARD_SHADOW, LAYOUT_FRAME_FIELDS, LOOK_KINDS, type LayerCard, type LayoutParts, type Look, type LookBrand, type LookKind, type LookPlacement, type LowerProgramOptions, type LoweredAudioClip, type LoweredClick, type LoweredComposition, type LoweredZoomSpan, MEDIA_ENTER_KINDS, MEDIA_EXIT_KINDS, MEDIA_FRAME_KEYS, MEDIA_KEY_PREFIX, MINIMAL_BAR_THEMES, MOTION_DELTA, MOTION_EASE, type Media, type MediaFrame, type MediaFrameKey, type MediaOverlayClip, type MediaSegment, type MicRms, type MinimalBarTheme, type Moment, type MomentKind, type MomentsOptions, type MotionKey, type MotionPose, type MotionPose3D, type MusicBedInput, type NormRect, OBJECT_DEFAULT_SCALE, OVERLAY_FONT_FACES, OVERLAY_LINE_HEIGHT, OVERLAY_MEDIA_DEFAULT_RADIUS, OVERLAY_MEDIA_DEFAULT_WIDTH, OVERLAY_MIN_DURATION, OVERLAY_SCALE_MAX, OVERLAY_SIZE_MAX, OVERLAY_SIZE_MIN, OVERLAY_TRANSITION_DUR, OVERLAY_Z, type ObjectAnimation, type ObjectAsset, type ObjectClip, type ObjectPrimitiveShape, type OverlayClip, type OverlayFontFace, type OverlayKind, type OverlayPin, type OverlayPresetStyle, type OverlayRect, type OverlayTransform, type OverlayTransition, PIN_GAP, PIN_MARGIN, PLATE_GROUND, PLAYBACK_ACTIVITY, PRIMARY_MEDIA, PROGRAM_RETIME, type PinMark, type PinPlacement, type PinPlacementInput, type PinReferent, type PinSide, type PinSideResolved, type PlanOptions, type PlanTiltOptions, type PlaneSize, type ProgramAnchorDoc, type ProgramTweenEdit, type ProjectDoc, type PxRect, REJECT_OVERLAP, REST_TILT_ID, type RecordingArtifact, type RecordingMeta, type Rect, type RejectedLane, type RejectedSpan, type ResolvedOverlayBox, type ResolvedOverlayStyle, SCENE_MOTION, SCENE_QUIET, SEGMENT_ENTER_KINDS, SEGMENT_EXIT_KINDS, SPEED_RATE_MAX, SPEED_RATE_MIN, SPEED_SPAN_MIN, STAGE_CLIP_PREFIX, STILL_DEFAULT, STUDIO_ENTRY_ID, STYLE_FIELDS, type SegmentExtent, type SmoothOptions, type SmoothPoint, type SpeedParams, type SpeedSpan, type StepAnchor, type StepSpan, type StudioAudioPlan, type StudioDoc, type StudioEntry, type StyleField, TEXT3D_DEPTH_DEFAULT, TEXT3D_DEPTH_MAX, TEXT3D_DEPTH_MIN, TEXT_ENTER_KINDS, TEXT_EXIT_KINDS, TEXT_PRESETS, TILT_AUTO_DEAD_ZONE, TILT_AUTO_MIN, TILT_CHAIN_GAP, TILT_DEG_MAX, TILT_EASE, TILT_INTENSITY_MAX, TILT_PAN, TILT_PAN_EASE, TILT_RAMP_IN, TILT_RAMP_OUT, TILT_SPAN_MIN, TILT_UI_DEG_MAX, TRANSITION_SECONDS, TRANSITION_SECONDS_MAX, TRANSITION_SECONDS_MIN, TRANSITION_SPEED_MULT, type TemplateAnchor, type Text3dMaterial, type TextFxDirection, type TextFxKind, type TextFxSpec, type TextFxUnit, type TextOverlayBox, type TextOverlayClip, type TextOverlayPreset, type TextOverlayStroke, type TiltPersonality, type TiltSpan, type TiltStyleName, type TranscriptSegment, type Transition, type TransitionKind, type TransitionMove, type TransitionOut, type TransitionSpeed, WINDOW_FOCUS_MIN, ZOOM_CHAIN_GAP, ZOOM_EASE, ZOOM_LEVELS, ZOOM_LEVEL_MAX, ZOOM_LEVEL_MIN, ZOOM_PAN, ZOOM_PAN_EASE, ZOOM_RAMP_IN, ZOOM_RAMP_IN_OVERLAP, ZOOM_RAMP_OUT, ZOOM_SPAN_MIN, ZOOM_STYLES, ZOOM_STYLE_OPTIONS, type ZoomSpan, type ZoomStyleName, type ZoomStyleParams, type ZoomView, type ZoomWindow, anchorKindOf, anchorSourceDuration, animStep, applyLook, applyTemplate, aspectRatioValue, audioLane, backdropMedia, buildDigest, camBubbleRect, camBubbleRectAt, camLane, camMoveLane, camRectFromPose, camRestPose, camTrackFromDoc, cameraCentring, cameraModel, cardEnter, cardExit, cardFields, cardInset, cardPointToScreen, cardPoseTrack, clampCamFrac, clampCamSize, clampFocus, clampFreezeSeconds, clampSpeedRate, clampTiltDeg, clampZoomLevel, clipEnvelope, clipLength, clipsFrom, computeCardLayout, computeMicRms, computePeaks, copyLayout, copyStyle, cropBox, cssFamilies, cssWeights, cursorIdleFade, deriveViewportCrop, destinationById, destinationsForChannel, docCardLayout, docFreezes, docMediaList, docOutputDuration, docRestTime, docStillTime, docToCropSpace, docToFullSpace, docTransitions, docZoomTrack, dragsFromTrack, dropTemplate, duckCurve, effectiveSegments, endCardClips, enterKey, enterOf, entranceSeconds, envelopeAt, envelopeValueAt, exitKey, exitOf, exitSeconds, expandEndCard, expectedFrameSize, exportSizeFor, extractClicks, findStep, focusBounds, focusForViewportCentre, followFocusEvents, frameGeometry, freezeLane, freezeOutputExtents, hexToRgbTriplet, houseLook, htmlLayerBleed, htmlLayerBleedFor, htmlLayerFaces, htmlLayerKey, htmlLayerLabel, htmlLayerPayload, htmlLayerPictureBox, htmlLayerProblems, htmlLayerSvg, htmlLayerText, htmlLayerUnhostedFamilies, htmlLayerWidth, htmlStarterClip, idleGaps, idleKey, isKeyedOverlay, isLookKind, isMusicBed, isPlayback, isProgramDoc, isRecordingDoc, isRejected, isStageClip, isUnitStep, lastLayerEnd, layerMedia, layoutOf, levelForFocusFraction, lookFromBrand, lookKindForGround, lowerProgramDoc, lowerStudioDoc, lowerToComposition, mediaAtOutput, mediaDuration, mediaFrame, mediaKey, mediaRef, mediaRefId, mediaSource, micLane, migrateHostedDoc, migrateMotion, momentsFromDoc, motionTrack, musicBedClip, nextMediaId, normalizeCaptureSpace, objectMotionBase, objectMotionPoseAt, objectsLane, outputDurationOf, outputEnd, outputRangeToSource, overlapFraction, overlayFaceFor, overlayFontFaces, overlayFontString, overlayFxSpec, overlayHit, overlayLines, overlayMotionBase, overlayMotionPoseAt, overlayPinPoseAt, overlayRect, overlaysLane, ownFreezes, pageDisplayUrl, parsePoseId, pickStyle, pinBox, pinPlacement, pinRectOnScreen, pinReferent, placeFreezes, planAutoSpeed, planAutoTilt, planAutoZoom, planForDigest, planeSizeAtDepth, platformBarKind, programDuration, projectFromArtifact, ratedSegments, recommendedExportResolution, refillAudioBeds, rejectSpan, removeSourceRange, removeSpeedInRange, resolveExportSize, resolveOverlayBox, resolveOverlayStyle, resolvePins, resolveText3dAsset, resolveZoomStyle, restLeanOf, restSpansThroughTransitions, sameMedia, sceneChanges, scrollRuns, segmentOutputExtents, outputLen as segmentOutputLen, segmentStarts, setSpeedInRange, slideSide, smoothCursor, spanOutputExtent, speedLane, studioAudioPlan, studioEntry, studioLayerData, tiltLane, tiltTrackFromDoc, transitionMult, transitionSeconds, videoLane, voiceKey, wellFormedXml, withBackdrop, withFreezes, withHolds, withoutRejected, wrapProgramLength, zoomCoversRect, zoomLane, zoomSpanForRange, zoomTrackFromDoc, zoomView, zoomViewport, zoomWindow };
+export { ASPECT_RATIOS, AUDIO_PLAN_STEP, type AnchorKind, type Anim, type AnimKind, type AnimSide, type AnimStep, type AppliedTemplate, type ApplyTemplateOptions, type AspectRatioOption, type AudioClip, type AudioPlanPoint, type AudioPlanTrack, BACKGROUND_Z, BASE_FRAME_STYLE, type Backdrop, type BackgroundMedia, type BakedText3dAsset, type BakedText3dMaterial, type BrowserBarStyle, type BuildDigestInput, CAMERA_CENTRE_RAMP, CAMERA_COVER_MIN, CAMERA_FAR, CAMERA_NEAR, CAM_CHAIN_GAP, CAM_EASE, CAM_PAN, CAM_PAN_EASE, CAM_RAMP_IN, CAM_RAMP_OUT, CAM_SIZE_MAX, CAM_SIZE_MIN, CAM_SPAN_MIN, CAPTURE_COVERAGE_MIN, CARD_EDGE_OVERDRAW, CARD_ENTER_KINDS, CARD_EXIT_KINDS, CARD_FADE_SECONDS, CARD_FOV, CARD_Z, CHANNEL_SPECS_HASH, CHANNEL_SPECS_VERIFIED, CLICK_FX_INTENSITY, CLICK_FX_PRE, CLICK_HIGHLIGHT_FADE, CLICK_PAIR_MAX, CLICK_PULSE_DUR, CLICK_RECT_MAX_FRAC, CLICK_RIPPLE_DUR, CLICK_SYNTH_RELEASE, CROP_MAX_PX, CROP_MIN_FRAC, CROP_MIN_PX, CROP_PAD, CURSOR_IDLE_EPS_FRAC, CURSOR_IDLE_FADE_IN, CURSOR_IDLE_FADE_OUT, CURSOR_IDLE_HOLD, type CamBubbleRect, type CamPoseSpan, type CamStyle, type CameraModel, type CaptureNormalization, type CardLayout, type ClickFxStyle, type CopiedLayout, type CopyLayoutOptions, type CopyStyleOptions, type CursorEvent, type CursorFadeKey, type CursorIdleOptions, type CursorStyle, type CursorTrack, DARK_GROUND, DEFAULT_BROWSER_BAR, DEFAULT_CAM_POSE, DEFAULT_CAM_STYLE, DEFAULT_CLICK_FX, DEFAULT_CURSOR_STYLE, DEFAULT_DUCK, DEFAULT_FRAME_STYLE, DEFAULT_SPEED_PARAMS, DEFAULT_TILT_POSE, DEFAULT_ZOOM_LEVEL, DEFAULT_ZOOM_STYLE, DESIGN_FRAME_WIDTH, DESTINATIONS, DIGEST_CROP_MAX, DIGEST_FULL_MAX, DIGEST_VERSION, DOC_SCHEMA_VERSION, DRAG_FIT_LEVEL, DRAG_MIN_S, DRAG_MIN_TRAVEL_FRAC, type Destination, type Digest, type DigestImageRef, type DigestPlan, type DigestTakeFacts, type DocSegment, type Drag, type DuckOptions, END_CARD_FROM, END_CARD_RECEDE, END_CARD_SECONDS, ENTRANCE_SECONDS, EXPORT_RESOLUTION_OPTIONS, EXPORT_SHORT_EDGE, type EndCard, type EnvelopePoint, type ExportResolution, type ExtractClickOptions, FOLLOW_RECENTER, FOLLOW_SAFE_RATIO, FRAME_BORDER_COLOR_DEFAULT, FRAME_BORDER_DEFAULT, FRAME_BORDER_WIDTH_DEFAULT, FREEZE_DEFAULT_SECONDS, FREEZE_SECONDS_MAX, FREEZE_SECONDS_MIN, type FocusBounds, type FollowEvent, type FollowOptions, type FrameEntrance, type FrameGeometry, type FrameStyle, type FreezeExtent, type FreezeSpan, HOUSE_GRADIENT, HTML_LAYER_FOREIGN_FIELDS, HTML_LAYER_MAX_BYTES, HTML_LAYER_SVG_CODE, HTML_LAYER_WARN_BYTES, HTML_STARTERS, type HtmlLayerFace, type HtmlLayerInlineFace, type HtmlLayerPayload, type HtmlLayerProblem, type HtmlLayerProblemCode, type HtmlLayerSource, type HtmlOverlayClip, type HtmlOverlayFont, type HtmlStarter, IDLE_KINDS, type IdleKind, type IngestOptions, LAYER_CARD_SHADOW, LAYOUT_FRAME_FIELDS, LOOK_KINDS, type LayerCard, type LayoutParts, type Look, type LookBrand, type LookKind, type LookPlacement, type LowerProgramOptions, type LoweredAudioClip, type LoweredClick, type LoweredComposition, type LoweredZoomSpan, MEDIA_ENTER_KINDS, MEDIA_EXIT_KINDS, MEDIA_FRAME_KEYS, MEDIA_KEY_PREFIX, MINIMAL_BAR_THEMES, MOTION_DELTA, MOTION_EASE, type Media, type MediaFrame, type MediaFrameKey, type MediaOverlayClip, type MediaSegment, type MicRms, type MinimalBarTheme, type Moment, type MomentKind, type MomentsOptions, type MotionKey, type MotionPose, type MotionPose3D, type MusicBedInput, type NormRect, OBJECT_DEFAULT_SCALE, OVERLAY_FONT_FACES, OVERLAY_LINE_HEIGHT, OVERLAY_MEDIA_DEFAULT_RADIUS, OVERLAY_MEDIA_DEFAULT_WIDTH, OVERLAY_MIN_DURATION, OVERLAY_SCALE_MAX, OVERLAY_SIZE_MAX, OVERLAY_SIZE_MIN, OVERLAY_TRANSITION_DUR, OVERLAY_Z, type ObjectAnimation, type ObjectAsset, type ObjectClip, type ObjectPrimitiveShape, type OverlayClip, type OverlayFontFace, type OverlayKind, type OverlayPin, type OverlayPresetStyle, type OverlayRect, type OverlayTransform, type OverlayTransition, PIN_GAP, PIN_MARGIN, PLATE_GROUND, PLAYBACK_ACTIVITY, PRIMARY_MEDIA, PROGRAM_RETIME, type PinCarry, type PinMark, type PinPlacement, type PinPlacementInput, type PinReferent, type PinSide, type PinSideResolved, type PlanOptions, type PlanTiltOptions, type PlaneSize, type ProgramAnchorDoc, type ProgramTweenEdit, type ProjectDoc, type PxRect, REJECT_OVERLAP, REST_TILT_ID, type RecordingArtifact, type RecordingMeta, type Rect, type RejectedLane, type RejectedSpan, type ResolvedOverlayBox, type ResolvedOverlayStyle, SCENE_MOTION, SCENE_QUIET, SEGMENT_ENTER_KINDS, SEGMENT_EXIT_KINDS, SPEED_RATE_MAX, SPEED_RATE_MIN, SPEED_SPAN_MIN, STAGE_CLIP_PREFIX, STILL_DEFAULT, STUDIO_ENTRY_ID, STYLE_FIELDS, type SegmentExtent, type SmoothOptions, type SmoothPoint, type SpeedParams, type SpeedSpan, type StepAnchor, type StepSpan, type StudioAudioPlan, type StudioDoc, type StudioEntry, type StyleField, TEXT3D_DEPTH_DEFAULT, TEXT3D_DEPTH_MAX, TEXT3D_DEPTH_MIN, TEXT_ENTER_KINDS, TEXT_EXIT_KINDS, TEXT_PRESETS, TILT_AUTO_DEAD_ZONE, TILT_AUTO_MIN, TILT_CHAIN_GAP, TILT_DEG_MAX, TILT_EASE, TILT_INTENSITY_MAX, TILT_PAN, TILT_PAN_EASE, TILT_RAMP_IN, TILT_RAMP_OUT, TILT_SPAN_MIN, TILT_UI_DEG_MAX, TRANSITION_SECONDS, TRANSITION_SECONDS_MAX, TRANSITION_SECONDS_MIN, TRANSITION_SPEED_MULT, type TemplateAnchor, type Text3dMaterial, type TextFxDirection, type TextFxKind, type TextFxSpec, type TextFxUnit, type TextOverlayBox, type TextOverlayClip, type TextOverlayPreset, type TextOverlayStroke, type TiltPersonality, type TiltSpan, type TiltStyleName, type TranscriptSegment, type Transition, type TransitionKind, type TransitionMove, type TransitionOut, type TransitionSpeed, WINDOW_FOCUS_MIN, ZOOM_CHAIN_GAP, ZOOM_EASE, ZOOM_LEVELS, ZOOM_LEVEL_MAX, ZOOM_LEVEL_MIN, ZOOM_PAN, ZOOM_PAN_EASE, ZOOM_RAMP_IN, ZOOM_RAMP_IN_OVERLAP, ZOOM_RAMP_OUT, ZOOM_SPAN_MIN, ZOOM_STYLES, ZOOM_STYLE_OPTIONS, type ZoomSpan, type ZoomStyleName, type ZoomStyleParams, type ZoomView, type ZoomWindow, anchorKindOf, anchorSourceDuration, animStep, applyLook, applyTemplate, aspectRatioValue, audioLane, backdropMedia, buildDigest, camBubbleRect, camBubbleRectAt, camLane, camMoveLane, camRectFromPose, camRestPose, camTrackFromDoc, cameraCentring, cameraModel, cardEnter, cardExit, cardFields, cardInset, cardPointToScreen, cardPoseTrack, clampCamFrac, clampCamSize, clampFocus, clampFreezeSeconds, clampSpeedRate, clampTiltDeg, clampZoomLevel, clipEnvelope, clipLength, clipsFrom, computeCardLayout, computeMicRms, computePeaks, copyLayout, copyStyle, cropBox, cssFamilies, cssWeights, cursorIdleFade, deriveViewportCrop, destinationById, destinationsForChannel, docCardLayout, docFreezes, docMediaList, docOutputDuration, docRestTime, docStillTime, docToCropSpace, docToFullSpace, docTransitions, docZoomTrack, dragsFromTrack, dropTemplate, duckCurve, effectiveSegments, endCardClips, enterKey, enterOf, entranceSeconds, envelopeAt, envelopeValueAt, exitKey, exitOf, exitSeconds, expandEndCard, expectedFrameSize, exportSizeFor, extractClicks, findStep, focusBounds, focusForViewportCentre, followFocusEvents, frameGeometry, freezeLane, freezeOutputExtents, hexToRgbTriplet, houseLook, htmlLayerBleed, htmlLayerBleedFor, htmlLayerFaces, htmlLayerKey, htmlLayerLabel, htmlLayerPayload, htmlLayerPictureBox, htmlLayerProblems, htmlLayerSvg, htmlLayerText, htmlLayerUnhostedFamilies, htmlLayerWidth, htmlStarterClip, idleGaps, idleKey, isKeyedOverlay, isLookKind, isMusicBed, isPlayback, isProgramDoc, isRecordingDoc, isRejected, isStageClip, isUnitStep, lastLayerEnd, layerMedia, layoutOf, levelForFocusFraction, lookFromBrand, lookKindForGround, lowerProgramDoc, lowerStudioDoc, lowerToComposition, mediaAtOutput, mediaDuration, mediaFrame, mediaKey, mediaRef, mediaRefId, mediaSource, micLane, migrateHostedDoc, migrateMotion, momentsFromDoc, motionTrack, musicBedClip, nextMediaId, normalizeCaptureSpace, objectMotionBase, objectMotionPoseAt, objectsLane, outputDurationOf, outputEnd, outputRangeToSource, overlapFraction, overlayFaceFor, overlayFontFaces, overlayFontString, overlayFxSpec, overlayHit, overlayLines, overlayMotionBase, overlayMotionPoseAt, overlayPinPoseAt, overlayRect, overlaysLane, ownFreezes, pageDisplayUrl, parsePoseId, pickStyle, pinBox, pinPlacement, pinRectOnScreen, pinReferent, pinReferentAt, placeFreezes, planAutoSpeed, planAutoTilt, planAutoZoom, planForDigest, planeSizeAtDepth, platformBarKind, programDuration, projectFromArtifact, ratedSegments, recommendedExportResolution, refillAudioBeds, rejectSpan, removeSourceRange, removeSpeedInRange, resolveExportSize, resolveOverlayBox, resolveOverlayStyle, resolvePins, resolveText3dAsset, resolveZoomStyle, restLeanOf, restSpansThroughTransitions, sameMedia, sceneChanges, scrollRuns, segmentOutputExtents, outputLen as segmentOutputLen, segmentStarts, setSpeedInRange, slideSide, smoothCursor, spanOutputExtent, speedLane, studioAudioPlan, studioEntry, studioLayerData, tiltLane, tiltTrackFromDoc, transitionMult, transitionSeconds, videoLane, voiceKey, wellFormedXml, withBackdrop, withFreezes, withHolds, withoutRejected, wrapProgramLength, zoomCoversRect, zoomLane, zoomSpanForRange, zoomTrackFromDoc, zoomView, zoomViewport, zoomWindow };

package/dist/index.js

@@ -3058,7 +3058,7 @@ function round2(v) {
 }
 
 // src/lower/pin.ts
-import { lerpArray, sample } from "@vosjs/timeline";
+import { lerpArray, mapTime, sample } from "@vosjs/timeline";
 var PIN_GAP = 24;
 var PIN_MARGIN = 24;
 var PIN_SAMPLE_HZ = 30;
@@ -3077,19 +3077,27 @@ function pinReferent(doc, pin) {
   if (pin.step !== void 0) {
     const step = findStep(meta.steps ?? [], pin.step);
     if (!step || step.skipped) return null;
+    const carry = dragCarry(doc, step.tStart - 0.05, step.tEnd + 0.05);
     if (step.rect && validRect(step.rect) && w > 0 && h > 0) {
       return {
         rect: normRect(step.rect, w, h),
         by: "step",
         step,
-        at: step.tStart
+        at: step.tStart,
+        ...carry ? { carry } : {}
       };
     }
     const union = unionRects(
       pressRects(doc, step.tStart - 0.05, step.tEnd + 0.05)
     );
     if (!union || w <= 0 || h <= 0) return null;
-    return { rect: normRect(union, w, h), by: "step", step, at: step.tStart };
+    return {
+      rect: normRect(union, w, h),
+      by: "step",
+      step,
+      at: step.tStart,
+      ...carry ? { carry } : {}
+    };
   }
   if (pin.press !== void 0 && Number.isFinite(pin.press)) {
     let best = null;
@@ -3101,10 +3109,42 @@ function pinReferent(doc, pin) {
       if (!best || d < Math.abs(best.t - pin.press)) best = { t, rect: e.rect };
     }
     if (!best || w <= 0 || h <= 0) return null;
-    return { rect: normRect(best.rect, w, h), by: "press", at: best.t };
+    const carry = dragCarry(doc, best.t - 0.01, best.t + 0.01);
+    return {
+      rect: normRect(best.rect, w, h),
+      by: "press",
+      at: best.t,
+      ...carry ? { carry } : {}
+    };
   }
   return null;
 }
+function dragCarry(doc, from, to) {
+  const meta = doc.source.meta;
+  if (!(meta.width > 0) || !(meta.height > 0)) return null;
+  const d = dragsFromTrack(doc.source.cursor, meta.width, meta.height).find(
+    (g) => g.t0 >= from && g.t0 <= to
+  );
+  if (!d) return null;
+  return { t0: d.t0, t1: d.t1, x0: d.nx, y0: d.ny };
+}
+function cursorAt(cursor, t, space) {
+  let prev = null;
+  for (const e of cursor) {
+    if (e.type !== "move" && e.type !== "down" && e.type !== "up") continue;
+    const cur = { t: e.t / 1e3, nx: e.x / space.w, ny: e.y / space.h };
+    if (cur.t >= t) {
+      if (!prev) return { nx: cur.nx, ny: cur.ny };
+      const k = cur.t > prev.t ? (t - prev.t) / (cur.t - prev.t) : 1;
+      return {
+        nx: prev.nx + (cur.nx - prev.nx) * k,
+        ny: prev.ny + (cur.ny - prev.ny) * k
+      };
+    }
+    prev = cur;
+  }
+  return prev ? { nx: prev.nx, ny: prev.ny } : null;
+}
 function findStep(steps, ref) {
   const byId = steps.find((s) => s.id !== void 0 && s.id === ref);
   if (byId) return byId;
@@ -3188,6 +3228,20 @@ function pinRectOnScreen(rect, t, layout, camera, zoomTrack) {
   const b = map(rect.x + rect.w, rect.y + rect.h);
   return { x: a.x, y: a.y, w: b.x - a.x, h: b.y - a.y };
 }
+function pinReferentAt(referent, t, input) {
+  const { carry, cursor, space, rated } = input;
+  if (!carry || !cursor || !space || !rated) return referent;
+  const s = mapTime(rated, t);
+  const sc = Math.max(carry.t0, Math.min(carry.t1, s));
+  const p = cursorAt(cursor, sc, space);
+  if (!p) return referent;
+  return {
+    x: referent.x + (p.nx - carry.x0),
+    y: referent.y + (p.ny - carry.y0),
+    w: referent.w,
+    h: referent.h
+  };
+}
 function pinPlacement(input) {
   const { clip, referent, layout, camera, zoomTrack, base, motion } = input;
   const dur = Math.max(1e-3, clip.duration);
@@ -3195,7 +3249,13 @@ function pinPlacement(input) {
   const box = pinBox(clip, layout);
   const W = layout.W;
   const H = layout.H;
-  const refAt = (local) => pinRectOnScreen(referent, clip.start + local, layout, camera, zoomTrack);
+  const refAt = (local) => pinRectOnScreen(
+    pinReferentAt(referent, clip.start + local, input),
+    clip.start + local,
+    layout,
+    camera,
+    zoomTrack
+  );
   const centreFor = (r, side2) => {
     switch (side2) {
       case "right":
@@ -6670,6 +6730,15 @@ var ON_FRAME = `(ctx, content, dt) => {
       if (pn.dur - pnT < 0.35) { var pnV = (pn.dur - pnT) / 0.35; pnA = Math.min(pnA, 1 - Math.pow(1 - pnV, 3)) }
       if (pnA <= 0.004) continue
       var pnX = dx + pn.x * dw, pnY = dy + pn.y * dh, pnW = pn.w * dw, pnH = pn.h * dh
+      // a carried referent (a drag): moved by where the pointer has taken
+      // it at the on-screen source moment, held at the release
+      if (pn.carry) {
+        var pcC = (actM ? actM.cursor : d.cursor) || []
+        var pcT = Math.max(pn.carry.t0, Math.min(pn.carry.t1, srcT))
+        var pcx = -1, pcy = -1
+        for (var pk = 0; pk < pcC.length; pk++) { if (pcC[pk].t <= pcT) { pcx = pcC[pk].x; pcy = pcC[pk].y } }
+        if (pcx >= 0) { pnX += (pcx / (space.w || vw) - pn.carry.x0) * dw; pnY += (pcy / (space.h || vh) - pn.carry.y0) * dh }
+      }
       var pnLw = 2 * s2 / ceZs, pnPad = 6 * s2 / ceZs
       var pnCol = pn.color || 'rgba(255,255,255,0.95)'
       c.save()
@@ -6839,6 +6908,15 @@ var ON_FRAME = `(ctx, content, dt) => {
       // the referent's corners in frame space under the live camera
       var pqAx = dx + pq.x * dw, pqAy = dy + pq.y * dh
       var pqBx = dx + (pq.x + pq.w) * dw, pqBy = dy + (pq.y + pq.h) * dh
+      if (pq.carry) {
+        var pqcT = Math.max(pq.carry.t0, Math.min(pq.carry.t1, srcT))
+        var pqcx = -1, pqcy = -1
+        for (var pqk = 0; pqk < cur.length; pqk++) { if (cur[pqk].t <= pqcT) { pqcx = cur[pqk].x; pqcy = cur[pqk].y } }
+        if (pqcx >= 0) {
+          var pqOx = (pqcx / (space.w || vw) - pq.carry.x0) * dw, pqOy = (pqcy / (space.h || vh) - pq.carry.y0) * dh
+          pqAx += pqOx; pqBx += pqOx; pqAy += pqOy; pqBy += pqOy
+        }
+      }
       if (lvl > 1.001 && !d.zoomSuppressed) {
         if (camStage) {
           pqAx = W / 2 + (pqAx - wcx) * lvl; pqAy = H / 2 + (pqAy - wcy) * lvl
@@ -7423,6 +7501,8 @@ function docZoomTrack(input) {
 }
 function resolvePins(doc, layout, camera, zoomTrack) {
   const out = /* @__PURE__ */ new Map();
+  const rated = ratedSegments(doc);
+  const space = { w: doc.source.meta.width, h: doc.source.meta.height };
   for (const o of doc.overlays ?? []) {
     if (!o.pin) continue;
     const ref = pinReferent(doc, o.pin);
@@ -7442,7 +7522,11 @@ function resolvePins(doc, layout, camera, zoomTrack) {
         camera,
         zoomTrack,
         base,
-        motion
+        motion,
+        carry: ref.carry ?? null,
+        cursor: doc.source.cursor,
+        space,
+        rated
       })
     );
   }
@@ -7484,6 +7568,16 @@ function pinsDataOf(doc, pins) {
       mark,
       leader: !!p.leader,
       ...p.color ? { color: p.color } : {},
+      // A carried referent (a drag): ON_FRAME moves the mark and the
+      // leader's end with the pointer through [t0, t1], source seconds.
+      ...ref.carry ? {
+        carry: {
+          t0: round7(ref.carry.t0),
+          t1: round7(ref.carry.t1),
+          x0: round43(ref.carry.x0),
+          y0: round43(ref.carry.y0)
+        }
+      } : {},
       enter: enterKey(o),
       tip: placed.tip
     });
@@ -8439,12 +8533,12 @@ function round10(v) {
 }
 
 // src/timeline/rangeActions.ts
-import { mapTime } from "@vosjs/timeline";
+import { mapTime as mapTime2 } from "@vosjs/timeline";
 function outputRangeToSource(doc, t0, t1) {
   const rated = ratedSegments(doc);
   return {
-    srcIn: mapTime(rated, Math.max(0, t0)),
-    srcOut: mapTime(rated, Math.max(0, t1))
+    srcIn: mapTime2(rated, Math.max(0, t0)),
+    srcOut: mapTime2(rated, Math.max(0, t1))
   };
 }
 var EPS = 1e-6;
@@ -9209,7 +9303,7 @@ function applyLook(frame, look, size, video, placement) {
 
 // src/timeline/lanes.ts
 import {
-  mapTime as mapTime2,
+  mapTime as mapTime3,
   removeSegment,
   segmentRate as segmentRate3,
   sourceToTimeline as sourceToTimeline2,
@@ -9277,7 +9371,7 @@ var videoLane = {
           index === 0 || !contiguous(segments, index)
         );
         const anchorOut = sourceToTimeline2(fullMap, Math.min(edgeSrc, sourceDuration)) ?? edgeSrc;
-        const sourceT = mapTime2(fullMap, anchorOut + (g.t - edgeOutNow));
+        const sourceT = mapTime3(fullMap, anchorOut + (g.t - edgeOutNow));
         const next = trimSegment(
           segments,
           index,
@@ -9313,7 +9407,7 @@ var videoLane = {
             return null;
         }
         const sourceT = round12(
-          mapTime2(segmentPieces(s, speeds, freezes, leading), local)
+          mapTime3(segmentPieces(s, speeds, freezes, leading), local)
         );
         if (sourceT - s.in < 0.05 || s.out - sourceT < 0.05) return null;
         const next = [
@@ -9403,7 +9497,7 @@ var freezeLane = {
         if (g.t >= m.t - 1e-9 && g.t <= m.t + m.duration + 1e-9) return null;
       }
       if (g.t > totalDuration7(rated) + 1e-9) return null;
-      const srcT = round12(mapTime2(rated, Math.max(0, g.t)));
+      const srcT = round12(mapTime3(rated, Math.max(0, g.t)));
       if (!kept(srcT) || !clear(srcT)) return null;
       const id = nextFreezeId(doc);
       const mediaHere = mediaAtOutput(rated, Math.max(0, g.t));
@@ -9446,7 +9540,7 @@ var freezeLane = {
       const mine = marks.get(f.id);
       const endOut = mine ? mine.t + mine.duration : null;
       const srcT = round12(
-        Math.min(sourceDuration, mapTime2(base, Math.max(0, g.t)))
+        Math.min(sourceDuration, mapTime3(base, Math.max(0, g.t)))
       );
       if (!kept(srcT) || !clear(srcT, f.id)) return null;
       return (d) => {
@@ -9517,7 +9611,7 @@ var zoomLane = {
     const rated = ratedSegments(doc);
     const sourceDuration = anchorSourceDuration(doc);
     if (g.type === "create") {
-      const srcT = mapTime2(rated, Math.max(0, g.t));
+      const srcT = mapTime3(rated, Math.max(0, g.t));
       const mediaHere = mediaAtOutput(rated, Math.max(0, g.t));
       const here = spans.filter((z) => (z.media ?? "") === mediaHere);
       const mediaLen = mediaDuration(mediaSource(doc, mediaHere) ?? doc.source);
@@ -9551,7 +9645,7 @@ var zoomLane = {
       const len = sp.out - sp.in;
       let newIn = clampToKept(
         effectiveSegments(doc),
-        mapTime2(rated, Math.max(0, g.t)),
+        mapTime3(rated, Math.max(0, g.t)),
         len
       );
       for (const o of others) {
@@ -9581,7 +9675,7 @@ var zoomLane = {
         sourceDuration,
         ...others.filter((o) => o.in >= sp.out).map((o) => o.in)
       );
-      const sourceT = mapTime2(rated, Math.max(0, g.t));
+      const sourceT = mapTime3(rated, Math.max(0, g.t));
       const minSrc = Math.min(
         ZOOM_SPAN_MIN * rateAt(rated, sp.in),
         sp.out - sp.in
@@ -9646,7 +9740,7 @@ var tiltLane = {
     const rated = ratedSegments(doc);
     const sourceDuration = anchorSourceDuration(doc);
     if (g.type === "create") {
-      const srcT = mapTime2(rated, Math.max(0, g.t));
+      const srcT = mapTime3(rated, Math.max(0, g.t));
       const mediaHere = mediaAtOutput(rated, Math.max(0, g.t));
       const here = spans.filter((z) => (z.media ?? "") === mediaHere);
       const mediaLen = mediaDuration(mediaSource(doc, mediaHere) ?? doc.source);
@@ -9678,7 +9772,7 @@ var tiltLane = {
       const len = sp.out - sp.in;
       let newIn = clampToKept(
         effectiveSegments(doc),
-        mapTime2(rated, Math.max(0, g.t)),
+        mapTime3(rated, Math.max(0, g.t)),
         len
       );
       for (const o of others) {
@@ -9708,7 +9802,7 @@ var tiltLane = {
         sourceDuration,
         ...others.filter((o) => o.in >= sp.out).map((o) => o.in)
       );
-      const sourceT = mapTime2(rated, Math.max(0, g.t));
+      const sourceT = mapTime3(rated, Math.max(0, g.t));
       const minSrc = Math.min(
         TILT_SPAN_MIN * rateAt(rated, sp.in),
         sp.out - sp.in
@@ -9764,7 +9858,7 @@ var camMoveLane = {
     const sourceDuration = anchorSourceDuration(doc);
     if (g.type === "create") {
       if (!doc.source.camKey) return null;
-      const srcT = mapTime2(rated, Math.max(0, g.t));
+      const srcT = mapTime3(rated, Math.max(0, g.t));
       if (spans.some((z) => srcT >= z.in && srcT < z.out)) return null;
       const next = spans.filter((z) => z.in > srcT).sort((a, b) => a.in - b.in).at(0);
       const limit = Math.min(sourceDuration, next ? next.in : sourceDuration);
@@ -9791,7 +9885,7 @@ var camMoveLane = {
       const len = sp.out - sp.in;
       let newIn = clampToKept(
         effectiveSegments(doc),
-        mapTime2(rated, Math.max(0, g.t)),
+        mapTime3(rated, Math.max(0, g.t)),
         len
       );
       for (const o of others) {
@@ -9821,7 +9915,7 @@ var camMoveLane = {
         sourceDuration,
         ...others.filter((o) => o.in >= sp.out).map((o) => o.in)
       );
-      const sourceT = mapTime2(rated, Math.max(0, g.t));
+      const sourceT = mapTime3(rated, Math.max(0, g.t));
       const minSrc = Math.min(
         CAM_SPAN_MIN * rateAt(rated, sp.in),
         sp.out - sp.in
@@ -9895,7 +9989,7 @@ var camLane = {
       if (!seg) return null;
       const clipSrcStart = Math.max(seg.in, Math.max(current.in, first.in));
       const span = Math.max(0.05, current.out - current.in);
-      const delta = mapTime2(rated, Math.max(0, g.t)) - clipSrcStart;
+      const delta = mapTime3(rated, Math.max(0, g.t)) - clipSrcStart;
       const base = Math.max(first.in, current.in);
       const newIn = Math.min(
         Math.max(first.in, base + delta),
@@ -9911,7 +10005,7 @@ var camLane = {
     })).filter((x) => x.len > 1e-6);
     const edgeIdx = g.edge === "start" ? overlapping.at(0)?.i : overlapping.at(-1)?.i;
     if (edgeIdx === void 0 || g.id !== `cam-${edgeIdx}`) return null;
-    const sourceT = Math.min(Math.max(mapTime2(rated, g.t), 0), sourceDuration);
+    const sourceT = Math.min(Math.max(mapTime3(rated, g.t), 0), sourceDuration);
     const next = g.edge === "start" ? { in: Math.min(sourceT, current.out - 0.05), out: current.out } : { in: current.in, out: Math.max(sourceT, current.in + 0.05) };
     return (d) => {
       d.cam.window = {
@@ -10005,7 +10099,7 @@ var speedLane = {
     const rated = ratedSegments(doc);
     const sourceDuration = anchorSourceDuration(doc);
     if (g.type === "create") {
-      const srcT = mapTime2(rated, Math.max(0, g.t));
+      const srcT = mapTime3(rated, Math.max(0, g.t));
       if (spans.some((s) => srcT >= s.in && srcT < s.out)) return null;
       const next = spans.filter((s) => s.in > srcT).sort((a, b) => a.in - b.in).at(0);
       const limit = Math.min(sourceDuration, next ? next.in : sourceDuration);
@@ -10035,7 +10129,7 @@ var speedLane = {
       const len = sp.out - sp.in;
       let newIn = clampToKept(
         effectiveSegments(doc),
-        mapTime2(base, Math.max(0, g.t)),
+        mapTime3(base, Math.max(0, g.t)),
         len
       );
       for (const o of others) {
@@ -10064,7 +10158,7 @@ var speedLane = {
       const minSrc = Math.min(SPEED_SPAN_MIN * sp.rate, sp.out - sp.in);
       let next;
       if (g.edge === "start") {
-        const sourceT = mapTime2(base, Math.max(0, g.t));
+        const sourceT = mapTime3(base, Math.max(0, g.t));
         next = {
           in: Math.min(Math.max(lo, sourceT), sp.out - minSrc),
           out: sp.out
@@ -10432,7 +10526,7 @@ function computePeaks(channels, buckets) {
 }
 
 // src/lower/duckCurve.ts
-import { mapTime as mapTime3 } from "@vosjs/timeline";
+import { mapTime as mapTime4 } from "@vosjs/timeline";
 var DEFAULT_DUCK = {
   threshold: 0.02,
   duckTo: 0.25,
@@ -10468,7 +10562,7 @@ function duckCurve(rms, segments, durationSec2, opts = DEFAULT_DUCK) {
   const steps = Math.ceil(durationSec2 * opts.gridHz);
   for (let i = 0; i <= steps; i++) {
     const t = Math.min(durationSec2, i * dt);
-    const srcT = mapTime3(segments, t);
+    const srcT = mapTime4(segments, t);
     const w = Math.min(
       rms.values.length - 1,
       Math.max(0, Math.floor(srcT * rms.rate))
@@ -10855,6 +10949,7 @@ export {
   pinPlacement,
   pinRectOnScreen,
   pinReferent,
+  pinReferentAt,
   placeFreezes,
   planAutoSpeed,
   planAutoTilt,