@symbiote-native/app-metrics 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A. Prokopenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+# @symbiote-native/app-metrics
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+See how your app really performs on users' devices: how long it takes to start and become
+interactive, how it handles network requests, when it crashes. One API for every
+[SymbioteNative](../../README.md) adapter (React, Vue, Svelte, Solid and Angular).
+
+It wraps [`expo-app-metrics`](https://github.com/expo/expo/tree/main/packages/expo-app-metrics)
+(app startup, frame rate, memory, network-request, crash, and session metrics): the core surface on
+every adapter, plus an `AppMetricsRoot` on all five and an `AppMetricsErrorBoundary` on React, Vue,
+Solid, and Svelte, each wrapping that framework's own catch primitive.
+
+## Scope decision (2026-09-28)
+
+Unlike every other package in this catalog, `expo-app-metrics` ships real per-framework
+surface, not just a thin async-function wrapper. React, Vue, Solid, and Svelte each already have
+a subtree-scoped error-catch mechanism (React's class boundary, Vue's `onErrorCaptured`, Solid's
+built-in `ErrorBoundary`, Svelte 5's `<svelte:boundary>`), so `AppMetricsErrorBoundary` wraps
+that mechanism on all four, sharing the report-building logic through
+`core/report-caught-error.ts`. `useNetworkRequestObserver`/`injectNetworkRequestObserver` ship on
+all five adapters (see "API" below).
+
+**Angular is NOT a permanent gap - it is version-gated.** Angular's own `@boundary`/`@error`
+template primitive (stable `@publicApi` since `@angular/core` 22.2.0) is a real, DI-resolved
+subtree error boundary (`ErrorHandler.onViewError`), the same caught-vs-uncaught split this
+package already uses elsewhere. This repo pins `@angular/core` to `~22.0.8`
+(`pnpm-workspace.yaml`) because `@angular/compiler-cli` >=22.1.0 bundles its own
+`@babel/core@8` and its AOT linker asserts Babel 8, while this repo loads that linker INSIDE
+Metro's own Babel 7 pipeline - re-tried bumping to 22.2.0 for this package (2026-09-28),
+reproduced the exact `assertVersion(8)` throw directly against the real installed Babel, no
+legacy Babel-7 linker build exists, reverted. `AppMetricsRoot` needed no version bump (it is a
+plain `<ng-content>` wrapper marking first render in `ngOnInit`) and ships on `./angular` now.
+`AppMetricsErrorBoundary` for Angular - as an `AppMetricsBoundaryErrorHandler` the consumer
+provides on their own `@boundary`-owning component, since Angular's own docs mark
+`<ng-content>` inside `@boundary`/`@error` an antipattern, so a reusable wrapper COMPONENT is
+not the right shape there either - ships once the catalog can move past 22.0.8.
+
+## Install
+
+**New app:**
+
+```bash
+npx @symbiote-native/cli new my-app --app-metrics
+```
+
+**Existing SymbioteNative app:**
+
+```bash
+npx @symbiote-native/cli add --app-metrics
+```
+
+Either way: installs `@symbiote-native/app-metrics` and wires the native autolinking
+automatically, see [`@symbiote-native/cli`](../cli).
+
+<details>
+<summary>Manual install (no CLI, wiring native autolinking by hand)</summary>
+
+```bash
+npm install @symbiote-native/app-metrics
+```
+
+`expo-app-metrics` and `expo-modules-core` come along as regular dependencies, pinned to exact
+versions. Never install either yourself, and never add the `expo` meta-package to your project
+(it bundles its own Metro/Babel pipeline, which conflicts with this project's own).
+
+## Required one-time step: native autolinking wiring
+
+Unlike a plain RN native module, `expo-app-metrics`'s native code is discovered by
+`expo-modules-autolinking`, not RN's own `react-native.config.cjs` mechanism. This needs wiring
+into the native host app **once**, covering this package and every other `expo-modules-core`
+package with zero further changes. Full mechanics live in the `symbiote-expo-native-module`
+project skill.
+
+No app-level permission strings are needed for this package.
+
+</details>
+
+## Shape
+
+```
+src/core/     markFirstRender / markInteractive / logEvent / setGlobalAttributes /
+              clearStoredEntries / getInactiveSessions / getAllCrashReports (android) /
+              reportError / getMainSession / getForegroundSession, the Session and
+              NetworkRequestObserver classes (re-exported straight off the native module, same
+              pattern as @symbiote-native/audio), installErrorHandler (wraps global ErrorUtils,
+              installed automatically on import), plus every public type
+src/react/    AppMetricsRoot, AppMetricsErrorBoundary, useNetworkRequestObserver
+src/vue/      AppMetricsRoot, AppMetricsErrorBoundary (over onErrorCaptured), useNetworkRequestObserver
+src/solid/    AppMetricsRoot, AppMetricsErrorBoundary (over solid-js's own ErrorBoundary), useNetworkRequestObserver
+src/svelte/   AppMetricsRoot.svelte, AppMetricsErrorBoundary.svelte (over <svelte:boundary>), useNetworkRequestObserver
+src/angular/  AppMetricsRoot (plain <ng-content> wrapper), injectNetworkRequestObserver, no boundary yet (see Scope decision)
+```
+
+## API
+
+```ts
+markFirstRender(): void
+markInteractive(attributes?: IMetricAttributes): void
+logEvent(name: string, options?: ILogEventOptions): void
+setGlobalAttributes(attributes?: Record<string, ILogAttributeValue> | null): void
+clearStoredEntries(): Promise<void>
+getInactiveSessions(): Promise<IDebugSession[]> // debug-only
+getAllCrashReports(): Promise<ICrashReport[]> // android only, debug-only
+reportError(error: IReportErrorInput): void
+getMainSession(): Session
+getForegroundSession(): Promise<Session | null>
+installErrorHandler(): void // called automatically on import
+
+class Session { id; type; startDate; isActive(); getEndDate(); getMetrics(); getLogs(); addMetric(metric) }
+class NetworkRequestObserver { constructor(filter?); setFilter(filter) } // + addListener/removeListener
+```
+
+`AppMetricsRoot` ships on all five adapters. `AppMetricsErrorBoundary` ships on `./react`,
+`./vue`, `./solid`, and `./svelte` only (see Scope decision for `./angular`):
+
+```tsx
+<AppMetricsRoot errorBoundaryFallback={...}>{children}</AppMetricsRoot>
+<AppMetricsErrorBoundary fallback={...}>{children}</AppMetricsErrorBoundary>
+```
+
+Angular's `AppMetricsRoot` takes no `errorBoundaryFallback` (no boundary to gate yet) - just
+`<app-metrics-root><ng-content /></app-metrics-root>` in a template.
+
+`AppMetricsRoot.wrap(App)` is React-only (a static helper on the class).
+
+`useNetworkRequestObserver` ships on React, Vue, Solid, and Svelte, taking a getter of
+`{ filter?, onStarted?, onCompleted? }` (a plain object on React) and returning the
+`NetworkRequestObserver`; Angular's twin is `injectNetworkRequestObserver`, same shape.
+
+```ts
+import { markFirstRender, reportError } from '@symbiote-native/app-metrics';
+import { AppMetricsRoot, AppMetricsErrorBoundary } from '@symbiote-native/app-metrics/react';
+// or '/vue', '/solid', '/svelte'; '/angular' exports AppMetricsRoot + injectNetworkRequestObserver only
+```
+
+## Notes
+
+- **`getForegroundSession` is typed `@platform ios` in upstream's own JSDoc, but its native
+  module implements it on both platforms**, confirmed by reading `AppMetricsModule.swift` and
+  `AppMetricsModule.kt` directly, not the comment. Ported as unconditionally available here.
+- **`getAllCrashReports` is Android-only** on the native module; calling it off Android throws
+  `UnavailabilityError`, matching this repo's own convention for every other platform-gated
+  function. Upstream itself has no such guard, since it never wraps the raw native module in
+  per-platform checks; this package normalizes it the same way every sibling package does.
+- **`installErrorHandler` runs automatically the moment this package is imported**, an eager
+  side effect in `src/core/index.ts` matching upstream's own `index.ts`, wrapping React
+  Native's global `ErrorUtils` handler so an unhandled JS error reaches `reportError` before
+  chaining to whatever handler ran before it.
+- **`AppMetricsErrorBoundary` reports through `core/report-caught-error.ts`, independent of this
+  engine's `reportUncaughtError` channel** (`core/engine/src/report-error.ts`). A caught error
+  never reaches this engine's own uncaught-error reporting, by design, on any of the four
+  adapters that have one - see each adapter's own `render-error-reporting.test.*`.
+- **Vue's `onErrorCaptured` gives no component stack** (its `info` argument is a lifecycle-phase
+  string, not a real trace), so the Vue and Solid boundaries call `reportCaughtError(error)` with
+  no second argument; only React's class boundary has a real `componentStack` to forward.
+- **Solid's `mount()` and Svelte's `mount()` both rethrow an uncaught error** rather than
+  swallowing it (each adapter's own tested contract) - `AppMetricsRoot` without
+  `errorBoundaryFallback` on those two adapters leaves that throw to reach the caller, same as
+  not wrapping the tree at all.
+- `Session` and `NetworkRequestObserver` are native `SharedObject` classes exposed as class
+  properties on the native module (see the `symbiote-expo-native-module` skill's SharedObject
+  section) - there is no JS logic to port beyond the re-export, same as
+  `@symbiote-native/audio`'s `AudioPlaylist`.
+- The canary `AppMetricsScreen` in the `examples/expo-*` apps exercises the root, the boundary and
+  the network observer.
+
+## Common questions
+
+- **What does it collect?** Startup (cold/warm launch, bundle load, time to first render), frame
+  rate, memory, sessions, and your own events.
+- **Where do the numbers go?** EAS Observe, or any OpenTelemetry-compatible backend.
+- **Time to interactive missing.** You must mark the app interactive yourself.
+
+Sources: [Expo docs: Introduction to EAS Observe](https://docs.expo.dev/eas/observe/introduction/),
+[Introducing Observe](https://expo.dev/blog/introducing-observe).
+
+## Test it
+
+Core is tested the same way as every other package in this catalog: a fake native-module object
+in place of `requireNativeModule` (`src/core/app-metrics.test.ts`, `src/core/
+install-error-handler.test.ts`). The React layer is a real mount through this repo's own
+Fabric-recording harness (`mount`/`unmount` + `installRecordingFabric`, ADR 0025):
+`src/react/app-metrics-root.test.tsx`, `src/react/app-metrics-error-boundary.test.tsx`, and
+`src/react/use-network-request-observer.test.tsx`, adapted from upstream's own
+`@testing-library/react-native` test suites onto this project's harness.

package/build/angular/app-metrics-root.d.ts

@@ -0,0 +1,5 @@
+import { type OnInit } from '@angular/core';
+/** Marks the first render, so time-to-first-render is measured without a manual call */
+export declare class AppMetricsRoot implements OnInit {
+    ngOnInit(): void;
+}

package/build/angular/app-metrics-root.js

@@ -0,0 +1,62 @@
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+import { Component } from '@angular/core';
+import { markFirstRender } from '../core/index.js';
+/** Marks the first render, so time-to-first-render is measured without a manual call */
+let AppMetricsRoot = (() => {
+    let _classDecorators = [Component({
+            selector: 'app-metrics-root',
+            standalone: true,
+            template: '<ng-content />',
+        })];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    var AppMetricsRoot = class {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            AppMetricsRoot = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+        ngOnInit() {
+            markFirstRender();
+        }
+    };
+    return AppMetricsRoot = _classThis;
+})();
+export { AppMetricsRoot };

package/build/angular/index.d.ts

@@ -0,0 +1,3 @@
+export * from '../core';
+export { AppMetricsRoot } from './app-metrics-root';
+export { injectNetworkRequestObserver, type IUseNetworkRequestObserverOptions, } from './inject-network-request-observer';

package/build/angular/index.js

@@ -0,0 +1,5 @@
+// No `AppMetricsErrorBoundary` here - blocked on `@angular/core` >=22.2
+// (this package's README "Scope decision")
+export * from '../core/index.js';
+export { AppMetricsRoot } from './app-metrics-root.js';
+export { injectNetworkRequestObserver, } from './inject-network-request-observer.js';

package/build/angular/inject-network-request-observer.d.ts

@@ -0,0 +1,5 @@
+import type { NetworkRequestObserver } from '../core';
+import type { IUseNetworkRequestObserverOptions } from '../core/network-request-observer-lifecycle';
+export type { IUseNetworkRequestObserverOptions } from '../core/network-request-observer-lifecycle';
+/** Angular twin of `expo-app-metrics`'s `useNetworkRequestObserver` */
+export declare function injectNetworkRequestObserver(getOptions?: () => IUseNetworkRequestObserverOptions): NetworkRequestObserver;

package/build/angular/inject-network-request-observer.js

@@ -0,0 +1,7 @@
+import { DestroyRef, effect, inject } from '@angular/core';
+import { createNetworkRequestObserverLifecycle } from '../core/network-request-observer-lifecycle.js';
+/** Angular twin of `expo-app-metrics`'s `useNetworkRequestObserver` */
+export function injectNetworkRequestObserver(getOptions = () => ({})) {
+    const destroyRef = inject(DestroyRef);
+    return createNetworkRequestObserverLifecycle(getOptions, filterEffect => effect(filterEffect), cleanup => destroyRef.onDestroy(cleanup));
+}

package/build/core/app-metrics.d.ts

@@ -0,0 +1,24 @@
+import type { ICrashReport, IDebugSession, ILogAttributeValue, ILogEventOptions, IMetricAttributes, IReportErrorInput } from './types';
+/** Marks the moment the app is ready to measure time to first render */
+export declare function markFirstRender(): void;
+export declare function markInteractive(attributes?: IMetricAttributes): void;
+/** Persisted locally, dispatched on the next flush as an OpenTelemetry log record */
+export declare function logEvent(name: string, options?: ILogEventOptions): void;
+/** Merged into every subsequent metric and log event, per-record keys win on collision */
+export declare function setGlobalAttributes(attributes?: Record<string, ILogAttributeValue> | null): void;
+export declare function clearStoredEntries(): Promise<void>;
+/** Debug-only, ordered most-recent-first, each session eagerly includes metrics/logs/crash */
+export declare function getInactiveSessions(): Promise<IDebugSession[]>;
+/** Debug-only, includes orphan crashes with `sessionId: null`. @platform android */
+export declare function getAllCrashReports(): Promise<ICrashReport[]>;
+/** Called by `installErrorHandler`'s global handler and `AppMetricsErrorBoundary` */
+export declare function reportError(error: IReportErrorInput): void;
+/** The per-launch session, a static reference: repeated calls return the same object */
+export declare function getMainSession(): import("./session").Session;
+/** Created when the app becomes active, ended when backgrounded, `null` when none is active */
+export declare function getForegroundSession(): Promise<import("./session").Session | null>;
+export declare const NetworkRequestObserver: typeof import("./network-request-observer").NetworkRequestObserver;
+export type NetworkRequestObserver = InstanceType<typeof NetworkRequestObserver>;
+/** Not intended to be constructed from user code, see `getMainSession`/`getForegroundSession` */
+export declare const Session: typeof import("./session").Session;
+export type Session = InstanceType<typeof Session>;

package/build/core/app-metrics.js

@@ -0,0 +1,47 @@
+import { Platform, UnavailabilityError } from 'expo-modules-core';
+import { expoAppMetrics } from './native-module.js';
+const NATIVE_MODULE_NAME = 'expo-app-metrics';
+/** Marks the moment the app is ready to measure time to first render */
+export function markFirstRender() {
+    expoAppMetrics.markFirstRender();
+}
+export function markInteractive(attributes) {
+    expoAppMetrics.markInteractive(attributes);
+}
+/** Persisted locally, dispatched on the next flush as an OpenTelemetry log record */
+export function logEvent(name, options) {
+    expoAppMetrics.logEvent(name, options);
+}
+/** Merged into every subsequent metric and log event, per-record keys win on collision */
+export function setGlobalAttributes(attributes) {
+    expoAppMetrics.setGlobalAttributes(attributes);
+}
+export async function clearStoredEntries() {
+    return expoAppMetrics.clearStoredEntries();
+}
+/** Debug-only, ordered most-recent-first, each session eagerly includes metrics/logs/crash */
+export async function getInactiveSessions() {
+    return expoAppMetrics.getInactiveSessions();
+}
+/** Debug-only, includes orphan crashes with `sessionId: null`. @platform android */
+export async function getAllCrashReports() {
+    if (Platform.OS !== 'android' || !expoAppMetrics.getAllCrashReports) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getAllCrashReports');
+    }
+    return expoAppMetrics.getAllCrashReports();
+}
+/** Called by `installErrorHandler`'s global handler and `AppMetricsErrorBoundary` */
+export function reportError(error) {
+    expoAppMetrics.reportError(error);
+}
+/** The per-launch session, a static reference: repeated calls return the same object */
+export function getMainSession() {
+    return expoAppMetrics.getMainSession();
+}
+/** Created when the app becomes active, ended when backgrounded, `null` when none is active */
+export async function getForegroundSession() {
+    return expoAppMetrics.getForegroundSession();
+}
+export const NetworkRequestObserver = expoAppMetrics.NetworkRequestObserver;
+/** Not intended to be constructed from user code, see `getMainSession`/`getForegroundSession` */
+export const Session = expoAppMetrics.Session;

package/build/core/index.d.ts

@@ -0,0 +1,5 @@
+export { clearStoredEntries, getAllCrashReports, getForegroundSession, getInactiveSessions, getMainSession, logEvent, markFirstRender, markInteractive, NetworkRequestObserver, reportError, Session, setGlobalAttributes, } from './app-metrics';
+export { filterKeyOf, subscribeNetworkRequestObserverEvents, } from './network-request-observer-subscription';
+export type { INetworkRequestObserverCallbacks, ISubscribableNetworkRequestObserver, } from './network-request-observer-subscription';
+export type { IAppStartupTimes, ICallStack, ICallStackFrame, ICallStackTree, ICrashReport, IDebugSession, IFrameRateMetrics, ILogAttributeValue, ILogEventOptions, ILogRecord, ILogSeverity, IMemoryUsageSnapshot, IMetric, IMetricAttributes, IMetricInput, INetworkRequestCompletedEvent, INetworkRequestFilter, INetworkRequestObserverEvents, INetworkRequestRedirect, INetworkRequestStartedEvent, IReportErrorInput, ISessionType, } from './types';
+export { installErrorHandler } from './install-error-handler';

package/build/core/index.js

@@ -0,0 +1,6 @@
+import { installErrorHandler } from './install-error-handler.js';
+export { clearStoredEntries, getAllCrashReports, getForegroundSession, getInactiveSessions, getMainSession, logEvent, markFirstRender, markInteractive, NetworkRequestObserver, reportError, Session, setGlobalAttributes, } from './app-metrics.js';
+export { filterKeyOf, subscribeNetworkRequestObserverEvents, } from './network-request-observer-subscription.js';
+export { installErrorHandler } from './install-error-handler.js';
+// Live as early as the app pulls this module in, matching upstream's own side effect
+installErrorHandler();

package/build/core/install-error-handler.d.ts

@@ -0,0 +1,2 @@
+/** Wraps React Native's global `ErrorUtils` handler, chaining to whatever ran before it */
+export declare function installErrorHandler(): void;

package/build/core/install-error-handler.js

@@ -0,0 +1,45 @@
+import { reportError } from './app-metrics.js';
+let installed = false;
+// react-native ships its own ambient `ErrorUtils` global, so a package whose tsconfig pulls
+// that in conflicts with a local `declare global` here (core/engine/src/report-error.ts hit
+// this, TS2451) - reading it off `globalThis` through Reflect sidesteps the whole ambient type
+function globalErrorUtils() {
+    const utils = Reflect.get(globalThis, 'ErrorUtils');
+    if (typeof utils !== 'object' || utils === null)
+        return null;
+    const getGlobalHandler = Reflect.get(utils, 'getGlobalHandler');
+    const setGlobalHandler = Reflect.get(utils, 'setGlobalHandler');
+    if (typeof getGlobalHandler !== 'function' ||
+        typeof setGlobalHandler !== 'function') {
+        return null;
+    }
+    return {
+        getGlobalHandler: () => Reflect.apply(getGlobalHandler, utils, []),
+        setGlobalHandler: handler => Reflect.apply(setGlobalHandler, utils, [handler]),
+    };
+}
+/** Wraps React Native's global `ErrorUtils` handler, chaining to whatever ran before it */
+export function installErrorHandler() {
+    if (installed)
+        return;
+    const errorUtils = globalErrorUtils();
+    if (!errorUtils)
+        return;
+    installed = true;
+    const previousHandler = errorUtils.getGlobalHandler();
+    errorUtils.setGlobalHandler((error, isFatal) => {
+        try {
+            const asError = error instanceof Error ? error : undefined;
+            reportError({
+                source: 'global',
+                type: asError?.name,
+                message: asError?.message ?? String(error),
+                stacktrace: asError?.stack,
+                isFatal: isFatal ?? false,
+            });
+        }
+        finally {
+            previousHandler?.(error, isFatal);
+        }
+    });
+}

package/build/core/native-module.d.ts

@@ -0,0 +1,19 @@
+import type { NetworkRequestObserver } from './network-request-observer';
+import type { Session } from './session';
+import type { ICrashReport, IDebugSession, ILogAttributeValue, ILogEventOptions, IMetricAttributes, IReportErrorInput } from './types';
+export type INativeAppMetricsModule = {
+    markFirstRender(): void;
+    markInteractive(attributes?: IMetricAttributes): void;
+    logEvent(name: string, options?: ILogEventOptions): void;
+    setGlobalAttributes(attributes?: Record<string, ILogAttributeValue> | null): void;
+    clearStoredEntries(): Promise<void>;
+    getInactiveSessions(): Promise<IDebugSession[]>;
+    /** Android's native module only, app-metrics.ts gates it on Platform.OS */
+    getAllCrashReports?(): Promise<ICrashReport[]>;
+    reportError(error: IReportErrorInput): void;
+    getMainSession(): Session;
+    getForegroundSession(): Promise<Session | null>;
+    NetworkRequestObserver: typeof NetworkRequestObserver;
+    Session: typeof Session;
+};
+export declare const expoAppMetrics: INativeAppMetricsModule;

package/build/core/native-module.js

@@ -0,0 +1,3 @@
+import { requireNativeModule } from 'expo-modules-core';
+const EXPO_APP_METRICS_MODULE_NAME = 'ExpoAppMetrics';
+export const expoAppMetrics = requireNativeModule(EXPO_APP_METRICS_MODULE_NAME);

package/build/core/network-request-observer-lifecycle.d.ts

@@ -0,0 +1,8 @@
+import { NetworkRequestObserver } from './app-metrics';
+import type { INetworkRequestObserverCallbacks } from './network-request-observer-subscription';
+import type { INetworkRequestFilter } from './types';
+export type IUseNetworkRequestObserverOptions = INetworkRequestObserverCallbacks & {
+    /** Applied natively. Omit or pass `null` to observe every request */
+    filter?: INetworkRequestFilter | null;
+};
+export declare function createNetworkRequestObserverLifecycle(getOptions: () => IUseNetworkRequestObserverOptions, runFilterEffect: (effect: () => void) => void, registerCleanup: (cleanup: () => void) => void): NetworkRequestObserver;

package/build/core/network-request-observer-lifecycle.js

@@ -0,0 +1,19 @@
+import { NetworkRequestObserver } from './app-metrics.js';
+import { filterKeyOf, subscribeNetworkRequestObserverEvents, } from './network-request-observer-subscription.js';
+// Shared by adapters whose reactivity auto-tracks reads inside a plain effect (Vue's
+// `watchEffect`, Solid's `createEffect`); React's render model doesn't, so it keeps its own wiring
+export function createNetworkRequestObserverLifecycle(getOptions, runFilterEffect, registerCleanup) {
+    const initialFilter = getOptions().filter;
+    const observer = new NetworkRequestObserver(initialFilter);
+    let appliedFilterKey = filterKeyOf(initialFilter);
+    runFilterEffect(() => {
+        const nextKey = filterKeyOf(getOptions().filter);
+        if (appliedFilterKey === nextKey)
+            return;
+        appliedFilterKey = nextKey;
+        observer.setFilter(getOptions().filter ?? null);
+    });
+    registerCleanup(subscribeNetworkRequestObserverEvents(observer, getOptions));
+    registerCleanup(() => observer.release());
+    return observer;
+}

package/build/core/network-request-observer-subscription.d.ts

@@ -0,0 +1,15 @@
+import type { INetworkRequestCompletedEvent, INetworkRequestFilter, INetworkRequestStartedEvent } from './types';
+export declare function filterKeyOf(filter: INetworkRequestFilter | null | undefined): string;
+export type INetworkRequestObserverCallbacks = {
+    onStarted?: (event: INetworkRequestStartedEvent) => void;
+    onCompleted?: (event: INetworkRequestCompletedEvent) => void;
+};
+export type ISubscribableNetworkRequestObserver = {
+    addListener(event: 'requestStarted', listener: (event: INetworkRequestStartedEvent) => void): {
+        remove: () => void;
+    };
+    addListener(event: 'requestCompleted', listener: (event: INetworkRequestCompletedEvent) => void): {
+        remove: () => void;
+    };
+};
+export declare function subscribeNetworkRequestObserverEvents(observer: ISubscribableNetworkRequestObserver, getCallbacks: () => INetworkRequestObserverCallbacks): () => void;

package/build/core/network-request-observer-subscription.js

@@ -0,0 +1,22 @@
+// Field-listed rather than a bare JSON.stringify(filter) so `{ hosts, methods }` and
+// `{ methods, hosts }` (the same filter) don't produce different keys
+export function filterKeyOf(filter) {
+    return JSON.stringify({
+        hosts: filter?.hosts ?? null,
+        methods: filter?.methods ?? null,
+    });
+}
+// `getCallbacks` is read fresh on every event, so a caller never needs to resubscribe just
+// because its own callbacks changed identity between renders
+export function subscribeNetworkRequestObserverEvents(observer, getCallbacks) {
+    const startedSubscription = observer.addListener('requestStarted', event => {
+        getCallbacks().onStarted?.(event);
+    });
+    const completedSubscription = observer.addListener('requestCompleted', event => {
+        getCallbacks().onCompleted?.(event);
+    });
+    return () => {
+        startedSubscription.remove();
+        completedSubscription.remove();
+    };
+}

package/build/core/network-request-observer.d.ts

@@ -0,0 +1,7 @@
+import type { SharedObject } from 'expo-modules-core';
+import type { INetworkRequestFilter, INetworkRequestObserverEvents } from './types';
+export declare class NetworkRequestObserver extends SharedObject<INetworkRequestObserverEvents> {
+    constructor(filter?: INetworkRequestFilter | null);
+    /** Applies atomically, in-flight events are emitted under either the old or new filter */
+    setFilter(filter: INetworkRequestFilter | null): void;
+}

package/build/core/network-request-observer.js

@@ -0,0 +1 @@
+export {};

package/build/core/report-caught-error.d.ts

@@ -0,0 +1,2 @@
+/** Shared by every adapter's error-boundary equivalent, builds and reports a caught render error */
+export declare function reportCaughtError(error: unknown, componentStack?: string): void;

package/build/core/report-caught-error.js

@@ -0,0 +1,20 @@
+import { reportError } from './app-metrics.js';
+/** Shared by every adapter's error-boundary equivalent, builds and reports a caught render error */
+export function reportCaughtError(error, componentStack) {
+    const caught = error instanceof Error ? error : undefined;
+    try {
+        reportError({
+            source: 'errorBoundary',
+            type: caught?.name,
+            message: caught?.message ?? String(error),
+            stacktrace: caught?.stack,
+            componentStack,
+            isFatal: false,
+        });
+    }
+    catch (reportingError) {
+        if (__DEV__) {
+            console.warn('[app-metrics] Failed to report a caught error:', reportingError);
+        }
+    }
+}

package/build/core/session.d.ts

@@ -0,0 +1,12 @@
+import type { SharedObject } from 'expo-modules-core';
+import type { ILogRecord, IMetric, IMetricInput, ISessionType } from './types';
+export declare class Session extends SharedObject {
+    readonly id: string;
+    readonly type: ISessionType;
+    readonly startDate: string;
+    isActive(): Promise<boolean>;
+    getEndDate(): Promise<string | null>;
+    getMetrics(): Promise<IMetric[]>;
+    getLogs(): Promise<ILogRecord[]>;
+    addMetric(metric: IMetricInput): Promise<void>;
+}

package/build/core/session.js

@@ -0,0 +1 @@
+export {};