@keyframerdev/vitals 0.0.0-stage → 0.1.0

package/dist/types/native.d.ts

@@ -0,0 +1,41 @@
+/**
+ * React Native wiring of the controller: the hooks the Babel plugin's calls run into (on the JS runtime
+ * and on the UI runtime), the two frame loops, AppState, navigation and Reduce Motion.
+ *
+ * Frame loops run only while the motion gate is open (production.md 2.6: nothing scheduled while
+ * nothing moves). The UI loop uses the UI runtime's requestAnimationFrame, like the inspector's, keeps
+ * its own "until" and stops itself; it hands frames to JS in batches of about a quarter second. The JS
+ * loop is requestAnimationFrame on the JS thread and asks the controller on every frame whether to go on.
+ */
+import { VitalsController, type ControllerOptions } from './controller';
+/** What startVitals reads from a React Navigation or expo-router container ref. */
+export type NavigationRefLike = {
+    isReady?(): boolean;
+    getCurrentRoute(): {
+        name: string;
+        path?: string;
+    } | undefined | null;
+    addListener(event: 'state', cb: () => void): (() => void) | {
+        remove(): void;
+    } | void;
+};
+export type VitalsOptions = ControllerOptions & {
+    /** A React Navigation `createNavigationContainerRef()` or expo-router `useNavigationContainerRef()`: screens are named from its routes. */
+    navigationRef?: NavigationRefLike | null;
+    /** Names a route yourself (still masked and cut to 64 characters). Default: the route's name. */
+    screenName?: (route: {
+        name: string;
+        path?: string;
+    }) => string;
+};
+export declare const controller: VitalsController;
+/**
+ * Starts Motion Vitals. Nothing runs before this call (call it after your own consent flow if your app
+ * needs one); from here this session may be sampled and report. Safe to call again with new options.
+ */
+export declare function startVitals(opts: VitalsOptions): Promise<void>;
+/** Stops (false: now, and drops what is pending) or starts again (true) with the options of startVitals. */
+export declare function setVitalsEnabled(enabled: boolean): Promise<void>;
+/** Names the current screen where navigation is not automatic (no navigationRef, or a screen inside one). */
+export declare function setVitalsScreen(name: string): void;
+export declare function vitalsTouch(down: boolean, activeTouches: number): void;

package/dist/types/protocol.d.ts

@@ -0,0 +1,315 @@
+/**
+ * Motion Vitals: the wire format between the production reporters and the ingest Worker.
+ *
+ * Reporters: `@keyframerdev/vitals` (React Native), `KeyframerVitals` (iOS), `dev.keyframer:vitals`
+ * (Android), `keyframer_vitals` (Flutter). Ingest: `https://vitals.keyframer.dev` (Keyframer's
+ * `apps/vitals`). Symbols: produced by `@keyframerdev/vitals-cli`, read by the ingest Worker.
+ *
+ * Import-free, like inspector.ts, so every SDK can mirror it. Design: `inspector/docs/production.md`;
+ * build plan and ownership: `inspector/docs/vitals-build.md`. Golden messages every SDK's tests check
+ * against: `inspector/packages/protocol/fixtures/vitals/`.
+ */
+export declare const VITALS_FORMAT: "keyframer-vitals";
+export declare const VITALS_VERSION: 1;
+export declare const VITALS_ENDPOINT = "https://vitals.keyframer.dev";
+/**
+ * Histogram buckets of frames missed per frame, by lower bound: 0, 1, 2, 3-4, 5-8, 9-16, 17-32, 33+.
+ * The same eight on every platform, so 60 and 120 Hz devices add up.
+ */
+export declare const VITALS_BUCKETS: readonly [0, 1, 2, 3, 5, 9, 17, 33];
+/** A frame this long or longer is frozen, in absolute time (Android vitals' definition). */
+export declare const VITALS_FROZEN_MS = 700;
+/** A session window is at most this much foreground time; a longer session sends several windows. */
+export declare const VITALS_WINDOW_MS: number;
+/** A session ends after this long in the background. */
+export declare const VITALS_SESSION_GAP_MS: number;
+/** Hard caps per report. Ingest refuses a report over any of them (413 for bytes, 400 otherwise). */
+export declare const VITALS_LIMITS: {
+    readonly screens: 40;
+    readonly sites: 200;
+    readonly worst: 10;
+    readonly images: 64;
+    readonly bytes: number;
+    readonly screenName: 64;
+};
+/** At most this many reported sessions per device per day (counted on the device, never sent). */
+export declare const VITALS_MAX_SESSIONS_PER_DAY = 3;
+/** Default share of sessions that report. The project's config can lower or raise it. */
+export declare const VITALS_DEFAULT_SAMPLE_RATE = 0.1;
+export type VitalsPlatform = 'react-native' | 'ios' | 'android' | 'flutter';
+export type VitalsOs = 'ios' | 'android';
+/** Same roles as InspectorThread: `js` is the app thread (JS, main, UI isolate), `ui` the frame thread (RN UI, Android RenderThread, Flutter raster). */
+export type VitalsThread = 'ui' | 'js';
+export type VitalsTier = 'low' | 'mid' | 'high';
+export type VitalsThermal = 'nominal' | 'fair' | 'serious' | 'critical';
+/**
+ * Why one of a window's worst frames was slow, computed on the device (production.md 1, "Attribution").
+ * `js-task`, `ui-work` and `slow-render` need deep mode and are not sent in version 1.
+ */
+export type VitalsCause = 'screen-mount' | 'burst' | 'busy-start' | 'scroll' | 'gesture' | 'js-task' | 'ui-work' | 'slow-render' | 'unknown';
+/** Frame counters of one thread on one screen. `hist` has VITALS_BUCKETS.length entries. */
+export type VitalsThreadStats = {
+    frames: number;
+    hist: number[];
+    frozen: number;
+    /** Sum of max(0, frameMs - budget). Divided by measured seconds it is Apple's hitch time ratio. */
+    hitchMs: number;
+    /** Frames and missed frames while no tracked animation ran: the screen's baseline. */
+    idleFrames: number;
+    idleMissed: number;
+};
+/**
+ * Where a call site is in the app, and what the server needs to name it.
+ * - `source`: exact file and line (React Native's Babel plugin; Flutter builds that keep positions).
+ * - `hashed`: React Native with `hashSites`; named from the uploaded `rn-sites` manifest.
+ * - `name`: a name the developer gave (`trace("card-expand")`, `kfTrack`, `KfAnimationController(name:)`), plus a type name when the build keeps it.
+ * - `native`: an instruction offset in `images[image]` (iOS, Flutter AOT); named from an uploaded `macho` or `elf` symbol file.
+ *   SDKs send the offset of the return address they captured, as is; the server looks up `offset - 1`
+ *   (the call instruction). Flutter on iOS is a `macho` image (App.framework/App, LC_UUID = the Dart build id); on Android an `elf` one (libapp.so).
+ * - `jvm`: an Android stack frame, possibly renamed by R8; named from an uploaded `r8` mapping.
+ */
+export type VitalsSiteRef = {
+    kind: 'source';
+    file: string;
+    line: number;
+    column?: number;
+} | {
+    kind: 'hashed';
+    hash: string;
+} | {
+    kind: 'name';
+    name: string;
+    type?: string;
+} | {
+    kind: 'native';
+    image: number;
+    offset: number;
+    type?: string;
+} | {
+    kind: 'jvm';
+    className: string;
+    method: string;
+    line?: number;
+    file?: string;
+};
+export type VitalsSite = {
+    ref: VitalsSiteRef;
+    /**
+     * Stable across versions when the SDK can tell: the site without line or column
+     * (`app/feed.tsx#FeedCard#withSpring#scale#1`, the ordinal telling identical calls apart), or the
+     * developer's name. Omitted for `native` and `jvm` refs: the server derives it after symbolication.
+     */
+    key?: string;
+    /** The animation API: withSpring, UIView.animate, animateFloatAsState, AnimationController.forward… */
+    fn: string;
+    component?: string | null;
+    /** The animated property or target when known: scale, translateY, alpha… */
+    prop?: string | null;
+    /** Index into `screens`: where it ran most in this window. */
+    screen: number;
+    runs: number;
+    activeMs: number;
+    /** Frames drawn while it ran, and frames missed while it ran. */
+    frames: number;
+    missed: number;
+    hitchMs: number;
+    worstMs: number;
+    /** Runs that started while Reduce Motion was on. Only when the project collects Reduce Motion. */
+    runsReduceMotion?: number;
+};
+export type VitalsWorstFrame = {
+    thread: VitalsThread;
+    ms: number;
+    missed: number;
+    screen: number;
+    /** Indexes into `sites`: what was running in that frame. */
+    sites: number[];
+    cause: VitalsCause;
+    /** For `screen-mount`: how long after the navigation the frame ended. */
+    afterNavMs?: number;
+};
+/** A binary image the report's `native` refs point into: a Mach-O UUID or an ELF build id. */
+export type VitalsImage = {
+    /** Lowercase hex without dashes. */
+    debugId: string;
+    kind: 'macho' | 'elf';
+    /** File name only (`Acme`, `App.framework/App`, `libapp.so`), never a path with a user name in it. */
+    name: string;
+    arch?: string;
+};
+export type VitalsReport = {
+    format: typeof VITALS_FORMAT;
+    version: typeof VITALS_VERSION;
+    app: {
+        /** Bundle id or package name. Lets the server warn when a key is used by another app. */
+        id?: string;
+        version: string;
+        build?: string;
+        platform: VitalsPlatform;
+        /** Free-form framework label for the dashboard: "SwiftUI", "Compose", "Views"… */
+        framework?: string;
+        environment: 'production' | 'development';
+        /** Android: the build id the Gradle plugin injects, matching the uploaded R8 mapping. */
+        debugId?: string;
+    };
+    sdk: {
+        name: string;
+        version: string;
+    };
+    device: {
+        os: VitalsOs;
+        osMajor: number;
+        /** Raw model identifier (iPhone15,3, SM-A146B) unless the project turns models off; the server maps it to a name and tier. */
+        model?: string;
+        tier?: VitalsTier;
+        memoryGb?: number;
+    };
+    display: {
+        hz: number;
+        adaptive?: boolean;
+        targetHz: number;
+    };
+    /** Any time true in this window. `reduceMotion` only when the project collects it. */
+    state: {
+        reduceMotion?: boolean;
+        lowPower?: boolean;
+        thermal?: VitalsThermal;
+    };
+    session: {
+        /** Random per session, in memory only, never written to disk or reused. Links the windows of one session. */
+        nonce: string;
+        /** 0 for the first window of a session. Only seq 0 counts toward usage. */
+        seq: number;
+        sampleRate: number;
+        foregroundMs: number;
+        measuredMs: number;
+        ended: 'background' | 'window' | 'unknown';
+    };
+    screens: Array<{
+        name: string;
+        ms: number;
+        threads: Partial<Record<VitalsThread, VitalsThreadStats>>;
+    }>;
+    sites: VitalsSite[];
+    /** The longest frames of the window, at most VITALS_LIMITS.worst (SDKs send 5). */
+    worst: VitalsWorstFrame[];
+    images?: VitalsImage[];
+};
+/** Per-project settings every SDK reads: from upload responses and from GET /v1/config/<field key>. */
+export type VitalsConfig = {
+    enabled: boolean;
+    /** The rate to use now: base x the allowance factor x the release boost, already combined. */
+    sampleRate: number;
+    /** ISO time. While boosted, sampleRate already includes the boost. */
+    boostUntil?: string;
+    /** SDK versions below these stop reporting (a buggy release in the wild). */
+    minSdk?: Partial<Record<VitalsPlatform, string>>;
+    collect: {
+        reduceMotion: boolean;
+        deviceModel: boolean;
+        development: boolean;
+    };
+    /** true: turn off on this device for 7 days. */
+    stop?: boolean;
+    /** How long a device may keep this config before fetching again. */
+    ttlSec: number;
+};
+/**
+ * POST /v1/reports, `Authorization: Bearer kfp_…`, JSON body (gzip with `Content-Encoding: gzip`
+ * where the platform can). 200 answers this; 400 invalid; 401 unknown or revoked key and 410 deleted
+ * project (the SDK stops for 7 days); 413 too large; 429 rate limited (retry later).
+ */
+export type VitalsIngestResponse = {
+    ok: boolean;
+    config: VitalsConfig;
+    error?: string;
+};
+/** What a symbol upload is for. */
+export type VitalsSymbolKind = 'macho' | 'elf' | 'r8' | 'rn-sites';
+/**
+ * Symbols are extracted on the developer's machine or CI by `keyframer-vitals symbols upload`, never on
+ * the server: a manifest plus chunks, so the Worker reads one small chunk per lookup.
+ *
+ * Upload: PUT /v1/symbols/<kind>/<debugId>/<chunk file> (gzipped JSON body) for each chunk, then
+ * POST /v1/symbols/<kind>/<debugId>/manifest with the manifest; both with `Authorization: Bearer kft_…`.
+ * The manifest is written last, so a symbol set is visible only when complete.
+ */
+export type VitalsSymbolManifest = {
+    format: 'keyframer-vitals-symbols';
+    version: 1;
+    kind: VitalsSymbolKind;
+    /**
+     * macho: LC_UUID; elf: GNU build id (both lowercase hex, no dashes); r8: the Gradle plugin's build id,
+     * else `<app version>+<build>`; rn-sites: `<app version>+<build>`.
+     */
+    debugId: string;
+    name?: string;
+    arch?: string;
+    app?: {
+        id?: string;
+        version?: string;
+        build?: string;
+    };
+    /**
+     * Name schemes left mangled in the chunks: `swift` when the upload ran without `swift-demangle`
+     * (not on macOS). Absent when every name is demangled.
+     */
+    mangled?: Array<'swift'>;
+    /**
+     * Sorted by `first`: the lowest offset or key in each chunk. macho/elf: the offset as 16 lowercase
+     * hex digits (string order is numeric order); r8: the obfuscated class name; rn-sites: the hash.
+     * A lookup reads only the last chunk whose `first` is at most the offset or key (code point order).
+     * Chunk files are named `0000.json`, `0001.json`, ….
+     */
+    chunks: Array<{
+        file: string;
+        first: string;
+    }>;
+    createdAt: string;
+    cli: {
+        name: string;
+        version: string;
+    };
+};
+/**
+ * macho and elf chunks. Offsets are relative to the image's load address (the __TEXT segment's vmaddr
+ * for Mach-O, the first PT_LOAD for ELF), which is what SDKs send in `native` refs.
+ */
+export type VitalsSymbolChunk = {
+    names: string[];
+    files: string[];
+    /** Functions sorted by start: [start, end, name index]. Demangled. */
+    fns: Array<[start: number, end: number, name: number]>;
+    /**
+     * The line table, sorted by start: [start, file index, line]. Consecutive equal rows merged. Line 0:
+     * no line information from that offset on. A chunk that starts inside a function or a row repeats
+     * them (the function in `fns`, the row at the chunk's first offset), so one chunk answers.
+     */
+    lines: Array<[start: number, file: number, line: number]>;
+};
+/**
+ * r8 chunks: obfuscated class name to the original class, and its methods' line ranges. A line L in
+ * obfStart..obfEnd resolves to `origStart` when `origEnd` equals it, else to `origStart + (L - obfStart)`
+ * (`origEnd` absent: linear). All four 0: no line information. Rows sharing an obfuscated name and range
+ * are an inline stack, innermost first. `original` is the method name, prefixed with its class when it
+ * was inlined from another class (`com.acme.SpringsKt.cardScale`). `file`: the R8 source file name.
+ */
+export type VitalsR8Chunk = {
+    classes: Record<string, {
+        name: string;
+        file?: string;
+        methods: Array<[obfuscated: string, original: string, obfStart: number, obfEnd: number, origStart: number, origEnd?: number]>;
+    }>;
+};
+/** rn-sites chunks: a hashed site id to the source site it stands for. */
+export type VitalsSitesChunk = {
+    sites: Record<string, {
+        file: string;
+        line: number;
+        column?: number;
+        fn: string;
+        component?: string | null;
+        prop?: string | null;
+        key: string;
+    }>;
+};

package/dist/types/runtime.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What the Babel plugin's rewritten calls run into (`@keyframerdev/vitals/babel`). Until `startVitals`
+ * installs a hook, and after `setVitalsEnabled(false)`, each one is a straight pass-through: one global
+ * read, then the original call, so an instrumented app behaves exactly like the original.
+ *
+ * `__kfvAnim` and `__kfvScroll` are worklets: animation calls are often made inside gesture callbacks,
+ * reactions and scroll handlers, which run on the UI runtime, where the hook is a second one installed
+ * there (native.ts). Nothing here reads an argument's value: the hook keeps only what an animation's
+ * length is estimated from.
+ */
+import type { SiteInfo } from './collector';
+type AnimFn = (...args: unknown[]) => unknown;
+export type VitalsHook = {
+    /** Runs the animation call (through `via`, the inspector's `__kfAnim`, when both plugins ran) and notes its start. */
+    anim(fn: AnimFn, site: SiteInfo, args: unknown[], via: AnimFn | null, viaSite: unknown): unknown;
+    scroll(): void;
+    /** JS runtime only: a layout animation (entering, exiting, layout) started. */
+    layout?(site: SiteInfo, kind: LayoutKind, builder: unknown): void;
+};
+export type LayoutKind = 'entering' | 'exiting' | 'layout';
+/** `withSpring(1, cfg)` → `__kfvAnim(withSpring, site, 1, cfg)`. */
+export declare function __kfvAnim(fn: AnimFn, site: SiteInfo, ...args: unknown[]): unknown;
+/**
+ * The same, for a call the inspector's development plugin wrapped first:
+ * `__kfAnim(withSpring, isite, 1, cfg)` → `__kfvAnimVia(__kfAnim, site, withSpring, isite, 1, cfg)`.
+ */
+export declare function __kfvAnimVia(via: AnimFn, site: SiteInfo, fn: AnimFn, viaSite: unknown, ...args: unknown[]): unknown;
+/** First statement of every useAnimatedScrollHandler worklet: a scroll keeps the meters running. */
+export declare function __kfvScroll(): void;
+/** A plain JS `onScroll` handler: same, then the app's handler. Anything that is not a function goes through untouched. */
+export declare function __kfvScrollJs<F>(fn: F): F;
+/** An entering / exiting / layout prop: returned as it is, remembered for its element. */
+export declare function __kfvLayout<B>(builder: B, kind: LayoutKind, site: SiteInfo): B;
+/**
+ * The ref of an element with `entering` or `exiting`: the entering animation starts when a new view
+ * mounts, the exiting one when a view goes; detaching and re-attaching the same view in one commit (a
+ * ref that changes every render) is neither. The app's own ref gets the view as before.
+ */
+export declare function __kfvMotionRef(entering: SiteInfo | null, exiting: SiteInfo | null, prev?: unknown): (instance: unknown) => unknown;
+/** The onLayout of an element with `layout`: every layout after a view's first is a layout animation. */
+export declare function __kfvLayoutMoved(site: SiteInfo, prev?: unknown): (e: unknown) => void;
+export {};

package/dist/types/version.d.ts

@@ -0,0 +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.0";

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@keyframerdev/vitals",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Motion Vitals for React Native: slow frames and janky animations from production, by screen and call site",
+  "keywords": [
+    "react-native",
+    "reanimated",
+    "expo",
+    "performance",
+    "animation",
+    "frame-drops",
+    "jank",
+    "monitoring",
+    "keyframer"
+  ],
+  "homepage": "https://keyframer.dev/inspector/docs/vitals/react-native",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keyframer-dev/inspector.git",
+    "directory": "react-native-vitals"
+  },
+  "bugs": "https://github.com/keyframer-dev/inspector/issues",
+  "license": "MIT",
+  "author": "Catalin Miron",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "react-native": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "react-native": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/types/runtime.d.ts",
+      "react-native": "./dist/runtime.js",
+      "default": "./dist/runtime.js"
+    },
+    "./babel": {
+      "require": "./dist/babel.cjs",
+      "default": "./dist/babel.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "react": ">=19.0.0",
+    "react-native": ">=0.78.0",
+    "react-native-reanimated": ">=4.1.0",
+    "react-native-worklets": ">=0.5.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native-reanimated": {
+      "optional": true
+    }
+  }
+}