@lucent-lang/lucent 0.0.4 → 0.1.1

package/runtime/cpp/lucent/jsi/host.cpp

@@ -20,6 +20,9 @@ std::unordered_map<jsi::Runtime*, std::weak_ptr<Host>>& registry() {
 // stale. Constant-initialized: reading it needs no guard.
 std::atomic<uint64_t> registryGeneration{1};
 
+// Constant-initialized: safe to use during static initialization.
+std::atomic<RuntimeId> nextRuntimeId{1};
+
 // The last host this thread looked up: every call from JavaScript asks for
 // it, and a thread nearly always talks to one runtime. One thread_local, as
 // each costs a lookup on some platforms (__tlv_get_addr on Apple's).
@@ -30,29 +33,109 @@ struct CachedHost {
 };
 thread_local CachedHost cached;
 
+/// Runs `job` on the legacy module context: here if this thread is in it,
+/// else as a turn there. Either way `job` is destroyed there, holding the
+/// Lucent lock, like the values it carries.
+void onModuleContext(Job job) {
+  if (!Scheduler::lock().heldByCurrentThread()) {
+    Scheduler::instance().post(std::move(job));
+    return;
+  }
+
+  detail::runGuarded(job, "job");
+}
+
+/// Counts one task or job in flight for a host while it lives.
+class Counted {
+ public:
+  explicit Counted(std::shared_ptr<std::atomic<size_t>> count) : count_(std::move(count)) { ++*count_; }
+
+  ~Counted() { --*count_; }
+
+  Counted(const Counted&) = delete;
+  Counted& operator=(const Counted&) = delete;
+
+ private:
+  std::shared_ptr<std::atomic<size_t>> count_;
+};
+
+/// A task for the JS thread. If it never runs there, it is released on the
+/// legacy module context, after `dropped`: the values it carries are the
+/// module context's, whichever thread gave up on the task. It counts as in
+/// flight until then.
+struct Parcel {
+  std::shared_ptr<Counted> counted;
+  JsTask task;
+  Job dropped;
+  std::atomic<bool> ran{false};
+
+  Parcel(std::shared_ptr<Counted> c, JsTask t, Job d) : counted(std::move(c)), task(std::move(t)), dropped(std::move(d)) {}
+
+  ~Parcel() {
+    if (ran.load()) return;
+
+    onModuleContext([counted = std::move(counted), task = std::move(task), dropped = std::move(dropped)]() mutable {
+      if (dropped) dropped();
+
+      task = nullptr;
+      dropped = nullptr;
+    });
+  }
+};
+
+}  // namespace
+
 // Installed on the JS global object so the runtime's teardown releases our
-// JSI references on the JS thread while the runtime still exists.
-class HostAnchor : public jsi::HostObject {
+// JSI references on the JS thread while the runtime still exists. It runs
+// no JavaScript: the runtime may be being destroyed.
+class Host::Anchor : public jsi::HostObject {
  public:
-  explicit HostAnchor(std::shared_ptr<Host> host) : host_(std::move(host)) {}
-  ~HostAnchor() override {
-    if (host_) host_->invalidate();
+  explicit Anchor(std::shared_ptr<Host> host) : host_(std::move(host)) {}
+
+  ~Anchor() override { host_->tearDown(false); }
+
+#ifndef NDEBUG
+  jsi::Value get(jsi::Runtime& rt, const jsi::PropNameID& name) override {
+    if (name.utf8(rt) != "ownership") return jsi::Value::undefined();
+
+    Ownership held = host_->ownership();
+    jsi::Object o(rt);
+    o.setProperty(rt, "runtime", static_cast<double>(held.runtime));
+    o.setProperty(rt, "promises", static_cast<double>(held.promises));
+    o.setProperty(rt, "callbacks", static_cast<double>(held.callbacks));
+    o.setProperty(rt, "identities", static_cast<double>(held.identities));
+    o.setProperty(rt, "prototypes", static_cast<double>(held.prototypes));
+    o.setProperty(rt, "modules", static_cast<double>(held.modules));
+    o.setProperty(rt, "registrations", static_cast<double>(held.registrations));
+    o.setProperty(rt, "inFlight", static_cast<double>(held.inFlight));
+    return o;
   }
+#endif
 
  private:
   std::shared_ptr<Host> host_;
 };
 
-}  // namespace
-
 std::shared_ptr<Host> Host::create(jsi::Runtime& rt, JsPoster poster) {
+  std::shared_ptr<Host> previous;
+  {
+    std::lock_guard<std::mutex> g(registryMutex());
+    auto it = registry().find(&rt);
+    if (it != registry().end()) previous = it->second.lock();
+  }
+
+  if (previous) previous->invalidate();
+
   std::shared_ptr<Host> host(new Host(rt, std::move(poster)));
   {
     std::lock_guard<std::mutex> g(registryMutex());
     registry()[&rt] = host;
     registryGeneration++;
   }
-  rt.global().setProperty(rt, "__lucentHost", jsi::Object::createFromHostObject(rt, std::make_shared<HostAnchor>(host)));
+  rt.global().setProperty(rt, "__lucentHost", jsi::Object::createFromHostObject(rt, std::make_shared<Anchor>(host)));
+
+  // Module code's work from now on belongs to this runtime: tearing it down cancels that work.
+  setModuleScope(host->scope());
   {
     LucentScope scope;
     resetModuleState();
@@ -81,7 +164,12 @@ const jsi::PropNameID& Host::makeProp(jsi::Runtime& rt, const PropName& name) {
   return *props_[name.id];
 }
 
-Host::Host(jsi::Runtime& rt, JsPoster poster) : rt_(rt), poster_(std::move(poster)), jsThread_(std::this_thread::get_id()) {}
+Host::Host(jsi::Runtime& rt, JsPoster poster)
+    : id_(nextRuntimeId.fetch_add(1, std::memory_order_relaxed)),
+      rt_(rt),
+      poster_(std::move(poster)),
+      jsThread_(std::this_thread::get_id()),
+      scope_(Scope::create(id_, Scheduler::instance().root())) {}
 
 Host::~Host() {
   std::lock_guard<std::mutex> g(registryMutex());
@@ -90,31 +178,102 @@ Host::~Host() {
   registryGeneration++;
 }
 
-void Host::postToJs(JsTask task) {
-  if (!alive_.load()) return;
+bool Host::postToJs(JsTask task, Job dropped) {
+  auto parcel = std::make_shared<Parcel>(std::make_shared<Counted>(inFlight_), std::move(task), std::move(dropped));
+
+  if (!alive_.load()) return false;
+
   std::weak_ptr<Host> weak = weak_from_this();
-  poster_([weak, task = std::move(task)](jsi::Runtime& rt) {
+  poster_([weak, parcel](jsi::Runtime& rt) {
     auto self = weak.lock();
     if (!self || !self->alive()) return;
-    task(rt);
+
+    parcel->ran = true;
+    parcel->task(rt);
   });
+
+  return true;
 }
 
-void Host::invalidate() {
+void Host::postToModule(Job job) {
+  std::weak_ptr<Host> weak = weak_from_this();
+
+  // The scope drops the job once disposed; until its disposal has run on
+  // the module context, the host's own state says it is torn down.
+  Scheduler::instance().post(
+      [weak, counted = std::make_shared<Counted>(inFlight_), job = std::move(job)]() mutable {
+        auto self = weak.lock();
+        if (self && self->alive()) job();
+
+        job = nullptr;
+      },
+      scope_);
+}
+
+Host::Ownership Host::ownership() const {
+  size_t identities = 0;
+  for (auto& [native, weak] : identities_) {
+    if (weak.lock(rt_).isObject()) identities++;
+  }
+
+  return {id_,
+          promises_.size(),
+          functions_.size(),
+          identities,
+          prototypes_.size(),
+          modules_.size(),
+          scope_->registrations(),
+          inFlight_->load()};
+}
+
+Error Host::goneError() { return makeError(String::fromLatin1("AbortError"), String::fromLatin1("The JavaScript runtime is gone")); }
+
+void Host::invalidate() { tearDown(true); }
+
+void Host::tearDown(bool runtimeUsable) {
   if (!alive_.exchange(false)) return;
+
+  // JavaScript still waiting for Lucent learns that it never will.
+  auto owed = std::move(promises_);
   promises_.clear();
+
+  if (runtimeUsable && !owed.empty()) {
+    Error torn = makeError(String::fromLatin1("AbortError"), String::fromLatin1("Lucent was torn down for this JavaScript runtime"));
+
+    for (auto& [id, resolvers] : owed) {
+      try {
+        resolvers.reject.call(rt_, errorToJs(rt_, torn));
+      } catch (...) {
+        reportUncaught(std::current_exception(), "host");
+      }
+    }
+  }
+
+  owed.clear();
+
+  // Cancels its operations and runs its cleanups on the module context.
+  if (auto e = scope_->dispose()) reportUncaught(e, "host");
+
   functions_.clear();
   prototypes_.clear();
   modules_.clear();
   identities_.clear();
   props_.clear();
+
+  // Only its own entry: the runtime may have a newer host by now.
+  std::weak_ptr<Host> self = weak_from_this();
   std::lock_guard<std::mutex> g(registryMutex());
   auto it = registry().find(&rt_);
-  if (it != registry().end()) registry().erase(it);
+  if (it != registry().end() && !it->second.owner_before(self) && !self.owner_before(it->second)) registry().erase(it);
   registryGeneration++;
 }
 
 jsi::Value Host::module(jsi::Runtime& rt, const std::string& name) {
+  // A replaced host's module (a TurboModule that kept it) is the new one's.
+  if (!alive()) return get(rt).module(rt, name);
+
+  if (name == kIdentityName) return identity(rt);
+
   auto it = modules_.find(name);
   if (it != modules_.end()) return jsi::Value(rt, it->second);
   size_t count = 0;
@@ -139,9 +298,27 @@ jsi::Object Host::modules(jsi::Runtime& rt) {
   size_t count = 0;
   const ModuleDef* defs = registeredModules(count);
   for (size_t i = 0; i < count; i++) all.setProperty(rt, defs[i].name, module(rt, defs[i].name));
+  all.setProperty(rt, kIdentityName, identity(rt));
   return all;
 }
 
+jsi::Object Host::identity(jsi::Runtime& rt) {
+  const BuildIdentity& built = buildIdentity();
+
+  jsi::Object modules(rt);
+  for (size_t i = 0; i < built.moduleCount; i++)
+    modules.setProperty(rt, built.modules[i].name, jsi::String::createFromUtf8(rt, built.modules[i].api));
+
+  jsi::Object o(rt);
+  o.setProperty(rt, "host", static_cast<double>(id_));
+  o.setProperty(rt, "runtimeAbi", kRuntimeAbi);
+  o.setProperty(rt, "target", jsi::String::createFromUtf8(rt, built.target));
+  o.setProperty(rt, "program", jsi::String::createFromUtf8(rt, built.program));
+  o.setProperty(rt, "modules", modules);
+
+  return o;
+}
+
 jsi::Value Host::createPromise(jsi::Runtime& rt, uint64_t& id) {
   id = nextId_++;
   auto slot = std::make_shared<std::pair<std::optional<jsi::Function>, std::optional<jsi::Function>>>();
@@ -215,16 +392,20 @@ jsi::Object& Host::prototype(jsi::Runtime& rt, const char* key, PrototypeInit in
   return prototypes_.emplace(key, std::move(proto)).first->second;
 }
 
-namespace {
-std::atomic<uint64_t> nextIdentity{1};
-}  // namespace
-
 Ref<Object> instanceOf(jsi::Runtime& rt, const jsi::Value& v) {
   if (!v.isObject()) return nullptr;
   jsi::Object o = v.getObject(rt);
   if (!o.hasNativeState(rt)) return nullptr;
   auto s = std::dynamic_pointer_cast<InstanceState>(o.getNativeState(rt));
-  return s ? s->object : nullptr;
+  if (!s) return nullptr;
+
+  // One host per runtime: a live one is this runtime's.
+  if (!s->host->alive()) {
+    jsi::Value error = rt.global().getPropertyAsFunction(rt, "TypeError").callAsConstructor(rt, "This Lucent object belongs to a host that was torn down");
+    throw jsi::JSError(rt, std::move(error));
+  }
+
+  return s->object;
 }
 
 void defineFunction(jsi::Runtime& rt, jsi::Object& target, const char* name, unsigned argc, HostFn fn) {
@@ -254,34 +435,31 @@ void defineClass(jsi::Runtime& rt, Host& host, jsi::Object& exports, const char*
 
 jsi::Value Host::wrap(jsi::Runtime& rt, const Ref<Object>& instance, const char* key, PrototypeInit init) {
   if (!instance) return jsi::Value::null();
-  if (instance->jsIdentity != 0) {
-    auto it = identities_.find(instance->jsIdentity);
-    if (it != identities_.end()) {
-      jsi::Value v = it->second.lock(rt);
-      if (v.isObject()) return v;
-    }
-  } else {
-    instance->jsIdentity = nextIdentity.fetch_add(1);
+  auto it = identities_.find(instance.get());
+  if (it != identities_.end()) {
+    jsi::Value v = it->second.lock(rt);
+    if (v.isObject()) return v;
   }
   jsi::Object& proto = prototype(rt, key, init);
   jsi::Object obj = jsi::Object::create(rt, jsi::Value(rt, proto));
-  obj.setNativeState(rt, std::make_shared<InstanceState>(instance));
+  obj.setNativeState(rt, std::make_shared<InstanceState>(instance, shared_from_this()));
   // Periodically drop cache entries whose JS objects were collected.
   if (++identitySweep_ >= 256) {
     identitySweep_ = 0;
-    std::vector<uint64_t> dead;
-    for (auto& [id, weak] : identities_) {
-      if (!weak.lock(rt).isObject()) dead.push_back(id);
+    std::vector<const Object*> dead;
+    for (auto& [native, weak] : identities_) {
+      if (!weak.lock(rt).isObject()) dead.push_back(native);
     }
-    for (uint64_t id : dead) identities_.erase(id);
+    for (const Object* native : dead) identities_.erase(native);
   }
-  identities_.insert_or_assign(instance->jsIdentity, jsi::WeakObject(rt, obj));
+  identities_.insert_or_assign(instance.get(), jsi::WeakObject(rt, obj));
   return jsi::Value(std::move(obj));
 }
 
 jsi::Value Host::errorToJs(jsi::Runtime& rt, const Error& e) {
   std::string name = e->name.toUtf8();
-  const char* ctor = (name == "TypeError" || name == "RangeError") ? name.c_str() : "Error";
+  // The kinds Lucent throws (SyntaxError from BigInt(string)), as JavaScript's own.
+  const char* ctor = (name == "TypeError" || name == "RangeError" || name == "SyntaxError") ? name.c_str() : "Error";
   jsi::Object err = rt.global()
                         .getPropertyAsFunction(rt, ctor)
                         .callAsConstructor(rt, jsi::String::createFromUtf8(rt, e->message.toUtf8()))

package/runtime/cpp/lucent/jsi/host.h

@@ -5,6 +5,11 @@
 // pending promise resolvers, JS callbacks, class prototypes and the identity
 // cache. JSI values may only be touched on the JS thread, so native code
 // refers to them by id and hops to the JS thread to use them.
+//
+// Work for a runtime belongs to its host's scope, and ends with the host:
+// torn down (a reload, the runtime's end), the host disposes its scope,
+// drops what it posted that has not run, and releases what that carried on
+// the legacy module context.
 #pragma once
 
 #include <jsi/jsi.h>
@@ -57,9 +62,39 @@ const ModuleDef* registeredModules(size_t& count);
 /// Implemented by generated code: resets module-level state for a new runtime.
 void resetModuleState();
 
+/// What generated code and JavaScript proxies expect of this runtime: a
+/// change that breaks either takes a new number. The compiler's
+/// RUNTIME_ABI; generated code checks it as it builds.
+inline constexpr int kRuntimeAbi = 1;
+
+/// A module as the program was compiled: its name, and a hash of what
+/// JavaScript sees of it (its exports and their signatures).
+struct ModuleIdentity {
+  const char* name;
+  const char* api;
+};
+
+/// What this app's native code was built from, which JavaScript checks its
+/// proxies against before they call it: the target it was compiled for
+/// ("all" for code every target shares), a hash of the program, and each
+/// module's API.
+struct BuildIdentity {
+  const char* target;
+  const char* program;
+  const ModuleIdentity* modules;
+  size_t moduleCount;
+};
+
+/// Implemented by generated code.
+const BuildIdentity& buildIdentity();
+
+/// The name JavaScript reads the build identity by, next to the modules.
+inline constexpr const char* kIdentityName = "__lucentIdentity";
+
 class Host : public std::enable_shared_from_this<Host> {
  public:
-  /// Creates the host for `rt`. Call on the JS thread.
+  /// Creates the host for `rt`. Call on the JS thread. A runtime has one
+  /// host: one it had already is torn down (invalidate) and replaced.
   static std::shared_ptr<Host> create(jsi::Runtime& rt, JsPoster poster);
   static Host& get(jsi::Runtime& rt);
   /// The host for a call to a function `installed` defined: that host while
@@ -70,20 +105,73 @@ class Host : public std::enable_shared_from_this<Host> {
   }
   ~Host();
 
+  /// Nonzero, and no other host has had it: what scopes and tokens of
+  /// work for this runtime carry.
+  RuntimeId id() const { return id_; }
+
   jsi::Runtime& runtime() { return rt_; }
   bool onJsThread() const { return std::this_thread::get_id() == jsThread_; }
   bool alive() const { return alive_.load(); }
 
-  /// Runs `task` on the JS thread unless the host was invalidated.
-  void postToJs(JsTask task);
-  /// Drops every JSI reference. Call on the JS thread before the runtime dies.
+  /// The root of the work done for this runtime, under the legacy module
+  /// context's root scope: disposed there when the host is torn down,
+  /// cancelling its operations and running its cleanups.
+  const std::shared_ptr<Scope>& scope() const { return scope_; }
+
+  /// Runs `task` on the JS thread unless the host is torn down first. A
+  /// task that never runs (the host torn down, or the poster dropped it)
+  /// is released on the legacy module context, after `dropped` runs there.
+  /// False if the host was already torn down.
+  bool postToJs(JsTask task, Job dropped = nullptr);
+
+  /// Runs `job` as a turn of the legacy module context unless the host is
+  /// torn down before it starts; dropped, it is released there.
+  void postToModule(Job job);
+
+  /// Tears the host down, on the JS thread while its runtime is usable:
+  /// the JS promises it owes reject with an AbortError, then its scope is
+  /// disposed and every JSI reference dropped. Idempotent.
   void invalidate();
 
-  /// The exports object of a module, created on first use.
+  /// What Lucent code waiting on this runtime gets once the host is torn
+  /// down: an AbortError.
+  static Error goneError();
+
+  /// What the host holds, for debug ownership reports and tests (debug
+  /// builds show it to JavaScript as `__lucentHost.ownership`).
+  struct Ownership {
+    RuntimeId runtime = 0;
+    /// JS promises it will settle.
+    size_t promises = 0;
+    /// JS functions Lucent holds.
+    size_t callbacks = 0;
+    /// Live JS objects of native instances.
+    size_t identities = 0;
+    size_t prototypes = 0;
+    size_t modules = 0;
+    /// What its scope holds: JS promises Lucent awaits, operations, …
+    size_t registrations = 0;
+    size_t inFlight = 0;
+  };
+
+  /// On the JS thread.
+  Ownership ownership() const;
+
+  /// Tasks for the JS thread and jobs for the module context posted for
+  /// this runtime that have not yet run or been released. Any thread.
+  size_t inFlight() const { return inFlight_->load(); }
+
+  /// The exports object of a module, created on first use; for
+  /// kIdentityName, identity().
   jsi::Value module(jsi::Runtime& rt, const std::string& name);
-  /// The object with every module as a property (for tests and debugging).
+  /// The object with every module as a property, and the identity (for
+  /// test hosts, which install it as React Native's module would be).
   jsi::Object modules(jsi::Runtime& rt);
 
+  /// The build identity for JavaScript: `{host, runtimeAbi, target,
+  /// program, modules: {name: api}}`, `host` being this host's id.
+  jsi::Object identity(jsi::Runtime& rt);
+
   // --- promises ---------------------------------------------------------
   /// Creates a JS promise; settle it later with resolve/reject on the JS thread.
   jsi::Value createPromise(jsi::Runtime& rt, uint64_t& id);
@@ -101,8 +189,9 @@ class Host : public std::enable_shared_from_this<Host> {
   /// The prototype for class `key`: the runtime's own across hosts (kept on
   /// the global object), with this host's methods.
   jsi::Object& prototype(jsi::Runtime& rt, const char* key, PrototypeInit init);
-  /// The JS object for a native instance: the same object each time while
-  /// JavaScript still references it.
+  /// The JS object for a native instance in this runtime: the same object
+  /// each time while JavaScript still references it. Each runtime has its
+  /// own for the same instance.
   jsi::Value wrap(jsi::Runtime& rt, const Ref<Object>& instance, const char* key, PrototypeInit init);
 
   /// Converts a Lucent error into a JS Error object (not thrown).
@@ -117,39 +206,50 @@ class Host : public std::enable_shared_from_this<Host> {
   }
 
  private:
+  /// On the global object: tears the host down when the runtime does.
+  class Anchor;
+
   Host(jsi::Runtime& rt, JsPoster poster);
 
+  /// invalidate(), but JS runs only if `runtimeUsable`: not while the
+  /// runtime is being destroyed.
+  void tearDown(bool runtimeUsable);
+
   struct Resolvers {
     jsi::Function resolve;
     jsi::Function reject;
   };
 
+  const RuntimeId id_;
   jsi::Runtime& rt_;
   JsPoster poster_;
   std::thread::id jsThread_;
   std::atomic<bool> alive_{true};
+  const std::shared_ptr<Scope> scope_;
+  const std::shared_ptr<std::atomic<size_t>> inFlight_ = std::make_shared<std::atomic<size_t>>(0);
   uint64_t nextId_ = 1;
   std::unordered_map<uint64_t, Resolvers> promises_;
   std::unordered_map<uint64_t, jsi::Function> functions_;
   std::unordered_map<std::string, jsi::Object> prototypes_;
   std::unordered_map<std::string, jsi::Value> modules_;
-  std::unordered_map<uint64_t, jsi::WeakObject> identities_;
+  // Keyed by the native instance: its JS object keeps it alive, so while
+  // an entry's object lives, no other instance can have its address.
+  std::unordered_map<const Object*, jsi::WeakObject> identities_;
   size_t identitySweep_ = 0;
   std::vector<std::unique_ptr<jsi::PropNameID>> props_;
   const jsi::PropNameID& makeProp(jsi::Runtime& rt, const PropName& name);
 };
 
-/// Holds a strong reference to the Host while posting results back to JS.
-using HostRef = std::shared_ptr<Host>;
-
-/// NativeState attached to the JS object of a Lucent class instance.
+/// NativeState attached to the JS object of a Lucent class instance, and
+/// the host that made it.
 struct InstanceState : jsi::NativeState {
-  explicit InstanceState(Ref<Object> o) : object(std::move(o)) {}
+  InstanceState(Ref<Object> o, std::shared_ptr<Host> h) : object(std::move(o)), host(std::move(h)) {}
   Ref<Object> object;
+  std::shared_ptr<Host> host;
 };
-using InstanceStateBase = InstanceState;
 
-/// The native instance behind a JS object, or null.
+/// The native instance behind a JS object, or null. Throws a TypeError for
+/// an object a torn-down host made: the state it belongs to has ended.
 Ref<Object> instanceOf(jsi::Runtime& rt, const jsi::Value& v);
 
 using HostFn = jsi::HostFunctionType;

package/runtime/cpp/lucent/json.h

@@ -8,6 +8,7 @@
 #include <variant>
 
 #include "array.h"
+#include "bigint.h"
 #include "bytes.h"
 #include "date.h"
 #include "regexp.h"
@@ -15,6 +16,7 @@
 #include "jserror.h"
 #include "function.h"
 #include "map.h"
+#include "native.h"
 #include "number.h"
 #include "jsstring.h"
 
@@ -51,10 +53,17 @@ inline void jsonWrite(JsonWriter& w, double v) {
   }
 }
 inline void jsonWrite(JsonWriter& w, bool v) { w.raw(v ? "true" : "false"); }
+/// JSON has no bigints: JSON.stringify throws, as in JavaScript.
+inline void jsonWrite(JsonWriter&, const BigInt&) { throwTypeError("Do not know how to serialize a BigInt"); }
 inline void jsonWrite(JsonWriter& w, const String& s) { w.quote(s); }
 inline void jsonWrite(JsonWriter& w, Undefined) { w.raw("null"); }
 inline void jsonWrite(JsonWriter& w, Null) { w.raw("null"); }
 inline void jsonWrite(JsonWriter& w, const Error&) { w.raw("{}"); }
+/// An SDK object: a host object, with no enumerable own properties.
+inline void jsonWrite(JsonWriter& w, const NativeRef&) { w.raw("{}"); }
+class NativeBufferObject;
+/// A NativeBuffer: an opaque handle, with no enumerable own properties either.
+inline void jsonWrite(JsonWriter& w, const Ref<NativeBufferObject>&) { w.raw("{}"); }
 template <class Sig>
 void jsonWrite(JsonWriter& w, const Fn<Sig>&) {
   w.raw("null");
@@ -123,7 +132,9 @@ inline void jsonWrite(JsonWriter& w, const Date& d) {
   if (std::isnan(d->getTime())) w.raw("null");
   else w.quote(d->toISOString());
 }
-inline void jsonWrite(JsonWriter& w, const Bytes& b) {
+/// A Uint8Array, or the bytes a buffer's borrow lends: its indexes as keys.
+template <class B>
+void jsonWriteBytes(JsonWriter& w, const B& b) {
   w.raw("{");
   for (size_t i = 0; i < b.size(); i++) {
     if (i) w.raw(",");
@@ -133,6 +144,13 @@ inline void jsonWrite(JsonWriter& w, const Bytes& b) {
   }
   w.raw("}");
 }
+inline void jsonWrite(JsonWriter& w, const Bytes& b) { jsonWriteBytes(w, b); }
+template <bool Writable>
+class BasicByteSpan;
+template <bool Writable>
+void jsonWrite(JsonWriter& w, const BasicByteSpan<Writable>& b) {
+  jsonWriteBytes(w, b);
+}
 /// Helper for generated struct writers: one `"name":value` member.
 template <class T>
 void jsonField(JsonWriter& w, bool& first, const char* name, const T& v) {