@vosjs/studio-core 0.45.2 → 0.47.0

package/README.md

@@ -35,7 +35,7 @@ The shared layers lower as one engine `stack` entry, `STUDIO_ENTRY_ID` (`'vosso.
 
 ## Time and space conventions
 
-- **Seconds everywhere.** Zoom, speed, tilt and cam-motion spans and the cursor samples are anchored in source time, so they follow footage through trims. Overlays, audio clips and click effects are anchored in output time, so a title keeps its perceived length through a speed change. An overlay may instead name a recorder step as its time (`anchor: { step, media?, at?, offset? }`): the lowering starts it where that step plays in the cut (`resolveOverlayAnchors`, `resolveAnchor`, `sourceMomentToOutput`), its `start` the fallback, and fills a text layer's `{elapsed}` from the step's recorded off-camera wait (`formatElapsed`). `ratedSegments`, `effectiveSegments`, `docOutputDuration` and `outputRangeToSource` are the remaps.
+- **Seconds everywhere.** Zoom, speed, tilt and cam-motion spans and the cursor samples are anchored in source time, so they follow footage through trims. Overlays, audio clips, click effects and the ranges in which the drawn cursor is off (`cursor.off: [{ in, out? }]`, an absent `out` running to the end of the film; `cursorOffAlpha` is the rule) are anchored in output time, so a title keeps its perceived length through a speed change. An overlay may instead name a recorder step as its time (`anchor: { step, media?, at?, offset? }`): the lowering starts it where that step plays in the cut (`resolveOverlayAnchors`, `resolveAnchor`, `sourceMomentToOutput`), its `start` the fallback, and fills a text layer's `{elapsed}` from the step's recorded off-camera wait (`formatElapsed`). `ratedSegments`, `effectiveSegments`, `docOutputDuration` and `outputRangeToSource` are the remaps.
 - **Normalized coordinates.** A zoom's `cx`/`cy` and an overlay's `transform.x`/`y` are fractions of the frame in `[0, 1]`, never pixels, so a document survives an aspect-ratio switch. `focusBounds` and `clampFocus` keep a focus inside the card at a given `level`.
 - **Camera styles.** `ZOOM_STYLES` names six camera personalities (`glide`, the default, then `focus`, `cinema`, `snappy`, `cut`, `none`); a style parametrizes the planner, the camera motion and the tilt track's tempo, and `doc.zoomParams` layers per-document overrides. `keynote` and `drift` are retired names (`RETIRED_ZOOM_STYLES`) that resolve to `glide` + medium tilt and `cinema` + subtle tilt, and `migrateHostedDoc` rewrites them on read. Every style's chain gap sits above its pump-free floor (`pumpFreeChainGap`), and the lowering fits a ramp longer than its span to the room it has, never below `RAMP_FLOOR`.
 - **The stage.** `CARD_FOV`, `CARD_Z`, `OVERLAY_Z`, `BACKGROUND_Z` and `planeSizeAtDepth` define the frustum-filling planes the program draws (background, the tiltable card, the overlay); `cardVisibleExtent` and `cardOverscanFor` are how far a posed card is seen past the frame, which is what the card layer's canvas and plane grow by (so a lean over zoomed footage never shows the texture's edge); `computeCardLayout` and `docCardLayout` are the host-side mirror of the program's card math, pinned to it by tests.
@@ -51,20 +51,20 @@ The shared layers lower as one engine `stack` entry, `STUDIO_ENTRY_ID` (`'vosso.
 
 ## Exports by area
 
-| Area           | Exports                                                                                                                                                                                                                                                                                    |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Ingest         | `projectFromArtifact`, `normalizeCaptureSpace`, `deriveViewportCrop`, `docToCropSpace`, `docToFullSpace`, `CAPTURE_COVERAGE_MIN`, `WINDOW_FOCUS_MIN`                                                                                                                                       |
-| Document       | `StudioDoc`, `ProjectDoc`, `ProgramAnchorDoc`, `anchorKindOf`, `isRecordingDoc`, `isProgramDoc`, `DOC_SCHEMA_VERSION`, `migrateHostedDoc`, `DEFAULT_FRAME_STYLE`, `BASE_FRAME_STYLE`, the constants (`ZOOM_LEVELS`, `TILT_DEG_MAX`, …)                                                     |
-| Planners       | `planAutoZoom`, `planAutoSpeed`, `planAutoTilt`, `smoothCursor`, `idleGaps`, `scrollRuns`, `rejectSpan`, `isRejected`, `withoutRejected`                                                                                                                                                   |
-| Camera styles  | `ZOOM_STYLES`, `ZOOM_STYLE_OPTIONS`, `DEFAULT_ZOOM_STYLE`, `resolveZoomStyle`, `RETIRED_ZOOM_STYLES`, `pumpFreeChainGap`                                                                                                                                                                   |
-| Lowering       | `lowerStudioDoc`, `lowerProgramDoc`, `lowerToComposition`, `zoomTrackFromDoc`, `tiltTrackFromDoc`, `camTrackFromDoc`, `motionTrack`, `followFocusEvents`, `extractClicks`, `cursorIdleFade`, `ratedSegments`, `resolveOverlayAnchors`, `STUDIO_ENTRY_ID`, `studioEntry`, `studioLayerData` |
-| Layout         | `computeCardLayout`, `docCardLayout`, `focusBounds`, `clampFocus`, `camBubbleRectAt`, `overlayRect`, `overlayHit`, `CARD_FOV`, `CARD_Z`, `planeSizeAtDepth`, `recommendedExportResolution`                                                                                                 |
-| Text           | `TEXT_PRESETS`, `OVERLAY_FONT_FACES`, `resolveOverlayStyle`, `resolveOverlayBox`, `resolveText3dAsset`                                                                                                                                                                                     |
-| Audio          | `studioAudioPlan`, `clipEnvelope`, `duckCurve`, `computePeaks`, `computeMicRms`, `voiceKey`, `musicBedClip`, `refillAudioBeds`                                                                                                                                                             |
-| Backdrops      | `withBackdrop`, `backdropMedia`                                                                                                                                                                                                                                                            |
-| Digest         | `momentsFromDoc`, `planForDigest`, `buildDigest`, `sceneChanges`, `zoomCoversRect`, `zoomWindow`, `cropBox`, `frameGeometry`, `STYLE_FIELDS`, `copyStyle`, `pickStyle`, `DIGEST_VERSION`                                                                                                   |
-| Destinations   | `DESTINATIONS`, `destinationById`, `destinationsForChannel`, `exportSizeFor`, `resolveExportSize`, `ASPECT_RATIOS`                                                                                                                                                                         |
-| Timeline lanes | `videoLane`, `micLane`, `camLane`, `zoomLane`, `tiltLane`, `camMoveLane`, `speedLane`, `overlaysLane`, `objectsLane`, `audioLane`; range actions `outputRangeToSource`, `removeSourceRange`, `setSpeedInRange`, `zoomSpanForRange`                                                         |
+| Area           | Exports                                                                                                                                                                                                                                                                                                      |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Ingest         | `projectFromArtifact`, `normalizeCaptureSpace`, `deriveViewportCrop`, `docToCropSpace`, `docToFullSpace`, `CAPTURE_COVERAGE_MIN`, `WINDOW_FOCUS_MIN`                                                                                                                                                         |
+| Document       | `StudioDoc`, `ProjectDoc`, `ProgramAnchorDoc`, `anchorKindOf`, `isRecordingDoc`, `isProgramDoc`, `DOC_SCHEMA_VERSION`, `migrateHostedDoc`, `DEFAULT_FRAME_STYLE`, `BASE_FRAME_STYLE`, the constants (`ZOOM_LEVELS`, `TILT_DEG_MAX`, …)                                                                       |
+| Planners       | `planAutoZoom`, `planAutoSpeed`, `planAutoTilt`, `smoothCursor`, `idleGaps`, `scrollRuns`, `rejectSpan`, `isRejected`, `withoutRejected`                                                                                                                                                                     |
+| Camera styles  | `ZOOM_STYLES`, `ZOOM_STYLE_OPTIONS`, `DEFAULT_ZOOM_STYLE`, `resolveZoomStyle`, `RETIRED_ZOOM_STYLES`, `pumpFreeChainGap`                                                                                                                                                                                     |
+| Lowering       | `lowerStudioDoc`, `lowerProgramDoc`, `lowerToComposition`, `zoomTrackFromDoc`, `tiltTrackFromDoc`, `camTrackFromDoc`, `motionTrack`, `followFocusEvents`, `extractClicks`, `cursorIdleFade`, `cursorOffAlpha`, `ratedSegments`, `resolveOverlayAnchors`, `STUDIO_ENTRY_ID`, `studioEntry`, `studioLayerData` |
+| Layout         | `computeCardLayout`, `docCardLayout`, `focusBounds`, `clampFocus`, `camBubbleRectAt`, `overlayRect`, `overlayHit`, `CARD_FOV`, `CARD_Z`, `planeSizeAtDepth`, `recommendedExportResolution`                                                                                                                   |
+| Text           | `TEXT_PRESETS`, `OVERLAY_FONT_FACES`, `resolveOverlayStyle`, `resolveOverlayBox`, `resolveText3dAsset`                                                                                                                                                                                                       |
+| Audio          | `studioAudioPlan`, `clipEnvelope`, `duckCurve`, `computePeaks`, `computeMicRms`, `voiceKey`, `musicBedClip`, `refillAudioBeds`                                                                                                                                                                               |
+| Backdrops      | `withBackdrop`, `backdropMedia`                                                                                                                                                                                                                                                                              |
+| Digest         | `momentsFromDoc`, `planForDigest`, `buildDigest`, `sceneChanges`, `zoomCoversRect`, `zoomWindow`, `cropBox`, `frameGeometry`, `STYLE_FIELDS`, `copyStyle`, `pickStyle`, `DIGEST_VERSION`                                                                                                                     |
+| Destinations   | `DESTINATIONS`, `destinationById`, `destinationsForChannel`, `exportSizeFor`, `resolveExportSize`, `ASPECT_RATIOS`                                                                                                                                                                                           |
+| Timeline lanes | `videoLane`, `micLane`, `camLane`, `zoomLane`, `tiltLane`, `camMoveLane`, `speedLane`, `overlaysLane`, `objectsLane`, `audioLane`; range actions `outputRangeToSource`, `removeSourceRange`, `setSpeedInRange`, `zoomSpanForRange`                                                                           |
 
 The full document shape is in [`src/types.ts`](src/types.ts); the JSON Schema that ships to users is [`doc.schema.json`](../cli/schema/doc.schema.json) in `@vosjs/cli`.
 

package/dist/index.d.ts

@@ -4,6 +4,8 @@ import { Segment, KeyframeTrack } from '@vosjs/timeline';
 export { Segment } from '@vosjs/timeline';
 import { TimelineEdit } from '@vosjs/shared/timelineEdits';
 import { LaneAdapter } from '@vosjs/editor';
+import { FilmSummary } from '@vosjs/shared/music';
+export { FilmSummary } from '@vosjs/shared/music';
 
 /**
  * Zoom/pan camera styles — named strategy
@@ -1021,6 +1023,28 @@ interface CursorStyle {
     style: 'default' | 'dot' | 'ring' | 'arrow';
     hideWhenIdle: boolean;
     clickFx: ClickFxStyle;
+    /**
+     * Time ranges in which the drawn cursor is off, in OUTPUT seconds (the
+     * timeline the viewer sees, like overlays: a hide stays where it was put
+     * through trims and speed changes). The track still drives cursor-follow
+     * zoom and click effects, as with `visible: false`. The dot fades out over
+     * a short beat before `in` and back in after `out`, so the range itself is
+     * fully hidden. Overlapping ranges read as their union. Absent = the cursor
+     * is never hidden by time.
+     */
+    off?: CursorOff[];
+}
+/**
+ * One range in which the drawn cursor is hidden (`CursorStyle.off`), in
+ * OUTPUT seconds. An absent `out` hides it to the end of the film. `from`
+ * marks a range something else placed (`'endcard'`: the end card's), which
+ * that thing replaces or removes on its next pass; a range without one is a
+ * person's and is never touched by a re-plan.
+ */
+interface CursorOff {
+    in: number;
+    out?: number;
+    from?: string;
 }
 /**
  * Click-effect styling. Clicks are extracted
@@ -3386,7 +3410,11 @@ declare function zoomCoversRect(span: {
 
 declare const STYLE_FIELDS: readonly ["zoomStyle", "zoomParams", "speedParams", "tiltStyle", "frame", "cursor", "cam", "export"];
 type StyleField = (typeof STYLE_FIELDS)[number];
-/** The style fields present on a doc, deep-cloned. */
+/**
+ * The style fields present on a doc, deep-cloned. The cursor's `off`
+ * ranges are left out: they are moments of one cut (output seconds), never
+ * a look another take can wear.
+ */
 declare function pickStyle(doc: ProjectDoc): Partial<Pick<ProjectDoc, StyleField>>;
 interface CopyStyleOptions {
     /**
@@ -3497,9 +3525,11 @@ declare function clipsFrom(doc: Pick<ProjectDoc, 'overlays' | 'objects' | 'audio
     audio: AudioClip[];
 };
 /**
- * The document without the clips a template placed. The card's `anim` is
- * the card's own once set, so it stays; a caller that wants the card still
- * clears it. Returns the same object when nothing came from `from`.
+ * The document without the clips a template placed, its freezes, and the
+ * cursor-off ranges stamped with the same `from`. The card's `anim` is the
+ * card's own once set, so it stays; a caller that wants the card still
+ * clears it. A range a person wrote (no `from`) is never touched. Returns
+ * the same object when nothing came from `from`.
  */
 declare function dropTemplate(doc: ProjectDoc, from: string): ProjectDoc;
 /**
@@ -5556,6 +5586,29 @@ interface CursorFadeKey {
  */
 declare function cursorIdleFade(track: CursorTrack, o: CursorIdleOptions): CursorFadeKey[];
 
+/**
+ * Time ranges in which the drawn cursor is off (`doc.cursor.off`), read at
+ * OUTPUT time. One rule for every place the cursor is drawn: the primary
+ * card (any media it plays), the dot carried across a transition, and a
+ * layer card's own cursor. A pure function of `t`, so a frame stays a pure
+ * function of time, and the ranges ride the document's data (a live edit).
+ *
+ * The fades sit OUTSIDE a range: the dot fades out over `CURSOR_OFF_FADE`
+ * before `in` and back in over the same after `out`, so every moment inside
+ * the range is fully hidden. A range at 0 is hidden from the first frame
+ * (nothing before it to fade over), and one with no `out` never returns.
+ */
+
+/** Seconds the dot takes to leave before a range and return after it. */
+declare const CURSOR_OFF_FADE = 0.15;
+/**
+ * The cursor's opacity factor at OUTPUT time `t`, 0..1: 1 away from every
+ * range, 0 inside one, a linear ramp over the fade beside each edge. A range
+ * whose `in` is not a finite number, or whose `out` is present and not past
+ * its `in`, hides nothing (the lint names both).
+ */
+declare function cursorOffAlpha(off: readonly CursorOff[] | null | undefined, t: number): number;
+
 /** Anticipation lead — effects start this many output seconds before the click. */
 declare const CLICK_FX_PRE = 0.06;
 /** Base effect durations in output seconds (× the intensity's `dur`). */
@@ -5970,4 +6023,41 @@ declare function rejectSpan(rejected: RejectedSpan[] | undefined, lane: Rejected
     anchor?: StepAnchor;
 }, note?: string): RejectedSpan;
 
-export { ASPECT_RATIOS, AUDIO_PLAN_STEP, type AnchorKind, type AnchorMiss, type AnchorResolution, type Anim, type AnimKind, type AnimSide, type AnimStep, type AppliedTemplate, type ApplyTemplateOptions, type AspectRatioOption, type AudioClip, type AudioLoudness, type AudioPlanPoint, type AudioPlanTrack, BACKGROUND_Z, BASE_FRAME_STYLE, type Backdrop, type BackgroundMedia, type BakeResult, type BakedText3dAsset, type BakedText3dMaterial, type BrowserBarStyle, type BuildDigestInput, CALLOUT_DEFAULT_BODY_PX, CALLOUT_SHAPES, CALLOUT_TYPE_RATIO, 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, CHANGE_FLOOR, CHANGE_GRID, CHANGE_LEAD, CHANGE_OFFSETS, CHANNEL_SPECS_HASH, CHANNEL_SPECS_VERIFIED, CLICK_FX_INTENSITY, CLICK_FX_PRE, CLICK_HIGHLIGHT_FADE, CLICK_HOLD_MS, CLICK_PAIR_MAX, CLICK_PULSE_DUR, CLICK_RECT_MAX_FRAC, CLICK_RIPPLE_DUR, CLICK_SYNTH_RELEASE, CLUSTER_FILL, 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 CalloutBox, type CalloutClipOptions, type CalloutLook, type CalloutRegister, type CalloutShape, type CalloutWords, type CamBubbleRect, type CamPoseSpan, type CamStyle, type CameraModel, type CaptureNormalization, type CardLayout, type ChangeSample, type ChangeWitness, type ChangedRegion, type ClickFxStyle, type ClipGain, type ClipGainBasis, 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_FEATURES, DOC_SCHEMA_VERSION, DRAG_FIT_LEVEL, DRAG_MIN_S, DRAG_MIN_TRAVEL_FRAC, type Destination, type Digest, type DigestImageRef, type DigestPlan, type DigestTakeFacts, type DocFeature, type DocSegment, type Drag, type DuckOptions, ELAPSED_PLACEHOLDER, 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, FOOTAGE_FRAME_STYLE, 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, HOLD_DRIFT_MAX, HOUSE_GRADIENT, HOUSE_REGISTER, 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, type LumaGrid, 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, NORMALIZE_MAX_LIFT_DB, NORMALIZE_MAX_LUFS, NORMALIZE_MIN_LUFS, NORMALIZE_PEAK_CEILING_DB, 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 OutputExtent, type OverlayAnchor, 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, PUMP_REST, type PeerStepSpan, type PeerTrack, type PinCandidate, 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, REPLAY_EPS, REST_TILT_ID, RETIRED_ZOOM_STYLES, type RecordingArtifact, type RecordingMeta, type RecordingNotice, type RecordingOutput, type RecordingPageMedia, type RecordingSkip, type Rect, type RejectedLane, type RejectedSpan, type ReplayedSpan, type ResolvedOverlayBox, type ResolvedOverlayStyle, type Rgb, 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, type StyledText, 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 TraceFileKind, type TraceOptions, type TraceResult, type TranscriptSegment, type Transition, type TransitionKind, type TransitionMove, type TransitionOut, type TransitionSpeed, type UsedFeature, 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 ZipEntry, type ZoomScreen, type ZoomSpan, type ZoomStyleName, type ZoomStyleParams, type ZoomView, type ZoomWindow, ambientDrift, anchorKindOf, anchorSourceDuration, anchoredClip, animStep, applyLook, applyTemplate, aspectRatioValue, audioLane, backdropMedia, bakeDocFeatures, boldWeightFor, buildDigest, calloutBox, calloutClip, calloutGroundOf, calloutLook, calloutSource, camBubbleRect, camBubbleRectAt, camLane, camMoveLane, camRectFromPose, camRestPose, camTrackFromDoc, cameraCentring, cameraModel, cameraRestWindows, cameraRests, cameraSpanExtents, cardEnter, cardExit, cardFields, cardInset, cardPointToScreen, cardPoseTrack, changedRegion, clampCamFrac, clampCamSize, clampFocus, clampFreezeSeconds, clampSpeedRate, clampTiltDeg, clampZoomLevel, clipEnvelope, clipGain, clipLength, clipsFrom, compareVersions, computeCardLayout, computeMicRms, computePeaks, copyLayout, copyStyle, cropBox, cssFamilies, cssWeights, cursorFromCsv, cursorFromPlaywrightTrace, cursorFromRecords, cursorFromTrace, cursorIdleFade, deltaE, deriveViewportCrop, destinationById, destinationsForChannel, docCardLayout, docFeatures, docFreezes, docMediaList, docOutputDuration, docRestTime, docStillTime, docToCropSpace, docToFullSpace, docTransitions, docZoomTrack, dragsFromTrack, dropTemplate, duckCurve, effectiveSegments, elapsedFor, endCardClips, enterKey, enterOf, entranceAt, entranceEnd, entranceSeconds, envelopeAt, envelopeValueAt, exitKey, exitOf, exitSeconds, expandEndCard, expectedFrameSize, exportSizeFor, extractClicks, featuresNewerThan, findStep, focusBounds, focusForViewportCentre, followFocusEvents, formatElapsed, frameGeometry, freezeLane, freezeOutputExtents, hasElapsed, hasReplay, hexToRgb, hexToRgbTriplet, houseLook, htmlLayerBleed, htmlLayerBleedFor, htmlLayerFaces, htmlLayerKey, htmlLayerLabel, htmlLayerPayload, htmlLayerPictureBox, htmlLayerProblems, htmlLayerSvg, htmlLayerText, htmlLayerUnhostedFamilies, htmlLayerWidth, htmlStarterClip, idleGaps, idleKey, isKeyedOverlay, isLookKind, isLoweredRecording, isMusicBed, isPlayback, isProgramDoc, isRecordingDoc, isRejected, isStageClip, isUnitStep, lastLayerEnd, layerMedia, layerStart, layoutOf, levelForFocusFraction, liveZoomStyleName, longestOutputExtent, lookFromBrand, lookKindForGround, loudnessMatches, lowerProgramDoc, lowerStudioDoc, lowerToComposition, marksEmphasis, mediaAtOutput, mediaDuration, mediaFrame, mediaKey, mediaRef, mediaRefId, mediaSource, micLane, migrateHostedDoc, migrateMotion, migrateText, migrateTextClip, migrateZoomStyle, momentOutputs, momentsFromDoc, motionTrack, musicBedClip, nextMediaId, normalizeCaptureSpace, objectMotionBase, objectMotionPoseAt, objectsLane, outputDurationOf, outputEnd, outputRangeToSource, overlapFraction, overlayFaceFor, overlayFontFaces, overlayFontString, overlayFxSpec, overlayHit, overlayLines, overlayMotionBase, overlayMotionPoseAt, overlayPinPoseAt, overlayPlainText, overlayRect, overlaysLane, ownFreezes, pageDisplayUrl, parseCssColour, parsePoseId, pickChange, pickStyle, pinBox, pinCandidates, pinPlacement, pinRectOnScreen, pinReferent, pinReferentAt, placeFreezes, planAutoSpeed, planAutoTilt, planAutoZoom, planForDigest, planeSizeAtDepth, platformBarKind, playwrightTraceEntry, programDuration, programStillTime, projectFromArtifact, pumpFreeChainGap, ratedSegments, recommendedExportResolution, refillAudioBeds, rejectSpan, relativeLuminance, removeSourceRange, removeSpeedInRange, replayFlags, replayedSeconds, resolveAnchor, resolveExportSize, resolveOverlayAnchors, resolveOverlayBox, resolveOverlayStyle, resolvePins, resolveText3dAsset, resolveZoomStyle, restLeanOf, restSpansThroughTransitions, rgbToHex, sameMedia, sceneChanges, scrollRuns, segmentOutputExtents, outputLen as segmentOutputLen, segmentStarts, setSpeedInRange, slideSide, smoothCursor, snapRunWeight, sourceMomentToOutput, spanOutputExtent, spanOutputExtents, speedLane, stepElapsedMs, stepMomentToOutput, studioAudioPlan, studioEntry, studioLayerData, styledTextOf, textRunsOf, tiltLane, tiltTrackFromDoc, traceKindOf, transitionMult, transitionSeconds, unionFitLevel, unionRect, videoLane, voiceKey, wellFormedXml, withBackdrop, withFreezes, withHolds, withoutRejected, wrapProgramLength, zipEntries, zipEntryBytes, zoomCoversRect, zoomLane, zoomSpanForRange, zoomTrackFromDoc, zoomView, zoomViewport, zoomWindow };
+/**
+ * A film as the music ranking reads it: its output length, the
+ * instants a beat should land on, the moment the music should open up,
+ * whether a voice plays. Built from the document here, where the document
+ * is known, and handed to `@vosjs/shared/music`'s `rankBeds`, which never
+ * reads one; the CLI's `vos music pick` and the studio's Sound panel read
+ * the same summary, so one rule says what a cut is.
+ *
+ * A recording's cuts are its layers' starts (a caption landed on a step,
+ * a callout), its segment boundaries (a join, a page change, a freeze) and
+ * the page changes the recorder marked; its payoff is the last step the
+ * script marks `"zoom": true`, else the last cut. A program's cuts are its
+ * scene labels (`tl.addLabel`), its payoff the last scene. Pure.
+ */
+
+interface FilmSummaryOptions {
+    /** Stable identity: the vos id, else the take directory's name. */
+    seed: string;
+    /** The payoff, output seconds, when the person said it (`--at`). */
+    payoff?: number;
+    /** Override what the document says about a voice. */
+    voice?: boolean;
+    mood?: string;
+    words?: string;
+    like?: string[];
+    fadeIn?: boolean;
+}
+/** The scene labels a program declares, output seconds, in order. */
+declare function programSceneTimes(config: Record<string, unknown>): number[];
+/**
+ * The film summary of a document. `seed` is the caller's (a vos id when
+ * the take is on vos.so, else its directory's name).
+ */
+declare function filmSummaryOf(doc: StudioDoc, opts: FilmSummaryOptions): FilmSummary;
+/** The library slugs a document's audio clips play, for a project's `like`. */
+declare function musicSlugsOfDoc(doc: Pick<StudioDoc, 'audio'>): string[];
+
+export { ASPECT_RATIOS, AUDIO_PLAN_STEP, type AnchorKind, type AnchorMiss, type AnchorResolution, type Anim, type AnimKind, type AnimSide, type AnimStep, type AppliedTemplate, type ApplyTemplateOptions, type AspectRatioOption, type AudioClip, type AudioLoudness, type AudioPlanPoint, type AudioPlanTrack, BACKGROUND_Z, BASE_FRAME_STYLE, type Backdrop, type BackgroundMedia, type BakeResult, type BakedText3dAsset, type BakedText3dMaterial, type BrowserBarStyle, type BuildDigestInput, CALLOUT_DEFAULT_BODY_PX, CALLOUT_SHAPES, CALLOUT_TYPE_RATIO, 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, CHANGE_FLOOR, CHANGE_GRID, CHANGE_LEAD, CHANGE_OFFSETS, CHANNEL_SPECS_HASH, CHANNEL_SPECS_VERIFIED, CLICK_FX_INTENSITY, CLICK_FX_PRE, CLICK_HIGHLIGHT_FADE, CLICK_HOLD_MS, CLICK_PAIR_MAX, CLICK_PULSE_DUR, CLICK_RECT_MAX_FRAC, CLICK_RIPPLE_DUR, CLICK_SYNTH_RELEASE, CLUSTER_FILL, 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, CURSOR_OFF_FADE, type CalloutBox, type CalloutClipOptions, type CalloutLook, type CalloutRegister, type CalloutShape, type CalloutWords, type CamBubbleRect, type CamPoseSpan, type CamStyle, type CameraModel, type CaptureNormalization, type CardLayout, type ChangeSample, type ChangeWitness, type ChangedRegion, type ClickFxStyle, type ClipGain, type ClipGainBasis, type CopiedLayout, type CopyLayoutOptions, type CopyStyleOptions, type CursorEvent, type CursorFadeKey, type CursorIdleOptions, type CursorOff, 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_FEATURES, DOC_SCHEMA_VERSION, DRAG_FIT_LEVEL, DRAG_MIN_S, DRAG_MIN_TRAVEL_FRAC, type Destination, type Digest, type DigestImageRef, type DigestPlan, type DigestTakeFacts, type DocFeature, type DocSegment, type Drag, type DuckOptions, ELAPSED_PLACEHOLDER, 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, FOOTAGE_FRAME_STYLE, FRAME_BORDER_COLOR_DEFAULT, FRAME_BORDER_DEFAULT, FRAME_BORDER_WIDTH_DEFAULT, FREEZE_DEFAULT_SECONDS, FREEZE_SECONDS_MAX, FREEZE_SECONDS_MIN, type FilmSummaryOptions, type FocusBounds, type FollowEvent, type FollowOptions, type FrameEntrance, type FrameGeometry, type FrameStyle, type FreezeExtent, type FreezeSpan, HOLD_DRIFT_MAX, HOUSE_GRADIENT, HOUSE_REGISTER, 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, type LumaGrid, 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, NORMALIZE_MAX_LIFT_DB, NORMALIZE_MAX_LUFS, NORMALIZE_MIN_LUFS, NORMALIZE_PEAK_CEILING_DB, 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 OutputExtent, type OverlayAnchor, 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, PUMP_REST, type PeerStepSpan, type PeerTrack, type PinCandidate, 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, REPLAY_EPS, REST_TILT_ID, RETIRED_ZOOM_STYLES, type RecordingArtifact, type RecordingMeta, type RecordingNotice, type RecordingOutput, type RecordingPageMedia, type RecordingSkip, type Rect, type RejectedLane, type RejectedSpan, type ReplayedSpan, type ResolvedOverlayBox, type ResolvedOverlayStyle, type Rgb, 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, type StyledText, 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 TraceFileKind, type TraceOptions, type TraceResult, type TranscriptSegment, type Transition, type TransitionKind, type TransitionMove, type TransitionOut, type TransitionSpeed, type UsedFeature, 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 ZipEntry, type ZoomScreen, type ZoomSpan, type ZoomStyleName, type ZoomStyleParams, type ZoomView, type ZoomWindow, ambientDrift, anchorKindOf, anchorSourceDuration, anchoredClip, animStep, applyLook, applyTemplate, aspectRatioValue, audioLane, backdropMedia, bakeDocFeatures, boldWeightFor, buildDigest, calloutBox, calloutClip, calloutGroundOf, calloutLook, calloutSource, camBubbleRect, camBubbleRectAt, camLane, camMoveLane, camRectFromPose, camRestPose, camTrackFromDoc, cameraCentring, cameraModel, cameraRestWindows, cameraRests, cameraSpanExtents, cardEnter, cardExit, cardFields, cardInset, cardPointToScreen, cardPoseTrack, changedRegion, clampCamFrac, clampCamSize, clampFocus, clampFreezeSeconds, clampSpeedRate, clampTiltDeg, clampZoomLevel, clipEnvelope, clipGain, clipLength, clipsFrom, compareVersions, computeCardLayout, computeMicRms, computePeaks, copyLayout, copyStyle, cropBox, cssFamilies, cssWeights, cursorFromCsv, cursorFromPlaywrightTrace, cursorFromRecords, cursorFromTrace, cursorIdleFade, cursorOffAlpha, deltaE, deriveViewportCrop, destinationById, destinationsForChannel, docCardLayout, docFeatures, docFreezes, docMediaList, docOutputDuration, docRestTime, docStillTime, docToCropSpace, docToFullSpace, docTransitions, docZoomTrack, dragsFromTrack, dropTemplate, duckCurve, effectiveSegments, elapsedFor, endCardClips, enterKey, enterOf, entranceAt, entranceEnd, entranceSeconds, envelopeAt, envelopeValueAt, exitKey, exitOf, exitSeconds, expandEndCard, expectedFrameSize, exportSizeFor, extractClicks, featuresNewerThan, filmSummaryOf, findStep, focusBounds, focusForViewportCentre, followFocusEvents, formatElapsed, frameGeometry, freezeLane, freezeOutputExtents, hasElapsed, hasReplay, hexToRgb, hexToRgbTriplet, houseLook, htmlLayerBleed, htmlLayerBleedFor, htmlLayerFaces, htmlLayerKey, htmlLayerLabel, htmlLayerPayload, htmlLayerPictureBox, htmlLayerProblems, htmlLayerSvg, htmlLayerText, htmlLayerUnhostedFamilies, htmlLayerWidth, htmlStarterClip, idleGaps, idleKey, isKeyedOverlay, isLookKind, isLoweredRecording, isMusicBed, isPlayback, isProgramDoc, isRecordingDoc, isRejected, isStageClip, isUnitStep, lastLayerEnd, layerMedia, layerStart, layoutOf, levelForFocusFraction, liveZoomStyleName, longestOutputExtent, lookFromBrand, lookKindForGround, loudnessMatches, lowerProgramDoc, lowerStudioDoc, lowerToComposition, marksEmphasis, mediaAtOutput, mediaDuration, mediaFrame, mediaKey, mediaRef, mediaRefId, mediaSource, micLane, migrateHostedDoc, migrateMotion, migrateText, migrateTextClip, migrateZoomStyle, momentOutputs, momentsFromDoc, motionTrack, musicBedClip, musicSlugsOfDoc, nextMediaId, normalizeCaptureSpace, objectMotionBase, objectMotionPoseAt, objectsLane, outputDurationOf, outputEnd, outputRangeToSource, overlapFraction, overlayFaceFor, overlayFontFaces, overlayFontString, overlayFxSpec, overlayHit, overlayLines, overlayMotionBase, overlayMotionPoseAt, overlayPinPoseAt, overlayPlainText, overlayRect, overlaysLane, ownFreezes, pageDisplayUrl, parseCssColour, parsePoseId, pickChange, pickStyle, pinBox, pinCandidates, pinPlacement, pinRectOnScreen, pinReferent, pinReferentAt, placeFreezes, planAutoSpeed, planAutoTilt, planAutoZoom, planForDigest, planeSizeAtDepth, platformBarKind, playwrightTraceEntry, programDuration, programSceneTimes, programStillTime, projectFromArtifact, pumpFreeChainGap, ratedSegments, recommendedExportResolution, refillAudioBeds, rejectSpan, relativeLuminance, removeSourceRange, removeSpeedInRange, replayFlags, replayedSeconds, resolveAnchor, resolveExportSize, resolveOverlayAnchors, resolveOverlayBox, resolveOverlayStyle, resolvePins, resolveText3dAsset, resolveZoomStyle, restLeanOf, restSpansThroughTransitions, rgbToHex, sameMedia, sceneChanges, scrollRuns, segmentOutputExtents, outputLen as segmentOutputLen, segmentStarts, setSpeedInRange, slideSide, smoothCursor, snapRunWeight, sourceMomentToOutput, spanOutputExtent, spanOutputExtents, speedLane, stepElapsedMs, stepMomentToOutput, studioAudioPlan, studioEntry, studioLayerData, styledTextOf, textRunsOf, tiltLane, tiltTrackFromDoc, traceKindOf, transitionMult, transitionSeconds, unionFitLevel, unionRect, videoLane, voiceKey, wellFormedXml, withBackdrop, withFreezes, withHolds, withoutRejected, wrapProgramLength, zipEntries, zipEntryBytes, zoomCoversRect, zoomLane, zoomSpanForRange, zoomTrackFromDoc, zoomView, zoomViewport, zoomWindow };

package/dist/index.js

@@ -5300,6 +5300,35 @@ function push(keys, t, a) {
   keys.push({ t: rt, a });
 }
 
+// src/lower/cursorOff.ts
+var CURSOR_OFF_FADE = 0.15;
+function cursorOffAlpha(off, t) {
+  let a = 1;
+  if (!Array.isArray(off)) return a;
+  for (const r of off) {
+    if (!r || typeof r.in !== "number" || !Number.isFinite(r.in)) continue;
+    if (r.out !== void 0 && !(typeof r.out === "number" && r.out > r.in))
+      continue;
+    const out = r.out === void 0 ? Infinity : r.out;
+    const k = t < r.in ? (r.in - t) / CURSOR_OFF_FADE : t > out ? (t - out) / CURSOR_OFF_FADE : 0;
+    if (k < a) a = k;
+  }
+  return a < 0 ? 0 : a > 1 ? 1 : a;
+}
+var CURSOR_OFF_CODE = `function cxoAlpha(cxoL, cxoT) {
+    var cxoA = 1
+    if (!cxoL || !cxoL.length) return cxoA
+    for (var cxoI = 0; cxoI < cxoL.length; cxoI++) {
+      var cxoR = cxoL[cxoI]
+      if (!cxoR || typeof cxoR.in !== 'number' || !isFinite(cxoR.in)) continue
+      if (cxoR.out !== undefined && !(typeof cxoR.out === 'number' && cxoR.out > cxoR.in)) continue
+      var cxoO = cxoR.out === undefined ? Infinity : cxoR.out
+      var cxoK = cxoT < cxoR.in ? (cxoR.in - cxoT) / ${CURSOR_OFF_FADE} : cxoT > cxoO ? (cxoT - cxoO) / ${CURSOR_OFF_FADE} : 0
+      if (cxoK < cxoA) cxoA = cxoK
+    }
+    return cxoA < 0 ? 0 : cxoA > 1 ? 1 : cxoA
+  }`;
+
 // src/lower/studioEntry.ts
 import { timelineRuntimeCode } from "@vosjs/timeline/bundle";
 
@@ -5707,6 +5736,8 @@ var STUDIO_FRAME = `(ctx, content, dt) => {
   var TL = globalThis.__vosTimeline
   var t = ctx.time || 0
   var s = H / 1080 // scale design-px controls to comp px
+  // The take's cursor-off ranges (a layer card's cursor reads them at t).
+  ${CURSOR_OFF_CODE}
   var ns = window.__vos__ || {}
   var playing = ns.isPaused === false
   // The styled-text layout (the engine's text/layout.ts, generated), installed once:
@@ -6775,10 +6806,14 @@ var STUDIO_FRAME = `(ctx, content, dt) => {
         }
         var lcPts = lcCu.pts, lcPX = lcPts[0].x, lcPY = lcPts[0].y
         for (var lcp = 0; lcp < lcPts.length; lcp++) { if (lcPts[lcp].t <= lcT) { lcPX = lcPts[lcp].x; lcPY = lcPts[lcp].y } }
-        lcX.save()
-        lcX.fillStyle = 'rgba(255,255,255,0.95)'; lcX.strokeStyle = 'rgba(0,0,0,0.4)'; lcX.lineWidth = 2 * lcS
-        lcX.beginPath(); lcX.arc(lcX0 + (lcPX / (lcSp.w || lcNW)) * lcW, lcMY + (lcPY / (lcSp.h || lcNH)) * lcMH, lcSize, 0, Math.PI * 2); lcX.fill(); lcX.stroke()
-        lcX.restore()
+        // the take's cursor-off ranges, at OUTPUT time like the primary's
+        var lcOffA = cxoAlpha(lcCu.off, t)
+        if (lcOffA > 0.01) {
+          lcX.save()
+          lcX.fillStyle = 'rgba(255,255,255,' + (0.95 * lcOffA) + ')'; lcX.strokeStyle = 'rgba(0,0,0,' + (0.4 * lcOffA) + ')'; lcX.lineWidth = 2 * lcS
+          lcX.beginPath(); lcX.arc(lcX0 + (lcPX / (lcSp.w || lcNW)) * lcW, lcMY + (lcPY / (lcSp.h || lcNH)) * lcMH, lcSize, 0, Math.PI * 2); lcX.fill(); lcX.stroke()
+          lcX.restore()
+        }
       }
       lcX.restore()
       if (lcO.border && lcO.border.width > 0) {
@@ -8421,6 +8456,11 @@ var ON_FRAME = `(ctx, content, dt) => {
     }
     cc.restore()
   }
+  // The ranges the cursor is off (cursorStyle.off), read at OUTPUT time:
+  // one factor for every place the dot is drawn below (the card, any media
+  // it plays, the dot across a boundary). 1 when nothing is off.
+  ${CURSOR_OFF_CODE}
+  var cxoF = cxoAlpha(d.cursorStyle && d.cursorStyle.off, t)
 
   // The card paints in PASSES: the ghost first (the outgoing clip's last
   // frame on its own canvas, while a boundary is crossing), then the live
@@ -8912,7 +8952,8 @@ var ON_FRAME = `(ctx, content, dt) => {
   // cursor (SOURCE-anchored samples, read at the on-screen source moment).
   // The dot is the only thing cursorStyle.visible hides \u2014 the track still drives
   // cursor-follow zoom, and click effects draw above on their own switch.
-  // Undefined reads as visible so pre-toggle docs are unchanged.
+  // Undefined reads as visible so pre-toggle docs are unchanged. The ranges
+  // in cursorStyle.off hide the dot the same way, by time (cxoF).
   var cur = (actM ? actM.cursor : d.cursor) || []
   if (cur.length && !(d.cursorStyle && d.cursorStyle.visible === false)) {
     var px = cur[0].x, py = cur[0].y
@@ -8947,8 +8988,8 @@ var ON_FRAME = `(ctx, content, dt) => {
       }
       if (tpG) trQa = [tqX, tqY]
       else { trQb = [tqX, tqY]; trQs = curSize * ckPress; trQw = s2 }
-    } else if (cuA > 0.01) {
-      drawCur(c, ax, ay, curSize * ckPress, cuA, 2 * s2)
+    } else if (cuA * cxoF > 0.01) {
+      drawCur(c, ax, ay, curSize * ckPress, cuA * cxoF, 2 * s2)
     }
   }
   if (fitCover) c.restore()
@@ -9110,7 +9151,7 @@ var ON_FRAME = `(ctx, content, dt) => {
       tqX2 = tqOut ? tqAx : tqBx; tqY2 = tqOut ? tqAy : tqBy
     }
     var tqR = trQs || (((d.cursorStyle && d.cursorStyle.size) || 24) * s * 0.5)
-    if (tqOn) drawCur(ovC, tqX2, tqY2, tqR, 1, 2 * (trQw || s))
+    if (tqOn && cxoF > 0.01) drawCur(ovC, tqX2, tqY2, tqR, cxoF, 2 * (trQw || s))
   }
   ov.sig = ovSig
   ov.active = camActiveNow || !!trOut || pqLive
@@ -9361,7 +9402,10 @@ function studioLayerData(input, duration, pins) {
                 })),
                 space: { w: lm.meta.width, h: lm.meta.height },
                 size: rec.cursor.size,
-                clicks
+                clicks,
+                // The take's cursor-off ranges (OUTPUT time),
+                // only when there are any.
+                ...rec.cursor.off?.length ? { off: rec.cursor.off } : {}
               }
             };
           })() : {};
@@ -10346,6 +10390,7 @@ function pickStyle(doc) {
     const v = doc[k];
     if (v !== void 0) out[k] = structuredClone(v);
   }
+  if (out.cursor) delete out.cursor.off;
   return out;
 }
 function copyStyle(from, to, opts = {}) {
@@ -10364,6 +10409,9 @@ function copyStyle(from, to, opts = {}) {
     }
     next.export = merged;
   }
+  const ownOff = to.cursor?.off;
+  if (ownOff && next.cursor)
+    next.cursor = { ...next.cursor, off: structuredClone(ownOff) };
   const styled = next;
   return opts.layout ? copyLayout(from, styled, { keys: opts.keys }).doc : styled;
 }
@@ -10507,13 +10555,19 @@ function clipsFrom(doc, from) {
 function dropTemplate(doc, from) {
   const has = clipsFrom(doc, from);
   const freezes = (doc.freeze ?? []).some((f) => f.from === from);
-  if (!has.overlays.length && !has.objects.length && !has.audio.length && !freezes)
+  const cursorOff = (doc.cursor?.off ?? []).some((r) => r?.from === from);
+  if (!has.overlays.length && !has.objects.length && !has.audio.length && !freezes && !cursorOff)
     return doc;
   const out = { ...doc };
   if (doc.overlays) out.overlays = doc.overlays.filter((o) => o.from !== from);
   if (doc.objects) out.objects = doc.objects.filter((o) => o.from !== from);
   out.audio = doc.audio.filter((a) => a.from !== from);
   if (doc.freeze) out.freeze = doc.freeze.filter((f) => f.from !== from);
+  if (cursorOff) {
+    const off = (doc.cursor.off ?? []).filter((r) => r?.from !== from);
+    const { off: _off, ...cursor } = doc.cursor;
+    out.cursor = off.length ? { ...cursor, off } : cursor;
+  }
   return out;
 }
 function applyTemplate(template, take, opts) {
@@ -12657,6 +12711,14 @@ var DOC_FEATURES = [
     name: "clips whose camera rests",
     before: "would play the zooms, tilts and cam moves over those clips as if the camera were not resting",
     uses: (doc) => isRecordingDoc(doc) ? doc.segments.filter((s) => s && s.camera === "rest").length : 0
+  },
+  {
+    id: "cursor-off",
+    since: "0.46.0",
+    name: "cursor-off ranges",
+    before: "would draw the cursor through them",
+    // Nothing older can hide the cursor by time, so there is no bake.
+    uses: (doc) => isRecordingDoc(doc) && doc.cursor && Array.isArray(doc.cursor.off) ? doc.cursor.off.length : 0
   }
 ];
 function compareVersions(a, b) {
@@ -12753,6 +12815,116 @@ function rejectSpan(rejected, lane, span, note) {
   if (note) entry.note = note;
   return entry;
 }
+
+// src/filmSummary.ts
+var CUT_MERGE = 0.25;
+var r32 = (v) => Math.round(v * 1e3) / 1e3;
+var isMusicOrEffect = (key) => /\/music\/[^/?#]+\.mp3(?:[?#]|$)/.test(key) || /\/audio-sfx\//.test(key);
+function programSceneTimes(config) {
+  const code = JSON.stringify(config);
+  const times = /* @__PURE__ */ new Set();
+  for (const m of code.matchAll(
+    /addLabel\(\s*(?:\\"|['`])[^'`"\\]*(?:\\"|['`])\s*,\s*([\d.]+)/g
+  )) {
+    const t = Number(m[1]);
+    if (Number.isFinite(t) && t > 0) times.add(r32(t));
+  }
+  return [...times].sort((a, b) => a - b);
+}
+function markedSteps(source) {
+  const steps = source.script?.steps;
+  if (!Array.isArray(steps)) return [];
+  const out = [];
+  steps.forEach((s, i) => {
+    if (!s || typeof s !== "object") return;
+    const step = s;
+    if (step.zoom === true) out.push(typeof step.id === "string" ? step.id : i);
+  });
+  return out;
+}
+function tidy(cuts, duration) {
+  const sorted = cuts.filter((t) => Number.isFinite(t) && t > CUT_MERGE && t < duration - 0.05).map(r32).sort((a, b) => a - b);
+  const out = [];
+  for (const t of sorted) {
+    if (!out.length || t - out[out.length - 1] > CUT_MERGE) out.push(t);
+  }
+  return out;
+}
+function filmSummaryOf(doc, opts) {
+  const duration = r32(docOutputDuration(doc));
+  const cuts = [];
+  let payoff = opts.payoff;
+  let voice = opts.voice ?? false;
+  if (isRecordingDoc(doc)) {
+    const rated = ratedSegments(doc);
+    let t = 0;
+    for (const s of rated) {
+      const rate = s.rate && s.rate > 0 ? s.rate : 1;
+      t += (s.out - s.in) / rate;
+      cuts.push(t);
+    }
+    for (const clip of doc.overlays ?? []) {
+      const start = layerStart(clip, doc, rated);
+      if (start !== null) cuts.push(start);
+    }
+    let lastMarked = null;
+    for (const { id, source } of docMediaList(doc)) {
+      for (const step of source.meta.steps ?? []) {
+        if (step.navigated && typeof step.tEnd === "number") {
+          const out = sourceMomentToOutput(rated, step.tEnd, id || void 0);
+          if (out !== null) cuts.push(out);
+        }
+      }
+      for (const step of markedSteps(source)) {
+        const r = resolveAnchor(
+          doc,
+          { step, ...id ? { media: id } : {} },
+          rated
+        );
+        if (r.start !== null) {
+          cuts.push(r.start);
+          if (lastMarked === null || r.start > lastMarked) lastMarked = r.start;
+        }
+      }
+    }
+    if (payoff === void 0 && lastMarked !== null) payoff = lastMarked;
+    if (opts.voice === void 0) {
+      voice = voiceKey(doc) !== null || (doc.audio ?? []).some((a) => !isMusicOrEffect(a.key));
+    }
+  } else {
+    const scenes = programSceneTimes(doc.program.config);
+    cuts.push(...scenes);
+    if (payoff === void 0 && scenes.length)
+      payoff = scenes[scenes.length - 1];
+    if (opts.voice === void 0) {
+      voice = (doc.audio ?? []).some((a) => !isMusicOrEffect(a.key));
+    }
+  }
+  const tidied = tidy(cuts, duration);
+  if (payoff === void 0 && tidied.length) payoff = tidied[tidied.length - 1];
+  if (payoff !== void 0 && !(payoff > 0 && payoff < duration)) {
+    payoff = void 0;
+  }
+  return {
+    duration,
+    ...payoff !== void 0 ? { payoff: r32(payoff) } : {},
+    cuts: tidied,
+    voice,
+    ...opts.mood ? { mood: opts.mood } : {},
+    ...opts.words ? { words: opts.words } : {},
+    seed: opts.seed,
+    ...opts.like?.length ? { like: opts.like } : {},
+    ...opts.fadeIn ? { fadeIn: true } : {}
+  };
+}
+function musicSlugsOfDoc(doc) {
+  const out = /* @__PURE__ */ new Set();
+  for (const a of doc.audio ?? []) {
+    const m = /\/music\/([a-z0-9][a-z0-9-]*)\.mp3(?:[?#]|$)/.exec(a.key);
+    if (m) out.add(m[1]);
+  }
+  return [...out].sort();
+}
 export {
   ASPECT_RATIOS,
   AUDIO_PLAN_STEP,
@@ -12805,6 +12977,7 @@ export {
   CURSOR_IDLE_FADE_IN,
   CURSOR_IDLE_FADE_OUT,
   CURSOR_IDLE_HOLD,
+  CURSOR_OFF_FADE,
   DARK_GROUND,
   DECORATION_THICKNESS_EM,
   DEFAULT_BROWSER_BAR,
@@ -13007,6 +13180,7 @@ export {
   cursorFromRecords,
   cursorFromTrace,
   cursorIdleFade,
+  cursorOffAlpha,
   decorationRect,
   deltaE,
   deriveViewportCrop,
@@ -13045,6 +13219,7 @@ export {
   exportSizeFor,
   extractClicks,
   featuresNewerThan,
+  filmSummaryOf,
   findStep,
   focusBounds,
   focusForViewportCentre,
@@ -13117,6 +13292,7 @@ export {
   momentsFromDoc,
   motionTrack,
   musicBedClip,
+  musicSlugsOfDoc,
   nextMediaId,
   normalizeCaptureSpace,
   normalizeRuns,
@@ -13162,6 +13338,7 @@ export {
   platformBarKind,
   playwrightTraceEntry,
   programDuration,
+  programSceneTimes,
   programStillTime,
   projectFromArtifact,
   pumpFreeChainGap,