basalt-core 0.0.0-rc5

package/native/core/AppearanceModule.cpp

@@ -0,0 +1,60 @@
+#include "AppearanceModule.h"
+
+#include "ColorScheme.h"
+
+namespace basalt {
+
+using facebook::jsi::Runtime;
+using facebook::jsi::String;
+
+DesktopAppearanceModule::DesktopAppearanceModule(
+    std::shared_ptr<facebook::react::CallInvoker> jsInvoker)
+    : NativeAppearanceCxxSpec(std::move(jsInvoker)) {
+  // Subscribed for the module's whole life rather than when JavaScript adds a
+  // listener. `Appearance.addChangeListener` is a JavaScript-side subscription
+  // on an event emitter; this is the thing that feeds it, and it has to be
+  // running before the first listener arrives or the first change is lost.
+  observerToken_ = addColorSchemeObserver([this](ColorScheme scheme) {
+    emitDeviceEvent("appearanceChanged",
+                    [scheme](Runtime &rt, std::vector<facebook::jsi::Value> &args) {
+                      // NativeAppearancePreferences: { colorScheme }.
+                      auto preferences = facebook::jsi::Object(rt);
+                      preferences.setProperty(
+                          rt, "colorScheme", String::createFromUtf8(rt, colorSchemeName(scheme)));
+                      args.emplace_back(rt, preferences);
+                    });
+  });
+}
+
+DesktopAppearanceModule::~DesktopAppearanceModule() {
+  removeColorSchemeObserver(observerToken_);
+}
+
+String DesktopAppearanceModule::getColorScheme(Runtime &rt) {
+  return String::createFromUtf8(rt, colorSchemeName(effectiveColorScheme()));
+}
+
+void DesktopAppearanceModule::setColorScheme(Runtime &rt, std::string colorScheme) {
+  (void)rt;
+  // ColorSchemeOverride is 'light' | 'dark' | 'auto' | 'unspecified', and the
+  // last two both mean "stop overriding". Handling only one of them is the kind
+  // of gap an app finds and a test does not, because which spelling reaches
+  // here depends on what the app passed.
+  if (colorScheme == "unspecified" || colorScheme == "auto") {
+    clearColorSchemeOverride();
+    return;
+  }
+  setColorSchemeOverride(colorScheme);
+}
+
+void DesktopAppearanceModule::addListener(Runtime &rt, std::string eventName) {
+  (void)rt;
+  (void)eventName;
+}
+
+void DesktopAppearanceModule::removeListeners(Runtime &rt, double count) {
+  (void)rt;
+  (void)count;
+}
+
+} // namespace basalt

package/native/core/AppearanceModule.h

@@ -0,0 +1,40 @@
+// `Appearance`, which is how an app learns it should be dark.
+//
+// Everything here is portable. Which scheme the system is in is not, and is
+// behind the seam in ColorScheme.h.
+//
+// React Native looks this module up with `getEnforcing`, so its absence is not
+// a quiet no-op: `Appearance.getColorScheme()` throws and takes the first render
+// with it. That is what a stock Expo app hit in phase 29.
+
+#pragma once
+
+#include <FBReactNativeSpec/FBReactNativeSpecJSI.h>
+
+#include <string>
+
+namespace basalt {
+
+class DesktopAppearanceModule
+    : public facebook::react::NativeAppearanceCxxSpec<DesktopAppearanceModule> {
+ public:
+  explicit DesktopAppearanceModule(std::shared_ptr<facebook::react::CallInvoker> jsInvoker);
+  ~DesktopAppearanceModule() override;
+
+  static constexpr const char *kModuleName = "Appearance";
+
+  facebook::jsi::String getColorScheme(facebook::jsi::Runtime &rt);
+  void setColorScheme(facebook::jsi::Runtime &rt, std::string colorScheme);
+
+  // The listener bookkeeping React Native's NativeEventEmitter contract wants.
+  // The real subscription is the one taken out in the constructor: JavaScript
+  // adding a listener does not change what this module watches, only whether
+  // anybody is there when it fires.
+  void addListener(facebook::jsi::Runtime &rt, std::string eventName);
+  void removeListeners(facebook::jsi::Runtime &rt, double count);
+
+ private:
+  int observerToken_{0};
+};
+
+} // namespace basalt

package/native/core/Backface.h

@@ -0,0 +1,59 @@
+// Whether a transform has turned a view away from the viewer.
+//
+// `backfaceVisibility: 'hidden'` is what stops the back of a card being drawn
+// mirrored halfway through a flip. Without it a rotation past ninety degrees
+// shows the front face reversed, which reads as a rendering bug rather than a
+// missing prop -- and all three hosts ignored the prop entirely.
+//
+// ## The test is the sign of the determinant
+//
+// A transform faces away exactly when it mirrors: the 2D part of the matrix
+// has a negative determinant. `rotateY(180deg)` and `rotateX(180deg)` both
+// produce one, `rotateZ(180deg)` does not -- turning something in its own
+// plane never shows its back -- and `scaleX(-1)` does, which is right, because
+// CSS hides that too.
+//
+// ## Why not CALayer's `doubleSided`
+//
+// macOS has this prop natively and the others do not. Using it there would be
+// less code and would answer differently the day perspective lands: Core
+// Animation would consider the whole 4x4 and the other two would consider the
+// 2D part. One rule that all three obey is worth more than one host being
+// idiomatic, and it is the same argument core/ScrollIndicator.h and
+// core/ScrollBounds.h make. Nothing here draws perspective yet;
+// docs/backlog/correctness.md records that.
+
+// Header-only on purpose. `RnView.cpp` and `RnWin32View.cpp` are in the
+// view-layer libraries, which link no React Native and no core -- that is what
+// lets `demo_layout_gtk` and the view tests build without one. A .cpp here
+// would put a link dependency between the two, the same reason
+// core/ScrollIndicator.h keeps its constants inline.
+
+#pragma once
+
+namespace basalt {
+
+// `matrix` is sixteen floats in CSS `matrix3d` order, which is what React
+// Native produces and what every host here already stores.
+//
+// False for an identity or any rotation in the plane, so a view with no
+// transform is never hidden by this.
+// The rule from the four numbers that matter. A host that keeps only the 2D
+// affine -- Windows does, because that is all its paint and hit testing need
+// -- comes in here; everything else comes in below.
+inline bool facesAway(float a, float b, float c, float d) {
+  // A negative determinant means the transform mirrors, and a mirrored view is
+  // one you are looking at the back of.
+  return (a * d - b * c) < 0.0f;
+}
+
+inline bool facesAway(const float matrix[16]) {
+  if (matrix == nullptr) {
+    return false;
+  }
+  // The 2D part, in `matrix3d` order: m11 m12 are the first column and m21 m22
+  // the second, so the four that matter are 0, 1, 4 and 5.
+  return facesAway(matrix[0], matrix[1], matrix[4], matrix[5]);
+}
+
+} // namespace basalt

package/native/core/BlobModule.cpp

@@ -0,0 +1,283 @@
+#include "BlobModule.h"
+
+#include "BlobRegistry.h"
+
+#include <glog/logging.h>
+
+#include <array>
+#include <cstdint>
+
+namespace basalt {
+
+using facebook::jsi::Array;
+using facebook::jsi::Object;
+using facebook::jsi::Runtime;
+using facebook::jsi::String;
+using facebook::jsi::Value;
+
+namespace {
+
+// A blob handle as JavaScript passes it: {blobId, offset, size}.
+struct BlobHandle {
+  std::string blobId;
+  size_t offset{0};
+  size_t size{0};
+};
+
+BlobHandle readHandle(Runtime &rt, const Object &blob) {
+  BlobHandle handle;
+  handle.blobId = blob.getProperty(rt, "blobId").asString(rt).utf8(rt);
+  const Value offset = blob.getProperty(rt, "offset");
+  const Value size = blob.getProperty(rt, "size");
+  handle.offset = offset.isNumber() ? static_cast<size_t>(offset.asNumber()) : 0;
+  handle.size = size.isNumber() ? static_cast<size_t>(size.asNumber()) : 0;
+  return handle;
+}
+
+// A promise already settled, since the bytes never left memory.
+//
+// Through JavaScript's own `Promise.resolve` rather than through jsi's
+// AsyncPromise: this needs no thread hop and no invoker, and borrowing the
+// machinery for one would only add a way for it to be wrong.
+Value resolved(Runtime &rt, Value &&value) {
+  auto promise = rt.global().getPropertyAsObject(rt, "Promise");
+  return promise.getPropertyAsFunction(rt, "resolve").callWithThis(rt, promise, value);
+}
+
+Value rejected(Runtime &rt, const std::string &message) {
+  auto promise = rt.global().getPropertyAsObject(rt, "Promise");
+  auto error = rt.global()
+                   .getPropertyAsFunction(rt, "Error")
+                   .callAsConstructor(rt, String::createFromUtf8(rt, message));
+  return promise.getPropertyAsFunction(rt, "reject").callWithThis(rt, promise, error);
+}
+
+} // namespace
+
+namespace detail {
+
+std::string base64Encode(const std::string &bytes) {
+  static constexpr std::string_view kAlphabet =
+      "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+  std::string out;
+  out.reserve(((bytes.size() + 2) / 3) * 4);
+
+  size_t i = 0;
+  while (i + 2 < bytes.size()) {
+    const uint32_t triple = (static_cast<unsigned char>(bytes[i]) << 16) |
+        (static_cast<unsigned char>(bytes[i + 1]) << 8) |
+        static_cast<unsigned char>(bytes[i + 2]);
+    out.push_back(kAlphabet[(triple >> 18) & 0x3F]);
+    out.push_back(kAlphabet[(triple >> 12) & 0x3F]);
+    out.push_back(kAlphabet[(triple >> 6) & 0x3F]);
+    out.push_back(kAlphabet[triple & 0x3F]);
+    i += 3;
+  }
+
+  // The tail, padded. Getting this wrong is the classic base64 bug and it only
+  // shows on inputs whose length is not a multiple of three.
+  if (i < bytes.size()) {
+    const size_t remaining = bytes.size() - i;
+    uint32_t triple = static_cast<unsigned char>(bytes[i]) << 16;
+    if (remaining == 2) {
+      triple |= static_cast<unsigned char>(bytes[i + 1]) << 8;
+    }
+    out.push_back(kAlphabet[(triple >> 18) & 0x3F]);
+    out.push_back(kAlphabet[(triple >> 12) & 0x3F]);
+    out.push_back(remaining == 2 ? kAlphabet[(triple >> 6) & 0x3F] : '=');
+    out.push_back('=');
+  }
+
+  return out;
+}
+
+// The inverse, for the `base64` part type below.
+//
+// Skips anything outside the alphabet rather than rejecting it, which covers
+// the padding and any newlines a transport introduced. A truncated group -- one
+// leftover character, which encodes nothing -- is dropped.
+std::string base64Decode(const std::string &text) {
+  static constexpr std::string_view kAlphabet =
+      "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+  std::string out;
+  out.reserve((text.size() / 4) * 3);
+
+  uint32_t group = 0;
+  int digits = 0;
+  for (const char c : text) {
+    const size_t value = kAlphabet.find(c);
+    if (value == std::string_view::npos) {
+      continue;
+    }
+    group = (group << 6) | static_cast<uint32_t>(value);
+    if (++digits == 4) {
+      out.push_back(static_cast<char>((group >> 16) & 0xFF));
+      out.push_back(static_cast<char>((group >> 8) & 0xFF));
+      out.push_back(static_cast<char>(group & 0xFF));
+      group = 0;
+      digits = 0;
+    }
+  }
+
+  // A trailing group of two digits carries one byte, three carries two.
+  if (digits == 2) {
+    out.push_back(static_cast<char>((group >> 4) & 0xFF));
+  } else if (digits == 3) {
+    out.push_back(static_cast<char>((group >> 10) & 0xFF));
+    out.push_back(static_cast<char>((group >> 2) & 0xFF));
+  }
+
+  return out;
+}
+
+} // namespace detail
+
+// ---------------------------------------------------------------------------
+// BlobModule
+// ---------------------------------------------------------------------------
+
+Object DesktopBlobModule::getConstants(Runtime &rt) {
+  Object constants(rt);
+  // `blob:`, which is what the web and iOS use. Android says `content:` because
+  // its blobs are served through a ContentProvider; nothing here is.
+  //
+  // BLOB_URI_HOST is deliberately absent: URL.js only prefixes a host when this
+  // is a string, and a blob URL with an empty authority -- `blob://` -- is a
+  // worse thing to hand anybody than one without.
+  constants.setProperty(rt, "BLOB_URI_SCHEME", String::createFromUtf8(rt, "blob"));
+  return constants;
+}
+
+void DesktopBlobModule::createFromParts(Runtime &rt, Array parts, String blobId) {
+  std::string bytes;
+
+  const size_t count = parts.size(rt);
+  for (size_t i = 0; i < count; i++) {
+    Object part = parts.getValueAtIndex(rt, i).asObject(rt);
+    const std::string type = part.getProperty(rt, "type").asString(rt).utf8(rt);
+
+    if (type == "string") {
+      bytes += part.getProperty(rt, "data").asString(rt).utf8(rt);
+      continue;
+    }
+
+    // Not one of React Native's own part types. `fetch` on this platform routes
+    // a `responseType: 'blob'` response through base64 -- see
+    // src/overrides/setUpXHR.js -- because ReactCxxPlatform's NetworkingModule
+    // delivers every body as a JavaScript string, and a string cannot carry
+    // arbitrary bytes intact. Base64 can, and this is where it is turned back
+    // into bytes.
+    if (type == "base64") {
+      bytes += detail::base64Decode(part.getProperty(rt, "data").asString(rt).utf8(rt));
+      continue;
+    }
+
+    if (type == "blob") {
+      const BlobHandle handle = readHandle(rt, part.getProperty(rt, "data").asObject(rt));
+      if (auto slice = blobSlice(handle.blobId, handle.offset, handle.size)) {
+        bytes += *slice;
+      } else {
+        // A part naming a blob that has been released. Skipping it makes the
+        // result quietly short; saying so at least leaves a trace, and throwing
+        // would take down a Blob constructor that JavaScript considers valid.
+        LOG(WARNING) << "blob part refers to released blob " << handle.blobId;
+      }
+      continue;
+    }
+
+    LOG(WARNING) << "unknown blob part type '" << type << "'";
+  }
+
+  storeBlob(blobId.utf8(rt), std::move(bytes));
+}
+
+void DesktopBlobModule::release(Runtime &rt, String blobId) {
+  releaseBlob(blobId.utf8(rt));
+}
+
+void DesktopBlobModule::addNetworkingHandler(Runtime &rt) {
+  (void)rt;
+  // On iOS and Android this registers a handler with the networking module so
+  // that a request body of `{blob: ...}` is sent as bytes and a response with
+  // `responseType: 'blob'` comes back as one.
+  //
+  // ReactCxxPlatform's NetworkingModule has no such hook -- it does not mention
+  // blobs at all -- so there is nothing to register with. Request bodies still
+  // work, because core/HttpClient.cpp resolves a blob body through the registry
+  // itself; `responseType: 'blob'` does not, and cannot until upstream's
+  // networking module grows a seam.
+  //
+  // Silent rather than warning: JavaScript calls this once at startup on every
+  // platform, and a warning every app sees and nobody can act on is noise.
+}
+
+void DesktopBlobModule::addWebSocketHandler(Runtime &rt, double id) {
+  (void)rt;
+  (void)id;
+}
+
+void DesktopBlobModule::removeWebSocketHandler(Runtime &rt, double id) {
+  (void)rt;
+  (void)id;
+}
+
+void DesktopBlobModule::sendOverSocket(Runtime &rt, Object blob, double socketID) {
+  (void)blob;
+  (void)socketID;
+  (void)rt;
+  // Sending a blob over a websocket needs the socket, and WebSocketModule is
+  // ReactCxxPlatform's rather than ours. Unlike the handlers above this one is
+  // a call an app makes deliberately, so it says so rather than vanishing.
+  LOG(WARNING) << "sendOverSocket is not implemented: binary websocket frames "
+                  "need a hook ReactCxxPlatform's WebSocketModule does not have";
+}
+
+// ---------------------------------------------------------------------------
+// FileReaderModule
+// ---------------------------------------------------------------------------
+
+Value DesktopFileReaderModule::readAsDataURL(Runtime &rt, Object blob) {
+  const BlobHandle handle = readHandle(rt, blob);
+  auto slice = blobSlice(handle.blobId, handle.offset, handle.size);
+  if (!slice) {
+    return rejected(rt, "Unable to resolve data for blob: " + handle.blobId);
+  }
+
+  // The type is on the handle, not in the registry: two Blobs can share bytes
+  // and disagree about what they are.
+  std::string type;
+  const Value typeValue = blob.getProperty(rt, "type");
+  if (typeValue.isString()) {
+    type = typeValue.asString(rt).utf8(rt);
+  }
+  if (type.empty()) {
+    // What the web does for a Blob with no type, and what iOS does here.
+    type = "application/octet-stream";
+  }
+
+  const std::string url = "data:" + type + ";base64," + detail::base64Encode(*slice);
+  return resolved(rt, Value(String::createFromUtf8(rt, url)));
+}
+
+Value DesktopFileReaderModule::readAsText(Runtime &rt, Object blob, String encoding) {
+  const BlobHandle handle = readHandle(rt, blob);
+  auto slice = blobSlice(handle.blobId, handle.offset, handle.size);
+  if (!slice) {
+    return rejected(rt, "Unable to resolve data for blob: " + handle.blobId);
+  }
+
+  // Only UTF-8. React Native's JavaScript defaults to it and nothing in the
+  // library asks for another, but an app can, and a wrong answer that looks
+  // right is worse than a rejection that names the encoding.
+  const std::string requested = encoding.utf8(rt);
+  if (!requested.empty() && requested != "UTF-8" && requested != "utf-8" &&
+      requested != "utf8") {
+    return rejected(rt, "Unsupported encoding for readAsText: " + requested);
+  }
+
+  return resolved(rt, Value(String::createFromUtf8(rt, *slice)));
+}
+
+} // namespace basalt

package/native/core/BlobModule.h

@@ -0,0 +1,76 @@
+// `BlobModule` and `FileReaderModule`: what `Blob`, `File` and `FileReader`
+// stand on.
+//
+// A stock Expo app asks for BlobModule during startup -- `fetch` and
+// `XMLHttpRequest` both register a blob handler if one exists -- and phase 29
+// found it was the one missing module a real app would notice. Anything
+// fetching binary data needs it.
+//
+// Both modules are portable in full. A blob is a byte array with a name on
+// every platform, and reading one as text or as a data URL is arithmetic. The
+// bytes live in BlobRegistry.h; these two are the JavaScript-facing half.
+
+#pragma once
+
+#include <FBReactNativeSpec/FBReactNativeSpecJSI.h>
+
+#include <string>
+
+namespace basalt {
+
+// base64, both ways.
+//
+// Exposed rather than kept file-local because every `fetch` on this platform
+// now goes through the decoder -- see src/overrides/setUpXHR.js -- and because
+// the padded tail is the classic base64 bug, which only shows on inputs whose
+// length is not a multiple of three. native/tests/test_blobs.cpp covers it.
+namespace detail {
+std::string base64Encode(const std::string &bytes);
+std::string base64Decode(const std::string &text);
+} // namespace detail
+
+class DesktopBlobModule : public facebook::react::NativeBlobModuleCxxSpec<DesktopBlobModule> {
+ public:
+  explicit DesktopBlobModule(std::shared_ptr<facebook::react::CallInvoker> jsInvoker)
+      : NativeBlobModuleCxxSpec(std::move(jsInvoker)) {}
+
+  static constexpr const char *kModuleName = "BlobModule";
+
+  facebook::jsi::Object getConstants(facebook::jsi::Runtime &rt);
+
+  // `parts` is an array of `{data, type}`: a `string` part carries its text,
+  // and a `blob` part carries another blob's `{blobId, offset, size}`. The
+  // concatenation is stored under `blobId`.
+  void createFromParts(facebook::jsi::Runtime &rt,
+                       facebook::jsi::Array parts,
+                       facebook::jsi::String blobId);
+
+  void release(facebook::jsi::Runtime &rt, facebook::jsi::String blobId);
+
+  // The three below are about wiring blobs into networking and websockets, and
+  // none of them can do anything here. See the .cpp for why, which is a
+  // limitation of ReactCxxPlatform rather than of this platform.
+  void addNetworkingHandler(facebook::jsi::Runtime &rt);
+  void addWebSocketHandler(facebook::jsi::Runtime &rt, double id);
+  void removeWebSocketHandler(facebook::jsi::Runtime &rt, double id);
+  void sendOverSocket(facebook::jsi::Runtime &rt, facebook::jsi::Object blob, double socketID);
+};
+
+class DesktopFileReaderModule
+    : public facebook::react::NativeFileReaderModuleCxxSpec<DesktopFileReaderModule> {
+ public:
+  explicit DesktopFileReaderModule(std::shared_ptr<facebook::react::CallInvoker> jsInvoker)
+      : NativeFileReaderModuleCxxSpec(std::move(jsInvoker)) {}
+
+  static constexpr const char *kModuleName = "FileReaderModule";
+
+  // Both take a blob handle -- `{blobId, offset, size}` -- and return a
+  // promise, because that is what the spec says even though the bytes are
+  // already in memory and the answer is immediate.
+  facebook::jsi::Value readAsDataURL(facebook::jsi::Runtime &rt, facebook::jsi::Object blob);
+  facebook::jsi::Value readAsText(facebook::jsi::Runtime &rt,
+                                  facebook::jsi::Object blob,
+                                  facebook::jsi::String encoding);
+};
+
+} // namespace basalt

package/native/core/BlobRegistry.cpp

@@ -0,0 +1,75 @@
+#include "BlobRegistry.h"
+
+// For std::min, which libstdc++ does not promise through <string>.
+#include <algorithm>
+#include <mutex>
+#include <unordered_map>
+
+namespace basalt {
+
+namespace {
+
+struct Registry {
+  std::mutex mutex;
+  std::unordered_map<std::string, std::string> blobs;
+};
+
+Registry &registry() {
+  static Registry instance;
+  return instance;
+}
+
+} // namespace
+
+void storeBlob(const std::string &blobId, std::string bytes) {
+  Registry &state = registry();
+  const std::lock_guard<std::mutex> lock(state.mutex);
+  state.blobs[blobId] = std::move(bytes);
+}
+
+std::optional<std::string> blobSlice(const std::string &blobId, size_t offset, size_t size) {
+  Registry &state = registry();
+  const std::lock_guard<std::mutex> lock(state.mutex);
+
+  const auto it = state.blobs.find(blobId);
+  if (it == state.blobs.end()) {
+    return std::nullopt;
+  }
+
+  const std::string &bytes = it->second;
+  if (offset >= bytes.size()) {
+    return std::string{};
+  }
+  return bytes.substr(offset, std::min(size, bytes.size() - offset));
+}
+
+std::optional<std::string> blobBytes(const std::string &blobId) {
+  Registry &state = registry();
+  const std::lock_guard<std::mutex> lock(state.mutex);
+  const auto it = state.blobs.find(blobId);
+  if (it == state.blobs.end()) {
+    return std::nullopt;
+  }
+  return it->second;
+}
+
+size_t blobSize(const std::string &blobId) {
+  Registry &state = registry();
+  const std::lock_guard<std::mutex> lock(state.mutex);
+  const auto it = state.blobs.find(blobId);
+  return it == state.blobs.end() ? 0 : it->second.size();
+}
+
+void releaseBlob(const std::string &blobId) {
+  Registry &state = registry();
+  const std::lock_guard<std::mutex> lock(state.mutex);
+  state.blobs.erase(blobId);
+}
+
+size_t blobCount() {
+  Registry &state = registry();
+  const std::lock_guard<std::mutex> lock(state.mutex);
+  return state.blobs.size();
+}
+
+} // namespace basalt

package/native/core/BlobRegistry.h

@@ -0,0 +1,44 @@
+// The bytes behind a Blob.
+//
+// React Native's `Blob` is a handle, not data: JavaScript holds
+// `{blobId, offset, size}` and the bytes live natively, so that a 20MB file
+// picked by a user is never copied into the JavaScript heap. This is where they
+// live.
+//
+// Entirely portable -- a blob is a byte array with a name, on every platform --
+// which is why it is here and not behind a seam. The only part of blobs that
+// touches an operating system is sending one as an HTTP body, and that is in
+// HttpClient.cpp, which is also shared.
+
+#pragma once
+
+#include <cstddef>
+#include <optional>
+#include <string>
+
+namespace basalt {
+
+// Stores `bytes` under `blobId`, replacing anything already there.
+void storeBlob(const std::string &blobId, std::string bytes);
+
+// A slice of a stored blob, or nullopt if the id is unknown.
+//
+// The range is clamped rather than rejected: JavaScript computes offsets from
+// sizes it was told, and a rounding disagreement should produce a short read
+// rather than an exception three layers from the cause.
+std::optional<std::string> blobSlice(const std::string &blobId, size_t offset, size_t size);
+
+// The whole of a stored blob, or nullopt if the id is unknown.
+std::optional<std::string> blobBytes(const std::string &blobId);
+
+size_t blobSize(const std::string &blobId);
+
+// `BlobModule.release`. JavaScript owns the lifetime: a Blob that goes out of
+// scope there has to say so, because nothing here can tell.
+void releaseBlob(const std::string &blobId);
+
+// How many blobs are held. For tests and for a future leak check -- nothing
+// evicts on its own, by design.
+size_t blobCount();
+
+} // namespace basalt