basalt-win32 0.0.0-rc5

package/native/win32/Win32Focus.cpp

@@ -0,0 +1,262 @@
+#include "Win32Focus.h"
+
+#include "Win32KeyEvents.h"
+
+#include <algorithm>
+#include <optional>
+#include <vector>
+
+#include <folly/dynamic.h>
+
+#include <react/renderer/components/view/ViewEventEmitter.h>
+#include <react/renderer/core/EventEmitter.h>
+
+#include <windows.h>
+
+namespace basalt {
+
+using facebook::react::RawEvent;
+using facebook::react::Tag;
+using win32::RnWin32View;
+
+namespace {
+
+// Everything Tab should stop on, in tree order.
+//
+// Tree order rather than paint order: zIndex changes what is on top and must
+// not change what Tab reaches next, which is what both other hosts' chains do.
+void collectInto(RnWin32View *view, std::vector<RnWin32View *> &stops) {
+  if (view == nullptr || view->hidden()) {
+    return;
+  }
+  if (view->editablePeer() != nullptr || view->focusable()) {
+    stops.push_back(view);
+  }
+  for (RnWin32View *child : view->children()) {
+    collectInto(child, stops);
+  }
+}
+
+} // namespace
+
+Win32FocusManager::Win32FocusManager(Win32MountingManager *mountingManager,
+                                     RnWin32View *surfaceRoot)
+    : mountingManager_(mountingManager), surfaceRoot_(surfaceRoot) {}
+
+void Win32FocusManager::setSurfaceRoot(RnWin32View *surfaceRoot) {
+  surfaceRoot_ = surfaceRoot;
+  // Every tag in the old tree is about to stop existing, so the focus goes with
+  // it -- without an event, because the emitter is going too.
+  focusedTag_ = 0;
+}
+
+std::vector<RnWin32View *> Win32FocusManager::collectStops() const {
+  std::vector<RnWin32View *> stops;
+  collectInto(surfaceRoot_, stops);
+  return stops;
+}
+
+void Win32FocusManager::setFocusedView(RnWin32View *view) {
+  const Tag tag = view == nullptr ? 0 : static_cast<Tag>(view->tag());
+  if (tag == focusedTag_) {
+    return;
+  }
+  const Tag previous = focusedTag_;
+  if (previous != 0) {
+    if (RnWin32View *old = mountingManager_->viewForTag(previous)) {
+      old->setShowsFocusRing(false);
+    }
+  }
+  focusedTag_ = tag;
+  if (previous != 0) {
+    emitFocus(previous, false);
+  }
+  if (view != nullptr) {
+    view->setShowsFocusRing(true);
+    emitFocus(tag, true);
+  }
+}
+
+void Win32FocusManager::emitFocus(Tag tag, bool focused) {
+  const auto emitter = std::dynamic_pointer_cast<const facebook::react::ViewEventEmitter>(
+      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.
+  if (focused) {
+    emitter->onFocus();
+  } else {
+    emitter->onBlur();
+  }
+}
+
+void Win32FocusManager::textInputTookFocus() {
+  // A field's peer is a real window and holds real Win32 focus; a view's ring
+  // is this project's own idea of focus. Only one of the two can be true, and
+  // the peer reports its own onFocus, so this just gives up the ring.
+  setFocusedView(nullptr);
+}
+
+bool Win32FocusManager::moveFocus(bool forward) {
+  const std::vector<RnWin32View *> stops = collectStops();
+  if (stops.empty()) {
+    return false;
+  }
+
+  // Where focus is now. A <TextInput> holds it through its peer and reports no
+  // tag, so both kinds of stop have to be recognised.
+  const HWND focusedWindow = GetFocus();
+  std::size_t index = stops.size();
+  for (std::size_t i = 0; i < stops.size(); i++) {
+    const bool isPeer =
+        stops[i]->editablePeer() != nullptr && stops[i]->editablePeer() == focusedWindow;
+    const bool isView = focusedTag_ != 0 && static_cast<Tag>(stops[i]->tag()) == focusedTag_;
+    if (isPeer || isView) {
+      index = i;
+      break;
+    }
+  }
+
+  std::size_t next = 0;
+  if (index == stops.size()) {
+    next = forward ? 0 : stops.size() - 1;
+  } else if (forward) {
+    next = (index + 1) % stops.size();
+  } else {
+    next = (index + stops.size() - 1) % stops.size();
+  }
+
+  RnWin32View *target = stops[next];
+  if (HWND peer = target->editablePeer()) {
+    // Real Win32 focus for a real window. The ring goes out first: the peer
+    // draws its own focus, and two of them at once would say focus is in two
+    // places.
+    setFocusedView(nullptr);
+    SetFocus(peer);
+    return true;
+  }
+
+  // Taking focus away from a field is the other half of the same rule, and
+  // Windows will not do it on its own: the peer keeps focus until something
+  // else asks for it, and nothing here is a window that can.
+  if (focusedWindow != nullptr && focusedWindow != GetAncestor(focusedWindow, GA_ROOT)) {
+    SetFocus(GetAncestor(focusedWindow, GA_ROOT));
+  }
+  setFocusedView(target);
+  return true;
+}
+
+bool Win32FocusManager::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;
+}
+
+namespace {
+
+// The ancestors of `target`, innermost first.
+//
+// Downwards from the root, because a RnWin32View has no parent pointer -- the
+// same reason win32/Win32DropTarget.cpp walks down to find a drop target's
+// ancestry. Two near-identical walks in two files is a smell; they stay apart
+// because that one collects views from a view and this one collects tags from a
+// tag, and merging them would mean a shared header for seventeen lines. A third
+// caller should merge all three.
+bool tagPathTo(win32::RnWin32View *view,
+               facebook::react::Tag target,
+               std::vector<facebook::react::Tag> &path) {
+  if (view == nullptr) {
+    return false;
+  }
+  path.push_back(static_cast<facebook::react::Tag>(view->tag()));
+  if (static_cast<facebook::react::Tag>(view->tag()) == target) {
+    return true;
+  }
+  for (win32::RnWin32View *child : view->children()) {
+    if (tagPathTo(child, target, path)) {
+      return true;
+    }
+  }
+  path.pop_back();
+  return false;
+}
+
+} // namespace
+
+bool Win32FocusManager::handleDeclaredKey(unsigned int virtualKey) {
+  // Almost every app claims nothing and presses plenty.
+  if (handledKeyViewCount() == 0) {
+    return false;
+  }
+  const std::optional<KeyCombination> pressed = keyCombinationFrom(virtualKey);
+  if (!pressed.has_value()) {
+    return false;
+  }
+  return deliverTestKey(*pressed);
+}
+
+bool Win32FocusManager::deliverTestKey(const KeyCombination &pressed) {
+  // Root-first from the walk, so reversed to put the focused view first and let
+  // the innermost claim win -- the order core/KeyEvents.h expects.
+  std::vector<facebook::react::Tag> path;
+  if (focusedTag_ != 0) {
+    tagPathTo(surfaceRoot_, focusedTag_, path);
+    std::reverse(path.begin(), path.end());
+  } else if (surfaceRoot_ != nullptr) {
+    // Nothing focused. The root is still a candidate: a window-level shortcut
+    // holder is the common case and would otherwise never be asked.
+    path.push_back(static_cast<facebook::react::Tag>(surfaceRoot_->tag()));
+  }
+
+  std::optional<facebook::react::Tag> handler = handledBy(path, pressed);
+  if (!handler.has_value() && focusedTag_ == 0) {
+    // See the AppKit host and core/KeyEvents.h.
+    handler = handledByAny(pressed);
+  }
+  if (!handler.has_value()) {
+    return false;
+  }
+  reportKey(*handler, pressed);
+  return true;
+}
+
+bool Win32FocusManager::handleKeyDown(unsigned int virtualKey) {
+  switch (virtualKey) {
+    case VK_TAB:
+      // Shift-Tab goes backwards. GetKeyState rather than a message parameter,
+      // because WM_KEYDOWN carries no modifier state of its own.
+      return moveFocus((GetKeyState(VK_SHIFT) & 0x8000) == 0);
+    case VK_RETURN:
+    case VK_SPACE:
+      // Only when something is focused. Otherwise the key goes on, so a window
+      // with no focus does not swallow it.
+      return activateFocused();
+    default:
+      return false;
+  }
+}
+
+} // namespace basalt

package/native/win32/Win32Focus.h

@@ -0,0 +1,109 @@
+// Keyboard focus, for everything that is not a <TextInput>.
+//
+// Deliberately the same shape as basalt-gtk's GtkFocusManager and
+// the AppKit one, down to what makes a view focusable and what activating one
+// dispatches, because none of that is about the toolkit: if the three diverge,
+// an app's buttons will be reachable from the keyboard on some desktops and not
+// others.
+//
+// ## 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, and what a screen reader already
+// stops on.
+//
+// ## What activating one does
+//
+// Dispatches `topClick` with an empty payload, which is 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.
+//
+// ## The chain, all of which is here
+//
+// The other two desktops have something to start from. GTK hands over its focus
+// chain outright; AppKit has a key-view loop that turned out to be unusable for
+// a window built without a nib, but at least has a first responder to ask about.
+// Here a React Native view is not a window at all -- it is a C++ object painted
+// with Direct2D -- so there is nothing for Windows to focus and nothing to ask.
+// The order, the current stop, the ring and the key handling are all this file's.
+//
+// The exception is a <TextInput>, whose peer *is* a real child window. Focus
+// there is Win32 focus, moved with SetFocus and reported by EN_SETFOCUS, so a
+// field is a stop in the same order as the buttons around it and the two kinds
+// of focus have to be kept from being held at once.
+
+#pragma once
+
+#include "KeyEvents.h"
+
+#include "RnWin32View.h"
+#include "Win32MountingManager.h"
+
+#include <vector>
+
+namespace basalt {
+
+class Win32FocusManager {
+ public:
+  Win32FocusManager(Win32MountingManager *mountingManager, win32::RnWin32View *surfaceRoot);
+
+  Win32FocusManager(const Win32FocusManager &) = delete;
+  Win32FocusManager &operator=(const Win32FocusManager &) = delete;
+  Win32FocusManager(Win32FocusManager &&) = delete;
+  Win32FocusManager &operator=(Win32FocusManager &&) = delete;
+
+  // The surface root can be replaced after a surface restart; every tag in the
+  // old tree goes with it.
+  void setSurfaceRoot(win32::RnWin32View *surfaceRoot);
+
+  // Moves focus to the next or previous stop, wrapping, and reports whether
+  // anything took it.
+  bool moveFocus(bool forward);
+
+  // Activates whatever has focus, as Enter or space does.
+  bool activateFocused();
+
+  // WM_KEYDOWN, from the host's window procedure. True when the key was used,
+  // which is what keeps Tab from also reaching whatever else might want it.
+  bool handleKeyDown(unsigned int virtualKey);
+
+  // An app's own declared shortcuts, asked before the platform's own keys. True
+  // when a view from the focused one outwards claimed this combination, in which
+  // case it has already been reported; see core/KeyEvents.h.
+  bool handleDeclaredKey(unsigned int virtualKey);
+
+  // BASALT_TEST_KEY. The same delivery a real press gets, minus the virtual-key
+  // translation, which tests/test_win32_key_events.cpp covers instead. Named as
+  // the other two hosts name it, so the three read alike. See core/TestKeys.h.
+  bool deliverTestKey(const KeyCombination &pressed);
+
+  // Called when a <TextInput>'s peer takes Win32 focus, so that a view holding
+  // the ring gives it up. The two kinds of focus are different mechanisms and
+  // only one of them can be true at a time.
+  void textInputTookFocus();
+
+  // The tag of the focused view, or 0. Zero while a <TextInput> holds focus:
+  // that is the peer's, and the peer reports its own onFocus.
+  facebook::react::Tag focusedTag() const { return focusedTag_; }
+
+ private:
+  // Everything Tab should stop on, in tree order. Rebuilt per move rather than
+  // cached: views arrive and leave with every mutation, and a stale order is
+  // worse than a walk of a tree that is already in memory.
+  std::vector<win32::RnWin32View *> collectStops() const;
+
+  void setFocusedView(win32::RnWin32View *view);
+  void emitFocus(facebook::react::Tag tag, bool focused);
+
+  Win32MountingManager *mountingManager_;
+  win32::RnWin32View *surfaceRoot_;
+  facebook::react::Tag focusedTag_{0};
+};
+
+} // namespace basalt

package/native/win32/Win32ImageLoader.cpp

@@ -0,0 +1,167 @@
+#include "Win32ImageLoader.h"
+
+#include "ImageBytes.h"
+#include "PlatformServices.h"
+#include "Win32UiThread.h"
+
+#include <cstdint>
+#include <thread>
+#include <utility>
+
+namespace basalt::win32 {
+
+using basalt::hasUiThread;
+using basalt::postToUiThread;
+
+Win32ImageLoader::Win32ImageLoader() : state_(std::make_shared<State>()) {}
+
+Win32ImageLoader::~Win32ImageLoader() {
+  // The state outlives this object whenever a load is in flight. Marking it
+  // dead is what makes the completion a no-op rather than a use-after-free.
+  const std::lock_guard<std::mutex> lock(state_->mutex);
+  state_->alive = false;
+}
+
+void Win32ImageLoader::clearCache() {
+  const std::lock_guard<std::mutex> lock(state_->mutex);
+  state_->cache.clear();
+  state_->policy.clear();
+}
+
+void Win32ImageLoader::load(const std::string &uri, Callback callback) {
+  if (!callback) {
+    return;
+  }
+  if (uri.empty()) {
+    callback(nullptr, "empty uri");
+    return;
+  }
+
+  // Answered synchronously, deliberately: an <Image> whose pixels are already
+  // decoded should not flicker through a frame of nothing on its way back to
+  // the screen. Both other platforms answer a cache hit inline too.
+  {
+    const std::lock_guard<std::mutex> lock(state_->mutex);
+    if (const auto it = state_->cache.find(uri); it != state_->cache.end()) {
+      const auto image = it->second;
+      state_->policy.noteUse(uri);
+      // Outside the lock would be tidier; inside is fine because the callback
+      // never re-enters the loader, and holding it across the call is what
+      // stops a concurrent clearCache from dropping the entry underneath.
+      callback(image, {});
+      return;
+    }
+  }
+
+  // Fetch and decode, and where they run depends on whether there is anywhere
+  // to come back to.
+  const auto work = [uri](std::shared_ptr<RnWin32Image> &image, std::string &error) {
+    std::string bytes;
+    if (!fetchImageBytes(uri, &bytes, &error)) {
+      if (error.empty()) {
+        error = "could not fetch " + uri;
+      }
+      return;
+    }
+    if (bytes.empty()) {
+      error = "no bytes for " + uri;
+      return;
+    }
+    image = RnWin32Image::fromEncodedBytes(
+        reinterpret_cast<const uint8_t *>(bytes.data()), bytes.size());
+    if (image == nullptr) {
+      error = "could not decode " + uri;
+    }
+  };
+
+  auto state = state_;
+  const auto deliver = [state, uri](const std::shared_ptr<RnWin32Image> &image,
+                                    const std::string &error,
+                                    const Callback &callback) {
+    // The loader may have gone while this was in flight -- a surface torn down,
+    // not only the process exiting. The state is still here, which is the point
+    // of it being shared, and there is simply nothing to deliver to.
+    {
+      const std::lock_guard<std::mutex> lock(state->mutex);
+      if (!state->alive) {
+        return;
+      }
+      if (image != nullptr) {
+        state->cache[uri] = image;
+
+        // Four bytes a pixel, premultiplied BGRA, which is what
+        // `fromEncodedBytes` decodes to and what RnWin32Image's own stride
+        // says. See core/ImageCache.h for which URI goes next.
+        const size_t bytes = static_cast<size_t>(image->width()) *
+                             static_cast<size_t>(image->height()) * 4u;
+        for (const std::string &evicted : state->policy.insert(uri, bytes)) {
+          state->cache.erase(evicted);
+        }
+      }
+    }
+    callback(image, error);
+  };
+
+  // No message loop to post back to, so no worker either.
+  //
+  // This is the case the harness and the tests are in, and going asynchronous
+  // anyway would be actively wrong rather than merely pointless:
+  // `postToUiThread` runs its work inline when nothing is installed, so the
+  // completion would run *on the worker* and reach straight into the mounting
+  // manager's registry from the wrong thread. Staying synchronous keeps that
+  // configuration single-threaded, which is what it already assumes everywhere
+  // else.
+  if (!hasUiThread()) {
+    std::shared_ptr<RnWin32Image> image;
+    std::string error;
+    work(image, error);
+    deliver(image, error, callback);
+    return;
+  }
+
+  // With a host, both halves go to a worker. GTK reads on a worker and decodes
+  // back on the main thread, because a GdkTexture is a GObject and the
+  // expensive part there is the read; WIC has neither constraint -- its factory
+  // is agile and the decode is the expensive part -- so the whole job leaves
+  // the UI thread and only the delivery comes back.
+  //
+  // Detached rather than joined: nothing waits for an image, and everything the
+  // thread touches is either its own or the shared state above.
+  std::thread([work, deliver, callback = std::move(callback)]() mutable {
+    std::shared_ptr<RnWin32Image> image;
+    std::string error;
+    work(image, error);
+    postToUiThread([deliver, image, error, callback = std::move(callback)]() {
+      deliver(image, error, callback);
+    });
+  }).detach();
+}
+
+
+void Win32ImageLoader::loadImage(const std::string &uri,
+                                 const facebook::react::IImageLoaderOnLoadCallback &&onLoad) {
+  // Copied because the callback may outlive this call, as it does on the other
+  // two hosts; here a cache hit answers inline, and a miss does not.
+  auto callback = onLoad;
+  load(uri, [callback](std::shared_ptr<RnWin32Image> image, const std::string &error) {
+    if (image == 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>(image->width()), static_cast<double>(image->height()), nullptr);
+  });
+}
+
+facebook::react::IImageLoader::CacheStatus Win32ImageLoader::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.
+  const std::lock_guard<std::mutex> lock(state_->mutex);
+  return state_->cache.find(uri) != state_->cache.end()
+      ? facebook::react::IImageLoader::CacheStatus::Memory
+      : facebook::react::IImageLoader::CacheStatus::None;
+}
+
+} // namespace basalt::win32

package/native/win32/Win32ImageLoader.h

@@ -0,0 +1,104 @@
+// The pixels behind an <Image>, fetched and decoded off the UI thread.
+//
+// React Native's cxx `ImageManager` is a stub -- `requestImage` returns an
+// `ImageRequest` with no observer coordinator, so no `ImageResponse` ever
+// arrives and `ImageState` never carries anything to render. The platform view
+// is expected to load its own pixels, which is what Android does too, from
+// `ReactImageView` rather than from the shadow node. `docs/DECISIONS.md` records
+// the same conclusion for GTK.
+//
+// Two rules fall out of the lifetimes, and both are the reason this is a class
+// rather than a function.
+//
+// **A load must survive the view that asked for it.** A view can be deleted
+// while its bytes are still in flight, so the completion may not capture a
+// view; the mounting manager looks the tag up again when it runs. That is the
+// same arrangement GTK settled on.
+//
+// **A load must survive the loader.** The worker thread and the queued
+// completion both outlive any particular call, and a mounting manager can be
+// destroyed between the two -- which happens on surface teardown, not only at
+// exit. So the cache lives in a shared state object that the in-flight work
+// holds a reference to, and a completion arriving after the loader is gone
+// finds the state alive and the callback already neutered. The AppKit loader
+// captures its `this` raw and has the bug this avoids.
+
+#pragma once
+
+#include "RnWin32Image.h"
+
+#include <functional>
+#include <mutex>
+#include <memory>
+#include <string>
+#include <unordered_map>
+
+#include "ImageCache.h"
+
+#include <react/io/IImageLoader.h>
+
+namespace basalt::win32 {
+
+// 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 Win32ImageLoader : public facebook::react::IImageLoader {
+ public:
+  // `image` is null when the load failed, and `error` says why. Always called
+  // on the UI thread, and possibly before `load` has returned -- a cache hit is
+  // answered synchronously, because making it asynchronous would mean an
+  // <Image> that is already decoded still flickers through a frame of nothing.
+  using Callback = std::function<void(std::shared_ptr<RnWin32Image> image,
+                                      const std::string &error)>;
+
+  Win32ImageLoader();
+  ~Win32ImageLoader();
+
+  Win32ImageLoader(const Win32ImageLoader &) = delete;
+  Win32ImageLoader &operator=(const Win32ImageLoader &) = 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;
+
+  // Drops every decoded image at once, for a host shutting a surface down.
+  // Ordinary eviction is core/ImageCache.h's, which runs on every insert.
+  void clearCache();
+
+ private:
+  struct State {
+    // Locked, rather than relying on "everything happens on the UI thread".
+    //
+    // That reasoning was tried and is wrong here in a way worth recording,
+    // because it looks right: `load` is called on the UI thread and every
+    // completion is posted back to it, so a lock seems redundant. But
+    // `postToUiThread` runs its work *inline* when no host has installed a
+    // message loop, and inline on a worker thread is not the UI thread. The
+    // load below avoids that case entirely by not spawning a worker when there
+    // is nothing to marshal back to; this lock is the belt to that pair of
+    // braces, and it costs a hash lookup's worth of nothing.
+    std::mutex mutex;
+    std::unordered_map<std::string, std::shared_ptr<RnWin32Image>> cache;
+    // Which URI goes next, and when. Shared with the other two hosts; the
+    // images are this loader's. See core/ImageCache.h. Guarded by the mutex
+    // beside it, like the cache it decides for.
+    basalt::ImageCachePolicy policy;
+    // Cleared when the loader is destroyed, so a completion that outlives it
+    // delivers nowhere instead of into freed memory.
+    bool alive = true;
+  };
+
+  std::shared_ptr<State> state_;
+};
+
+} // namespace basalt::win32