@vosjs/studio-core 0.21.0 → 0.22.1

package/dist/index.js

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