@keyframerdev/vitals 0.1.2 → 0.1.4

package/README.md

@@ -27,12 +27,15 @@ At the app's entry, with the project's field key (`kfp_live_…`, public and wri
 ```ts
 import { startVitals } from '@keyframerdev/vitals'
 import AsyncStorage from '@react-native-async-storage/async-storage'
-import * as Application from 'expo-application'
+import Constants from 'expo-constants'
+import { Platform } from 'react-native'
+
+const build = Platform.OS === 'ios' ? Constants.platform?.ios?.buildNumber : Constants.expoConfig?.android?.versionCode
 
 startVitals({
   key: 'kfp_live_…',
-  appVersion: Application.nativeApplicationVersion!,
-  build: Application.nativeBuildVersion ?? undefined,
+  appVersion: Constants.expoConfig?.version ?? '0',
+  build: build == null ? undefined : String(build),
   navigationRef, // React Navigation's createNavigationContainerRef() or expo-router's useNavigationContainerRef()
   storage: AsyncStorage, // optional: checkpoints, retries and the daily cap survive restarts
 })
@@ -40,6 +43,10 @@ startVitals({
 
 Nothing is measured or sent before `startVitals`. If your app asks for consent, call it after.
 
+`expo-constants` rather than `expo-application`: the latter is a native module, and an EAS Update that adds it crashes every installed binary built without it. Without Expo, use `react-native-device-info` or your own constants.
+
+Before your store release, declare it in the stores' privacy forms (App Store: Diagnostics > Performance Data; Google Play: Diagnostics) and add a sentence to your privacy policy: [what to declare](https://keyframer.dev/inspector/docs/vitals/store-privacy).
+
 | Option | Default | What it does |
 | --- | --- | --- |
 | `key` | required | The project's field key |

package/dist/index.js

@@ -618,9 +618,13 @@ function slimArg(a, idOf) {
   return null;
 }
 
+// ../protocol/src/vitals-validate.ts
+var VITALS_MAX_HZ = 240;
+var MAX_FRAME_MS = 10 * 60 * 1000;
+
 // src/version.ts
 var SDK_NAME = "@keyframerdev/vitals";
-var SDK_VERSION = "0.1.2";
+var SDK_VERSION = "0.1.4";
 
 // src/controller.ts
 var STORAGE_KEYS = {
@@ -707,6 +711,11 @@ class VitalsController {
   meters = null;
   screen = "app";
   reduceMotion = false;
+  traced = {};
+  tracedAnims = 0;
+  metering = false;
+  drawing = true;
+  toldDevelopment = null;
   constructor(env) {
     this.env = env;
   }
@@ -736,7 +745,8 @@ class VitalsController {
       this.enabled = false;
       return;
     }
-    this.config = cached?.config ?? null;
+    const dev = opts.environment === "development";
+    this.config = dev ? null : cached?.config ?? null;
     if (!this.allowed()) {
       this.enabled = false;
       return;
@@ -753,7 +763,7 @@ class VitalsController {
       return;
     this.retryStep = 0;
     this.scheduleRetry();
-    const fresh = cached && this.env.wall() - cached.at < Math.max(60, cached.config.ttlSec) * 1000;
+    const fresh = !dev && cached && this.env.wall() - cached.at < Math.max(60, cached.config.ttlSec) * 1000;
     if (!fresh)
       this.configTimer = this.env.setTimeout(() => void this.fetchConfig(run), START_DELAY_MS);
     await this.beginSession(run);
@@ -803,6 +813,7 @@ class VitalsController {
       }
     }
     this.sampled = sampled;
+    this.debug(`session ${this.nonce.slice(0, 6)}: ${sampled ? "sampled" : "not sampled"} (rate ${this.sampleRate}, environment ${env}` + `${devOk ? "" : ", the project does not collect development builds"})`);
     if (!sampled)
       return;
     this.collector.clear();
@@ -815,6 +826,7 @@ class VitalsController {
     this.meters.install();
   }
   endSampling() {
+    this.metering = false;
     if (this.sampled) {
       this.meters?.stop();
       this.meters?.uninstall();
@@ -829,10 +841,17 @@ class VitalsController {
       this.checkpointTimer = null;
     }
   }
-  appState(active) {
+  appState(active, drawing = active) {
     if (!this.enabled)
       return;
     const now = this.env.now();
+    if (this.drawing !== drawing) {
+      this.drawing = drawing;
+      if (!drawing && this.sampled && this.foreground) {
+        this.pauseMeters(now);
+        this.debug("app inactive: meters paused until it is active again");
+      }
+    }
     if (!active && this.foreground) {
       this.foreground = false;
       this.backgroundAt = now;
@@ -841,8 +860,7 @@ class VitalsController {
         this.retryTimer = null;
       }
       if (this.sampled) {
-        this.gate.reset();
-        this.meters?.stop();
+        this.pauseMeters(now);
         this.collector.foreground(false, now);
         this.closeWindow("background");
       }
@@ -882,6 +900,8 @@ class VitalsController {
       if (isRef2(a))
         this.collector.consume(a.$anim);
     this.collector.animStart(site, t, ms, thread, eid);
+    if (this.opts?.debug)
+      this.tracedAnims++;
     this.motion(t + ms, t);
   }
   layout(site, kind, builder, t = this.env.now()) {
@@ -905,17 +925,35 @@ class VitalsController {
     if (!this.sampled || !this.foreground)
       return;
     this.collector.touch(down, t);
+    if (!this.drawing)
+      return;
     if (this.gate.touch(down, t))
       this.opened(t);
     this.keepUi(t);
   }
   motion(end, now) {
+    if (!this.drawing)
+      return;
     if (this.gate.note(end, now))
       this.opened(now);
     this.keepUi(now);
     this.checkWindow(now);
   }
+  pauseMeters(now) {
+    this.gate.reset();
+    this.meters?.stop();
+    this.collector.measure(false, now);
+    if (this.metering && this.opts?.debug) {
+      this.flushTrace();
+      this.debug("meters off: the app left the screen");
+    }
+    this.metering = false;
+    this.uiKnownUntil = -Infinity;
+  }
   opened(now) {
+    if (!this.metering)
+      this.debug("meters on: something moves");
+    this.metering = true;
     this.collector.measure(true, now);
     this.meters?.start();
     this.scheduleCheckpoint();
@@ -929,12 +967,20 @@ class VitalsController {
     }
   }
   jsFrame(t, dt, budget) {
-    if (!this.sampled || !this.foreground)
+    if (!this.sampled || !this.foreground || !this.drawing)
       return false;
-    if (dt > 0)
+    if (dt > 0) {
       this.collector.frame("js", t, dt, budget);
+      if (this.opts?.debug)
+        this.traceFrame("js", dt, t);
+    }
     if (!this.gate.open(t)) {
       this.collector.measure(false, Math.min(t, this.gate.until));
+      if (this.metering && this.opts?.debug) {
+        this.flushTrace();
+        this.debug("meters off: the motion window closed");
+      }
+      this.metering = false;
       return false;
     }
     this.keepUi(t);
@@ -946,6 +992,49 @@ class VitalsController {
       return;
     for (let i = 0;i + 2 < buf.length; i += 3)
       this.collector.frame("ui", buf[i], buf[i + 1], buf[i + 2]);
+    if (this.opts?.debug)
+      for (let i = 0;i + 2 < buf.length; i += 3)
+        this.traceFrame("ui", buf[i + 1], buf[i]);
+  }
+  traceFrame(thread, dt, t) {
+    const cur = this.traced[thread];
+    if (cur && (t - cur.since >= 1000 || t - dt > cur.last + 100))
+      this.flushTrace();
+    const s = this.traced[thread] ??= { n: 0, sum: 0, min: Infinity, max: 0, since: t - dt, last: t };
+    s.n++;
+    s.sum += dt;
+    if (dt < s.min)
+      s.min = dt;
+    if (dt > s.max)
+      s.max = dt;
+    s.since = Math.min(s.since, t - dt);
+    s.last = Math.max(s.last, t);
+  }
+  flushTrace() {
+    const all = Object.values(this.traced);
+    if (!all.length)
+      return;
+    const ms = (v) => (Math.round(v * 10) / 10).toString();
+    const part = (th) => {
+      const s = this.traced[th];
+      if (!s)
+        return `${th}: no frames`;
+      const span = Math.max(1, s.last - s.since);
+      return `${th}: ${s.n} frames in ${Math.round(span)} ms, ${Math.round(s.n * 1000 / span)}/s (gap min ${ms(s.min)}, avg ${ms(s.sum / s.n)}, max ${ms(s.max)} ms)`;
+    };
+    this.debug(`on ${this.collector.currentScreen}, ${this.tracedAnims} animation starts. ${part("js")}; ${part("ui")}`);
+    this.traced = {};
+    this.tracedAnims = 0;
+  }
+  traceReport(report) {
+    const frames = {};
+    for (const s of report.screens)
+      for (const [th, st] of Object.entries(s.threads))
+        frames[th] = (frames[th] ?? 0) + (st?.frames ?? 0);
+    const measured = report.session.measuredMs;
+    const cap = Math.ceil(measured * VITALS_MAX_HZ / 1000);
+    const over = Object.entries(frames).filter(([, n]) => n > cap).map(([th]) => th);
+    this.debug(`report ${report.session.seq} (${report.session.ended}): measured ${measured} ms of ${report.session.foregroundMs} ms in the foreground, ` + `so at most about ${cap} frames a thread; js ${frames.js ?? 0}, ui ${frames.ui ?? 0}` + `${over.length ? ` (too many on ${over.join(" and ")}: the server will refuse it)` : ""}; ` + `${report.screens.length} screens, ${report.sites.length} animation sites`);
   }
   checkWindow(now) {
     if (this.collector.foregroundAt(now) >= VITALS_WINDOW_MS)
@@ -971,10 +1060,15 @@ class VitalsController {
     }
     const storage = this.opts?.storage;
     if (!report) {
+      this.debug(`window closed (${ended}) with nothing to report`);
       await write(storage, STORAGE_KEYS.checkpoint, null);
       return;
     }
     this.seq++;
+    if (this.opts?.debug) {
+      this.flushTrace();
+      this.traceReport(report);
+    }
     await write(storage, STORAGE_KEYS.checkpoint, report);
     await this.send(JSON.stringify(report));
     await write(storage, STORAGE_KEYS.checkpoint, null);
@@ -1103,6 +1197,7 @@ class VitalsController {
         body
       });
       if (res.status === 200) {
+        this.debug("report accepted");
         const json = await res.json().catch(() => null);
         if (json?.config)
           await this.applyConfig(json.config);
@@ -1126,13 +1221,19 @@ class VitalsController {
     if (run !== this.run || !this.opts)
       return;
     try {
-      const res = await this.env.fetch(`${this.endpoint()}/v1/config/${encodeURIComponent(this.opts.key)}`, { method: "GET", headers: {} });
+      const fresh = Math.round(this.env.wall()).toString(36);
+      const res = await this.env.fetch(`${this.endpoint()}/v1/config/${encodeURIComponent(this.opts.key)}?t=${fresh}`, {
+        method: "GET",
+        headers: { "Cache-Control": "no-cache" }
+      });
       if (run !== this.run)
         return;
       if (res.status === 200) {
         const config = await res.json();
-        if (config && typeof config === "object" && typeof config.sampleRate === "number")
+        if (config && typeof config === "object" && typeof config.sampleRate === "number") {
+          this.debug(`config: sample rate ${config.sampleRate}, development builds ${config.collect?.development ? "collected" : "not collected"}`);
           await this.applyConfig(config);
+        }
       } else if (res.status === 401 || res.status === 410)
         await this.killSwitch();
     } catch {}
@@ -1148,6 +1249,19 @@ class VitalsController {
     }
     if (!config.collect.reduceMotion)
       this.setReduceMotion(false);
+    if (this.opts?.environment === "development")
+      this.developmentConfig(config.collect.development);
+  }
+  developmentConfig(kept) {
+    if (this.toldDevelopment !== kept) {
+      this.toldDevelopment = kept;
+      if (kept)
+        this.debug("this project keeps development builds: this build's reports show in the dashboard's Development view");
+      else
+        this.env.log?.("[keyframer vitals] This project does not keep reports from development builds, so this build sends nothing. " + `To test here, turn on "Development builds" in the project's setup on keyframer.dev, then reload. Release builds are not affected.`, "info");
+    }
+    if (!kept && this.sampled)
+      this.endSampling();
   }
   async killSwitch() {
     this.log("turned off on this device for 7 days by the project");
@@ -1183,6 +1297,10 @@ class VitalsController {
   log(message) {
     this.env.log?.(`[keyframer vitals] ${message}`);
   }
+  debug(message) {
+    if (this.opts?.debug)
+      this.env.log?.(`[keyframer vitals] ${message}`, "debug");
+  }
 }
 
 // src/hook.ts
@@ -1266,14 +1384,22 @@ function tickFieldMeter(f, t) {
 }
 
 // src/jsLoop.ts
-function createJsLoop({ raf, frame }) {
+var MIN_FRAME_GAP_MS = 1000 / 240;
+function createJsLoop({ raf, later, now, frame }) {
   let running = false;
   let gen = 0;
+  let last = -1;
   const chain = (mine) => {
     const tick = () => {
       if (!running || mine !== gen)
         return;
-      if (frame())
+      const t = now();
+      if (last >= 0 && t - last < MIN_FRAME_GAP_MS) {
+        later(tick);
+        return;
+      }
+      last = t;
+      if (frame(t))
         raf(tick);
       else
         running = false;
@@ -1289,6 +1415,7 @@ function createJsLoop({ raf, frame }) {
         return false;
       running = true;
       gen++;
+      last = -1;
       raf(chain(gen));
       return true;
     },
@@ -1323,7 +1450,7 @@ var env = {
   setTimeout: (fn, ms) => setTimeout(fn, ms),
   clearTimeout: (h) => clearTimeout(h),
   platform: { os: Platform.OS === "ios" ? "ios" : "android", osMajor: osMajor() },
-  log: (m) => console.warn(m)
+  log: (m, level) => level === "debug" || level === "info" ? console.log(m) : console.warn(m)
 };
 var controller = new VitalsController(env);
 var jsHook = createJsHook(controller, () => checkScreen());
@@ -1441,8 +1568,9 @@ function extendUi(ms) {
 var jsMeter = createFieldMeter("js");
 var jsLoop = createJsLoop({
   raf: (cb) => requestAnimationFrame(cb),
-  frame: () => {
-    const t = now();
+  later: (cb) => setTimeout(cb, 16),
+  now,
+  frame: (t) => {
     const last = jsMeter.m.last;
     const interval = jsMeter.m.interval;
     tickFrameMeter(jsMeter.m, t);
@@ -1526,7 +1654,11 @@ async function startVitals(opts) {
   lastRoute = null;
   manualScreen = false;
   const environment = opts.environment ?? (typeof __DEV__ !== "undefined" && __DEV__ ? "development" : "production");
-  const appState = AppState.addEventListener("change", (s) => controller.appState(s !== "background"));
+  const appState = AppState.addEventListener("change", (s) => {
+    if (s !== "active")
+      touchDown = false;
+    controller.appState(s !== "background", s === "active");
+  });
   subscriptions.push(() => appState.remove());
   if (opts.navigationRef) {
     const off = opts.navigationRef.addListener("state", checkScreen);

package/dist/types/controller.d.ts

@@ -48,6 +48,12 @@ export type ControllerOptions = {
     endpoint?: string;
     /** Bundle id or package name. */
     appId?: string;
+    /**
+     * Logs what this device measures and sends, with console.log: the sampling decision, when the frame
+     * meters run, frames a second per thread with their gaps, and each report against the server's
+     * limits. For development builds; leave it off in production.
+     */
+    debug?: boolean;
 };
 type HttpResponse = {
     status: number;
@@ -72,7 +78,8 @@ export type ControllerEnv = {
     };
     /** Local calendar day of a wall time, `YYYY-MM-DD`. */
     day?(wall: number): string;
-    log?(message: string): void;
+    /** Warnings (refusals, kill switch), notes for the developer ('info') and, with `debug`, the trace ('debug'). */
+    log?(message: string, level?: 'warn' | 'info' | 'debug'): void;
 };
 /** The frame meters and the instrumentation hooks, as the platform runs them. */
 export type Meters = {
@@ -134,6 +141,19 @@ export declare class VitalsController {
     private meters;
     private screen;
     private reduceMotion;
+    /**
+     * debug: frames per thread, printed about once a second. Each thread keeps its own span (its earliest
+     * frame start to its latest end): UI frames reach the JS side in batches of about half a second, so a
+     * shared span would halve one thread's rate.
+     */
+    private traced;
+    private tracedAnims;
+    /** debug: between "meters on" and "meters off", so each is logged once per motion window. */
+    private metering;
+    /** False while the app is in the foreground but not active (iOS 'inactive'): nothing is measured. */
+    private drawing;
+    /** What this launch last told the developer about the project keeping development builds. */
+    private toldDevelopment;
     constructor(env: ControllerEnv);
     get isSampled(): boolean;
     get isEnabled(): boolean;
@@ -150,8 +170,11 @@ export declare class VitalsController {
     stop(drop: boolean): Promise<void>;
     private beginSession;
     private endSampling;
-    /** AppState: 'active' or anything else (background, inactive counts as foreground on iOS). */
-    appState(active: boolean): void;
+    /**
+     * AppState. `active`: in the foreground (iOS 'inactive' counts, the app is still on screen). `drawing`:
+     * 'active' itself; while it is false the meters stop and motion does not start them (jsLoop.ts).
+     */
+    appState(active: boolean, drawing?: boolean): void;
     setScreen(name: string): void;
     setReduceMotion(on: boolean): void;
     /** A new id for an animation call on the JS thread (the UI runtime numbers its own from UI_EVENT_BASE). */
@@ -169,6 +192,8 @@ export declare class VitalsController {
     scroll(t?: number): void;
     touch(down: boolean, t?: number): void;
     private motion;
+    /** Meters off and the gate shut: measured time stops at `now`; the next motion starts them again. */
+    private pauseMeters;
     private opened;
     /** The UI loop keeps its own time: tell it how long the gate stays open when that grows. */
     private keepUi;
@@ -179,6 +204,10 @@ export declare class VitalsController {
     jsFrame(t: number, dt: number, budget: number): boolean;
     /** UI-thread frames as `[t, dt, budget, …]`, `t` already on the JS clock. */
     uiFrames(buf: number[]): void;
+    private traceFrame;
+    /** One line: frames a second per thread (60, 90 or 120 when the meters are right) and their gaps. */
+    private flushTrace;
+    private traceReport;
     private checkWindow;
     /** The report the open window would send now, or null when it holds nothing. */
     report(ended: VitalsReport['session']['ended'], now?: number): VitalsReport | null;
@@ -200,10 +229,16 @@ export declare class VitalsController {
     private fetchConfig;
     /** A config from the server: cached, and acted on (stop, disabled, a minimum SDK version). */
     applyConfig(config: VitalsConfig): Promise<void>;
+    /**
+     * A development build learns whether the project keeps its reports. Off: the developer is told once a
+     * launch (the server would drop every report) and measuring stops; on: said under `debug`.
+     */
+    private developmentConfig;
     private killSwitch;
     private allowed;
     private rate;
     private clearTimers;
     private log;
+    private debug;
 }
 export {};

package/dist/types/jsLoop.d.ts

@@ -1,9 +1,14 @@
+/** The shortest gap between two display frames: 240 Hz, the server's limit (VITALS_MAX_HZ). */
+export declare const MIN_FRAME_GAP_MS: number;
 export type JsLoopDeps = {
     raf: (cb: () => void) => unknown;
-    /** One frame: return false to end the loop (the motion window closed). */
-    frame: () => boolean;
+    /** Waits about a frame without the display (setTimeout): used when requestAnimationFrame stops waiting for it. */
+    later: (cb: () => void) => unknown;
+    now: () => number;
+    /** One frame that ended at `t`: return false to end the loop (the motion window closed). */
+    frame: (t: number) => boolean;
 };
-export declare function createJsLoop({ raf, frame }: JsLoopDeps): {
+export declare function createJsLoop({ raf, later, now, frame }: JsLoopDeps): {
     readonly running: boolean;
     /** Starts the loop unless it is already running. Returns true when it started a new chain. */
     start(): boolean;

package/dist/types/version.d.ts

@@ -1,3 +1,3 @@
 /** This package's version: sent in every report's `sdk`, and compared with the config's `minSdk`. Keep it in step with package.json. */
 export declare const SDK_NAME = "@keyframerdev/vitals";
-export declare const SDK_VERSION = "0.1.2";
+export declare const SDK_VERSION = "0.1.4";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keyframerdev/vitals",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Motion Vitals for React Native: slow frames and janky animations from production, by screen and call site",
   "keywords": [
     "react-native",