@@ -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)
 
@@ -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()`.
@@ -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'],
 
@@ -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');
 
@@ -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");
+  });
+});
@@ -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);
+      });
+    });
+  });
+});
@@ -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.
 
@@ -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