@vosjs/studio-core 0.2.1 → 0.3.1

package/dist/index.d.ts

@@ -172,6 +172,14 @@ declare function idleGaps(track: readonly CursorEvent[], durationS: number, idle
 /** Mean activity over [a, b) source seconds exceeds PLAYBACK_ACTIVITY. */
 declare function isPlayback(activity: readonly number[] | null | undefined, a: number, b: number): boolean;
 
+/**
+ * The studio — shared contracts.
+ *
+ * These are the seams between the capture extension, the editor, the planner,
+ * and the lowering. Branding lives at the app layer;
+ * these types are intentionally generic so the core stays extraction-ready.
+ */
+
 /** A single input event captured in the page, relative to the recording's t0. */
 interface CursorEvent {
     /** ms since t0 (recording start). */
@@ -1311,11 +1319,18 @@ declare const DEFAULT_CURSOR_STYLE: CursorStyle;
 declare const DEFAULT_CAM_STYLE: CamStyle;
 declare const DEFAULT_BROWSER_BAR: BrowserBarStyle;
 /**
- * The frame a NEW take opens on. Once `BACKDROP_DEFAULT_ON`
- * flips (backdrop.ts), the default is the house loop on its own ground;
- * until then the brand gradient. Every ingest path spreads this, so the
- * flip reaches the extension handoff, the in-page recorder, a dropped file
- * and `vos record` at once; a doc that already carries a frame keeps it.
+ * The frame with no backdrop: the card, its chrome and a flat ground. A
+ * host that opens new takes on a backdrop builds its own opening frame
+ * with `withBackdrop` (backdrop.ts) and hands it to `projectFromArtifact`,
+ * so the pick never lives in the document model.
+ */
+declare const BASE_FRAME_STYLE: FrameStyle;
+/**
+ * The frame a NEW take opens on when the host names none: the bare frame.
+ * Every ingest path spreads the frame it is handed (or this one), so a
+ * host's pick reaches the extension handoff, the in-page recorder, a
+ * dropped file and `vos record` through one argument; a doc that already
+ * carries a frame keeps it.
  */
 declare const DEFAULT_FRAME_STYLE: FrameStyle;
 /** Border alpha applied when the Frame-border toggle turns on. */
@@ -1462,8 +1477,16 @@ declare function docToFullSpace(d: ProjectDoc): void;
 /** Remap a full-space doc back into crop space (hide the chrome again). */
 declare function docToCropSpace(d: ProjectDoc): void;
 
+interface IngestOptions {
+    /**
+     * The frame the take opens on: a host's house backdrop on the bare frame,
+     * say (`withBackdrop`). Its browser bar is still derived from the footage
+     * below. Absent, `DEFAULT_FRAME_STYLE`.
+     */
+    frame?: FrameStyle;
+}
 /** Build a ProjectDoc from a RecordingArtifact handed off by a recorder. */
-declare function projectFromArtifact(artifact: RecordingArtifact, videoUrl: string): {
+declare function projectFromArtifact(artifact: RecordingArtifact, videoUrl: string, opts?: IngestOptions): {
     doc: ProjectDoc;
     videoUrl: string;
 };
@@ -2963,38 +2986,41 @@ declare function refillAudioBeds(doc: ProjectDoc, prevDuration: number, nextDura
 declare function voiceKey(doc: Pick<ProjectDoc, 'source'> | StudioDoc): string | null;
 
 /**
- * The DEFAULT backdrop: the house loop every NEW take opens on
- * once the flag below is on. A committed constant, not a live vos, the same
- * way Home's door tiles are a deliberate asset push (decided 2026-08-17):
- * changing it is a code change with a review, never something an autosave
- * can re-skin.
- *
- * `ground` is the loop's average colour, written into `frame.background` so
+ * A backdrop is the loop (or still) a frame opens on, together with its
+ * GROUND: the loop's average colour, written into `frame.background` so
  * the frame before the first decoded frame, the reduced-motion still and
- * the offline fail-open all land on the loop's own colour. The
- * keys are the pre-registry bucket objects, which stay in the bucket
- * forever; the registry's `backdrops/{slug}/…` keys replace them when the
- * house loop is featured through the verb.
+ * the offline fail-open all land on the loop's own colour instead of
+ * whatever the frame carried before.
  *
- * BACKDROP_DEFAULT_ON is the flip. It stays OFF until the set has a signed-off
- * seed and the fleet measurement has run: a switch, not a surprise.
- * Docs already carrying a frame are never touched either way.
+ * WHICH backdrop a new take opens on is the host's decision, never this
+ * package's: the studio hands its pick to `projectFromArtifact` as `frame`,
+ * the CLI reads the set the platform publishes. The document model carries
+ * the mechanism only, so the default here is a frame with no backdrop.
+ * A doc that already carries a frame is never touched either way.
  */
 
-declare const DEFAULT_BACKDROP: {
-    readonly slug: "soft-beams";
-    readonly title: "Soft Beams";
-    readonly key: "https://assets.vos.so/backgrounds/soft-beams-1080p.webm";
-    readonly key2k: "https://assets.vos.so/backgrounds/soft-beams-2k.webm";
-    readonly poster: "https://assets.vos.so/backgrounds/soft-beams-poster.jpg";
-    readonly duration: 10;
-    readonly ground: "#a7b2d1";
-};
-declare const BACKDROP_DEFAULT_ON: boolean;
-/** The default backdrop as a doc's `frame.backgroundMedia`. */
-declare function defaultBackdropMedia(): BackgroundMedia;
-/** A frame style opening on the default backdrop (media + its ground). */
-declare function withDefaultBackdrop(frame: FrameStyle): FrameStyle;
+interface Backdrop {
+    /** The loop's URL, or a take-dir path (`/bg.webm`). */
+    key: string;
+    /** `video` unless said otherwise. */
+    kind?: BackgroundMedia['kind'];
+    /** The loop's period in seconds, a fact of the asset. Video only. */
+    duration?: number;
+    /** A still to show before the first decoded frame and under reduced motion. */
+    poster?: string;
+    /**
+     * The loop's average colour. Written as `frame.background` when given; a
+     * backdrop without one keeps the frame's own fill under it.
+     */
+    ground?: string;
+}
+/** A backdrop as a doc's `frame.backgroundMedia`. */
+declare function backdropMedia(backdrop: Backdrop): BackgroundMedia;
+/**
+ * A frame opening on a backdrop: the media, and its ground when it has one,
+ * in one write. Everything else on the frame is kept.
+ */
+declare function withBackdrop(frame: FrameStyle, backdrop: Backdrop): FrameStyle;
 
 /**
  * Rejected proposals: the document's way to say "not this one".
@@ -3036,4 +3062,4 @@ declare function rejectSpan(rejected: RejectedSpan[] | undefined, lane: Rejected
     anchor?: StepAnchor;
 }, note?: string): RejectedSpan;
 
-export { ASPECT_RATIOS, AUDIO_PLAN_STEP, type AnchorKind, type AspectRatioOption, type AudioClip, type AudioPlanPoint, type AudioPlanTrack, BACKDROP_DEFAULT_ON, BACKGROUND_Z, 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_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 CursorEvent, type CursorFadeKey, type CursorIdleOptions, type CursorStyle, type CursorTrack, DEFAULT_BACKDROP, 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, 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 DuckOptions, EXPORT_RESOLUTION_OPTIONS, EXPORT_SHORT_EDGE, type EnvelopePoint, type ExportResolution, type ExtractClickOptions, FOLLOW_RECENTER, FOLLOW_SAFE_RATIO, FRAME_BORDER_COLOR_DEFAULT, FRAME_BORDER_DEFAULT, FRAME_BORDER_WIDTH_DEFAULT, type FocusBounds, type FollowEvent, type FollowOptions, type FrameGeometry, type FrameStyle, type LowerProgramOptions, type LoweredAudioClip, type LoweredClick, type LoweredComposition, type LoweredZoomSpan, MINIMAL_BAR_THEMES, MOTION_DELTA, MOTION_EASE, type MediaOverlayClip, 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, PLAYBACK_ACTIVITY, PROGRAM_RETIME, type PlanOptions, type PlanTiltOptions, type PlaneSize, type ProgramAnchorDoc, type ProgramTweenEdit, type ProjectDoc, type PxRect, REJECT_OVERLAP, type RecordingArtifact, type RecordingMeta, type Rect, type RejectedLane, type RejectedSpan, type ResolvedOverlayBox, type ResolvedOverlayStyle, SCENE_MOTION, SCENE_QUIET, SPEED_RATE_MAX, SPEED_RATE_MIN, SPEED_SPAN_MIN, STUDIO_ENTRY_ID, STYLE_FIELDS, 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_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_SPEED_MULT, 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 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, aspectRatioValue, audioLane, buildDigest, camBubbleRect, camBubbleRectAt, camLane, camMoveLane, camRectFromPose, camRestPose, camTrackFromDoc, cardPointToScreen, clampCamFrac, clampCamSize, clampFocus, clampSpeedRate, clampTiltDeg, clampZoomLevel, clipEnvelope, clipLength, computeCardLayout, computeMicRms, computePeaks, copyStyle, cropBox, cursorIdleFade, defaultBackdropMedia, deriveViewportCrop, destinationById, destinationsForChannel, docCardLayout, docOutputDuration, docToCropSpace, docToFullSpace, duckCurve, effectiveSegments, envelopeAt, envelopeValueAt, expectedFrameSize, exportSizeFor, extractClicks, focusBounds, followFocusEvents, frameGeometry, hexToRgbTriplet, idleGaps, isMusicBed, isPlayback, isProgramDoc, isRecordingDoc, isRejected, levelForFocusFraction, lowerProgramDoc, lowerStudioDoc, lowerToComposition, micLane, migrateHostedDoc, momentsFromDoc, motionTrack, musicBedClip, normalizeCaptureSpace, objectMotionBase, objectMotionPoseAt, objectsLane, outputDurationOf, outputRangeToSource, overlapFraction, overlayFaceFor, overlayFontFaces, overlayFontString, overlayHit, overlayLines, overlayMotionBase, overlayMotionPoseAt, overlayRect, overlaysLane, pageDisplayUrl, parsePoseId, pickStyle, planAutoSpeed, planAutoTilt, planAutoZoom, planForDigest, planeSizeAtDepth, platformBarKind, programDuration, projectFromArtifact, ratedSegments, recommendedExportResolution, refillAudioBeds, rejectSpan, removeSourceRange, removeSpeedInRange, resolveExportSize, resolveOverlayBox, resolveOverlayStyle, resolveText3dAsset, resolveZoomStyle, sceneChanges, scrollRuns, setSpeedInRange, smoothCursor, spanOutputExtent, speedLane, studioAudioPlan, studioEntry, studioLayerData, tiltLane, tiltTrackFromDoc, transitionMult, videoLane, voiceKey, withDefaultBackdrop, withoutRejected, wrapProgramLength, zoomCoversRect, zoomLane, zoomSpanForRange, zoomTrackFromDoc, zoomWindow };
+export { ASPECT_RATIOS, AUDIO_PLAN_STEP, type AnchorKind, 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_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 CursorEvent, type CursorFadeKey, type CursorIdleOptions, type CursorStyle, type CursorTrack, 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, 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 DuckOptions, EXPORT_RESOLUTION_OPTIONS, EXPORT_SHORT_EDGE, type EnvelopePoint, type ExportResolution, type ExtractClickOptions, FOLLOW_RECENTER, FOLLOW_SAFE_RATIO, FRAME_BORDER_COLOR_DEFAULT, FRAME_BORDER_DEFAULT, FRAME_BORDER_WIDTH_DEFAULT, type FocusBounds, type FollowEvent, type FollowOptions, type FrameGeometry, type FrameStyle, type IngestOptions, type LowerProgramOptions, type LoweredAudioClip, type LoweredClick, type LoweredComposition, type LoweredZoomSpan, MINIMAL_BAR_THEMES, MOTION_DELTA, MOTION_EASE, type MediaOverlayClip, 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, PLAYBACK_ACTIVITY, PROGRAM_RETIME, type PlanOptions, type PlanTiltOptions, type PlaneSize, type ProgramAnchorDoc, type ProgramTweenEdit, type ProjectDoc, type PxRect, REJECT_OVERLAP, type RecordingArtifact, type RecordingMeta, type Rect, type RejectedLane, type RejectedSpan, type ResolvedOverlayBox, type ResolvedOverlayStyle, SCENE_MOTION, SCENE_QUIET, SPEED_RATE_MAX, SPEED_RATE_MIN, SPEED_SPAN_MIN, STUDIO_ENTRY_ID, STYLE_FIELDS, 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_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_SPEED_MULT, 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 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, aspectRatioValue, audioLane, backdropMedia, buildDigest, camBubbleRect, camBubbleRectAt, camLane, camMoveLane, camRectFromPose, camRestPose, camTrackFromDoc, cardPointToScreen, clampCamFrac, clampCamSize, clampFocus, clampSpeedRate, clampTiltDeg, clampZoomLevel, clipEnvelope, clipLength, computeCardLayout, computeMicRms, computePeaks, copyStyle, cropBox, cursorIdleFade, deriveViewportCrop, destinationById, destinationsForChannel, docCardLayout, docOutputDuration, docToCropSpace, docToFullSpace, duckCurve, effectiveSegments, envelopeAt, envelopeValueAt, expectedFrameSize, exportSizeFor, extractClicks, focusBounds, followFocusEvents, frameGeometry, hexToRgbTriplet, idleGaps, isMusicBed, isPlayback, isProgramDoc, isRecordingDoc, isRejected, levelForFocusFraction, lowerProgramDoc, lowerStudioDoc, lowerToComposition, micLane, migrateHostedDoc, momentsFromDoc, motionTrack, musicBedClip, normalizeCaptureSpace, objectMotionBase, objectMotionPoseAt, objectsLane, outputDurationOf, outputRangeToSource, overlapFraction, overlayFaceFor, overlayFontFaces, overlayFontString, overlayHit, overlayLines, overlayMotionBase, overlayMotionPoseAt, overlayRect, overlaysLane, pageDisplayUrl, parsePoseId, pickStyle, planAutoSpeed, planAutoTilt, planAutoZoom, planForDigest, planeSizeAtDepth, platformBarKind, programDuration, projectFromArtifact, ratedSegments, recommendedExportResolution, refillAudioBeds, rejectSpan, removeSourceRange, removeSpeedInRange, resolveExportSize, resolveOverlayBox, resolveOverlayStyle, resolveText3dAsset, resolveZoomStyle, sceneChanges, scrollRuns, setSpeedInRange, smoothCursor, spanOutputExtent, speedLane, studioAudioPlan, studioEntry, studioLayerData, tiltLane, tiltTrackFromDoc, transitionMult, videoLane, voiceKey, withBackdrop, withoutRejected, wrapProgramLength, zoomCoversRect, zoomLane, zoomSpanForRange, zoomTrackFromDoc, zoomWindow };

package/dist/index.js

@@ -1,31 +1,3 @@
-// src/backdrop.ts
-var DEFAULT_BACKDROP = {
-  slug: "soft-beams",
-  title: "Soft Beams",
-  key: "https://assets.vos.so/backgrounds/soft-beams-1080p.webm",
-  key2k: "https://assets.vos.so/backgrounds/soft-beams-2k.webm",
-  poster: "https://assets.vos.so/backgrounds/soft-beams-poster.jpg",
-  duration: 10,
-  ground: "#a7b2d1"
-};
-var BACKDROP_DEFAULT_ON = false;
-function defaultBackdropMedia() {
-  return {
-    kind: "video",
-    key: DEFAULT_BACKDROP.key,
-    duration: DEFAULT_BACKDROP.duration,
-    poster: DEFAULT_BACKDROP.poster,
-    dim: 0
-  };
-}
-function withDefaultBackdrop(frame) {
-  return {
-    ...frame,
-    background: DEFAULT_BACKDROP.ground,
-    backgroundMedia: defaultBackdropMedia()
-  };
-}
-
 // src/types.ts
 var TRANSITION_SPEED_MULT = {
   instant: 0,
@@ -177,7 +149,7 @@ var BASE_FRAME_STYLE = {
   aspectRatio: "native",
   browserBar: DEFAULT_BROWSER_BAR
 };
-var DEFAULT_FRAME_STYLE = BACKDROP_DEFAULT_ON ? withDefaultBackdrop(BASE_FRAME_STYLE) : BASE_FRAME_STYLE;
+var DEFAULT_FRAME_STYLE = BASE_FRAME_STYLE;
 var FRAME_BORDER_DEFAULT = 0.35;
 var FRAME_BORDER_WIDTH_DEFAULT = 1.5;
 var FRAME_BORDER_COLOR_DEFAULT = "#ffffff";
@@ -392,7 +364,8 @@ function median(values) {
 }
 
 // src/ingest.ts
-function projectFromArtifact(artifact, videoUrl) {
+function projectFromArtifact(artifact, videoUrl, opts = {}) {
+  const baseFrame = opts.frame ?? DEFAULT_FRAME_STYLE;
   const surface = artifact.meta.captureSurface ?? "tab";
   const norm = normalizeCaptureSpace(artifact.cursor, artifact.meta);
   const { cursor, meta } = norm;
@@ -434,9 +407,9 @@ function projectFromArtifact(artifact, videoUrl) {
     cursor: { ...DEFAULT_CURSOR_STYLE },
     cam: { ...DEFAULT_CAM_STYLE },
     frame: {
-      ...DEFAULT_FRAME_STYLE,
+      ...baseFrame,
       browserBar: {
-        ...DEFAULT_FRAME_STYLE.browserBar,
+        ...baseFrame.browserBar,
         // Chrome-free footage (tab takes, cropped window takes) opens with the
         // OS-matched realistic frame — the Screen-Studio first render; Hidden is
         // one click away. Footage that still contains real chrome gets none.
@@ -6778,6 +6751,24 @@ function duckCurve(rms, segments, durationSec2, opts = DEFAULT_DUCK) {
   return points;
 }
 
+// src/backdrop.ts
+function backdropMedia(backdrop) {
+  return {
+    kind: backdrop.kind ?? "video",
+    key: backdrop.key,
+    ...backdrop.duration !== void 0 ? { duration: backdrop.duration } : {},
+    ...backdrop.poster ? { poster: backdrop.poster } : {},
+    dim: 0
+  };
+}
+function withBackdrop(frame, backdrop) {
+  return {
+    ...frame,
+    ...backdrop.ground ? { background: backdrop.ground } : {},
+    backgroundMedia: backdropMedia(backdrop)
+  };
+}
+
 // src/rejected.ts
 var REJECT_OVERLAP = 0.5;
 function overlapFraction(a, b) {
@@ -6813,8 +6804,8 @@ function rejectSpan(rejected, lane, span, note) {
 export {
   ASPECT_RATIOS,
   AUDIO_PLAN_STEP,
-  BACKDROP_DEFAULT_ON,
   BACKGROUND_Z,
+  BASE_FRAME_STYLE,
   CAMERA_FAR,
   CAMERA_NEAR,
   CAM_CHAIN_GAP,
@@ -6847,7 +6838,6 @@ export {
   CURSOR_IDLE_FADE_IN,
   CURSOR_IDLE_FADE_OUT,
   CURSOR_IDLE_HOLD,
-  DEFAULT_BACKDROP,
   DEFAULT_BROWSER_BAR,
   DEFAULT_CAM_POSE,
   DEFAULT_CAM_STYLE,
@@ -6931,6 +6921,7 @@ export {
   anchorSourceDuration,
   aspectRatioValue,
   audioLane,
+  backdropMedia,
   buildDigest,
   camBubbleRect,
   camBubbleRectAt,
@@ -6954,7 +6945,6 @@ export {
   copyStyle,
   cropBox,
   cursorIdleFade,
-  defaultBackdropMedia,
   deriveViewportCrop,
   destinationById,
   destinationsForChannel,
@@ -7040,7 +7030,7 @@ export {
   transitionMult,
   videoLane,
   voiceKey,
-  withDefaultBackdrop,
+  withBackdrop,
   withoutRejected,
   wrapProgramLength,
   zoomCoversRect,