@vosjs/studio-core 0.20.0 → 0.21.0

package/dist/index.d.ts

@@ -61,7 +61,13 @@ interface ZoomStyleParams {
     autoZoom: boolean;
     /** clicks within this many seconds merge into one span (session merge). */
     clusterGap: number;
-    /** minimum clicks for a cluster to earn a zoom (Cursorful's ≥2 rule). */
+    /**
+     * Minimum clicks for a cluster to earn a zoom. Every style is 1: the
+     * Cursorful ≥2 rule glide and keynote carried was never in effect on a
+     * recorded take (the recorder counted each press twice, so a lone click
+     * was a pair on most pages and a stray on the rest), and the lone click on
+     * a button is the zoom people miss when it goes.
+     */
     minClusterClicks: number;
     /** zoom so the clicked element fills ~this fraction of the frame. */
     targetFill: number;
@@ -2023,11 +2029,18 @@ interface SmoothOptions {
 declare function smoothCursor(track: CursorTrack, options?: SmoothOptions): SmoothPoint[];
 
 /**
- * A click cluster whose element FITS the frame at less than this level is
- * not a target: it is a drag (aiming, scrubbing, moving a thing across the
- * canvas) or a frame-sized surface, and a zoom on it says nothing. Five real
- * takes (2026-08-25) each carried 1-4 such clusters, planned at the floor
- * level for 10-25s; every one was dropped by hand. Now they plan nothing.
+ * A press whose element FITS the frame at less than this level is not a
+ * target: it is a drag (aiming, scrubbing, moving a thing across the canvas)
+ * or a frame-sized surface (a canvas, a panel, a modal clicked to focus or
+ * dismiss it), and a zoom on it says nothing. Five real takes (2026-08-25)
+ * each carried 1-4 clusters of these, planned at the floor level for 10-25s;
+ * every one was dropped by hand. Now they plan nothing.
+ *
+ * The rule is PER PRESS, never per cluster: a target cluster's level came
+ * from its LARGEST element, so one press on a panel inside a chain of button
+ * clicks read the whole chain as a drag and threw every zoom away — two real
+ * takes (2026-09-11) lost 5 of 8 and 4 of 4 clicks that way. A surface press
+ * is set aside before clustering; the targets around it keep their zoom.
  */
 declare const DRAG_FIT_LEVEL = 1.15;
 interface PlanOptions {
@@ -2117,6 +2130,12 @@ interface Moment {
     /** Normalized target bounds (element rect union), when the events had one. */
     rect: NormRect | null;
     clicks?: number;
+    /**
+     * A click cluster on a frame-sized element (a canvas, a panel, a drag):
+     * the planner frames nothing on it (DRAG_FIT_LEVEL), so a zoom here is
+     * the agent's call, never a proposal.
+     */
+    surface?: boolean;
     pings?: number;
     /** Motion in the window, 0..1 (fraction of changed pixels), null without frames. */
     activity: number | null;

package/dist/index.js

@@ -1135,7 +1135,7 @@ var ZOOM_STYLES = {
   glide: {
     autoZoom: true,
     clusterGap: 3,
-    minClusterClicks: 2,
+    minClusterClicks: 1,
     targetFill: 0.42,
     minLevel: 1.3,
     maxLevel: 1.8,
@@ -1308,7 +1308,7 @@ var ZOOM_STYLES = {
   keynote: {
     autoZoom: true,
     clusterGap: 3,
-    minClusterClicks: 2,
+    minClusterClicks: 1,
     targetFill: 0.42,
     minLevel: 1.3,
     maxLevel: 1.8,
@@ -1417,13 +1417,17 @@ var DWELL_MIN = 0.45;
 var DWELL_MAX = 2.6;
 var DWELL_SPACING = 1.8;
 var DRAG_FIT_LEVEL = 1.15;
+var PRESS_ECHO_MS = 4;
+var PRESS_ECHO_PX = 2;
 var TYPING_MIN_PINGS = 2;
 var TYPING_MIN_DUR = 0.5;
 var TYPING_CLICK_ABSORB = 1.5;
 var TYPING_REFOCUS_FRAC = 0.08;
 function groupTrack(track, opts) {
-  const { width, height, clusterGap, typingGap, typingZoom } = opts;
-  const clicks = track.filter((e) => e.type === "down").map((e) => ({ t: e.t / 1e3, rect: e.rect, x: e.x, y: e.y }));
+  const { width, height, clusterGap, typingGap, typingZoom, targetFill } = opts;
+  const clicks = dedupePresses(
+    track.filter((e) => e.type === "down")
+  ).map((e) => ({ t: e.t / 1e3, rect: e.rect, x: e.x, y: e.y }));
   const sessions = typingZoom ? typingSessions(track, width, height, typingGap) : [];
   const absorbed = /* @__PURE__ */ new Set();
   for (const s of sessions) {
@@ -1441,15 +1445,43 @@ function groupTrack(track, opts) {
       s.events = [best, ...s.events];
     }
   }
-  const clusters = [];
+  const targets = [];
+  const surfaces = [];
   for (const c of clicks) {
     if (absorbed.has(c)) continue;
-    const last = clusters.at(-1);
-    const prev = last?.at(-1);
-    if (last && prev && c.t - prev.t <= clusterGap) last.push(c);
-    else clusters.push([c]);
+    if (isSurfacePress(c, width, height, targetFill)) surfaces.push(c);
+    else targets.push(c);
+  }
+  const chain = (list) => {
+    const clusters = [];
+    for (const c of list) {
+      const last = clusters.at(-1);
+      const prev = last?.at(-1);
+      if (last && prev && c.t - prev.t <= clusterGap) last.push(c);
+      else clusters.push([c]);
+    }
+    return clusters;
+  };
+  return { sessions, clusters: chain(targets), surfaces: chain(surfaces) };
+}
+function dedupePresses(downs) {
+  const kept = [];
+  for (const e of downs) {
+    const prev = kept.at(-1);
+    if (prev && e.t - prev.t <= PRESS_ECHO_MS && Math.abs(e.x - prev.x) <= PRESS_ECHO_PX && Math.abs(e.y - prev.y) <= PRESS_ECHO_PX) {
+      continue;
+    }
+    kept.push(e);
   }
-  return { sessions, clusters };
+  return kept;
+}
+function fitLevel(rect, width, height, targetFill) {
+  if (!rect || rect.w <= 0 || rect.h <= 0) return null;
+  return Math.min(width * targetFill / rect.w, height * targetFill / rect.h);
+}
+function isSurfacePress(c, width, height, targetFill) {
+  const fit = fitLevel(c.rect, width, height, targetFill);
+  return fit !== null && fit < DRAG_FIT_LEVEL;
 }
 function planAutoZoom(track, options) {
   const style = resolveZoomStyle(options.style, options.params);
@@ -1470,31 +1502,31 @@ function planAutoZoom(track, options) {
     typingHold = style.typingHold,
     typingMinLevel = style.typingMinLevel
   } = options;
-  const { sessions, clusters } = groupTrack(track, {
+  const { sessions, clusters, surfaces } = groupTrack(track, {
     width,
     height,
     clusterGap,
     typingGap,
-    typingZoom
+    typingZoom,
+    targetFill
   });
   const eligible = clusters.filter((c) => c.length >= minClusterClicks);
   const clickSpans = [];
-  const dragReserved = [];
+  const dragReserved = surfaces.map((cluster, i) => {
+    const f = clusterFocus(cluster, width, height);
+    return {
+      id: `drag${i}`,
+      in: Math.max(0, cluster[0].t - lead),
+      out: cluster[cluster.length - 1].t + hold,
+      level: 1,
+      cx: f.cx,
+      cy: f.cy
+    };
+  });
   for (const cluster of eligible) {
     const first = cluster[0];
     const last = cluster[cluster.length - 1];
     const f = focusFor(cluster, width, height, targetFill, minLevel, maxLevel);
-    if (f.fit !== null && f.fit < DRAG_FIT_LEVEL) {
-      dragReserved.push({
-        id: `drag${dragReserved.length}`,
-        in: Math.max(0, first.t - lead),
-        out: last.t + hold,
-        level: 1,
-        cx: f.cx,
-        cy: f.cy
-      });
-      continue;
-    }
     clickSpans.push({
       in: Math.max(0, first.t - lead),
       out: last.t + hold,
@@ -1668,15 +1700,8 @@ function focusFor(cluster, width, height, targetFill, minLevel, maxLevel) {
   const n = cluster.length;
   const cx = clamp012(sx / n / width);
   const cy = clamp012(sy / n / height);
-  let level = maxLevel;
-  let fit = null;
-  if (maxW > 0 && maxH > 0) {
-    const fitX = width * targetFill / maxW;
-    const fitY = height * targetFill / maxH;
-    level = Math.min(fitX, fitY);
-    fit = level;
-  }
-  return { cx, cy, level: clamp2(level, minLevel, maxLevel), fit };
+  const level = fitLevel({ x: 0, y: 0, w: maxW, h: maxH }, width, height, targetFill) ?? maxLevel;
+  return { cx, cy, level: clamp2(level, minLevel, maxLevel) };
 }
 function clusterFocus(events, width, height) {
   let sx = 0;
@@ -6962,14 +6987,15 @@ function momentsFromDoc(doc, plan, opts = {}) {
     rect: null
   });
   if (track.length) {
-    const { sessions, clusters } = groupTrack(track, {
+    const { sessions, clusters, surfaces } = groupTrack(track, {
       width,
       height,
       clusterGap: style.clusterGap,
       typingGap: style.typingGap,
-      typingZoom: style.typingZoom
+      typingZoom: style.typingZoom,
+      targetFill: style.targetFill
     });
-    for (const c of clusters) {
+    const pressed = (c, surface) => {
       const f = clusterFocus(c, width, height);
       drafts.push({
         kind: "click",
@@ -6980,9 +7006,12 @@ function momentsFromDoc(doc, plan, opts = {}) {
         at: c[0].t,
         focus: { cx: f.cx, cy: f.cy },
         rect: f.rect,
-        clicks: c.length
+        clicks: c.length,
+        ...surface ? { surface: true } : {}
       });
-    }
+    };
+    for (const c of clusters) pressed(c, false);
+    for (const c of surfaces) pressed(c, true);
     for (const s of sessions) {
       const f = clusterFocus(s.events, width, height);
       drafts.push({
@@ -7102,6 +7131,7 @@ function momentsFromDoc(doc, plan, opts = {}) {
         h: round8(d.rect.h)
       } : null,
       ...d.clicks !== void 0 ? { clicks: d.clicks } : {},
+      ...d.surface ? { surface: true } : {},
       ...d.pings !== void 0 ? { pings: d.pings } : {},
       activity: activityOf(opts.bins, d),
       proposed,