@vosjs/studio-core 0.22.0 → 0.23.0

package/dist/index.d.ts

@@ -73,6 +73,14 @@ interface ZoomStyleParams {
     targetFill: number;
     minLevel: number;
     maxLevel: number;
+    /**
+     * The level a DRAG is followed at (a press that travels before its
+     * release: a slider thumb, a scrubber, a thing moved across a canvas).
+     * The camera pans WITH the pointer for the whole press (a path follow,
+     * not a dead zone), so the level stays mild: the thumb and what it drives
+     * both stay in the window.
+     */
+    dragLevel: number;
     /** span lead-in before the first click / hold after the last (seconds). */
     lead: number;
     hold: number;
@@ -2065,6 +2073,35 @@ declare function smoothCursor(track: CursorTrack, options?: SmoothOptions): Smoo
  * is set aside before clustering; the targets around it keep their zoom.
  */
 declare const DRAG_FIT_LEVEL = 1.15;
+/**
+ * A press that TRAVELS before its release is a drag (a slider thumb, a
+ * scrubber, a thing moved across a canvas): the pointer's path is the
+ * content, so the camera follows it for the whole press at the style's
+ * dragLevel instead of framing the press as a click. Travel is the farthest
+ * the pointer gets from the press point, as a fraction of the frame width;
+ * a press held still (a long click) stays a click.
+ */
+declare const DRAG_MIN_TRAVEL_FRAC = 0.015;
+declare const DRAG_MIN_S = 0.2;
+/** A press that travelled before its release, in seconds and frame fractions. */
+interface Drag {
+    /** the press and the release, seconds */
+    t0: number;
+    t1: number;
+    /** the press point, normalized */
+    nx: number;
+    ny: number;
+    /** the pointer's farthest excursion from the press point, frame widths */
+    travel: number;
+}
+/**
+ * The drags in a cursor track: each `down` paired with the next `up`, kept
+ * when the pointer travelled ≥ DRAG_MIN_TRAVEL_FRAC between them over
+ * ≥ DRAG_MIN_S. Shared by the planner (a drag plans a follow span, and its
+ * press is not a click) and the lowering's cursor follow (a drag inside any
+ * follow span is tracked as a path).
+ */
+declare function dragsFromTrack(track: CursorTrack, width: number, height: number): Drag[];
 interface PlanOptions {
     /** captured frame size (for normalizing rects → [0..1] focus points). */
     width: number;
@@ -2088,6 +2125,8 @@ interface PlanOptions {
     hold?: number;
     /** minimum clicks for a cluster to earn a zoom (Cursorful's ≥2 rule). */
     minClusterClicks?: number;
+    /** the level a drag is followed at (see ZoomStyleParams.dragLevel). */
+    dragLevel?: number;
     /** emit spans with focusMode 'auto' (cursor-follow camera). */
     followByDefault?: boolean;
     /** typing sessions plan spans. */
@@ -2337,10 +2376,12 @@ declare function cameraModel(frame: {
     camera?: string | null;
 } | null | undefined): CameraModel;
 /**
- * How much of the level the stage camera spends pulling the focus to the
- * frame's centre: 0 at level 1 (the identity), fully centred from level
- * 1 + CAMERA_CENTRE_RAMP. A smoothstep, so a ramp that passes through the
- * band slides the card without a kink.
+ * The stage camera's centring is a component of the zoom TRACK (0 at rest,
+ * 1 at an apex, eased with the level), so the card's slide and its scale
+ * are one motion. This band is the FALLBACK for a track lowered before the
+ * component existed: centring as a smoothstep of the level over
+ * 1 .. 1 + CAMERA_CENTRE_RAMP. Keyed to the level it front-loaded the
+ * slide, since any ease crosses the band in its first frames (the twitch).
  */
 declare const CAMERA_CENTRE_RAMP = 0.3;
 /**
@@ -2372,7 +2413,14 @@ interface ZoomView {
     ox: number;
     oy: number;
 }
-declare function zoomView(level: number, cx: number, cy: number, layout: CardLayout, camera?: CameraModel): ZoomView;
+declare function zoomView(level: number, cx: number, cy: number, layout: CardLayout, camera?: CameraModel, 
+/**
+ * The stage camera's centring at this instant, 0..1: the zoom track's
+ * fourth component (0 at rest, 1 at an apex, eased with the level).
+ * Absent = the apex (1) under the stage camera, which is what a span's
+ * stored focus describes; always 0 under the magnifier.
+ */
+centring?: number): ZoomView;
 /**
  * The visible window as fractions of the canvas (x/y its top-left, w/h its
  * size, both 1/level): what the studio's aiming rect draws and what the
@@ -2380,7 +2428,7 @@ declare function zoomView(level: number, cx: number, cy: number, layout: CardLay
  * under the stage camera; it never does under the magnifier once the focus
  * is clamped.
  */
-declare function zoomViewport(level: number, cx: number, cy: number, layout: CardLayout, camera?: CameraModel): {
+declare function zoomViewport(level: number, cx: number, cy: number, layout: CardLayout, camera?: CameraModel, centring?: number): {
     x: number;
     y: number;
     w: number;
@@ -2392,7 +2440,7 @@ declare function zoomViewport(level: number, cx: number, cy: number, layout: Car
  * `level`. The aiming rect's corner drag re-derives its focus through this
  * so the rect stays under the pointer in either camera model.
  */
-declare function focusForViewportCentre(cX: number, cY: number, level: number, layout: CardLayout, camera?: CameraModel): {
+declare function focusForViewportCentre(cX: number, cY: number, level: number, layout: CardLayout, camera?: CameraModel, centring?: number): {
     cx: number;
     cy: number;
 };
@@ -2835,6 +2883,13 @@ interface FollowOptions {
 interface FollowEvent {
     /** SOURCE seconds — the moment the recenter starts. */
     t: number;
+    /**
+     * A PATH sample: the camera is at this focus AT `t` (a linear segment
+     * from the previous keyframe), not the start of a glide toward it. Baked
+     * every FOLLOW_PATH_STEP through a drag, so the camera pans with the
+     * pointer for the whole press.
+     */
+    path?: true;
     cx: number;
     cy: number;
 }
@@ -4451,4 +4506,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, type Destination, type Digest, type DigestImageRef, type DigestPlan, type DigestTakeFacts, type DocSegment, 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 OverlayPresetStyle, type OverlayRect, type OverlayTransform, type OverlayTransition, PLATE_GROUND, PLAYBACK_ACTIVITY, PRIMARY_MEDIA, PROGRAM_RETIME, 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, dropTemplate, duckCurve, effectiveSegments, endCardClips, enterKey, enterOf, entranceSeconds, envelopeAt, envelopeValueAt, exitKey, exitOf, exitSeconds, expandEndCard, expectedFrameSize, exportSizeFor, extractClicks, 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, overlayRect, overlaysLane, ownFreezes, pageDisplayUrl, parsePoseId, pickStyle, placeFreezes, planAutoSpeed, planAutoTilt, planAutoZoom, planForDigest, planeSizeAtDepth, platformBarKind, programDuration, projectFromArtifact, ratedSegments, recommendedExportResolution, refillAudioBeds, rejectSpan, removeSourceRange, removeSpeedInRange, resolveExportSize, resolveOverlayBox, resolveOverlayStyle, 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 OverlayPresetStyle, type OverlayRect, type OverlayTransform, type OverlayTransition, PLATE_GROUND, PLAYBACK_ACTIVITY, PRIMARY_MEDIA, PROGRAM_RETIME, 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, dragsFromTrack, dropTemplate, duckCurve, effectiveSegments, endCardClips, enterKey, enterOf, entranceSeconds, envelopeAt, envelopeValueAt, exitKey, exitOf, exitSeconds, expandEndCard, expectedFrameSize, exportSizeFor, extractClicks, 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, overlayRect, overlaysLane, ownFreezes, pageDisplayUrl, parsePoseId, pickStyle, placeFreezes, planAutoSpeed, planAutoTilt, planAutoZoom, planForDigest, planeSizeAtDepth, platformBarKind, programDuration, projectFromArtifact, ratedSegments, recommendedExportResolution, refillAudioBeds, rejectSpan, removeSourceRange, removeSpeedInRange, resolveExportSize, resolveOverlayBox, resolveOverlayStyle, 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

@@ -1156,6 +1156,7 @@ var ZOOM_STYLES = {
     targetFill: 0.42,
     minLevel: 1.3,
     maxLevel: 1.8,
+    dragLevel: 1.5,
     lead: 0.35,
     hold: 1.2,
     followByDefault: true,
@@ -1168,8 +1169,13 @@ var ZOOM_STYLES = {
     rampOut: 0.5,
     chainGap: 3,
     pan: 0.55,
-    ease: "css-bezier(0.16, 1, 0.3, 1)",
-    panEase: "css-bezier(0.22, 1, 0.36, 1)",
+    // The reference's corner trace at 60 fps: a quarter of the move by a
+    // fifth of the time, two thirds by half, the rest a settle. That is
+    // CSS `ease` (0.25, 0.1, 0.25, 1), a small lead-in and a long tail;
+    // (0.16, 1, 0.3, 1) put half the move in the first sixty milliseconds
+    // and read as a twitch.
+    ease: "css-bezier(0.25, 0.1, 0.25, 1)",
+    panEase: "css-bezier(0.3, 0.05, 0.25, 1)",
     followSafeRatio: 0.45,
     followRecenter: 0.55,
     followLookahead: 0.4,
@@ -1183,6 +1189,7 @@ var ZOOM_STYLES = {
     targetFill: 0.5,
     minLevel: 1.5,
     maxLevel: 2.2,
+    dragLevel: 1.7,
     lead: 0.35,
     hold: 1,
     followByDefault: false,
@@ -1210,6 +1217,7 @@ var ZOOM_STYLES = {
     targetFill: 0.45,
     minLevel: 1.35,
     maxLevel: 2,
+    dragLevel: 1.5,
     lead: 0.6,
     hold: 1.4,
     followByDefault: true,
@@ -1237,6 +1245,7 @@ var ZOOM_STYLES = {
     targetFill: 0.5,
     minLevel: 1.4,
     maxLevel: 2.5,
+    dragLevel: 1.7,
     lead: 0.25,
     hold: 1,
     followByDefault: false,
@@ -1264,6 +1273,7 @@ var ZOOM_STYLES = {
     targetFill: 0.5,
     minLevel: 1.5,
     maxLevel: 2.2,
+    dragLevel: 1.7,
     lead: 0.2,
     hold: 1,
     followByDefault: false,
@@ -1292,6 +1302,7 @@ var ZOOM_STYLES = {
     targetFill: 0.42,
     minLevel: 1.3,
     maxLevel: 1.8,
+    dragLevel: 1.5,
     lead: 0.5,
     hold: 0.6,
     followByDefault: false,
@@ -1329,6 +1340,7 @@ var ZOOM_STYLES = {
     targetFill: 0.42,
     minLevel: 1.3,
     maxLevel: 1.8,
+    dragLevel: 1.5,
     lead: 0.5,
     hold: 0.7,
     followByDefault: true,
@@ -1366,6 +1378,7 @@ var ZOOM_STYLES = {
     targetFill: 0.45,
     minLevel: 1.35,
     maxLevel: 2,
+    dragLevel: 1.5,
     lead: 0.6,
     hold: 1.4,
     followByDefault: true,
@@ -1436,6 +1449,37 @@ var DWELL_SPACING = 1.8;
 var DRAG_FIT_LEVEL = 1.15;
 var PRESS_ECHO_MS = 4;
 var PRESS_ECHO_PX = 2;
+var DRAG_MIN_TRAVEL_FRAC = 0.015;
+var DRAG_MIN_S = 0.2;
+function dragsFromTrack(track, width, height) {
+  if (!(width > 0) || !(height > 0)) return [];
+  const downs = dedupePresses(track.filter((e) => e.type === "down"));
+  const out = [];
+  for (const d of downs) {
+    const up = track.find((e) => e.type === "up" && e.t > d.t);
+    if (!up) continue;
+    const t0 = d.t / 1e3;
+    const t1 = up.t / 1e3;
+    if (t1 - t0 < DRAG_MIN_S) continue;
+    let travel = 0;
+    for (const e of track) {
+      if (e.t < d.t) continue;
+      if (e.t > up.t) break;
+      if (e.type !== "move" && e.type !== "up") continue;
+      const dist = Math.hypot(e.x - d.x, e.y - d.y) / width;
+      if (dist > travel) travel = dist;
+    }
+    if (travel < DRAG_MIN_TRAVEL_FRAC) continue;
+    out.push({
+      t0,
+      t1,
+      nx: clamp012(d.x / width),
+      ny: clamp012(d.y / height),
+      travel
+    });
+  }
+  return out;
+}
 var TYPING_MIN_PINGS = 2;
 var TYPING_MIN_DUR = 0.5;
 var TYPING_CLICK_ABSORB = 1.5;
@@ -1513,13 +1557,14 @@ function planAutoZoom(track, options) {
     lead = style.lead,
     hold = style.hold,
     minClusterClicks = style.minClusterClicks,
+    dragLevel = style.dragLevel,
     followByDefault = style.followByDefault,
     typingZoom = style.typingZoom,
     typingGap = style.typingGap,
     typingHold = style.typingHold,
     typingMinLevel = style.typingMinLevel
   } = options;
-  const { sessions, clusters, surfaces } = groupTrack(track, {
+  const grouped = groupTrack(track, {
     width,
     height,
     clusterGap,
@@ -1527,6 +1572,22 @@ function planAutoZoom(track, options) {
     typingZoom,
     targetFill
   });
+  const { sessions } = grouped;
+  const drags = dragsFromTrack(track, width, height);
+  const dragPress = new Set(drags.map((d) => round(d.t0)));
+  const withoutDrags = (list) => list.map((cl) => cl.filter((c) => !dragPress.has(round(c.t)))).filter((cl) => cl.length > 0);
+  const clusters = withoutDrags(grouped.clusters);
+  const surfaces = withoutDrags(grouped.surfaces);
+  const dragSpans = drags.map((d, i) => ({
+    id: `g${i}`,
+    in: round(Math.max(0, d.t0 - lead)),
+    out: round(d.t1 + hold),
+    level: clampZoomLevel(Math.min(Math.max(dragLevel, 1.1), maxLevel)),
+    cx: round(d.nx),
+    cy: round(d.ny),
+    focusMode: "auto",
+    source: "auto"
+  }));
   const eligible = clusters.filter((c) => c.length >= minClusterClicks);
   const clickSpans = [];
   const dragReserved = surfaces.map((cluster, i) => {
@@ -1615,7 +1676,7 @@ function planAutoZoom(track, options) {
     // the FIELD is the anchor, and a follow would be a no-op at best.
     source: "auto"
   }));
-  const spans = [...zSpans, ...kSpans].sort((a, b) => a.in - b.in);
+  const spans = [...zSpans, ...kSpans, ...dragSpans].sort((a, b) => a.in - b.in);
   const dwells = dwellSpans(track, width, height, maxLevel, [
     ...spans,
     ...dragReserved
@@ -1964,19 +2025,19 @@ function cameraCentring(level) {
   const u = clamp013((level - 1) / CAMERA_CENTRE_RAMP);
   return u * u * (3 - 2 * u);
 }
-function zoomView(level, cx, cy, layout, camera = "card") {
+function zoomView(level, cx, cy, layout, camera = "card", centring) {
   const L = Math.max(1, level);
   const fx = layout.dx + cx * layout.dw;
   const fy = layout.dy + cy * layout.dh;
   const ox = layout.W / 2;
   const oy = layout.H / 2;
-  const t = camera === "stage" ? cameraCentring(L) : 0;
+  const t = camera === "stage" ? clamp013(centring ?? 1) : 0;
   const wcx = fx + (ox - fx) / L * (1 - t);
   const wcy = fy + (oy - fy) / L * (1 - t);
   return { level: L, fx, fy, wcx, wcy, ox, oy };
 }
-function zoomViewport(level, cx, cy, layout, camera = "card") {
-  const v = zoomView(level, cx, cy, layout, camera);
+function zoomViewport(level, cx, cy, layout, camera = "card", centring) {
+  const v = zoomView(level, cx, cy, layout, camera, centring);
   const size = 1 / v.level;
   return {
     x: (v.wcx - layout.W / (2 * v.level)) / layout.W,
@@ -1985,9 +2046,9 @@ function zoomViewport(level, cx, cy, layout, camera = "card") {
     h: size
   };
 }
-function focusForViewportCentre(cX, cY, level, layout, camera = "card") {
+function focusForViewportCentre(cX, cY, level, layout, camera = "card", centring) {
   const L = Math.max(1, level);
-  const t = camera === "stage" ? cameraCentring(L) : 0;
+  const t = camera === "stage" ? clamp013(centring ?? 1) : 0;
   const a = 1 - (1 - t) / L;
   if (a <= 1e-6) return { cx: 0.5, cy: 0.5 };
   const fx = (cX * layout.W - layout.W / 2 * (1 - t) / L) / a;
@@ -2894,6 +2955,8 @@ function envelopeValueAt(env, t) {
 // src/lower/cursorFollow.ts
 var FOLLOW_SAFE_RATIO = ZOOM_STYLES.glide.followSafeRatio;
 var FOLLOW_RECENTER = ZOOM_STYLES.glide.followRecenter;
+var FOLLOW_PATH_STEP = 0.1;
+var FOLLOW_PATH_SMOOTH = 0.08;
 function followFocusEvents(span, cursor, space, layout, options = {}) {
   const safeRatio = options.safeRatio ?? FOLLOW_SAFE_RATIO;
   const recenter = options.recenter ?? FOLLOW_RECENTER;
@@ -2916,9 +2979,48 @@ function followFocusEvents(span, cursor, space, layout, options = {}) {
   let cx = entry.cx;
   let cy = entry.cy;
   let nextAllowed = span.in + recenter;
+  const drags = dragsFromTrack(cursor, space.w, space.h).filter(
+    (d) => d.t1 > span.in && d.t0 < span.out
+  );
+  const pathEvents = [];
+  for (const d of drags) {
+    const from = Math.max(d.t0, span.in);
+    const to = Math.min(d.t1, span.out);
+    for (let t = from; ; t += FOLLOW_PATH_STEP) {
+      const at = Math.min(t, to);
+      const a = sampleAt2(pts, at - FOLLOW_PATH_SMOOTH);
+      const b = sampleAt2(pts, at);
+      const c = sampleAt2(pts, at + FOLLOW_PATH_SMOOTH);
+      const f = clampFocus(
+        (a.nx + b.nx + c.nx) / 3,
+        (a.ny + b.ny + c.ny) / 3,
+        level,
+        layout,
+        camera
+      );
+      pathEvents.push({
+        t: round2(at),
+        path: true,
+        cx: round2(f.cx),
+        cy: round2(f.cy)
+      });
+      if (at >= to) break;
+    }
+  }
+  let dragIdx = 0;
   for (const p of pts) {
     if (p.t < span.in) continue;
     if (p.t > span.out) break;
+    while (dragIdx < drags.length && p.t > drags[dragIdx].t1) {
+      const last = pathEvents.filter((e) => e.t <= drags[dragIdx].t1).at(-1);
+      if (last) {
+        cx = last.cx;
+        cy = last.cy;
+      }
+      nextAllowed = drags[dragIdx].t1 + recenter;
+      dragIdx++;
+    }
+    if (dragIdx < drags.length && p.t >= drags[dragIdx].t0) continue;
     if (p.t < nextAllowed) continue;
     if (Math.abs(p.nx - cx) > thrX || Math.abs(p.ny - cy) > thrY) {
       const target = lookahead > 0 ? sampleAt2(pts, Math.min(p.t + lookahead, span.out)) : p;
@@ -2930,7 +3032,8 @@ function followFocusEvents(span, cursor, space, layout, options = {}) {
       nextAllowed = p.t + recenter;
     }
   }
-  return { entry, events };
+  const merged = [...events, ...pathEvents].sort((a, b) => a.t - b.t);
+  return { entry, events: merged };
 }
 function sampleAt2(pts, t) {
   if (t <= pts[0].t) return pts[0];
@@ -4655,30 +4758,42 @@ function zoomTrackFromDoc(zoom, segments, style = ZOOM_STYLES[DEFAULT_ZOOM_STYLE
   let chained = false;
   for (let i = 0; i < mapped.length; i++) {
     const { z, tIn, tOut } = mapped[i];
-    const entry = [clampZoomLevel(z.level), z.cx, z.cy];
+    const entry = [clampZoomLevel(z.level), z.cx, z.cy, 1];
     let cur = entry;
     const m = transitionMult(z.transition);
     if (!chained) {
       const start = push2(
         tIn - (style.rampIn - style.rampInOverlap) * m,
-        [1, z.cx, z.cy],
+        [1, z.cx, z.cy, 0],
         "none"
       );
       push2(start + style.rampIn * m, entry, spanEase(z.ease, style.ease));
     }
+    let inPath = false;
     for (const e of z.followEvents ?? []) {
       const eOut = sourceToTimeline(segments, e.t);
       if (eOut === null || eOut <= tIn || eOut >= tOut) continue;
-      const next2 = [cur[0], e.cx, e.cy];
-      push2(eOut, cur, "none");
-      push2(Math.min(eOut + style.followRecenter, tOut), next2, panEase);
+      const next2 = [cur[0], e.cx, e.cy, 1];
+      if (e.path) {
+        if (!inPath) {
+          push2(Math.max(tIn, eOut - style.followRecenter), cur, "none");
+          push2(eOut, next2, panEase);
+          inPath = true;
+        } else {
+          push2(eOut, next2, "linear");
+        }
+      } else {
+        inPath = false;
+        push2(eOut, cur, "none");
+        push2(Math.min(eOut + style.followRecenter, tOut), next2, panEase);
+      }
       cur = next2;
     }
     push2(tOut, cur, "none");
     const next = mapped.at(i + 1);
     if (next && next.tIn - tOut <= style.chainGap) {
       const mNext = transitionMult(next.z.transition);
-      const nextValue = [clampZoomLevel(next.z.level), next.z.cx, next.z.cy];
+      const nextValue = [clampZoomLevel(next.z.level), next.z.cx, next.z.cy, 1];
       push2(
         Math.min(
           tOut + style.pan * mNext,
@@ -4691,7 +4806,7 @@ function zoomTrackFromDoc(zoom, segments, style = ZOOM_STYLES[DEFAULT_ZOOM_STYLE
     } else {
       push2(
         tOut + style.rampOut * m,
-        [1, cur[1], cur[2]],
+        [1, cur[1], cur[2], 0],
         spanEase(z.ease, style.ease)
       );
       chained = false;
@@ -5873,11 +5988,15 @@ var ON_FRAME = `(ctx, content, dt) => {
   // current zoom \u2014 a standard keyframe track in OUTPUT time (hold + arrival pairs
   // expanded by the lowering), sampled with the shared deterministic interpolator.
   // Sampled here, before the rect math, so a cover crop can follow it.
-  var lvl = 1, zx = 0.5, zy = 0.5
+  var lvl = 1, zx = 0.5, zy = 0.5, zc = -1
   var zt = d.zoomTrack
   if (zt && zt.keyframes && zt.keyframes.length) {
     var z = TL.sample(zt, tpT, TL.lerpArray)
     lvl = z[0]; zx = z[1]; zy = z[2]
+    // The stage camera's centring rides the track (0 rest, 1 apex, eased
+    // with the level); a three-component track (a document lowered before
+    // the component existed) falls back to the level band below.
+    if (z.length > 3) zc = z[3]
   }
   var barH = bar.kind && bar.kind !== 'none' ? (bar.height || 44) * s2 : 0
   var availW = Math.max(1, W - ipL - ipR), availH = Math.max(1, H - ipT - ipB - barH)
@@ -5940,8 +6059,11 @@ var ON_FRAME = `(ctx, content, dt) => {
   var wcx = fx, wcy = fy
   if (lvl > 1.001 && !d.zoomSuppressed) {
     if (camStage) {
-      var ctu = Math.max(0, Math.min(1, (lvl - 1) / ${CAMERA_CENTRE_RAMP}))
-      var ctt = ctu * ctu * (3 - 2 * ctu)
+      var ctt = zc
+      if (ctt < 0) {
+        var ctu = Math.max(0, Math.min(1, (lvl - 1) / ${CAMERA_CENTRE_RAMP}))
+        ctt = ctu * ctu * (3 - 2 * ctu)
+      }
       wcx = fx + ((W / 2 - fx) / lvl) * (1 - ctt)
       wcy = fy + ((H / 2 - fy) / lvl) * (1 - ctt)
       c.translate(W / 2, H / 2); c.scale(lvl, lvl); c.translate(-wcx, -wcy)
@@ -9995,6 +10117,8 @@ export {
   DIGEST_VERSION,
   DOC_SCHEMA_VERSION,
   DRAG_FIT_LEVEL,
+  DRAG_MIN_S,
+  DRAG_MIN_TRAVEL_FRAC,
   END_CARD_FROM,
   END_CARD_RECEDE,
   END_CARD_SECONDS,
@@ -10145,6 +10269,7 @@ export {
   docToCropSpace,
   docToFullSpace,
   docTransitions,
+  dragsFromTrack,
   dropTemplate,
   duckCurve,
   effectiveSegments,