feat: expose requestAnimationFrame under the standard global names

Register requestAnimationFrame/cancelAnimationFrame on every global
(workers included), built on the existing frame-callback machinery with
spec semantics: one one-shot entry per request, a returned handle,
cancellation by handle, and a single performance-timeline timestamp
argument. The __postFrameCallback/__removeFrameCallback pair stays as
the backwards-compatible surface.

Author: edusperoni

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

@@ -141,6 +141,100 @@ describe("test PostFrameCallback", function () {
   });
 });
 
+describe("requestAnimationFrame", function () {
+  const defaultWaitTime = 300;
+
+  it("is exposed under the standard global names", () => {
+    expect(typeof global.requestAnimationFrame).toBe("function");
+    expect(typeof global.cancelAnimationFrame).toBe("function");
+  });
+
+  it("throws on non-function callbacks and ignores bogus cancel handles", () => {
+    expect(() => global.requestAnimationFrame()).toThrowError(TypeError);
+    expect(() => global.requestAnimationFrame(null)).toThrowError(TypeError);
+    expect(() => global.requestAnimationFrame("")).toThrowError(TypeError);
+    expect(() => global.cancelAnimationFrame()).not.toThrow();
+    expect(() => global.cancelAnimationFrame(null)).not.toThrow();
+    expect(() => global.cancelAnimationFrame(-1)).not.toThrow();
+    expect(() => global.cancelAnimationFrame(Number.MAX_SAFE_INTEGER)).not.toThrow();
+  });
+
+  it("returns a handle and passes a single performance-timeline timestamp", (done) => {
+    const handle = global.requestAnimationFrame(function (timestamp) {
+      expect(arguments.length).toBe(1);
+      expect(typeof timestamp).toBe("number");
+      const now = performance.now();
+      expect(timestamp).toBeGreaterThan(0);
+      expect(timestamp).not.toBeGreaterThan(now);
+      expect(now - timestamp).toBeLessThan(250);
+      done();
+    });
+    expect(typeof handle).toBe("number");
+    expect(handle).toBeGreaterThan(0);
+  });
+
+  it("runs the same function once per request", (done) => {
+    let callCount = 0;
+    const callback = () => {
+      callCount++;
+    };
+    const first = global.requestAnimationFrame(callback);
+    const second = global.requestAnimationFrame(callback);
+    expect(second).not.toBe(first);
+    setTimeout(() => {
+      expect(callCount).toBe(2);
+      done();
+    }, defaultWaitTime);
+  });
+
+  it("cancels only the cancelled request", (done) => {
+    let cancelledRan = false;
+    let keptRan = false;
+    const cancelled = global.requestAnimationFrame(() => {
+      cancelledRan = true;
+    });
+    global.requestAnimationFrame(() => {
+      keptRan = true;
+    });
+    global.cancelAnimationFrame(cancelled);
+    setTimeout(() => {
+      expect(cancelledRan).toBe(false);
+      expect(keptRan).toBe(true);
+      done();
+    }, defaultWaitTime);
+  });
+
+  it("chains frames when the callback re-requests itself", (done) => {
+    const timestamps = [];
+    const callback = (timestamp) => {
+      timestamps.push(timestamp);
+      if (timestamps.length === 1) {
+        global.requestAnimationFrame(callback);
+      }
+    };
+    global.requestAnimationFrame(callback);
+    setTimeout(() => {
+      expect(timestamps.length).toBe(2);
+      expect(timestamps[1]).not.toBeLessThan(timestamps[0]);
+      done();
+    }, defaultWaitTime);
+  });
+
+  it("does not disturb __postFrameCallback dedupe for the same function", (done) => {
+    let callCount = 0;
+    const callback = () => {
+      callCount++;
+    };
+    global.__postFrameCallback(callback);
+    global.requestAnimationFrame(callback);
+    global.__postFrameCallback(callback);
+    setTimeout(() => {
+      expect(callCount).toBe(2);
+      done();
+    }, 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

test-app/runtime/src/main/cpp/FrameCallbacks.cpp

@@ -151,8 +151,12 @@ void ResolveFrameCallbacksClass(JEnv& env) {
 using EntryId = uintptr_t;
 
 struct FrameCallbackEntry {
-    FrameCallbackEntry(Isolate* isolate, Local<Function> callback, EntryId id)
-        : isolate_(isolate), callback_(isolate, callback), id_(id) {
+    FrameCallbackEntry(Isolate* isolate, Local<Function> callback, EntryId id,
+                       bool isAnimationFrame = false)
+        : isolate_(isolate),
+          callback_(isolate, callback),
+          id_(id),
+          isAnimationFrame_(isAnimationFrame) {
     }
 
     ~FrameCallbackEntry() {
@@ -200,6 +204,13 @@ struct FrameCallbackEntry {
     Isolate* isolate_;
     Global<Function> callback_;
     EntryId id_;
+    /*
+     * requestAnimationFrame entries are anonymous one-shots addressed only by
+     * their returned handle: they never dedupe by function, take the single
+     * spec-mandated timestamp argument, and cancelAnimationFrame may only
+     * touch entries carrying this flag.
+     */
+    bool isAnimationFrame_;
     jobject javaCallback_ = nullptr;
 
 private:
@@ -273,15 +284,23 @@ void Dispatch(EntryId id, int64_t frameTimeNanos) {
 
     entry->MarkUnscheduled();
 
+    Local<Value> timelineMillis =
+            Number::New(isolate, Performance::MonotonicNanosToTimelineMillis(
+                                         isolate, frameTimeNanos));
     Local<Value> args[2] = {
             Number::New(isolate, (double) frameTimeNanos),
-            Number::New(isolate, Performance::MonotonicNanosToTimelineMillis(
-                                         isolate, frameTimeNanos)),
+            timelineMillis,
     };
 
     TryCatch tc(isolate);
 
-    cb->Call(context, context->Global(), 2, args);  // ignore JS return value
+    if (entry->isAnimationFrame_) {
+        // spec signature: a single DOMHighResTimeStamp on this isolate's
+        // performance timeline
+        cb->Call(context, context->Global(), 1, &timelineMillis);
+    } else {
+        cb->Call(context, context->Global(), 2, args);  // ignore JS return value
+    }
 
     // Re-resolve: the callback may have rescheduled or removed itself.
     entry = FindEntryById(id);
@@ -436,6 +455,58 @@ void FrameCallbacks::RemoveFrameCallback(const FunctionCallbackInfo<Value>& args
     }
 }
 
+void FrameCallbacks::RequestAnimationFrame(const FunctionCallbackInfo<Value>& args) {
+    Isolate* isolate = args.GetIsolate();
+    Locker locker(isolate);
+    Isolate::Scope isolateScope(isolate);
+    HandleScope handleScope(isolate);
+    Local<Context> context = isolate->GetCurrentContext();
+    Context::Scope contextScope(context);
+
+    if (args.Length() < 1 || !args[0]->IsFunction()) {
+        isolate->ThrowException(Exception::TypeError(String::NewFromUtf8Literal(
+                isolate, "Animation frame callback argument is not a function")));
+        return;
+    }
+
+    // Every call registers its own entry: the spec runs a function as many
+    // times as it was requested, so no dedupe by function here.
+    EntryId id = ++entryCount_;
+    FrameCallbackEntry* entry;
+    {
+        std::lock_guard<std::mutex> lock(entriesMutex_);
+        auto inserted = entries_.emplace(
+                id, std::make_unique<FrameCallbackEntry>(
+                            isolate, args[0].As<Function>(), id,
+                            /* isAnimationFrame */ true));
+        NS_DCHECK(inserted.second && "Frame callback ID should not be duplicated");
+        entry = inserted.first->second.get();
+    }
+
+    entry->MarkScheduled();
+    Post(entry, 0);
+    args.GetReturnValue().Set(Number::New(isolate, (double) id));
+}
+
+void FrameCallbacks::CancelAnimationFrame(const FunctionCallbackInfo<Value>& args) {
+    Isolate* isolate = args.GetIsolate();
+    Locker locker(isolate);
+    Isolate::Scope isolateScope(isolate);
+    HandleScope handleScope(isolate);
+    Local<Context> context = isolate->GetCurrentContext();
+    Context::Scope contextScope(context);
+
+    // per spec an unknown or malformed handle is a silent no-op
+    if (args.Length() < 1 || !args[0]->IsNumber()) {
+        return;
+    }
+    EntryId id = (EntryId) args[0]->IntegerValue(context).FromMaybe(0);
+    FrameCallbackEntry* entry = FindEntryById(id);
+    if (entry != nullptr && entry->isAnimationFrame_) {
+        entry->MarkRemoved();
+    }
+}
+
 void FrameCallbacks::RemoveIsolateEntries(Isolate* isolate) {
     // Detached first, destroyed after the mutex is released: the destructors
     // call into Java.
@@ -454,6 +525,15 @@ void FrameCallbacks::RemoveIsolateEntries(Isolate* isolate) {
 }
 
 void FrameCallbacks::Init(Isolate* isolate, Local<ObjectTemplate> globalTemplate) {
+    globalTemplate->Set(
+            ArgConverter::ConvertToV8String(isolate, "requestAnimationFrame"),
+            FunctionTemplate::New(isolate, RequestAnimationFrame));
+    globalTemplate->Set(
+            ArgConverter::ConvertToV8String(isolate, "cancelAnimationFrame"),
+            FunctionTemplate::New(isolate, CancelAnimationFrame));
+    // kept for backwards compatibility with callers that predate
+    // requestAnimationFrame; unlike it, these dedupe by function, take an
+    // optional delay, and hand the callback the raw frame time as well
     globalTemplate->Set(
             ArgConverter::ConvertToV8String(isolate, "__postFrameCallback"),
             FunctionTemplate::New(isolate, PostFrameCallback));

test-app/runtime/src/main/cpp/FrameCallbacks.h

@@ -10,8 +10,15 @@
 namespace tns {
 
 /*
- * __postFrameCallback(fn[, delayMillis]) / __removeFrameCallback(fn): schedule
- * a JS function for the next display frame.
+ * requestAnimationFrame(fn) / cancelAnimationFrame(handle): the standard
+ * animation-frame surface. Each request registers its own one-shot entry and
+ * returns a handle; fn receives a single DOMHighResTimeStamp on the isolate's
+ * performance timeline.
+ *
+ * __postFrameCallback(fn[, delayMillis]) / __removeFrameCallback(fn): the
+ * compatibility surface predating requestAnimationFrame. Schedules a JS
+ * function for the next display frame, deduping by function: rescheduling a
+ * callback that is already pending is a no-op.
  *
  * fn receives two arguments:
  *   fn(frameTimeNanos, performanceMillis)
@@ -25,9 +32,8 @@ namespace tns {
  *   - android.view.Choreographer (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. Rescheduling a callback that is already pending is a no-op, and
- * removal only marks the entry: a posted frame callback cannot be recalled, so
- * the dispatch drops it instead.
+ * looper. Cancellation on either surface only marks the entry: a posted frame
+ * callback cannot be recalled, so the dispatch drops it instead.
  */
 class FrameCallbacks {
 public:
@@ -42,6 +48,8 @@ class FrameCallbacks {
     static void RemoveIsolateEntries(v8::Isolate* isolate);
 
 private:
+    static void RequestAnimationFrame(const v8::FunctionCallbackInfo<v8::Value>& args);
+    static void CancelAnimationFrame(const v8::FunctionCallbackInfo<v8::Value>& args);
     static void PostFrameCallback(const v8::FunctionCallbackInfo<v8::Value>& args);
     static void RemoveFrameCallback(const v8::FunctionCallbackInfo<v8::Value>& args);
 };