basalt-gtk 0.0.0-rc5

package/native/gtk/GtkFocus.cpp

@@ -0,0 +1,296 @@
+#include "GtkFocus.h"
+
+#include "GtkKeyEvents.h"
+
+#include <optional>
+#include <vector>
+
+#include <folly/dynamic.h>
+
+#include <react/renderer/core/EventEmitter.h>
+
+namespace basalt {
+
+using facebook::react::EventEmitter;
+using facebook::react::RawEvent;
+using facebook::react::Tag;
+
+namespace {
+
+// The React Native view a widget belongs to, or null. A <TextInput>'s peer is a
+// GtkText inside an RnView, so focus landing on the peer is focus landing on
+// the wrapper as far as React Native is concerned.
+RnView *owningView(GtkWidget *widget) {
+  while (widget != nullptr && !RN_IS_VIEW(widget)) {
+    widget = gtk_widget_get_parent(widget);
+  }
+  return widget == nullptr ? nullptr : RN_VIEW(widget);
+}
+
+} // namespace
+
+GtkFocusManager::GtkFocusManager(GtkMountingManager *mountingManager, RnView *surfaceRoot)
+    : mountingManager_(mountingManager), surfaceRoot_(surfaceRoot) {
+  keyController_ = gtk_event_controller_key_new();
+  // Bubble rather than capture: a <TextInput> with focus must see space and
+  // Enter first, or typing a space in a field would activate it instead.
+  gtk_event_controller_set_propagation_phase(keyController_, GTK_PHASE_BUBBLE);
+  g_signal_connect(keyController_, "key-pressed", G_CALLBACK(onKeyPressed), this);
+  gtk_widget_add_controller(GTK_WIDGET(surfaceRoot_), keyController_);
+  // Weak, so it becomes NULL when the widget takes it down rather than
+  // dangling. See the destructor.
+  g_object_add_weak_pointer(G_OBJECT(keyController_),
+                            reinterpret_cast<gpointer *>(&keyController_));
+
+  // The root may or may not be in a window yet, depending on the order the host
+  // built things in, so both are handled rather than one being assumed.
+  attachToWindow();
+  g_signal_connect(surfaceRoot_, "notify::root", G_CALLBACK(onRootChanged), this);
+}
+
+GtkFocusManager::~GtkFocusManager() {
+  if (window_ != nullptr) {
+    g_signal_handlers_disconnect_by_data(window_, this);
+    window_ = nullptr;
+  }
+  if (surfaceRoot_ != nullptr && RN_IS_VIEW(surfaceRoot_)) {
+    g_signal_handlers_disconnect_by_data(surfaceRoot_, this);
+  }
+  // The key controller belongs to the widget, and that is exactly why it has to
+  // be disconnected: it outlives *this*, because both teardown paths reset the
+  // focus manager before destroying the window. A key press delivered in
+  // between would call `onKeyPressed` with a freed pointer.
+  //
+  // The dispatcher next door had the same hazard and it was not theoretical --
+  // a leave crossing between the two crashed in `dispatchHoverLeave`. Weak
+  // pointer rather than a flag, because the widget may have gone first and
+  // taken the controller with it.
+  if (keyController_ != nullptr) {
+    g_signal_handlers_disconnect_by_data(keyController_, this);
+    g_object_remove_weak_pointer(G_OBJECT(keyController_),
+                                 reinterpret_cast<gpointer *>(&keyController_));
+  }
+}
+
+void GtkFocusManager::onRootChanged(GObject * /*widget*/, GParamSpec * /*spec*/, gpointer userData) {
+  static_cast<GtkFocusManager *>(userData)->attachToWindow();
+}
+
+void GtkFocusManager::attachToWindow() {
+  GtkRoot *root = gtk_widget_get_root(GTK_WIDGET(surfaceRoot_));
+  GtkWindow *window = GTK_IS_WINDOW(root) ? GTK_WINDOW(root) : nullptr;
+  if (window == window_) {
+    return;
+  }
+  if (window_ != nullptr) {
+    g_signal_handlers_disconnect_by_data(window_, this);
+  }
+  window_ = window;
+  if (window_ == nullptr) {
+    return;
+  }
+  // One signal for the whole tree. GtkWindow reports which widget holds focus,
+  // so there is nothing to connect per view -- which matters, because views
+  // arrive and leave with every mutation and the window does not.
+  g_signal_connect(window_, "notify::focus-widget", G_CALLBACK(onFocusChanged), this);
+  refreshFocus();
+}
+
+void GtkFocusManager::onFocusChanged(GObject * /*window*/, GParamSpec * /*spec*/, gpointer userData) {
+  static_cast<GtkFocusManager *>(userData)->refreshFocus();
+}
+
+void GtkFocusManager::refreshFocus() {
+  Tag tag = 0;
+  if (window_ != nullptr) {
+    if (RnView *view = owningView(gtk_window_get_focus(window_))) {
+      // A <TextInput> reports its own focus and blur, through the peer that
+      // actually has them. Reporting them here as well would fire onFocus twice
+      // for every field in the app.
+      if (rn_view_get_editable(view) == nullptr) {
+        tag = static_cast<Tag>(rn_view_get_tag(view));
+      }
+    }
+  }
+  if (tag == focusedTag_) {
+    return;
+  }
+  const Tag previous = focusedTag_;
+  focusedTag_ = tag;
+  if (previous != 0) {
+    emitFocus(previous, false);
+  }
+  if (tag != 0) {
+    emitFocus(tag, true);
+  }
+}
+
+void GtkFocusManager::emitFocus(Tag tag, bool focused) {
+  const auto emitter = mountingManager_->eventEmitterForTag(tag);
+  if (emitter == nullptr) {
+    return;
+  }
+  // `topFocus` and `topBlur`, which React Native registers as bubbling events
+  // with an empty payload. BaseViewEventEmitter has both, so nothing here has
+  // to know the names.
+  const auto view = std::dynamic_pointer_cast<const facebook::react::ViewEventEmitter>(emitter);
+  if (view == nullptr) {
+    return;
+  }
+  if (focused) {
+    view->onFocus();
+  } else {
+    view->onBlur();
+  }
+}
+
+Tag GtkFocusManager::focusedTag() const {
+  return focusedTag_;
+}
+
+gboolean GtkFocusManager::onKeyPressed(GtkEventControllerKey * /*controller*/,
+                                       guint keyval,
+                                       guint /*keycode*/,
+                                       GdkModifierType state,
+                                       gpointer userData) {
+  auto *self = static_cast<GtkFocusManager *>(userData);
+
+  // An app's own declared shortcuts first, before Escape and before activation,
+  // for the reason the AppKit host gives: an app that binds Escape means it, and
+  // a platform default that beat an explicit declaration could not be overridden.
+  if (self->handleKey(keyval, state)) {
+    return GDK_EVENT_STOP;
+  }
+
+  // Escape closes the topmost <Modal> -- or rather, asks the app to. React
+  // Native's `onRequestClose` is documented as the hardware back button on
+  // Android and the swipe-down on iOS; on a desktop it is Escape, and a modal
+  // the app does not close in response stays up, which is deliberate.
+  //
+  // Handled here because this is the only key controller on the window, and
+  // because a modal is a surface-wide thing rather than a focused view's.
+  if (keyval == GDK_KEY_Escape) {
+    return self->mountingManager_->requestCloseTopModal() ? GDK_EVENT_STOP : GDK_EVENT_PROPAGATE;
+  }
+
+  if (keyval != GDK_KEY_Return && keyval != GDK_KEY_KP_Enter && keyval != GDK_KEY_space) {
+    return GDK_EVENT_PROPAGATE;
+  }
+  return self->activateFocused() ? GDK_EVENT_STOP : GDK_EVENT_PROPAGATE;
+}
+
+bool GtkFocusManager::handleKey(guint keyval, GdkModifierType state) {
+  // Almost every app claims nothing and presses plenty; without this the walk
+  // below would run on every keystroke in every text field.
+  if (handledKeyViewCount() == 0) {
+    return false;
+  }
+  const std::optional<KeyCombination> pressed = keyCombinationFrom(keyval, state);
+  if (!pressed.has_value()) {
+    return false;
+  }
+  return deliverTestKey(*pressed);
+}
+
+bool GtkFocusManager::deliverTestKey(const KeyCombination &pressed) {
+  // From the focused widget outwards, so the innermost claim wins. Only RnViews,
+  // because only they carry a React tag -- the box a scrolled window puts in
+  // between is not a step in the React tree. With nothing focused this walks from
+  // nothing and the root's own claim is added below, which is the ordinary case
+  // for a window-level shortcut holder.
+  std::vector<Tag> path;
+  for (GtkWidget *widget = gtk_window_get_focus(window_); widget != nullptr;
+       widget = gtk_widget_get_parent(widget)) {
+    if (RN_IS_VIEW(widget)) {
+      path.push_back(static_cast<Tag>(rn_view_get_tag(RN_VIEW(widget))));
+    }
+  }
+  if (path.empty() && mountingManager_ != nullptr) {
+    // Surface 1, which is the app's own -- the same constant main_gtk.cpp uses
+    // for it. A second window's surface has its own focus manager.
+    if (RnView *root = mountingManager_->getSurfaceRoot(1); root != nullptr) {
+      path.push_back(static_cast<Tag>(rn_view_get_tag(root)));
+    }
+  }
+
+  std::optional<Tag> handler = handledBy(path, pressed);
+  if (!handler.has_value() && focusedTag_ == 0) {
+    // See the AppKit host and core/KeyEvents.h: unfocused, a window-level
+    // shortcut holder is not on any path and would otherwise never fire.
+    handler = handledByAny(pressed);
+  }
+  if (!handler.has_value()) {
+    return false;
+  }
+  reportKey(*handler, pressed);
+  return true;
+}
+
+bool GtkFocusManager::activateFocused() {
+  if (focusedTag_ == 0) {
+    return false;
+  }
+  // True whether or not anything is listening: the key belongs to the focused
+  // view either way, and letting it travel on because a view between a Remove
+  // and its Delete has no emitter would deliver it somewhere else.
+  // A <Switch> is toggled from here too. It listens for no click -- React
+  // Native's is a controlled component driven by its own native control -- so
+  // without this a switch that Tab reaches is one Enter cannot work. The same
+  // call the touch path makes, and a no-op for every view that is not a switch.
+  mountingManager_->pressedView(focusedTag_);
+
+  const auto emitter = mountingManager_->eventEmitterForTag(focusedTag_);
+  if (emitter == nullptr) {
+    return true;
+  }
+
+  // `topClick` with an empty payload, which is exactly what React Native for
+  // Android sends from a focusable view's OnClickListener. It cannot go through
+  // TouchEventEmitter::onClick: that carries a PointerEvent, and Pressability
+  // ignores a click with a `pointerType` on it so that a real click does not
+  // fire onPress twice. See the header.
+  emitter->dispatchEvent("click", folly::dynamic::object(), RawEvent::Category::Discrete);
+  return true;
+}
+
+bool GtkFocusManager::moveFocus(bool forward) {
+  if (surfaceRoot_ == nullptr) {
+    return false;
+  }
+  // The blur first, before anything moves.
+  //
+  // React Native's own order is blur-then-focus, and a <TextInput> gaining
+  // focus reports it from its peer's own focus controller, which runs *before*
+  // the window gets round to saying which widget holds focus now. Left alone
+  // that produces focus-then-blur for a Tab from a button into a field -- both
+  // events, in the wrong order. A real Tab keypress is GTK's own and can still
+  // interleave that way; this is what the automated path and anything calling
+  // moveFocus get right.
+  if (focusedTag_ != 0) {
+    const Tag leaving = focusedTag_;
+    focusedTag_ = 0;
+    emitFocus(leaving, false);
+  }
+
+  // GTK's own chain, which is the point: a focusable widget joins the window's
+  // focus order, so the order here is the order Tab produces and nothing in
+  // this project decides what "next" means.
+  const GtkDirectionType direction = forward ? GTK_DIR_TAB_FORWARD : GTK_DIR_TAB_BACKWARD;
+  gboolean moved = gtk_widget_child_focus(GTK_WIDGET(surfaceRoot_), direction);
+
+  // Wrapping. `gtk_widget_child_focus` on a container stops at its last child,
+  // because a real window would carry on into whatever is next -- and here the
+  // surface root *is* the window's content, so there is nothing after it. The
+  // AppKit side wraps, and a Tab order that runs out on one desktop and goes
+  // round on the other is a difference an app did not ask for.
+  if (moved == FALSE) {
+    if (window_ != nullptr) {
+      gtk_window_set_focus(window_, nullptr);
+    }
+    moved = gtk_widget_child_focus(GTK_WIDGET(surfaceRoot_), direction);
+  }
+  refreshFocus();
+  return moved != FALSE;
+}
+
+} // namespace basalt

package/native/gtk/GtkFocus.h

@@ -0,0 +1,113 @@
+// Keyboard focus, for everything that is not a <TextInput>.
+//
+// A text field takes focus because it is a real GtkText and GTK gives it focus;
+// nothing else in a React Native tree was reachable by Tab at all, and an
+// application whose buttons cannot be reached from the keyboard is not really a
+// desktop application.
+//
+// ## What makes a view focusable
+//
+// `accessible`. React Native has a `focusable` prop and it does not reach this
+// platform: ReactCommon parses it only into Android's and tvOS's
+// `HostPlatformViewProps`, and the C++ host's is a bare alias of
+// `BaseViewProps`. So the signal has to be something that does arrive, and
+// `accessible` is both the nearest true thing and the right one -- it is what
+// `<Pressable>` sets on everything it renders, what an app sets on anything
+// else it means as a control, and what a screen reader already stops on. Tab
+// order following the accessibility tree is also what GTK and macOS do with
+// their own widgets.
+//
+// ## What activating one does
+//
+// Dispatches `topClick` with an empty payload, which is exactly what React
+// Native for Android does from `ReactViewManager.setFocusable`. Pressability
+// listens for it and calls `onPress`, but only when the payload has no
+// `pointerType` -- a click that came from a pointer would fire `onPress` twice.
+// So this cannot go through `TouchEventEmitter::onClick`, which always carries
+// one; it is `dispatchEvent("click", folly::dynamic::object())`, the same shape
+// Android's ViewGroupClickEvent has.
+//
+// Enter and space, because those are the two keys that activate a control on
+// every desktop and in the browser.
+//
+// ## What GTK contributes
+//
+// The chain. A focusable widget joins the window's focus order, so Tab and
+// Shift+Tab already work and nothing here decides what "next" means -- which
+// also means a <TextInput>'s peer sits in the same order as the buttons around
+// it, without this file knowing that text inputs exist. The Win32 host has no
+// such chain and has to build one; that is the difference between the two, and
+// it is GTK's to take credit for.
+
+#pragma once
+
+#include "KeyEvents.h"
+
+#include "GtkMountingManager.h"
+#include "RnView.h"
+
+namespace basalt {
+
+class GtkFocusManager {
+ public:
+  GtkFocusManager(GtkMountingManager *mountingManager, RnView *surfaceRoot);
+  ~GtkFocusManager();
+
+  GtkFocusManager(const GtkFocusManager &) = delete;
+  GtkFocusManager &operator=(const GtkFocusManager &) = delete;
+  GtkFocusManager(GtkFocusManager &&) = delete;
+  GtkFocusManager &operator=(GtkFocusManager &&) = delete;
+
+  // Moves focus to the next or previous focusable view, and reports whether
+  // anything took it. The keyboard's own Tab goes through GTK; this is the
+  // entry point automation uses, for the same reason `synthesiseTap` exists --
+  // a real Tab needs a window the display server considers focused, which a
+  // headless run does not have.
+  bool moveFocus(bool forward);
+
+  // Activates whatever has focus, as Enter or space does.
+  bool activateFocused();
+
+  // The tag of the focused view, or 0. For tests and for the tree dump.
+  facebook::react::Tag focusedTag() const;
+
+  // A key press. Answers whether some view from the focused one outwards declared
+  // this combination, and reports it when one did. The answer comes back in this
+  // call stack because `key-pressed` consumes or propagates by it; see
+  // core/KeyEvents.h.
+  bool handleKey(guint keyval, GdkModifierType state);
+
+  // BASALT_TEST_KEY. The same delivery a real press gets, minus the keyval
+  // translation, which tests/test_key_events_gtk.cpp covers instead. See
+  // core/TestKeys.h.
+  bool deliverTestKey(const KeyCombination &pressed);
+
+ private:
+  static gboolean onKeyPressed(GtkEventControllerKey *controller,
+                               guint keyval,
+                               guint keycode,
+                               GdkModifierType state,
+                               gpointer userData);
+  static void onFocusChanged(GObject *window, GParamSpec *spec, gpointer userData);
+  static void onRootChanged(GObject *widget, GParamSpec *spec, gpointer userData);
+
+  // Connects to the window's focus-widget notification. One signal for the
+  // whole tree, rather than one per view: views come and go with every
+  // mutation, and the window does not.
+  void attachToWindow();
+
+  // Works out which React Native view holds focus now and reports the change.
+  void refreshFocus();
+
+  void emitFocus(facebook::react::Tag tag, bool focused);
+
+  GtkMountingManager *mountingManager_;
+  RnView *surfaceRoot_;
+  GtkEventController *keyController_{nullptr};
+  // The window this is listening to, held weakly: it outlives the manager in
+  // the normal case and does not during teardown.
+  GtkWindow *window_{nullptr};
+  facebook::react::Tag focusedTag_{0};
+};
+
+} // namespace basalt

package/native/gtk/GtkImageLoader.cpp

@@ -0,0 +1,128 @@
+#include "GtkImageLoader.h"
+
+#include "ImageBytes.h"
+
+#include <string>
+#include <thread>
+#include <utility>
+
+namespace basalt {
+
+// Carries one completed load from the worker thread to the main thread.
+struct GtkImageLoader::Pending {
+  GtkImageLoader *loader;
+  std::string uri;
+  std::string bytes;
+  std::string error;
+  Callback callback;
+};
+
+GtkImageLoader::GtkImageLoader() = default;
+
+GtkImageLoader::~GtkImageLoader() {
+  for (auto &[uri, texture] : cache_) {
+    g_clear_object(&texture);
+  }
+  cache_.clear();
+}
+
+// Caches the texture and drops whatever that pushed out. See core/ImageCache.h
+// for the policy; the bytes are this file's to measure, because only GDK knows
+// how big a decoded texture is.
+void GtkImageLoader::remember(const std::string &uri, GdkTexture *texture) {
+  cache_[uri] = texture;
+
+  // Four bytes a pixel, which is what GDK decodes to. Not asked of the texture
+  // because `gdk_texture_get_format` reports the *source* format and the
+  // memory is what matters here.
+  const size_t bytes = static_cast<size_t>(gdk_texture_get_width(texture)) *
+                       static_cast<size_t>(gdk_texture_get_height(texture)) * 4u;
+
+  for (const std::string &evicted : policy_.insert(uri, bytes)) {
+    const auto it = cache_.find(evicted);
+    if (it != cache_.end()) {
+      g_clear_object(&it->second);
+      cache_.erase(it);
+    }
+  }
+}
+
+gboolean GtkImageLoader::deliver(gpointer data) {
+  auto *pending = static_cast<Pending *>(data);
+
+  GdkTexture *texture = nullptr;
+  std::string error = pending->error;
+
+  if (error.empty()) {
+    // Decoding happens here rather than on the worker thread: GdkTexture is a
+    // GObject, and creating one is only safe once, on the thread that will use
+    // it. The expensive part -- the I/O -- already happened off-thread.
+    GBytes *bytes = g_bytes_new(pending->bytes.data(), pending->bytes.size());
+    GError *decodeError = nullptr;
+    texture = gdk_texture_new_from_bytes(bytes, &decodeError);
+    g_bytes_unref(bytes);
+    if (texture == nullptr) {
+      error = decodeError != nullptr ? decodeError->message : "could not decode image";
+      g_clear_error(&decodeError);
+    } else {
+      pending->loader->remember(pending->uri, texture);
+    }
+  }
+
+  pending->callback(texture, error);
+  delete pending;
+  return G_SOURCE_REMOVE;
+}
+
+void GtkImageLoader::load(const std::string &uri, Callback &&callback) {
+  if (uri.empty()) {
+    callback(nullptr, "empty source uri");
+    return;
+  }
+
+  if (const auto it = cache_.find(uri); it != cache_.end()) {
+    policy_.noteUse(uri);
+    callback(it->second, {});
+    return;
+  }
+
+  auto *pending = new Pending{this, uri, {}, {}, std::move(callback)};
+
+  std::thread([pending]() {
+    // The fetch is in core, shared with the AppKit loader: a URI means the same
+    // thing on both, and only the decode below differs.
+    fetchImageBytes(pending->uri, &pending->bytes, &pending->error);
+    g_idle_add_full(G_PRIORITY_DEFAULT, deliver, pending, nullptr);
+  }).detach();
+}
+
+
+void GtkImageLoader::loadImage(const std::string &uri,
+                               const facebook::react::IImageLoaderOnLoadCallback &&onLoad) {
+  // Copied because the callback outlives this call: `load` may answer on a
+  // later turn of the main loop, and the reference it was handed is gone by
+  // then.
+  auto callback = onLoad;
+  load(uri, [callback](GdkTexture *texture, const std::string &error) {
+    if (texture == nullptr) {
+      // The message rather than a size: `Image.getSize` rejects with it, and a
+      // zero-by-zero success would be indistinguishable from a 0x0 image.
+      callback(0.0, 0.0, error.empty() ? "could not load image" : error.c_str());
+      return;
+    }
+    callback(static_cast<double>(gdk_texture_get_width(texture)),
+             static_cast<double>(gdk_texture_get_height(texture)),
+             nullptr);
+  });
+}
+
+facebook::react::IImageLoader::CacheStatus GtkImageLoader::getCacheStatus(
+    const std::string &uri) {
+  // Memory or nothing: there is no disk cache here, and saying `Disk` would be
+  // claiming a persistence this has not got.
+  return cache_.find(uri) != cache_.end()
+      ? facebook::react::IImageLoader::CacheStatus::Memory
+      : facebook::react::IImageLoader::CacheStatus::None;
+}
+
+} // namespace basalt

package/native/gtk/GtkImageLoader.h

@@ -0,0 +1,87 @@
+// Loading the pixels behind <Image>.
+//
+// React Native's cxx platform does not do this for us. `ImageManager` has a
+// platform variant under `imagemanager/platform/cxx`, and every method in it is
+// a stub that returns an empty `ImageRequest` -- so no `ImageResponse` ever
+// arrives, and `ImageState` never carries anything to render. The platform view
+// is expected to load its own image, which is also what Android does (Fresco,
+// from `ReactImageView`, not from the shadow node).
+//
+// So the mounting manager reads the URI straight off `ImageProps::sources` and
+// asks this to produce a texture.
+//
+// Scheme support:
+//   file://       read from disk
+//   http, https   fetched with libcurl, on a worker thread
+//   data:         decoded inline
+//   bare paths    treated as file paths, which is what a `require()`d asset
+//                 looks like once Metro has resolved it in a release bundle
+//
+// Everything is decoded off the main thread and delivered back onto it, because
+// GdkTexture is cheap to hand around but decoding a large PNG is not something
+// to do in a mount transaction.
+
+#pragma once
+
+#include <gtk/gtk.h>
+
+#include <functional>
+#include <memory>
+#include <string>
+#include <unordered_map>
+
+#include "ImageCache.h"
+
+#include <react/io/IImageLoader.h>
+
+namespace basalt {
+
+// Also React Native's own `IImageLoader`, which is what `Image.getSize` and
+// `Image.prefetch` reach. Upstream's `ImageLoaderModule` takes one and
+// `ReactCxxTurboModuleProvider` never supplies it -- see
+// docs/backlog/upstream.md -- so the host registers the module itself with
+// this as the loader.
+class GtkImageLoader : public facebook::react::IImageLoader {
+ public:
+  // `texture` is null when the load failed, and `error` says why. Always called
+  // on the GTK main thread, possibly synchronously if the image is cached.
+  using Callback = std::function<void(GdkTexture *texture, const std::string &error)>;
+
+  GtkImageLoader();
+  ~GtkImageLoader();
+
+  GtkImageLoader(const GtkImageLoader &) = delete;
+  GtkImageLoader &operator=(const GtkImageLoader &) = delete;
+  GtkImageLoader(GtkImageLoader &&) = delete;
+  GtkImageLoader &operator=(GtkImageLoader &&) = delete;
+
+  void load(const std::string &uri, Callback &&callback);
+
+  // --- IImageLoader ----------------------------------------------------------
+  //
+  // The same decode as `load`, reporting the size rather than the pixels. It
+  // goes through the same cache, so `Image.getSize` on something already on
+  // screen answers without touching the disk or the network.
+  void loadImage(const std::string &uri,
+                 const facebook::react::IImageLoaderOnLoadCallback &&onLoad) override;
+
+  facebook::react::IImageLoader::CacheStatus getCacheStatus(const std::string &uri) override;
+
+ private:
+  struct Pending;
+
+  static gboolean deliver(gpointer data);
+
+  // Decoded textures, keyed by URI. Textures are immutable and shareable, so
+  // two <Image>s with the same source paint the same object.
+  //
+  // Caches a texture and releases whatever the policy dropped.
+  void remember(const std::string &uri, GdkTexture *texture);
+
+  std::unordered_map<std::string, GdkTexture *> cache_;
+  // Which URI goes next, and when. The textures are this class's; the decision
+  // is shared with the other two hosts. See core/ImageCache.h.
+  basalt::ImageCachePolicy policy_;
+};
+
+} // namespace basalt