@keyframerdev/vitals 0.0.0-stage → 0.1.1

package/dist/runtime.js

@@ -0,0 +1,145 @@
+// src/runtime.ts
+function __kfvAnim(fn, site, ...args) {
+  "worklet";
+  const hook = globalThis.__KF_VITALS__;
+  if (hook === undefined || hook === null)
+    return fn(...args);
+  return hook.anim(fn, site, args, null, null);
+}
+function __kfvAnimVia(via, site, fn, viaSite, ...args) {
+  "worklet";
+  const hook = globalThis.__KF_VITALS__;
+  if (hook === undefined || hook === null)
+    return via(fn, viaSite, ...args);
+  return hook.anim(fn, site, args, via, viaSite);
+}
+function __kfvScroll() {
+  "worklet";
+  const hook = globalThis.__KF_VITALS__;
+  if (hook !== undefined && hook !== null)
+    hook.scroll();
+}
+var scrollWrappers = new WeakMap;
+function __kfvScrollJs(fn) {
+  if (typeof fn !== "function")
+    return fn;
+  const cached = scrollWrappers.get(fn);
+  if (cached)
+    return cached;
+  const wrapped = function(...args) {
+    const hook = globalThis.__KF_VITALS__;
+    if (hook)
+      hook.scroll();
+    return fn.apply(this, args);
+  };
+  scrollWrappers.set(fn, wrapped);
+  return wrapped;
+}
+var g = globalThis;
+var builders = g.__KFV_BUILDERS__ ??= new Map;
+var refs = g.__KFV_REFS__ ??= new Map;
+var moves = g.__KFV_MOVES__ ??= new Map;
+var liveViews = new WeakSet;
+var pendingExits = new Map;
+var laidOut = new Set;
+var idOf = (site) => site.key ?? JSON.stringify(site.ref);
+var jsHook = () => globalThis.__KF_VITALS__ ?? null;
+function __kfvLayout(builder, kind, site) {
+  if (builder == null)
+    return builder;
+  const id = idOf(site);
+  let byKind = builders.get(id);
+  if (!byKind)
+    builders.set(id, byKind = {});
+  byKind[kind] = builder;
+  return builder;
+}
+function startLayout(site, kind) {
+  const hook = jsHook();
+  const builder = builders.get(idOf(site))?.[kind];
+  if (hook?.layout && builder != null)
+    hook.layout(site, kind, builder);
+}
+function passRef(prev, instance) {
+  if (typeof prev === "function")
+    return prev(instance);
+  if (prev && typeof prev === "object" && "current" in prev)
+    prev.current = instance;
+  return;
+}
+function exitLater(id, exiting) {
+  const n = (pendingExits.get(id) ?? 0) + 1;
+  pendingExits.set(id, n);
+  if (n > 1)
+    return;
+  Promise.resolve().then(() => {
+    const k = pendingExits.get(id) ?? 0;
+    pendingExits.delete(id);
+    if (exiting)
+      for (let i = 0;i < k; i++)
+        startLayout(exiting, "exiting");
+  });
+}
+function __kfvMotionRef(entering, exiting, prev) {
+  const id = `${entering ? idOf(entering) : ""}|${exiting ? idOf(exiting) : ""}`;
+  const cached = refs.get(id);
+  if (cached && cached.prev === prev)
+    return cached.ref;
+  const ref = (instance) => {
+    if (!instance || typeof instance !== "object") {
+      if (instance === null)
+        exitLater(id, exiting);
+      return passRef(prev, instance);
+    }
+    if (liveViews.has(instance)) {
+      const n = pendingExits.get(id) ?? 0;
+      if (n > 0)
+        pendingExits.set(id, n - 1);
+    } else {
+      liveViews.add(instance);
+      if (entering)
+        startLayout(entering, "entering");
+    }
+    const theirs = passRef(prev, instance);
+    return () => {
+      exitLater(id, exiting);
+      if (typeof theirs === "function")
+        theirs();
+      else
+        passRef(prev, null);
+    };
+  };
+  refs.set(id, { prev, ref });
+  return ref;
+}
+function __kfvLayoutMoved(site, prev) {
+  const id = idOf(site);
+  const cached = moves.get(id);
+  if (cached && cached.prev === prev)
+    return cached.fn;
+  const fn = (e) => {
+    const ev = e;
+    const target = ev?.target ?? ev?.nativeEvent?.target;
+    if (target != null) {
+      if (!laidOut.has(target)) {
+        if (laidOut.size > 1000)
+          laidOut.clear();
+        laidOut.add(target);
+      } else
+        startLayout(site, "layout");
+    }
+    if (typeof prev === "function")
+      prev(e);
+  };
+  moves.set(id, { prev, fn });
+  return fn;
+}
+export {
+  __kfvScrollJs,
+  __kfvScroll,
+  __kfvMotionRef,
+  __kfvLayoutMoved,
+  __kfvLayout,
+  __kfvAnimVia,
+  __kfvAnim
+};

package/dist/types/collector.d.ts

@@ -0,0 +1,167 @@
+/**
+ * The on-device aggregation of one session window (production.md 1 and 2.1), pure so it runs and is
+ * tested outside React Native. Fed with animation starts, touches, scrolls, navigations and frames on
+ * one clock (ms, the JS thread's `performance.now()`); `snapshot()` returns the counters a report holds.
+ *
+ * Attribution is Motion Scan's rule (`MotionTracker` in the inspector): every animation call is ACTIVE
+ * from its start to its estimated end, and a frame counts against every animation active then, plus
+ * 32 ms of slack. Frames while no tracked animation ran are the screen's idle baseline. The 5 longest
+ * frames carry a cause, from the light-mode rules of production.md 1 ("Attribution").
+ */
+import { type VitalsCause, type VitalsSiteRef, type VitalsThread, type VitalsThreadStats } from './protocol';
+/** What the Babel plugin bakes into each call site (or a runtime names). */
+export type SiteInfo = {
+    ref: VitalsSiteRef;
+    key?: string;
+    fn: string;
+    component?: string | null;
+    prop?: string | null;
+};
+/** A window's frame stays charged to an animation this long after its estimated end (MotionTracker). */
+export declare const SLACK_MS = 32;
+/** How far before a long frame began an animation start counts as having started it (trace.ts). */
+export declare const LEAD_MS = 50;
+/** A frame that ends this soon after a navigation is a screen mount. */
+export declare const MOUNT_MS = 500;
+/** Distinct animations starting together that make a burst (trace.ts hintsFor). */
+export declare const BURST = 6;
+/** A touch keeps its window open this long after the finger lifts (scroll deceleration). */
+export declare const TOUCH_TAIL_MS = 1500;
+/** A scroll handler keeps its window open this long after its last event. */
+export declare const SCROLL_TAIL_MS = 250;
+/** Field caps (production.md 2.2: MotionTracker's 400 windows and 2000 events drop to 100 and 500). */
+export declare const MAX_WINDOWS = 100;
+export declare const MAX_EVENTS = 500;
+export type SiteStats = {
+    info: SiteInfo;
+    runs: number;
+    runsReduceMotion: number;
+    activeMs: number;
+    frames: number;
+    missed: number;
+    hitchMs: number;
+    worstMs: number;
+    /** Runs per screen name: the site's screen is where it ran most. */
+    screens: Map<string, number>;
+    /** End of the latest run counted into activeMs, so overlapping runs count once. */
+    activeUntil: number;
+};
+export type WorstFrame = {
+    thread: VitalsThread;
+    ms: number;
+    missed: number;
+    screen: string;
+    sites: SiteStats[];
+    cause: VitalsCause;
+    afterNavMs?: number;
+};
+export type ScreenStats = {
+    name: string;
+    ms: number;
+    threads: Partial<Record<VitalsThread, VitalsThreadStats>>;
+};
+export type Snapshot = {
+    screens: ScreenStats[];
+    sites: SiteStats[];
+    worst: WorstFrame[];
+    foregroundMs: number;
+    measuredMs: number;
+    /** The refresh rate most frames were counted against, and the fastest seen. */
+    targetHz: number;
+    maxHz: number;
+    reduceMotion: boolean;
+};
+export declare function bucketOf(missed: number): number;
+export declare class Collector {
+    private readonly keepWorst;
+    private screens;
+    private sites;
+    private windows;
+    private starts;
+    private touches;
+    private scrolls;
+    /** Navigations, for screen mounts. */
+    private navs;
+    /** Every screen change (navigations and renames), for the screen a late frame was drawn on. */
+    private shown;
+    private before;
+    private worst;
+    private touching;
+    private screen;
+    private fgSince;
+    private fgMs;
+    private measuring;
+    private measuredMs;
+    private latest;
+    private hzFrames;
+    /** Sum of frame lengths per thread: measured time as the meters saw it. */
+    private frameMs;
+    private reduceMotion;
+    private reduceMotionSeen;
+    constructor(keepWorst?: number);
+    /** The app came to the foreground (true) or left it. Screen time and foreground time accrue while in it. */
+    foreground(on: boolean, now: number): void;
+    /** A navigation (or the first screen). `nav` false: a rename that is not a mount (setScreen at start). */
+    setScreen(name: string, now: number, nav?: boolean): void;
+    setReduceMotion(on: boolean): void;
+    /** An animation started at `now` and runs about `ms`. */
+    animStart(info: SiteInfo, now: number, ms: number, thread: VitalsThread, eid?: number): void;
+    /**
+     * An outer call took an inner one in (`withDelay(200, withTiming(…))`): the inner one runs as part
+     * of it, so its window and its run go (MotionTracker drops the inner window the same way).
+     */
+    consume(eid: number): void;
+    touch(down: boolean, now: number): void;
+    scroll(now: number): void;
+    /** The frame meters started (true) or stopped: measured time. */
+    measure(on: boolean, now: number): void;
+    /** One frame of `thread` that ended at `t`, took `dt` ms, against a refresh interval of `budget` ms. */
+    frame(thread: VitalsThread, t: number, dt: number, budget: number): void;
+    snapshot(now: number): Snapshot;
+    /**
+     * A new session window starts at `now`: the counters empty, what is running and where the app is
+     * carry over (an animation that spans the cut keeps its window, counted in the new one from here).
+     */
+    reset(now: number): void;
+    /** Nothing is kept (setVitalsEnabled(false), a session that ends). */
+    clear(): void;
+    get currentScreen(): string;
+    get foregroundMs(): number;
+    /** Foreground time of this window so far, at `now`. */
+    foregroundAt(now: number): number;
+    private accrue;
+    /** A screen name, or `other` once VITALS_LIMITS.screens names are taken. */
+    private screenKey;
+    private screenStats;
+    /** The screen shown when a frame that ended at `t` was drawn: frames reach here late. */
+    private screenAt;
+    private site;
+    private pushSpan;
+    private open;
+    private considerWorst;
+    /** The light-mode cause of a long frame (production.md 1, "Attribution"), in the table's order. */
+    causeOf(thread: VitalsThread, t: number, dt: number): {
+        cause: VitalsCause;
+        afterNavMs?: number;
+    };
+    /** Windows long over (frames of the other thread arrive up to a few hundred ms late). */
+    private prune;
+}
+/**
+ * When the frame meters run: inside motion windows only, plus 250 ms after the last one closes
+ * (production.md 2.1). Nothing here keeps a timer: the meters ask `open(now)` on each frame and stop
+ * themselves.
+ */
+export declare const GATE_TAIL_MS = 250;
+export declare class MotionGate {
+    until: number;
+    private touching;
+    /** Something moves until `end`. True when the gate was closed at `now` (the meters must start). */
+    note(end: number, now: number): boolean;
+    /** A touch went down (true) or up. True when the gate opened. */
+    touch(down: boolean, now: number): boolean;
+    open(now: number): boolean;
+    /** When the gate closes if nothing else happens (Infinity while a finger is down). */
+    closesAt(): number;
+    reset(): void;
+}

package/dist/types/controller.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Motion Vitals' session lifecycle (production.md 2.1), with everything it touches injected so it is
+ * tested without React Native: the clocks, randomness, fetch, timers, the storage adapter and the
+ * frame meters.
+ *
+ * - Nothing runs before `start`. Then, per session (a foreground period; it ends after 30 s in the
+ *   background): a nonce made in memory, sampling decided once, at most 3 reported sessions per device
+ *   per day (counted in storage, never sent).
+ * - A sampled session measures inside motion windows only (`MotionGate`), cuts a report when it goes
+ *   to the background or fills 10 minutes of foreground, and checkpoints the open window at most once
+ *   a minute while something moves (a checkpoint left behind is sent on the next launch with
+ *   `ended: 'unknown'`).
+ * - Failed uploads wait in a retry store (5 reports, 100 KB, 7 days), retried 10 s after start, then
+ *   after 1, 5 and 30 minutes, only in the foreground.
+ * - Config comes from every upload response and from `GET /v1/config/<key>` at most once per its TTL;
+ *   `stop`, a 401 or a 410 turn the SDK off on this device for 7 days; `minSdk` above this version and
+ *   `enabled: false` turn it off.
+ * - `setEnabled(false)` stops at once and drops what is pending.
+ */
+import { type VitalsConfig, type VitalsReport, type VitalsThread, type VitalsTier } from './protocol';
+import { Collector, MotionGate, type SiteInfo } from './collector';
+/** Where the SDK keeps its config cache, checkpoint, retry store and day counter: AsyncStorage, an MMKV wrapper… */
+export type VitalsStorage = {
+    getItem(key: string): string | null | undefined | Promise<string | null | undefined>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+};
+export type VitalsDevice = {
+    /** Raw model identifier (`Device.modelId` on iOS, `Device.modelName` on Android from expo-device). */
+    model?: string | null;
+    memoryBytes?: number | null;
+    memoryGb?: number | null;
+    tier?: VitalsTier;
+    /** The display's refresh rate, when the app knows it. */
+    displayHz?: number;
+};
+export type ControllerOptions = {
+    /** The project's public field key, `kfp_live_…`. */
+    key: string;
+    appVersion: string;
+    build?: string;
+    environment?: 'production' | 'development';
+    /** Share of sessions that report, until the project's config says otherwise. Default 0.1. */
+    sampleRate?: number;
+    storage?: VitalsStorage;
+    device?: VitalsDevice;
+    /** Ingest origin. Default https://vitals.keyframer.dev. */
+    endpoint?: string;
+    /** Bundle id or package name. */
+    appId?: string;
+};
+type HttpResponse = {
+    status: number;
+    json(): Promise<unknown>;
+};
+export type ControllerEnv = {
+    /** Monotonic ms, the clock frames and animations are stamped with. */
+    now(): number;
+    /** Wall-clock ms: day counting, config age, retry age. Never sent. */
+    wall(): number;
+    random(): number;
+    fetch(url: string, init: {
+        method: string;
+        headers: Record<string, string>;
+        body?: string;
+    }): Promise<HttpResponse>;
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    platform: {
+        os: 'ios' | 'android';
+        osMajor: number;
+    };
+    /** Local calendar day of a wall time, `YYYY-MM-DD`. */
+    day?(wall: number): string;
+    log?(message: string): void;
+};
+/** The frame meters and the instrumentation hooks, as the platform runs them. */
+export type Meters = {
+    /** Install the animation hooks (JS and UI runtimes): call sites start reporting. */
+    install(): void;
+    uninstall(): void;
+    /** Start the JS and UI frame loops; each stops itself when the gate closes. */
+    start(): void;
+    /** Keep the UI loop running at least `ms` more (it keeps its own clock). */
+    extendUi(ms: number): void;
+    stop(): void;
+};
+export declare const STORAGE_KEYS: {
+    readonly config: "kfv:config";
+    readonly stop: "kfv:stop";
+    readonly day: "kfv:day";
+    readonly checkpoint: "kfv:checkpoint";
+    readonly queue: "kfv:queue";
+};
+export declare const CHECKPOINT_MS = 60000;
+export declare const STOP_MS: number;
+export declare const RETRY: {
+    readonly max: 5;
+    readonly bytes: number;
+    readonly ageMs: number;
+    readonly delays: readonly [10000, 60000, number, number];
+};
+/** First config fetch and first retry happen this long after start, never blocking it. */
+export declare const START_DELAY_MS = 10000;
+/** The UI runtime numbers its animation calls from here, so its ids never meet the JS thread's. */
+export declare const UI_EVENT_BASE = 1000000000;
+/** Compares dotted versions numerically: -1, 0 or 1. Pre-release tags are ignored. */
+export declare function compareVersions(a: string, b: string): number;
+export declare class VitalsController {
+    private readonly env;
+    readonly collector: Collector;
+    readonly gate: MotionGate;
+    private opts;
+    private enabled;
+    /** Bumped by every start and stop: async work from an older run checks it and gives up. */
+    private run;
+    private config;
+    private sampled;
+    private nonce;
+    private seq;
+    private sampleRate;
+    private foreground;
+    private backgroundAt;
+    private dayCount;
+    private events;
+    private nextEid;
+    private uiKnownUntil;
+    private checkpointTimer;
+    private retryTimer;
+    private retryStep;
+    /** Reports waiting in the retry store (no retry timer while it is empty). */
+    private queued;
+    private configTimer;
+    private meters;
+    private screen;
+    private reduceMotion;
+    constructor(env: ControllerEnv);
+    get isSampled(): boolean;
+    get isEnabled(): boolean;
+    get session(): {
+        nonce: string;
+        seq: number;
+        sampleRate: number;
+    };
+    /** Starts reporting. Resolves when the session is set up (storage read, sampling decided). */
+    start(opts: ControllerOptions, meters: Meters): Promise<void>;
+    /** setVitalsEnabled: false stops at once and drops what is pending; true starts again. */
+    setEnabled(on: boolean): Promise<void>;
+    /** Stops measuring and reporting. `drop`: the open window, the checkpoint and the retry store go too. */
+    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;
+    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). */
+    eid(): number;
+    /**
+     * An animation call started at `t` (the JS clock). `args` are slimmed (`slimArg`): numbers, nested
+     * calls as `{ $anim: eid }`, and config timing keys.
+     */
+    anim(site: SiteInfo, args: unknown[], eid: number, thread: VitalsThread, t?: number): void;
+    /**
+     * A layout animation started (entering, exiting, layout). Reanimated's builders keep their timing in
+     * `durationV` / `delayV`; a builder class passed as it is (`entering={FadeIn}`) runs its default 300 ms.
+     */
+    layout(site: SiteInfo, kind: 'entering' | 'exiting' | 'layout', builder: unknown, t?: number): void;
+    scroll(t?: number): void;
+    touch(down: boolean, t?: number): void;
+    private motion;
+    private opened;
+    /** The UI loop keeps its own time: tell it how long the gate stays open when that grows. */
+    private keepUi;
+    /**
+     * One JS-thread frame. Returns whether the JS loop goes on: false once the gate has closed (the
+     * meters stop themselves, nothing keeps a timer).
+     */
+    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 checkWindow;
+    /** The report the open window would send now, or null when it holds nothing. */
+    report(ended: VitalsReport['session']['ended'], now?: number): VitalsReport | null;
+    private closeWindow;
+    private scheduleCheckpoint;
+    /** Writes the open window to storage, sent on the next launch if this process never sends it. */
+    checkpoint(): Promise<void>;
+    private context;
+    private endpoint;
+    /** Posts a report; on a failure that may pass (offline, 429, 5xx), into the retry store. */
+    private send;
+    private enqueue;
+    /** The retry store's limits: newest first kept, at most 5 reports, 100 KB, 7 days old. */
+    private trim;
+    private scheduleRetry;
+    /** Sends what waits in the retry store, oldest first; what fails again stays for the next step. */
+    retry(): Promise<void>;
+    private sendOnce;
+    private fetchConfig;
+    /** A config from the server: cached, and acted on (stop, disabled, a minimum SDK version). */
+    applyConfig(config: VitalsConfig): Promise<void>;
+    private killSwitch;
+    private allowed;
+    private rate;
+    private clearTimers;
+    private log;
+}
+export {};

package/dist/types/encode.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A session window's counters as the report the ingest Worker takes (`VitalsReport`), within every
+ * limit of `VITALS_LIMITS`: 40 screens (the collector folds the rest into `other`), 200 sites (the ones
+ * that drew the most frames), 5 worst frames, 64-character screen names and 32 KB of JSON (sites with
+ * the fewest frames go first until it fits).
+ */
+import { type VitalsReport } from './protocol';
+import type { Snapshot } from './collector';
+/** What the report says about the app, the device and the session, beside the counters. */
+export type ReportContext = {
+    app: VitalsReport['app'];
+    sdk: VitalsReport['sdk'];
+    device: VitalsReport['device'];
+    /** The display's rate when the app knows it; else the fastest the meters saw. */
+    display?: {
+        hz?: number;
+        adaptive?: boolean;
+    };
+    state?: {
+        lowPower?: boolean;
+        thermal?: VitalsReport['state']['thermal'];
+    };
+    /** The project collects Reduce Motion (config `collect.reduceMotion`). */
+    collectReduceMotion: boolean;
+    session: Pick<VitalsReport['session'], 'nonce' | 'seq' | 'sampleRate' | 'ended'>;
+    /** Worst frames sent (the protocol allows 10, SDKs send 5). */
+    worst?: number;
+};
+/** True when the window holds anything worth a request: frames measured or animations run. */
+export declare function hasData(s: Snapshot): boolean;
+export declare function encodeReport(snap: Snapshot, ctx: ReportContext): VitalsReport;

package/dist/types/estimate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * How long an animation call runs, copied from the inspector's `motionStats.ts` (`springSettleMs`,
+ * `estimateMs`) so a field window and a local Motion Scan window are the same length.
+ * `estimate.parity.test.ts` runs both copies on the same calls: change them together.
+ *
+ * Every animation call opens an ACTIVE WINDOW from when it was called until its estimated end (a
+ * timing's duration, a spring's settle time, delays and sequences added up).
+ */
+/** The part of an animation event the estimate reads. Nested calls are `{ $anim: id }` in `args`. */
+export type EstimateEvent = {
+    site: {
+        fn: string;
+    };
+    args: unknown[];
+    durationMs?: number;
+};
+/** How long a spring takes to settle (ms), from its physics: 4 time constants of its slowest decay. */
+export declare function springSettleMs(c: Record<string, unknown>): number;
+/**
+ * Estimated run time of one animation call (ms). Nested animations are read through their ids
+ * (`withDelay(200, withTiming(…))` reports the inner call as `{ $anim: id }`); one whose inner call is
+ * not known falls back to a short default.
+ */
+export declare function estimateMs<E extends EstimateEvent>(ev: E, byEid: (eid: number) => E | undefined, depth?: number): number;
+/**
+ * An argument reduced to what the estimate needs: a number, a nested call's id, or a config's
+ * numeric timing keys. Values, colors, callbacks and easing functions never leave the thread they
+ * were passed on (and could not be copied between runtimes anyway).
+ */
+export declare function slimArg(a: unknown, idOf: (x: object) => number | undefined): unknown;

package/dist/types/frameMeter.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The frame meter math, copied from the inspector (`packages/inspector/src/frameMeter.ts` and
+ * `motionStats.ts` `droppedFrames`) so the field and a local recording count frames the same way.
+ * `frameMeter.parity.test.ts` runs both copies on the same frames: change them together.
+ *
+ * Plain state and a worklet tick, so the same code measures the JS thread (requestAnimationFrame) and
+ * the UI thread (the UI runtime's requestAnimationFrame). The refresh interval is what most frames of
+ * the last window took, snapped to 60/90/120 Hz: not the shortest, because a jittery loop sometimes
+ * delivers two callbacks a few ms apart.
+ */
+export type MeterStat = {
+    t: number;
+    thread: 'ui' | 'js';
+    fps: number;
+    dropped: number;
+};
+export type MeterDrop = {
+    t: number;
+    thread: 'ui' | 'js';
+    ms: number;
+    dropped: number;
+};
+export type FrameMeter = {
+    thread: 'ui' | 'js';
+    windowMs: number;
+    interval: number;
+    last: number;
+    windowStart: number;
+    frames: number;
+    dropped: number;
+    fast: number;
+    mid: number;
+    stats: MeterStat[];
+    drops: MeterDrop[];
+};
+export declare function createFrameMeter(thread: 'ui' | 'js', windowMs?: number): FrameMeter;
+/** A frame was drawn at `t` (ms). Finished windows land in `m.stats`, long frames in `m.drops`. */
+export declare function tickFrameMeter(m: FrameMeter, t: number): void;
+/** Frames a single frame of `dt` ms skipped at an `interval` ms refresh. */
+export declare function droppedFrames(dt: number, interval: number): number;
+/**
+ * One measured thread in the field: the meter above, plus every frame since the last flush as flat
+ * `[t, dt, budget, …]` (the frame's end, its length, the refresh interval it was counted against), so
+ * the JS side can attribute each frame to its screen and to the animations running then. The meter's
+ * own stats and drops are emptied as it goes: the field never keeps a recording.
+ */
+export type FieldMeter = {
+    m: FrameMeter;
+    buf: number[];
+};
+export declare function createFieldMeter(thread: 'ui' | 'js'): FieldMeter;
+/** A frame at `t`. Returns true when the buffer holds a flush's worth (about a quarter second). */
+export declare function tickFieldMeter(f: FieldMeter, t: number): boolean;

package/dist/types/hook.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The JS runtime's hook: what `__kfvAnim` and the layout and scroll helpers call into once startVitals
+ * installed it. Runs the app's call first (its result is what the app gets, whatever happens here),
+ * then notes the start with the arguments slimmed to timing numbers.
+ */
+import type { VitalsController } from './controller';
+import type { VitalsHook } from './runtime';
+export declare function createJsHook(controller: VitalsController, onMotion?: () => void): VitalsHook;

package/dist/types/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Motion Vitals for React Native: slow frames and janky animations from production, by screen and
+ * animation call site. MIT.
+ *
+ *   import { startVitals } from '@keyframerdev/vitals'
+ *   startVitals({ key: 'kfp_live_…', appVersion: '3.4.0', build: '412', navigationRef })
+ *
+ * Nothing runs before startVitals (an app that needs consent calls it after); setVitalsEnabled(false)
+ * stops and drops what is pending. Add `@keyframerdev/vitals/babel` to babel.config.js for call sites;
+ * without it, frames are still counted per screen. Never sent: screenshots, text, values, touches,
+ * identifiers, absolute times.
+ */
+import { type ReactNode } from 'react';
+import { View, type StyleProp, type ViewStyle } from 'react-native';
+export { setVitalsEnabled, setVitalsScreen, startVitals, type NavigationRefLike, type VitalsOptions } from './native';
+export type { VitalsDevice, VitalsStorage } from './controller';
+export { SDK_VERSION } from './version';
+/**
+ * Optional, around the app: touches open motion windows (a touch keeps the meters running until 1.5 s
+ * after the finger lifts), so a list without scroll handlers is measured while it scrolls. It only
+ * listens: it never becomes the responder and reads no coordinates.
+ */
+export declare function VitalsRoot({ children, style }: {
+    children?: ReactNode;
+    style?: StyleProp<ViewStyle>;
+}): import("react").CElement<import("react-native").ViewProps, View>;

package/dist/types/mask.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Screen names before they leave the device. A route name can carry data (`/users/42`,
+ * `Profile ada@example.com`): the same masks as the inspector's share links (`maskText` in
+ * `packages/inspector/src/redact.ts`, copied here; `mask.parity.test.ts` keeps them identical), then
+ * cut to VITALS_LIMITS.screenName characters.
+ */
+/** Replaces emails, long numbers, ids and tokens in `text`. */
+export declare function maskText(text: string): string;
+/** A screen name as it is sent: masked, trimmed, at most 64 characters, never empty. */
+export declare function screenName(raw: unknown): string;