feat: WHATWG performance API (hr-time, user timing, performance timeline) (#2001)

* feat: WHATWG performance API (hr-time, user timing, performance timeline)

Replaces the bare native {now, timeOrigin} object with a spec-shaped
implementation of High Resolution Time, User Timing Level 3 and the
Performance Timeline with PerformanceObserver. performance, Performance,
PerformanceEntry, PerformanceMark, PerformanceMeasure, PerformanceObserver
and PerformanceObserverEntryList are globals in the main and worker isolates
alike, with Performance extends EventTarget and WebIDL-shaped descriptors
and brands.

All spec logic lives in the internal/performance.js builtin, which the
native side feeds exactly two values -- binding.now() and
binding.timeOrigin -- so the file is shared verbatim with the iOS runtime.
tns::Performance::NowMillis(isolate) is the single native clock hook a
future requestAnimationFrame must read, so every JS-visible timestamp
shares performance.timeOrigin as its base. Time origins stay per-Runtime,
captured in PrepareV8Runtime, so each worker keeps its own.

mark/measure detail is structured-cloned at entry creation through the
structuredClone global installed by StructuredClone::Init, so entries hold
snapshots and an uncloneable detail throws the DataCloneError-named error;
the builtin keeps an identity fallback for a runtime that ships the
Performance API before structuredClone.

Mirrors NativeScript/ios#430 and 6dd55238d.

* feat: put frame callbacks on the performance timeline

__postFrameCallback now hands its callback two arguments,
(frameTimeNanos, performanceMillis). The first is unchanged -- the
platform's raw CLOCK_MONOTONIC frame time, which shipped app code divides
by 1e6 -- and the second is that same instant on the isolate's performance
timeline, so it compares directly with performance.now(). Choreographer
stamps frames on the clock the time origin is captured on, so the
conversion (Performance::MonotonicNanosToTimelineMillis, subtracting the
new Runtime::TimeOriginMonotonicMillis) is exact rather than a resampling.

The machinery moves out of CallbackHandlers into FrameCallbacks.{h,cpp},
which now covers the whole minSdk range: AChoreographer only exists from
API 24, so below it __postFrameCallback silently never fired. API 21-23 now
goes through android.view.Choreographer via com.tns.FrameCallbacks, holding
the same entry and producing the same two arguments. Entries are stored
behind unique_ptr so both implementations can hand the platform a stable
pointer, isolate teardown no longer erases while iterating, and the frame
time from the pre-API-29 AChoreographer entry point is widened to 64 bits,
which it is not on the 32-bit ABIs.

Debug runtimes expose __setFrameCallbackImpl so the Java bridge is
selectable on a modern device; both implementations are covered by specs.

* fix: guard the frame-callback registry and measure()'s null options

The registry holds entries for every isolate in the process, so its
lookups now take a mutex -- never held across the JS call, which a
self-rescheduling callback re-enters -- and the two lazy-init blocks (the
AChoreographer dlsym, the FrameCallbacks method ids) go through call_once.
Entries are identified to the platform by id rather than by address, so a
frame arriving after its entry was retired resolves to nothing instead of
to freed memory, and teardown detaches entries under the mutex and
destroys them after releasing it, since the destructor calls into Java.
The registry was shared and unguarded before it moved out of
CallbackHandlers; this is not a regression from the move.

Dispatch no longer throws. On the NDK path it runs inside a C callback in
libandroid, which a C++ exception may not unwind through, so a JS
exception the runtime still owns goes to Java the way Timers::FireTimer
does. com.tns.FrameCallbacks.released becomes volatile: it is set from
runtime teardown, which is not necessarily the frame thread.

measure() treats a null startOrMeasureOptions as absent. WebIDL converts
null for a (DOMString or PerformanceMeasureOptions) union to an empty
dictionary, so it means "no options", not the mark name "null". A null
endMark keeps throwing: that parameter is a plain DOMString, neither a
union nor nullable, so null stringifies per WebIDL.

* test: isolate the null end mark spec and bump the shared suite

The spec measured from "the-start", which it never created, so the
SyntaxError it asserts could have come from that missing mark rather than
from the null end mark it is about.

The shared suite moves to 0baab7c, which measures the timeOrigin anchor as
a min-of-N offset against a loose bound: reconstructing Date.now() from
timeOrigin + now() races three clock reads, and a stall between them read
as an anchoring error on a contended host.

Author: NathanWalker

docs/README.md

@@ -1,5 +1,9 @@
 # Runtime documentation
 
+- [Performance API](performance.md) — WHATWG `performance` (hr-time, user
+  timing, performance timeline with `PerformanceObserver`), per-isolate time
+  origins for workers, the native clock hook that future `requestAnimationFrame`
+  work must share, and the documented spec deviations.
 - [Error handling](error-handling.md) — global `error`/`unhandledrejection` events, `reportError`, catching Java exceptions in JS (`error.nativeException`), forwarding JS throws to Java callers (`interop.escapeException`), JS stacks on Java exceptions (`com.tns.JavaScriptStackTrace`), configuration flags, and crash-reporter integration.
 - [structuredClone](structured-clone.md) — the WHATWG `structuredClone(value, { transfer })` global: what clones, how graph identity and cycles are preserved, `ArrayBuffer` transfer, and the `DataCloneError`-named `Error` that stands in for `DOMException`.
 - [Implementing additional Chrome DevTools protocol Domains](extending-inspector.md)

docs/performance.md

@@ -0,0 +1,102 @@
+# Performance API
+
+The runtime implements the WHATWG/WinterTC-standard Performance surface: [High
+Resolution Time](https://w3c.github.io/hr-time/), [User Timing Level
+3](https://w3c.github.io/user-timing/) and the [Performance
+Timeline](https://w3c.github.io/performance-timeline/) with
+`PerformanceObserver`.
+
+## Surface
+
+Globals (own, writable, enumerable, configurable properties of `globalThis`,
+in main and worker isolates alike): `performance`, `Performance`,
+`PerformanceEntry`, `PerformanceMark`, `PerformanceMeasure`,
+`PerformanceObserver`, `PerformanceObserverEntryList`.
+
+- `performance.now()` — double milliseconds since the isolate's time origin,
+  monotonic (V8's platform clock, `CLOCK_MONOTONIC`-based: it does not tick
+  while the device is suspended), full double precision with no coarsening.
+- `performance.timeOrigin` — readonly accessor; wall-clock milliseconds since
+  the Unix epoch, sampled once when the isolate's runtime is created. Each
+  worker gets its own time origin at worker-thread start, so
+  `timeOrigin + now()` approximates `Date.now()` per isolate while the device
+  stays awake; it drifts behind after device suspend (the monotonic clock does
+  not tick then) and diverges under wall-clock adjustments.
+- `performance.toJSON()`, `Symbol.toStringTag`, and `Performance extends
+  EventTarget` per spec; `performance`, `PerformanceEntry`,
+  `PerformanceMeasure` and `PerformanceObserverEntryList` are not
+  user-constructible (`new` throws `TypeError`); `new PerformanceMark(name,
+  options)` is constructible per spec but does not buffer the entry.
+- User timing: `mark(name, {startTime, detail})`, `measure(name,
+  startOrOptions, endMark)` with the full Level 3 options algebra (`{start,
+  end, duration, detail}`, mark names or timestamps, over-/under-constraint
+  errors), `clearMarks(name?)`, `clearMeasures(name?)`.
+- Timeline: `getEntries()`, `getEntriesByType(type)`, `getEntriesByName(name,
+  type?)` return copies sorted chronologically by `startTime` (stable for
+  ties).
+- Observers: `new PerformanceObserver(cb)`, `observe({entryTypes})` or
+  `observe({type, buffered})`, `disconnect()`, `takeRecords()`, static frozen
+  `PerformanceObserver.supportedEntryTypes`, which is `["mark", "measure"]`.
+
+## Architecture
+
+All spec logic lives in the `internal/performance.js` builtin
+(`test-app/runtime/src/main/cpp/js/performance.js`), shared with the iOS
+runtime: the native side hands it only `{ now(), timeOrigin }`, so the same
+file runs unchanged on both runtimes and should be kept in sync with iOS's
+copy.
+
+The native clock is owned by `Runtime` (`Runtime::PerformanceNowMillis()`,
+`Runtime::TimeOriginMillis()`, `Runtime::TimeOriginMonotonicMillis()`,
+captured in `Runtime::PrepareV8Runtime`) and exposed to native callers through
+`tns::Performance::NowMillis(isolate)`
+(`test-app/runtime/src/main/cpp/Performance.h`). Any native producer of
+JS-visible timestamps must read the clock through that hook rather than
+sampling its own, so every timestamp shares `performance.timeOrigin` as its
+base.
+
+## Frame callbacks
+
+`__postFrameCallback(fn[, delayMillis])` / `__removeFrameCallback(fn)`
+(`test-app/runtime/src/main/cpp/FrameCallbacks.h`) schedule `fn` for the next
+display frame. `fn` receives **two** arguments:
+
+```js
+__postFrameCallback((frameTimeNanos, performanceMillis) => { … });
+```
+
+- `frameTimeNanos` — the platform's raw frame time: `CLOCK_MONOTONIC`
+  nanoseconds, the `System.nanoTime()` base. Unchanged from earlier runtimes,
+  which passed it as the only argument.
+- `performanceMillis` — the same instant on this isolate's performance
+  timeline, so it compares directly with `performance.now()`. Converted
+  natively through `Performance::MonotonicNanosToTimelineMillis()`, which
+  subtracts `Runtime::TimeOriginMonotonicMillis()` — Choreographer stamps
+  frames on the very clock the time origin is captured on, so the mapping is
+  exact rather than an approximation resampled in JS.
+
+Two implementations sit behind that one surface: the NDK's `AChoreographer`
+(API 24+, resolved with `dlsym`) and `android.view.Choreographer` through
+`com.tns.FrameCallbacks` for API 21–23, where the NDK API does not exist.
+Scheduling is per calling thread, so a worker schedules against its own looper.
+Both paths produce the same two arguments with the same exactness.
+
+## Deviations from the specs
+
+- **Buffers are unbounded.** Per spec for user timing. `detail` is
+  structured-cloned at entry creation (per spec — an uncloneable `detail`
+  throws the `DataCloneError`-named error, see
+  [structuredClone](structured-clone.md)), so entries hold snapshots, but a
+  long-lived app marking in a loop should still clear entries periodically.
+- **Observer callbacks run from a microtask**, not a queued task: delivery is
+  asynchronous relative to `mark()`/`measure()` but precedes timer callbacks
+  scheduled in the same turn. Callback exceptions are routed to
+  `reportError`, so one throwing observer does not starve the others.
+- **No `DOMException`.** Errors the specs express as `DOMException` — the
+  `SyntaxError` for a missing mark name, the `InvalidModificationError` for
+  switching an observer between the `entryTypes` and `type` forms — are
+  `Error` instances with `name` patched. `err.name` checks work;
+  `instanceof DOMException` does not.
+- Browser-only surface is absent: no resource/navigation timing, no
+  `eventCounts`, and no `PerformanceTiming`-attribute resolution in
+  `measure()`.

eslint.config.mjs

@@ -15,6 +15,7 @@ const capturedStatics = [
   ['Array', 'isArray', 'ArrayIsArray'],
   ['ArrayBuffer', 'isView', 'ArrayBufferIsView'],
   ['JSON', 'stringify', 'JSONStringify'],
+  ['Number', 'isFinite', 'NumberIsFinite'],
   ['Number', 'isNaN', 'NumberIsNaN'],
   ['Number', 'parseFloat', 'NumberParseFloat'],
   ['Number', 'parseInt', 'NumberParseInt'],

test-app/app/src/main/assets/app/mainpage.js

@@ -18,6 +18,7 @@ shared.runRequireTests();
 shared.runWeakRefTests();
 shared.runRuntimeTests();
 shared.runWorkerTests();
+shared.runPerformanceTests();
 shared.runStructuredCloneTests();
 require("./tests/testWebAssembly");
 require("./tests/testMultithreadedJavascript");
@@ -71,10 +72,10 @@ require("./tests/testPackagePrivate");
 require("./tests/kotlin/properties/testPropertiesSupport.js");
 require('./tests/testNativeTimers');
 require("./tests/testPostFrameCallback");
+require("./tests/testPerformance");
 require("./tests/console/logTests.js");
 require('./tests/testURLImpl.js');
 require('./tests/testURLSearchParamsImpl.js');
-require('./tests/testPerformanceNow');
 require('./tests/testQueueMicrotask');
 require('./tests/testErrorEvents');
 require('./tests/testUnhandledRejections');

test-app/app/src/main/assets/app/shared

@@ -0,0 +1,50 @@
+// Performance specs local to this runtime; the cross-runtime coverage lives in
+// the shared suite (app/shared/Performance).
+describe("Performance measure argument coercion", function () {
+  beforeEach(function () {
+    performance.clearMarks();
+    performance.clearMeasures();
+  });
+
+  // The startOrMeasureOptions parameter is a (DOMString or
+  // PerformanceMeasureOptions) union, and WebIDL converts null for such a
+  // union to an empty dictionary -- so null means "no options", never the mark
+  // name "null".
+  it("Should treat a null options argument as no argument at all", function () {
+    performance.mark("null-start");
+
+    const fromNull = performance.measure("from-null", null);
+    const fromOmitted = performance.measure("from-omitted");
+
+    expect(fromNull.startTime).toBe(0);
+    expect(fromNull.startTime).toBe(fromOmitted.startTime);
+    expect(fromNull.duration).toBeGreaterThan(0);
+    expect(fromNull.detail).toBeNull();
+  });
+
+  it("Should pair a null options argument with an end mark", function () {
+    performance.mark("the-end");
+    const endTime = performance.getEntriesByName("the-end")[0].startTime;
+
+    const measure = performance.measure("null-and-end", null, "the-end");
+
+    expect(measure.startTime).toBe(0);
+    expect(measure.duration).toBe(endTime);
+  });
+
+  // endMark is a plain optional DOMString, not a union and not nullable, so
+  // null stringifies and names a mark that does not exist.
+  it("Should reject a null end mark", function () {
+    // Present so the only mark this can fail to resolve is the null one.
+    performance.mark("the-start");
+
+    let thrown = null;
+    try {
+      performance.measure("null-end", "the-start", null);
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).not.toBeNull();
+    expect(thrown && thrown.name).toBe("SyntaxError");
+  });
+});

test-app/app/src/main/assets/app/tests/testPerformance.js

@@ -140,3 +140,98 @@ describe("test PostFrameCallback", function () {
     }, defaultWaitTime);
   });
 });
+
+// The two implementations behind __postFrameCallback (NDK AChoreographer,
+// android.view.Choreographer for API < 24) must be indistinguishable from JS.
+// A modern device always selects the NDK one, so the Java bridge is only
+// reachable through __setFrameCallbackImpl, which debug runtimes expose for
+// exactly this.
+describe("frame callback timestamps", function () {
+  const defaultWaitTime = 300;
+  const impls = ["native", "java"];
+
+  afterEach(() => {
+    if (typeof global.__setFrameCallbackImpl === "function") {
+      global.__setFrameCallbackImpl("auto");
+    }
+  });
+
+  function withImpl(impl) {
+    if (typeof global.__setFrameCallbackImpl !== "function") {
+      return impl === "native";
+    }
+    return global.__setFrameCallbackImpl(impl) === impl;
+  }
+
+  impls.forEach((impl) => {
+    describe(impl + " implementation", function () {
+      it("passes the raw frame time and a performance-timeline timestamp", (done) => {
+        if (!withImpl(impl)) {
+          pending("this runtime cannot select the " + impl + " implementation");
+          return;
+        }
+
+        global.__postFrameCallback((frameTimeNanos, performanceMillis) => {
+          const now = performance.now();
+
+          expect(typeof frameTimeNanos).toBe("number");
+          expect(typeof performanceMillis).toBe("number");
+
+          // Uptime-scale nanoseconds, not epoch-scale milliseconds.
+          expect(frameTimeNanos).toBeGreaterThan(1e9);
+          expect(frameTimeNanos / 1e6).toBeLessThan(Date.now());
+
+          // The frame is stamped just before the callback runs, so its
+          // timeline position sits a frame or two behind the reading taken
+          // inside it, never ahead of it.
+          expect(performanceMillis).toBeGreaterThan(0);
+          expect(performanceMillis).not.toBeGreaterThan(now);
+          expect(now - performanceMillis).toBeLessThan(250);
+
+          // Both arguments describe the same instant, so their difference is
+          // the timeline's monotonic origin. System.nanoTime() is on that same
+          // clock, so the pair (nanoTime, now) must yield the same origin --
+          // this is what would break if either argument moved off the base.
+          // The two clocks cannot be read at once, so nanoTime is bracketed
+          // and compared against the midpoint: the tolerance then only has to
+          // cover the sampling window, not whatever pause lands between them.
+          const beforeNow = performance.now();
+          const sampledNanos = java.lang.System.nanoTime();
+          const afterNow = performance.now();
+          const originFromFrame = frameTimeNanos / 1e6 - performanceMillis;
+          const originFromClock = sampledNanos / 1e6 - (beforeNow + afterNow) / 2;
+          expect(Math.abs(originFromFrame - originFromClock)).toBeLessThan(
+            5 + (afterNow - beforeNow)
+          );
+          done();
+        });
+      });
+
+      it("advances across consecutive frames", (done) => {
+        if (!withImpl(impl)) {
+          pending("this runtime cannot select the " + impl + " implementation");
+          return;
+        }
+
+        const frames = [];
+        const callback = (frameTimeNanos, performanceMillis) => {
+          frames.push({ nanos: frameTimeNanos, millis: performanceMillis });
+          if (frames.length === 1) {
+            global.__postFrameCallback(callback);
+          }
+        };
+        global.__postFrameCallback(callback);
+
+        setTimeout(() => {
+          expect(frames.length).toBe(2);
+          expect(frames[1].nanos).not.toBeLessThan(frames[0].nanos);
+          expect(frames[1].millis).not.toBeLessThan(frames[0].millis);
+          // The origin the two arguments imply is a constant of the isolate.
+          const origin = (f) => f.nanos / 1e6 - f.millis;
+          expect(Math.abs(origin(frames[1]) - origin(frames[0]))).toBeLessThan(1);
+          done();
+        }, defaultWaitTime);
+      });
+    });
+  });
+});

test-app/app/src/main/assets/app/tests/testPerformanceNow.js

@@ -32,6 +32,16 @@ describe("Runtime exposes", function () {
   });
 });
 
+// The shared Performance suite (submodule) gates itself on the API being
+// present and skips otherwise; this unguarded canary makes absence on THIS
+// runtime a failure rather than a silent skip.
+describe("Performance API canary", function () {
+  it("implements the Performance API", function () {
+    expect(typeof performance.mark).toBe("function");
+    expect(typeof PerformanceObserver).toBe("function");
+  });
+});
+
 // The shared StructuredClone suite skips itself where the API is missing, which
 // would turn this runtime losing structuredClone into a green run. This spec is
 // deliberately unguarded so that regression fails instead.

test-app/app/src/main/assets/app/tests/testPostFrameCallback.js

@@ -72,6 +72,7 @@ set(RUNTIME_BUILTIN_JS
         ${RUNTIME_BUILTIN_JS_DIR}/message-loop-timer.js
         ${RUNTIME_BUILTIN_JS_DIR}/node-util.js
         ${RUNTIME_BUILTIN_JS_DIR}/ns-util.js
+        ${RUNTIME_BUILTIN_JS_DIR}/performance.js
         ${RUNTIME_BUILTIN_JS_DIR}/primordials.js
         ${RUNTIME_BUILTIN_JS_DIR}/require-factory.js
         ${RUNTIME_BUILTIN_JS_DIR}/structured-clone.js
@@ -151,6 +152,7 @@ add_library(
         src/main/cpp/Constants.cpp
         src/main/cpp/DirectBuffer.cpp
         src/main/cpp/ErrorEvents.cpp
+        src/main/cpp/FrameCallbacks.cpp
         src/main/cpp/Events.cpp
         src/main/cpp/FieldAccessor.cpp
         src/main/cpp/File.cpp
@@ -180,6 +182,7 @@ add_library(
         src/main/cpp/NsBuiltinModules.cpp
         src/main/cpp/NumericCasts.cpp
         src/main/cpp/ObjectManager.cpp
+        src/main/cpp/Performance.cpp
         src/main/cpp/Profiler.cpp
         src/main/cpp/ReadWriteLock.cpp
         src/main/cpp/Runtime.cpp