@vosjs/studio-core 0.7.1 → 0.9.0

package/README.md

@@ -36,7 +36,7 @@ The shared layers lower as one engine `stack` entry, `STUDIO_ENTRY_ID` (`'vosso.
 - **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. `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 eight camera personalities (`glide`, the default, then `focus`, `cinema`, `snappy`, `cut`, `keynote`, `drift`, `none`); a style parametrizes both the planner and the camera motion, and `doc.zoomParams` layers per-document overrides.
-- **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); `computeCardLayout` and `docCardLayout` are the host-side mirror of the program's card math, pinned to it by tests.
+- **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.
 - **Backdrops.** `withBackdrop(frame, backdrop)` and `backdropMedia` put a looping video or a still behind the card, output-anchored modulo its duration. The package carries the mechanism and `BASE_FRAME_STYLE`; which loop a host opens on is the host's choice.
 
 ## Seeing a recording: the digest

package/dist/index.js

@@ -1266,7 +1266,8 @@ var CARD_FOV = 30;
 var OVERLAY_Z = -2;
 var CARD_Z = -4;
 var BACKGROUND_Z = -6;
-var CARD_OVERSCAN = 1.25;
+var CARD_OVERSCAN_STEP = 0.05;
+var CARD_OVERSCAN_MAX = 4;
 var CAMERA_NEAR = 0.1;
 var CAMERA_FAR = 100;
 function planeSizeAtDepth(distance, fovDeg, aspect) {
@@ -3299,6 +3300,54 @@ function objectMotionPoseAt(o, t, clipDur) {
   if (!track.keyframes.length) return null;
   return [...sample(track, t, lerpArray)];
 }
+var FRAME_STEP_SRC = `
+  function stepPaused(vid, srcT) {
+    if (!vid.paused) vid.pause()
+    // A WebCodecs provider (capture pages) services the frame by PTS at
+    // decode speed \u2014 no element seek, no 250ms settle cap. The element stays
+    // paused as the dimension source and fallback.
+    var wcp = vid.__voilaWc
+    if (wcp) {
+      var wcT = Math.min(srcT, wcp.duration || srcT)
+      if (wcp.req !== wcT) {
+        var wdp = wcp.seek(wcT)
+        if (ns.pendingDecodes) {
+          ns.pendingDecodes.add(wdp)
+          wdp.finally(function () { ns.pendingDecodes.delete(wdp) })
+        }
+      }
+      return
+    }
+    var target = Math.min(srcT, vid.duration || srcT)
+    if (vid.readyState >= 1 && Math.abs(vid.currentTime - target) > 0.02) {
+      if (ns.pendingDecodes) {
+        var dp = new Promise(function (resolve) {
+          var done = function () { vid.removeEventListener('seeked', done); resolve() }
+          vid.addEventListener('seeked', done)
+          setTimeout(done, 250) // fallback so a missed 'seeked' can't hang the export
+        })
+        ns.pendingDecodes.add(dp)
+        dp.finally(function () { ns.pendingDecodes.delete(dp) })
+      }
+      vid.currentTime = target
+    }
+  }
+  function stepBg(bgEl, bgT) {
+    if (!bgEl.paused) bgEl.pause()
+    var bgTarget = Math.min(bgT, bgEl.duration || bgT)
+    if (bgEl.readyState >= 1 && !bgEl.seeking && Math.abs(bgEl.currentTime - bgTarget) > 0.02) {
+      if (ns.pendingDecodes) {
+        var bgDp = new Promise(function (resolve) {
+          var bgDone = function () { bgEl.removeEventListener('seeked', bgDone); resolve() }
+          bgEl.addEventListener('seeked', bgDone)
+          setTimeout(bgDone, 250) // fallback so a missed 'seeked' can't hang the export
+        })
+        ns.pendingDecodes.add(bgDp)
+        bgDp.finally(function () { ns.pendingDecodes.delete(bgDp) })
+      }
+      bgEl.currentTime = bgTarget
+    }
+  }`;
 var SETUP = `async (ctx) => {
   ;${timelineRuntimeCode2}
   const ns = (window.__vos__ = window.__vos__ || {})
@@ -3311,6 +3360,7 @@ var SETUP = `async (ctx) => {
   if (!ns.waitForVideosReady) ns.waitForVideosReady = async () => {
     if (ns.pendingDecodes.size) await Promise.all([...ns.pendingDecodes])
   }
+  ${FRAME_STEP_SRC}
   const cache = ns.videoCache || (ns.videoCache = new Map())
   // Server capture pages opt into BLOB-backed elements (data.videoFetchMode,
   // merged in by the render queue \u2014 never stored in a doc or config): a
@@ -3504,6 +3554,36 @@ var SETUP = `async (ctx) => {
       else (await load(bgm.key, true)).loop = true
     } catch (e) { console.warn('[voila] background media failed to load', e) }
   }
+  // Frame prep: a capture harness calls every ns.framePrep hook right after
+  // seeking the timeline and before the first paint, then awaits
+  // waitForVideosReady. The footage for the frame is requested HERE, so the
+  // paint that follows draws the right frame the first time. Without the
+  // hook the request could only be issued from inside ON_FRAME (the only
+  // place that knew the source time), so every take frame painted twice:
+  // once with the previous footage, then again after the decode. The steps
+  // are the SAME functions ON_FRAME's syncVid runs (one source, inlined in
+  // both scopes), so the paint finds its target already met and registers
+  // nothing. Keyed by program so a warm LOAD re-registers instead of
+  // chaining; playback never calls it; a harness without it keeps the
+  // two-phase loop and stays correct.
+  ns.framePrep = ns.framePrep || new Map()
+  ns.framePrep.set('voila.card', (t) => {
+    if (ns.isPaused === false) return
+    const d = ctx.data
+    const TL = globalThis.__vosTimeline
+    const srcT = TL.mapTime(d.segments || [], t)
+    if (video.play) stepPaused(video, srcT)
+    if (cam) stepPaused(cam, srcT)
+    if (mic) stepPaused(mic, srcT)
+    const bg2 = d.frame && d.frame.backgroundMedia
+    if (bg2 && bg2.key && bg2.kind !== 'image') {
+      const bgEl2 = cache.get(bg2.key)
+      if (bgEl2 && bgEl2.play) {
+        const bgDur2 = bg2.duration || bgEl2.duration || 0
+        stepBg(bgEl2, bgDur2 > 0 ? t % bgDur2 : 0)
+      }
+    }
+  })
   return { video: video, cam: cam, mic: mic }
 }`;
 var CREATE_CONTENT = `(ctx, setupData) => {
@@ -3582,30 +3662,81 @@ var ON_FRAME = `(ctx, content, dt) => {
   // the GPU texture allocated at the original dims and re-uploads the new canvas
   // against stale dims \u2192 stretch/duplicate; dispose() forces a full realloc) and
   // rebuilding each frustum-filling plane at the new aspect + syncing the camera.
-  // Card OVERSCAN (stage.ts CARD_OVERSCAN): a frame whose inset bleeds the
-  // card past an edge paints it on a canvas and a plane larger than the
-  // frame by ck about the centre, so a tilt that turns the bled edge back
-  // toward the viewer shows card there, not the texture's edge. Every doc
-  // that keeps its card inside the frame (and the flat stub, which has no
-  // card layer) stays at 1: byte- and pixel-identical.
+  // Card OVERSCAN: the card's pose (the tilt track, the card-pose track)
+  // lets the frame see MORE plane than the frame is wide on a receding
+  // side, and the card's content (zoomed footage, a bled card, the shadow)
+  // runs past the frame, so a plane that ends at the frame edge shows its
+  // texture's edge, and the backdrop through it, as soon as it leans. The
+  // card layer's canvas and plane therefore grow about the frame's centre
+  // by the extent the two tracks can reach at the LIVE aspect: each frame
+  // corner's viewing ray meets the posed plane and reads back in plane
+  // units; the extremes of both tracks (largest lean per axis, smallest
+  // scale, largest rise, every sign) bound every interpolated frame. This
+  // is the twin of stage.ts cardVisibleExtent/cardOverscanFor (pinned by
+  // stage.test.ts + cardTilt.test.ts; change them together). A card that
+  // never moves, and the flat stub (no card layer), stay at 1: byte- and
+  // pixel-identical. The factor is quantised up in steps so a scrubbed
+  // pose grows the canvas a few times, not per tick.
   var d = ctx.data || {}
-  var ckIns = (d.frame && d.frame.inset) || {}
-  var ck = r.card && (ckIns.left < 0 || ckIns.right < 0 || ckIns.top < 0 || ckIns.bottom < 0) ? ${CARD_OVERSCAN} : 1
-  var cW = Math.round(W * ck), cH = Math.round(H * ck)
+  var okx = 1, oky = 1
+  if (r.card) {
+    var okT = d.tiltTrack, okP = d.cardPoseTrack, okKf, oki, okv
+    var okRx = 0, okRy = 0, okSc = 1, okDy = 0
+    okKf = okT && okT.keyframes || []
+    for (oki = 0; oki < okKf.length; oki++) { okv = okKf[oki].value || []; okRx = Math.max(okRx, Math.abs(okv[0] || 0)); okRy = Math.max(okRy, Math.abs(okv[1] || 0)) }
+    okKf = okP && okP.keyframes || []
+    for (oki = 0; oki < okKf.length; oki++) { okv = okKf[oki].value || []; okSc = Math.min(okSc, okv[0] == null ? 1 : okv[0]); okDy = Math.max(okDy, Math.abs(okv[1] || 0)) }
+    if (okRx || okRy || okSc < 1 || okDy) {
+      var okD = ${Math.abs(CARD_Z)}, okMax = ${CARD_OVERSCAN_MAX}, okStep = ${CARD_OVERSCAN_STEP}
+      var okHh = okD * Math.tan(${CARD_FOV} * Math.PI / 180 / 2), okHw = okHh * W / H
+      // [max |x|, max |y|] of the frame corners on the posed plane, in
+      // half-plane units (R = Rx \xB7 Ry, three.js Euler XYZ with rz = 0).
+      var okE = function (rxd, ryd, sc, dy) {
+        var rx = rxd * Math.PI / 180, ry = ryd * Math.PI / 180
+        var cx = Math.cos(rx), sx = Math.sin(rx), cy = Math.cos(ry), sy = Math.sin(ry)
+        var scl = Math.max(0.05, sc), py = dy * 2 * okHh
+        var n0 = sy, n1 = -sx * cy, n2 = cx * cy
+        var nPos = n1 * py - n2 * okD
+        var ex = 0, ey = 0
+        for (var kx = -1; kx <= 1; kx += 2) for (var ky = -1; ky <= 1; ky += 2) {
+          var d0 = kx * okHw, d1 = ky * okHh, d2 = -okD
+          var nd = n0 * d0 + n1 * d1 + n2 * d2
+          var lam = nd === 0 ? -1 : nPos / nd
+          if (!(lam > 0)) { ex = okMax; ey = okMax; continue }
+          var q0 = lam * d0, q1 = lam * d1 - py, q2 = lam * d2 + okD
+          ex = Math.max(ex, Math.abs((cy * q0 + sx * sy * q1 - cx * sy * q2) / scl / okHw))
+          ey = Math.max(ey, Math.abs((cx * q1 + sx * q2) / scl / okHh))
+        }
+        return [Math.min(okMax, ex), Math.min(okMax, ey)]
+      }
+      for (var okA = -1; okA <= 1; okA += 2) for (var okB = -1; okB <= 1; okB += 2) for (var okC = -1; okC <= 1; okC += 2) {
+        var okR = okE(okA * okRx, okB * okRy, okSc, okC * okDy)
+        okx = Math.max(okx, okR[0]); oky = Math.max(oky, okR[1])
+      }
+      var okQ = function (k) { if (!(k > 1)) return 1; var q = Math.ceil(Math.round((k + okStep / 10) * 1000) / (okStep * 1000)) * okStep; return Math.min(okMax, Math.round(q * 1000) / 1000) }
+      okx = okQ(okx); oky = okQ(oky)
+    }
+  }
+  // The canvas grows by an EVEN number of pixels on each axis so the frame
+  // region sits on whole pixels inside it (a half-pixel base translation
+  // would resample every draw).
+  var cW = W + 2 * Math.round(W * (okx - 1) / 2), cH = H + 2 * Math.round(H * (oky - 1) / 2)
   if (cv.width !== cW || cv.height !== cH) {
     var THREE = ctx.THREE
     var aspect = W / H
     var cm = ctx.camera
     if (cm && cm.isPerspectiveCamera) { cm.aspect = aspect; cm.updateProjectionMatrix() }
-    var lyr = [[bg, ${BACKGROUND_Z}, 1], [card, ${CARD_Z}, ck], [ov, ${OVERLAY_Z}, 1]]
+    // Each layer's canvas size and its plane's per-axis growth; the card's
+    // plane grows by exactly its canvas's ratio, so a texel stays a pixel.
+    var lyr = [[bg, ${BACKGROUND_Z}, W, H], [card, ${CARD_Z}, cW, cH], [ov, ${OVERLAY_Z}, W, H]]
     for (var Li = 0; Li < lyr.length; Li++) {
-      var Ly = lyr[Li][0], Lz = lyr[Li][1], Lk = lyr[Li][2]
-      if (Ly.canvas) { Ly.canvas.width = Math.round(W * Lk); Ly.canvas.height = Math.round(H * Lk) }
+      var Ly = lyr[Li][0], Lz = lyr[Li][1], Lw = lyr[Li][2], Lhp = lyr[Li][3]
+      if (Ly.canvas) { Ly.canvas.width = Lw; Ly.canvas.height = Lhp }
       if (Ly.texture && Ly.texture.dispose) Ly.texture.dispose()
       if (Ly.mesh && THREE) {
         if (Ly.mesh.geometry && Ly.mesh.geometry.dispose) Ly.mesh.geometry.dispose()
-        var Lh = 2 * Math.abs(Lz) * Math.tan(${CARD_FOV} * Math.PI / 180 / 2) * Lk
-        Ly.mesh.geometry = new THREE.PlaneGeometry(Lh * aspect, Lh)
+        var Lh = 2 * Math.abs(Lz) * Math.tan(${CARD_FOV} * Math.PI / 180 / 2)
+        Ly.mesh.geometry = new THREE.PlaneGeometry(Lh * aspect * (Lw / W), Lh * (Lhp / H))
       }
     }
   }
@@ -3631,6 +3762,7 @@ var ON_FRAME = `(ctx, content, dt) => {
   // correction covers cut-boundary jumps), else step to the exact frame (registering a
   // decode promise so the deterministic export awaits it). Shared by the screen video
   // and the webcam so both stay frame-accurate and in sync.
+  ${FRAME_STEP_SRC}
   function syncVid(vid) {
     try {
       if (playing) {
@@ -3676,35 +3808,11 @@ var ON_FRAME = `(ctx, content, dt) => {
           vid.__voilaAutoMuted = false
         }
       } else {
-        if (!vid.paused) vid.pause()
-        // A WebCodecs provider (capture pages) services the frame by
-        // PTS at decode speed \u2014 no element seek, no 250ms settle cap. The
-        // element stays paused as the dimension source and fallback.
-        var wcp = vid.__voilaWc
-        if (wcp) {
-          var wcT = Math.min(srcT, wcp.duration || srcT)
-          if (wcp.req !== wcT) {
-            var wdp = wcp.seek(wcT)
-            if (ns.pendingDecodes) {
-              ns.pendingDecodes.add(wdp)
-              wdp.finally(function () { ns.pendingDecodes.delete(wdp) })
-            }
-          }
-          return
-        }
-        var target = Math.min(srcT, vid.duration || srcT)
-        if (vid.readyState >= 1 && Math.abs(vid.currentTime - target) > 0.02) {
-          if (ns.pendingDecodes) {
-            var dp = new Promise(function (resolve) {
-              var done = function () { vid.removeEventListener('seeked', done); resolve() }
-              vid.addEventListener('seeked', done)
-              setTimeout(done, 250) // fallback so a missed 'seeked' can't hang the export
-            })
-            ns.pendingDecodes.add(dp)
-            dp.finally(function () { ns.pendingDecodes.delete(dp) })
-          }
-          vid.currentTime = target
-        }
+        // The paused step (FRAME_STEP_SRC): the provider by PTS, else the
+        // element seek. A capture harness that ran the frame-prep hook has
+        // already met this target, so nothing registers and the paint is
+        // the one that counts.
+        stepPaused(vid, srcT)
       }
     } catch (e) {}
   }
@@ -3798,27 +3906,9 @@ var ON_FRAME = `(ctx, content, dt) => {
           if (bgDur > 0 && !bgEl.seeking && bgDrift > 0.3 && bgDur - bgDrift > 0.3) bgEl.currentTime = bgT
           if (bgEl.paused) { var bgP = bgEl.play(); if (bgP && bgP.catch) bgP.catch(function () {}) }
         } else {
-          if (!bgEl.paused) bgEl.pause()
-          var bgTarget = Math.min(bgT, bgEl.duration || bgT)
-          // COALESCE seeks: a scrub moves t every frame, and re-assigning
-          // currentTime ABORTS the in-flight seek \u2014 on a remote (assets.vos.so)
-          // source that keeps the element mid-seek for the whole drag, so no
-          // frame ever decodes and the background pops in seconds late. Issue
-          // a seek only when none is in flight; the frame after 'seeked' fires
-          // corrects toward the latest target, so seeks run serially and
-          // converge on the release point.
-          if (bgEl.readyState >= 1 && !bgEl.seeking && Math.abs(bgEl.currentTime - bgTarget) > 0.02) {
-            if (ns.pendingDecodes) {
-              var bgDp = new Promise(function (resolve) {
-                var bgDone = function () { bgEl.removeEventListener('seeked', bgDone); resolve() }
-                bgEl.addEventListener('seeked', bgDone)
-                setTimeout(bgDone, 250) // fallback so a missed 'seeked' can't hang the export
-              })
-              ns.pendingDecodes.add(bgDp)
-              bgDp.finally(function () { ns.pendingDecodes.delete(bgDp) })
-            }
-            bgEl.currentTime = bgTarget
-          }
+          // The background step (FRAME_STEP_SRC): a coalesced seek, met
+          // already when a capture harness ran the frame-prep hook.
+          stepBg(bgEl, bgT)
         }
       } catch (e) {}
     }
@@ -3929,9 +4019,10 @@ var ON_FRAME = `(ctx, content, dt) => {
   // the contain-fit card shows the background layer through the plane's alpha.
   // Under overscan the canvas is larger than the frame and every frame-space
   // draw below rides a base translation to its centre.
-  if (ck !== 1) c.setTransform(1, 0, 0, 1, 0, 0)
+  var okOn = cW !== W || cH !== H
+  if (okOn) c.setTransform(1, 0, 0, 1, 0, 0)
   c.clearRect(0, 0, cv.width, cv.height)
-  if (ck !== 1) c.setTransform(1, 0, 0, 1, (cW - W) / 2, (cH - H) / 2)
+  if (okOn) c.setTransform(1, 0, 0, 1, (cW - W) / 2, (cH - H) / 2)
   // Footage is nearly always drawn SMALLER than it was recorded (a 1920
   // recording in a padded 1080 card, or a 440-wide tile): the default
   // bilinear tap aliases and blurs a large downscale; 'high' resamples.
@@ -4442,8 +4533,10 @@ var ON_FRAME = `(ctx, content, dt) => {
     card.mesh.rotation.y = ry
     // The card's pose through an entrance or an end card: [scale, dy,
     // opacity]; absent = the rest pose, exactly as before the track existed.
+    // dy is a fraction of the FRAME plane's height (not the geometry's,
+    // which the overscan grows).
     var cpk = d.cardPoseTrack
-    var cpH = card.mesh.geometry && card.mesh.geometry.parameters ? card.mesh.geometry.parameters.height : 0
+    var cpH = 2 * ${Math.abs(CARD_Z)} * Math.tan(${CARD_FOV} * Math.PI / 180 / 2)
     if (cpk && cpk.keyframes && cpk.keyframes.length && card.mesh.scale && card.mesh.position) {
       var cpv = TL.sample(cpk, t, TL.lerpArray)
       card.mesh.scale.x = cpv[0]; card.mesh.scale.y = cpv[0]