@vosjs/studio-core 0.21.0 → 0.22.0

package/dist/index.d.ts

@@ -656,7 +656,15 @@ interface CursorStyle {
     smoothing: number;
     /** rendered cursor size in px. */
     size: number;
-    style: 'default' | 'dot' | 'ring';
+    /**
+     * What the pointer is drawn as. `'arrow'` is an OS-style pointer (a
+     * black arrow with a white edge, its tip on the recorded point), the
+     * default for new takes: it is the pointer the viewer's own screen wears,
+     * so the frame reads as a screen and not as a screen recorder's overlay.
+     * `'default'`, `'dot'` and `'ring'` all draw the white dot every earlier
+     * take was cut with. Click effects bloom under the tip either way.
+     */
+    style: 'default' | 'dot' | 'ring' | 'arrow';
     hideWhenIdle: boolean;
     clickFx: ClickFxStyle;
 }
@@ -957,6 +965,20 @@ interface FrameStyle {
         cx: number;
         cy: number;
     };
+    /**
+     * The zoom camera's model. `'card'` (absent; every existing document) is
+     * the magnifier: the card scales about the focus point, which stays where
+     * it is on screen, and the lowering clamps the focus so the zoomed card
+     * always covers the canvas, which means a target near a card edge can
+     * never sit near the frame's centre. `'stage'` is a camera: the card
+     * scales AND slides so the focus lands at the frame's centre (blended in
+     * over the first CAMERA_CENTRE_RAMP of level, so level 1 is the identity),
+     * the focus is never clamped, and past the card's edge the frame shows
+     * the ground, radius and shadow, the way a filmed card reads. New takes
+     * open on `'stage'` (BASE_FRAME_STYLE); the layout helpers, the digest's
+     * framing window and the studio's aiming rect all read this field.
+     */
+    camera?: 'card' | 'stage';
     aspectRatio: string;
     browserBar: BrowserBarStyle;
     /**
@@ -2299,9 +2321,78 @@ interface FocusBounds {
  * the bounds cross — collapse to their midpoint (the least-uncovered focus;
  * 0.5 for a centered card, matching OpenScreen's margin collapse).
  */
-declare function focusBounds(level: number, layout: CardLayout): FocusBounds;
+declare function focusBounds(level: number, layout: CardLayout, camera?: CameraModel): FocusBounds;
 /** Clamp a focus point into the bounds for its zoom level. */
-declare function clampFocus(cx: number, cy: number, level: number, layout: CardLayout): {
+declare function clampFocus(cx: number, cy: number, level: number, layout: CardLayout, camera?: CameraModel): {
+    cx: number;
+    cy: number;
+};
+/**
+ * The zoom camera's model (FrameStyle.camera): the clamped magnifier every
+ * existing document was cut with, or the stage camera a new take opens on.
+ */
+type CameraModel = 'card' | 'stage';
+/** The frame's camera model; absent = the magnifier. */
+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.
+ */
+declare const CAMERA_CENTRE_RAMP = 0.3;
+/**
+ * The fraction of the frame (each axis, centred) the card must still cover
+ * at a stage-camera apex. 0.8 leaves a strip of ground a tenth of the
+ * frame wide beside a corner target, the composition a filmed card reads
+ * as; 1 would be the magnifier's rule, 0 no clamp at all.
+ */
+declare const CAMERA_COVER_MIN = 0.8;
+/** 0..1: the stage camera's centring at `level` (MIRRORS ON_FRAME). */
+declare function cameraCentring(level: number): number;
+/**
+ * The zoom transform at one instant, in canvas px: content point p maps to
+ * `(ox + (p.x − wcx)·level, oy + (p.y − wcy)·level)`. `fx/fy` is the focus
+ * in canvas px; `wcx/wcy` is the content point that lands at the frame's
+ * centre `ox/oy`. Under the magnifier `wc = f + (o − f) / L`, which is the
+ * old "scale about the focus" transform written the long way (the focus
+ * stays where it is on screen); under the stage camera that pull toward
+ * the focus fades out with cameraCentring, so `wc → f` and the target sits
+ * at the centre. ON_FRAME's zoom block mirrors this — change them together
+ * (layout.test.ts pins the pair).
+ */
+interface ZoomView {
+    level: number;
+    fx: number;
+    fy: number;
+    wcx: number;
+    wcy: number;
+    ox: number;
+    oy: number;
+}
+declare function zoomView(level: number, cx: number, cy: number, layout: CardLayout, camera?: CameraModel): 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
+ * framing lint tests a click rect against. The window may leave the card
+ * 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): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * The inverse of zoomViewport's centre: the focus (normalized video coords)
+ * that puts the visible window's centre at canvas fractions `cX/cY` at
+ * `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): {
     cx: number;
     cy: number;
 };
@@ -2320,12 +2411,16 @@ interface ZoomWindow {
     y0: number;
     y1: number;
 }
-/** The visible window in normalized video coords at `level` around the focus. */
+/**
+ * The visible window in normalized video coords at `level` around the
+ * focus, under the frame's camera model (absent = the magnifier, whose
+ * focus is clamped first exactly as the lowering clamps it).
+ */
 declare function zoomWindow(span: {
     level: number;
     cx: number;
     cy: number;
-}, layout: CardLayout): ZoomWindow;
+}, layout: CardLayout, camera?: CameraModel): ZoomWindow;
 /**
  * True when the rect (normalized) sits inside the zoom's visible window, with
  * `tol` of slack per edge (frame fractions). A level ≤ 1 zoom shows the whole
@@ -2335,7 +2430,7 @@ declare function zoomCoversRect(span: {
     level: number;
     cx: number;
     cy: number;
-}, rect: NormRect, layout: CardLayout, tol?: number): boolean;
+}, rect: NormRect, layout: CardLayout, tol?: number, camera?: CameraModel): boolean;
 
 declare const STYLE_FIELDS: readonly ["zoomStyle", "zoomParams", "speedParams", "tiltStyle", "frame", "cursor", "cam", "export"];
 type StyleField = (typeof STYLE_FIELDS)[number];
@@ -2734,6 +2829,8 @@ interface FollowOptions {
     recenter?: number;
     /** target the cursor this many seconds ahead of the exit moment. */
     lookahead?: number;
+    /** the frame's camera model: the stage camera never clamps a focus. */
+    camera?: CameraModel;
 }
 interface FollowEvent {
     /** SOURCE seconds — the moment the recenter starts. */
@@ -4354,4 +4451,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_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 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 ZoomWindow, anchorKindOf, anchorSourceDuration, animStep, applyLook, applyTemplate, aspectRatioValue, audioLane, backdropMedia, buildDigest, camBubbleRect, camBubbleRectAt, camLane, camMoveLane, camRectFromPose, camRestPose, camTrackFromDoc, 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, 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, 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, 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 };

package/dist/index.js

@@ -132,6 +132,9 @@ var DEFAULT_CURSOR_STYLE = {
   visible: true,
   smoothing: 0.15,
   size: 24,
+  // The dot every earlier take was cut with; a NEW take opens on the
+  // arrow (projectFromArtifact sets it), so a document that stores
+  // 'default' keeps its dot.
   style: "default",
   hideWhenIdle: true,
   clickFx: DEFAULT_CLICK_FX
@@ -157,6 +160,10 @@ var BASE_FRAME_STYLE = {
   radius: 12,
   shadow: 0.4,
   border: 0,
+  // The stage camera: a new take's zoom centres its target and shows the
+  // ground past the card's edge. A document without the field keeps the
+  // clamped magnifier it was cut with (see FrameStyle.camera).
+  camera: "stage",
   // 'native' = the recording's own aspect ratio (meta.width/height). See ASPECT_RATIOS.
   aspectRatio: "native",
   browserBar: DEFAULT_BROWSER_BAR
@@ -431,7 +438,9 @@ function projectFromArtifact(artifact, videoUrl, opts = {}) {
     zoom: [],
     // planner runs once the doc is loaded (editor) or planned (CLI)
     audio: [],
-    cursor: { ...DEFAULT_CURSOR_STYLE },
+    // A new take wears the OS pointer; DEFAULT_CURSOR_STYLE keeps the dot
+    // so a document that stores it renders as it was cut.
+    cursor: { ...DEFAULT_CURSOR_STYLE, style: "arrow" },
     cam: { ...DEFAULT_CAM_STYLE },
     frame: {
       ...baseFrame,
@@ -445,7 +454,9 @@ function projectFromArtifact(artifact, videoUrl, opts = {}) {
         url: pageDisplayUrl(artifact.meta.pageUrl)
       }
     },
-    export: { resolution: "1080p", fps: 30, format: "mp4" }
+    // 60 fps: the footage duplicates frames, the camera does not, and a
+    // 0.5 s glide at 30 fps is fifteen visible steps.
+    export: { resolution: "1080p", fps: 60, format: "mp4" }
   };
   return { doc, videoUrl };
 }
@@ -1132,6 +1143,12 @@ function clamp(v, lo, hi) {
 // src/zoomStyle.ts
 var ZOOM_STYLES = {
   // Cursorful strategy — one steady zoom per activity session, travel by pans.
+  // The camera's timing was measured against a Cursorful take of the same
+  // steps: a zoom-in of ~0.55 s on a heavy ease-out (most of the move in
+  // the first quarter second, a long settle), a zoom-out of ~0.45 s, and
+  // holds of four to five seconds per beat. The old 1.1 s ramp started
+  // 0.75 s BEFORE the click and landed 0.35 s after it, so the frame was
+  // moving more of the time than it was resting.
   glide: {
     autoZoom: true,
     clusterGap: 3,
@@ -1139,22 +1156,22 @@ var ZOOM_STYLES = {
     targetFill: 0.42,
     minLevel: 1.3,
     maxLevel: 1.8,
-    lead: 0.5,
-    hold: 0.6,
+    lead: 0.35,
+    hold: 1.2,
     followByDefault: true,
     typingZoom: true,
     typingGap: 2.5,
     typingHold: 1.1,
     typingMinLevel: 1.4,
-    rampIn: 1.1,
-    rampInOverlap: 0.35,
-    rampOut: 1,
-    chainGap: 2.5,
-    pan: 1,
-    ease: "css-bezier(0.26, 0, 0.16, 1)",
-    panEase: "css-bezier(0.3, 0, 0.2, 1)",
+    rampIn: 0.55,
+    rampInOverlap: 0.2,
+    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)",
     followSafeRatio: 0.45,
-    followRecenter: 0.8,
+    followRecenter: 0.55,
     followLookahead: 0.4,
     tilt: { intensity: "off" }
   },
@@ -1865,10 +1882,29 @@ function camBubbleRect(cam, W, H = 1080) {
     radius: cam.shape === "rounded" ? (cam.radius ?? 18) * s : size / 2
   };
 }
-function focusBounds(level, layout) {
+function focusBounds(level, layout, camera = "card") {
   if (level <= 1.001) {
     return { minX: 0.5, maxX: 0.5, minY: 0.5, maxY: 0.5 };
   }
+  if (camera === "stage") {
+    const x2 = stageAxisBounds(
+      layout.dx,
+      layout.dw,
+      layout.cardX,
+      layout.cardW,
+      layout.W,
+      level
+    );
+    const y2 = stageAxisBounds(
+      layout.dy,
+      layout.dh,
+      layout.cardY,
+      layout.cardH,
+      layout.H,
+      level
+    );
+    return { minX: x2.min, maxX: x2.max, minY: y2.min, maxY: y2.max };
+  }
   const x = axisBounds(
     layout.dx,
     layout.dw,
@@ -1898,8 +1934,19 @@ function axisBounds(anchorOff, anchorSize, coverOff, coverSize, viewport, level)
   }
   return { min: clamp013(lo), max: clamp013(hi) };
 }
-function clampFocus(cx, cy, level, layout) {
-  const b = focusBounds(level, layout);
+function stageAxisBounds(anchorOff, anchorSize, coverOff, coverSize, viewport, level) {
+  const b = CAMERA_COVER_MIN / 2 * viewport;
+  let lo = (coverOff + b / level - anchorOff) / anchorSize;
+  let hi = (coverOff + coverSize - b / level - anchorOff) / anchorSize;
+  if (lo > hi) {
+    const mid = (lo + hi) / 2;
+    lo = mid;
+    hi = mid;
+  }
+  return { min: clamp013(lo), max: clamp013(hi) };
+}
+function clampFocus(cx, cy, level, layout, camera = "card") {
+  const b = focusBounds(level, layout, camera);
   return {
     cx: Math.min(b.maxX, Math.max(b.minX, cx)),
     cy: Math.min(b.maxY, Math.max(b.minY, cy))
@@ -1908,6 +1955,45 @@ function clampFocus(cx, cy, level, layout) {
 function clamp013(v) {
   return Math.max(0, Math.min(1, v));
 }
+function cameraModel(frame) {
+  return frame?.camera === "stage" ? "stage" : "card";
+}
+var CAMERA_CENTRE_RAMP = 0.3;
+var CAMERA_COVER_MIN = 0.8;
+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") {
+  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 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);
+  const size = 1 / v.level;
+  return {
+    x: (v.wcx - layout.W / (2 * v.level)) / layout.W,
+    y: (v.wcy - layout.H / (2 * v.level)) / layout.H,
+    w: size,
+    h: size
+  };
+}
+function focusForViewportCentre(cX, cY, level, layout, camera = "card") {
+  const L = Math.max(1, level);
+  const t = camera === "stage" ? cameraCentring(L) : 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;
+  const fy = (cY * layout.H - layout.H / 2 * (1 - t) / L) / a;
+  return { cx: (fx - layout.dx) / layout.dw, cy: (fy - layout.dy) / layout.dh };
+}
 function levelForFocusFraction(frac) {
   if (!(frac > 0)) return clampZoomLevel(Number.POSITIVE_INFINITY);
   return clampZoomLevel(Math.max(1.1, 1 / frac));
@@ -2812,6 +2898,7 @@ function followFocusEvents(span, cursor, space, layout, options = {}) {
   const safeRatio = options.safeRatio ?? FOLLOW_SAFE_RATIO;
   const recenter = options.recenter ?? FOLLOW_RECENTER;
   const lookahead = options.lookahead ?? 0;
+  const camera = options.camera ?? "card";
   const level = clampZoomLevel(span.level);
   if (!cursor.length || !space.w || !space.h || level <= 1.001) {
     return { entry: null, events: [] };
@@ -2822,12 +2909,7 @@ function followFocusEvents(span, cursor, space, layout, options = {}) {
     ny: clamp014(e.y / space.h)
   }));
   if (!pts.length) return { entry: null, events: [] };
-  let entryPt = pts[0];
-  for (const p of pts) {
-    if (p.t > span.in) break;
-    entryPt = p;
-  }
-  const entry = clampFocus(entryPt.nx, entryPt.ny, level, layout);
+  const entry = clampFocus(span.cx, span.cy, level, layout, camera);
   const thrX = safeRatio * layout.W / (2 * level * layout.dw);
   const thrY = safeRatio * layout.H / (2 * level * layout.dh);
   const events = [];
@@ -2840,7 +2922,7 @@ function followFocusEvents(span, cursor, space, layout, options = {}) {
     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;
-      const f = clampFocus(target.nx, target.ny, level, layout);
+      const f = clampFocus(target.nx, target.ny, level, layout, camera);
       if (Math.abs(f.cx - cx) < 1e-3 && Math.abs(f.cy - cy) < 1e-3) continue;
       events.push({ t: round2(p.t), cx: round2(f.cx), cy: round2(f.cy) });
       cx = f.cx;
@@ -5844,9 +5926,28 @@ var ON_FRAME = `(ctx, content, dt) => {
   // ceZs = the zoom transform's device scale, for the two values below that
   // are sized in DEVICE pixels inside a scaled user space.
   var ceZs = 1
+  // The camera model (cfr.camera; MIRRORS layout.ts zoomView \u2014 change them
+  // together). The magnifier scales the card about the focus, which stays
+  // where it is on screen; the stage camera also slides the card so the
+  // focus lands at the frame's centre, blended in over CAMERA_CENTRE_RAMP
+  // of level (a smoothstep, 0 at level 1) so a ramp through the band slides
+  // without a kink, and past the card's edge the ground shows. wcx/wcy is
+  // the content point at the frame's centre under either model; the two
+  // branches are the same map, the magnifier's kept in its old float order
+  // so every existing document renders byte-identically.
+  var camStage = cfr.camera === 'stage'
+  var fx = dx + zx * dw, fy = dy + zy * dh
+  var wcx = fx, wcy = fy
   if (lvl > 1.001 && !d.zoomSuppressed) {
-    var fx = dx + zx * dw, fy = dy + zy * dh
-    c.translate(fx, fy); c.scale(lvl, lvl); c.translate(-fx, -fy)
+    if (camStage) {
+      var ctu = Math.max(0, Math.min(1, (lvl - 1) / ${CAMERA_CENTRE_RAMP}))
+      var 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)
+    } else {
+      c.translate(fx, fy); c.scale(lvl, lvl); c.translate(-fx, -fy)
+    }
     ceZs = lvl
   }
   // The card's shadows are cast by a body drawn OFF-CANVAS and brought back
@@ -5988,6 +6089,34 @@ var ON_FRAME = `(ctx, content, dt) => {
   // cursor coordinate space + drawn radius (shared by click effects + the dot)
   var space = (actM ? actM.cursorSpace : d.cursorSpace) || { w: vw, h: vh }
   var curSize = ((d.cursorStyle && d.cursorStyle.size) || 24) * s2 * 0.5
+  // The pointer's shape: an OS-style arrow (tip on the recorded point, a
+  // black body with a white edge, the shape of the pointer on the viewer's
+  // own screen) or the white dot every earlier take was cut with. One
+  // painter for both draw sites (in the card, and the ghost across a
+  // boundary); r is the dot's radius, so an arrow stands 2r tall.
+  var curArrow = !!(d.cursorStyle && d.cursorStyle.style === 'arrow')
+  function drawCur(cc, x, y, r, a, lw) {
+    cc.save()
+    if (curArrow) {
+      var h = 2 * r
+      var P = [[0, 0], [0, 0.72], [0.19, 0.55], [0.31, 0.83], [0.43, 0.78], [0.31, 0.5], [0.55, 0.5]]
+      cc.beginPath()
+      cc.moveTo(x, y)
+      for (var pi = 1; pi < P.length; pi++) cc.lineTo(x + P[pi][0] * h, y + P[pi][1] * h)
+      cc.closePath()
+      cc.lineJoin = 'round'
+      cc.fillStyle = 'rgba(0,0,0,' + (0.92 * a) + ')'
+      cc.strokeStyle = 'rgba(255,255,255,' + (0.95 * a) + ')'
+      cc.lineWidth = Math.max(1, lw * 0.75)
+      cc.fill(); cc.stroke()
+    } else {
+      cc.fillStyle = 'rgba(255,255,255,' + (0.95 * a) + ')'
+      cc.strokeStyle = 'rgba(0,0,0,' + (0.4 * a) + ')'
+      cc.lineWidth = lw
+      cc.beginPath(); cc.arc(x, y, r, 0, Math.PI * 2); cc.fill(); cc.stroke()
+    }
+    cc.restore()
+  }
 
   // click effects \u2014 pure f(t): d.clicks are
   // OUTPUT-anchored records baked at lowering (sorted by ot; re-baked on every
@@ -6161,16 +6290,14 @@ var ON_FRAME = `(ctx, content, dt) => {
     // moving: each pass leaves its point, mapped out of the zoom.
     if (trOut) {
       var tqX = ax, tqY = ay
-      if (lvl > 1.001 && !d.zoomSuppressed) { tqX = fx + (ax - fx) * lvl; tqY = fy + (ay - fy) * lvl }
+      if (lvl > 1.001 && !d.zoomSuppressed) {
+        if (camStage) { tqX = W / 2 + (ax - wcx) * lvl; tqY = H / 2 + (ay - wcy) * lvl }
+        else { tqX = fx + (ax - fx) * lvl; tqY = fy + (ay - fy) * lvl }
+      }
       if (tpG) trQa = [tqX, tqY]
       else { trQb = [tqX, tqY]; trQs = curSize * ckPress; trQw = s2 }
     } else if (cuA > 0.01) {
-      c.save()
-      c.fillStyle = 'rgba(255,255,255,' + (0.95 * cuA) + ')'
-      c.strokeStyle = 'rgba(0,0,0,' + (0.4 * cuA) + ')'
-      c.lineWidth = 2 * s2
-      c.beginPath(); c.arc(ax, ay, curSize * ckPress, 0, Math.PI * 2); c.fill(); c.stroke()
-      c.restore()
+      drawCur(c, ax, ay, curSize * ckPress, cuA, 2 * s2)
     }
   }
   if (fitCover) c.restore()
@@ -6255,12 +6382,7 @@ var ON_FRAME = `(ctx, content, dt) => {
     var tqBx = (tqB[0] - W / 2) * trSc + W / 2 + trOx * W, tqBy = (tqB[1] - H / 2) * trSc + H / 2 - trOy * H
     var tqX2 = tqAx + (tqBx - tqAx) * tqP, tqY2 = tqAy + (tqBy - tqAy) * tqP
     var tqR = trQs || (((d.cursorStyle && d.cursorStyle.size) || 24) * s * 0.5)
-    ovC.save()
-    ovC.fillStyle = 'rgba(255,255,255,0.95)'
-    ovC.strokeStyle = 'rgba(0,0,0,0.4)'
-    ovC.lineWidth = 2 * (trQw || s)
-    ovC.beginPath(); ovC.arc(tqX2, tqY2, tqR, 0, Math.PI * 2); ovC.fill(); ovC.stroke()
-    ovC.restore()
+    drawCur(ovC, tqX2, tqY2, tqR, 1, 2 * (trQw || s))
   }
   ov.sig = ovSig
   ov.active = camActiveNow || !!trOut
@@ -6599,6 +6721,7 @@ function lowerToComposition(input) {
   const layout = docCardLayout(doc);
   const meta = doc.source.meta;
   const zoomStyle = resolveZoomStyle(doc.zoomStyle, doc.zoomParams);
+  const camera = cameraModel(doc.frame);
   const zoomSpans = restSpansThroughTransitions(
     doc.zoom,
     rated,
@@ -6614,13 +6737,17 @@ function lowerToComposition(input) {
         {
           safeRatio: zoomStyle.followSafeRatio,
           recenter: zoomStyle.followRecenter,
-          lookahead: zoomStyle.followLookahead
+          lookahead: zoomStyle.followLookahead,
+          camera
         }
       );
       if (f.entry)
         return { ...z, cx: f.entry.cx, cy: f.entry.cy, followEvents: f.events };
     }
-    return { ...z, ...clampFocus(z.cx, z.cy, clampZoomLevel(z.level), layout) };
+    return {
+      ...z,
+      ...clampFocus(z.cx, z.cy, clampZoomLevel(z.level), layout, camera)
+    };
   });
   const data = {
     videoSrc: doc.source.videoKey,
@@ -7176,15 +7303,14 @@ function sceneChanges(bins, opts = {}) {
 }
 
 // src/digest/framing.ts
-function zoomWindow(span, layout) {
+function zoomWindow(span, layout, camera = "card") {
   const L = Math.max(1, span.level);
-  const { cx, cy } = clampFocus(span.cx, span.cy, L, layout);
-  const fx = layout.dx + cx * layout.dw;
-  const fy = layout.dy + cy * layout.dh;
-  const px0 = fx - fx / L;
-  const px1 = fx + (layout.W - fx) / L;
-  const py0 = fy - fy / L;
-  const py1 = fy + (layout.H - fy) / L;
+  const { cx, cy } = clampFocus(span.cx, span.cy, L, layout, camera);
+  const v = zoomViewport(L, cx, cy, layout, camera);
+  const px0 = v.x * layout.W;
+  const px1 = (v.x + v.w) * layout.W;
+  const py0 = v.y * layout.H;
+  const py1 = (v.y + v.h) * layout.H;
   return {
     x0: (px0 - layout.dx) / layout.dw,
     x1: (px1 - layout.dx) / layout.dw,
@@ -7192,9 +7318,9 @@ function zoomWindow(span, layout) {
     y1: (py1 - layout.dy) / layout.dh
   };
 }
-function zoomCoversRect(span, rect, layout, tol = 0.02) {
+function zoomCoversRect(span, rect, layout, tol = 0.02, camera = "card") {
   if (span.level <= 1.001) return true;
-  const w = zoomWindow(span, layout);
+  const w = zoomWindow(span, layout, camera);
   return rect.x >= w.x0 - tol && rect.x + rect.w <= w.x1 + tol && rect.y >= w.y0 - tol && rect.y + rect.h <= w.y1 + tol;
 }
 
@@ -9812,6 +9938,8 @@ export {
   AUDIO_PLAN_STEP,
   BACKGROUND_Z,
   BASE_FRAME_STYLE,
+  CAMERA_CENTRE_RAMP,
+  CAMERA_COVER_MIN,
   CAMERA_FAR,
   CAMERA_NEAR,
   CAM_CHAIN_GAP,
@@ -9978,6 +10106,8 @@ export {
   camRectFromPose,
   camRestPose,
   camTrackFromDoc,
+  cameraCentring,
+  cameraModel,
   cardEnter,
   cardExit,
   cardFields,
@@ -10032,6 +10162,7 @@ export {
   exportSizeFor,
   extractClicks,
   focusBounds,
+  focusForViewportCentre,
   followFocusEvents,
   frameGeometry,
   freezeLane,
@@ -10159,6 +10290,8 @@ export {
   zoomLane,
   zoomSpanForRange,
   zoomTrackFromDoc,
+  zoomView,
+  zoomViewport,
   zoomWindow
 };
 //# sourceMappingURL=index.js.map