basalt-core 0.0.0-rc5 → 0.2.0

package/native/core/ImageAnimation.h

@@ -0,0 +1,109 @@
+// Which frame an animated image is showing, and when the next one is due.
+//
+// A GIF carries a delay per frame and a loop count, and every platform hands
+// those over differently: ImageIO answers `CGImageSourceGetCount` and a
+// per-frame dictionary, WIC the same through its metadata reader, gdk-pixbuf
+// nothing at all -- it owns the timing itself behind `GdkPixbufAnimationIter`
+// and offers no indexed access to frames. So this file holds the part that is
+// the same wherever the frames come from: the clamp, and the arithmetic from
+// elapsed time to a frame index.
+//
+// The GTK host uses only the clamp, and asks gdk-pixbuf for the rest. It is
+// still worth sharing, because an animation driven by the platform's own clock
+// is one a test has to wait for, and a test that waits for a GIF is a test that
+// is slow and flaky at once. Both hosts advance their animation from an elapsed
+// time the caller supplies, which is what makes "150 milliseconds later" a
+// thing a suite can say.
+//
+// ## The clamp, which is the browsers' rule rather than the format's
+//
+// A GIF may ask for a delay of zero, and a great many do: in the format's own
+// terms that means "as fast as the hardware can", which in 1989 meant a
+// perceptible speed and now means a thousand frames a second. Every browser
+// refuses, and they refuse the same way: a delay at or below 10 milliseconds
+// becomes 100. The number is not arbitrary -- 100ms is the delay the oldest
+// authoring tools wrote by default, so it is what those files were drawn for.
+//
+// Chrome, Firefox and Safari all apply it, which is the reason to copy it
+// rather than invent one: an app author compares against a browser or against
+// React Native on a phone, and the phone is doing this too.
+//
+// ## Loop counts
+//
+// Zero means forever, which is the common case and what the NETSCAPE2.0
+// extension writes for a looping GIF. A positive count means that many passes
+// and then a stop, and the frame it stops on is the last one, not the first:
+// the final frame is what the animation was drawn to end on. A single frame, or
+// no frames at all, is finished before it starts.
+
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <vector>
+
+namespace basalt {
+
+// A delay of 10ms or less means 100ms. See the note above.
+inline unsigned clampedImageFrameDelay(unsigned delayMs) {
+  return delayMs <= 10U ? 100U : delayMs;
+}
+
+struct ImageAnimationStep {
+  // Which frame to show, always a valid index when there is at least one.
+  std::size_t frame{0};
+  // How long until the frame changes. Zero when nothing more is due, which is
+  // what a host uses to stop ticking.
+  unsigned nextInMs{0};
+  // Nothing more will change: one frame, or the last loop is over.
+  bool finished{true};
+};
+
+// `delaysMs` is one raw delay per frame, as the file carries it; the clamp is
+// applied here so no caller has to remember to. `loopCount` is zero for
+// forever. `elapsedMs` is how long the image has been animating, which the
+// caller accumulates from its own clock rather than reading one here -- see the
+// note above.
+inline ImageAnimationStep imageAnimationStep(const std::vector<unsigned> &delaysMs,
+                                             unsigned loopCount,
+                                             std::uint64_t elapsedMs) {
+  ImageAnimationStep step;
+  if (delaysMs.size() < 2) {
+    return step;
+  }
+
+  std::uint64_t cycle = 0;
+  for (const unsigned delay : delaysMs) {
+    cycle += clampedImageFrameDelay(delay);
+  }
+  if (cycle == 0) {
+    return step;
+  }
+
+  // The last frame, left showing. A count that has run out is the only way an
+  // animation ends, and it ends on what it was drawn to end on.
+  if (loopCount > 0 && elapsedMs >= cycle * loopCount) {
+    step.frame = delaysMs.size() - 1;
+    return step;
+  }
+
+  std::uint64_t into = elapsedMs % cycle;
+  for (std::size_t index = 0; index < delaysMs.size(); index++) {
+    const unsigned delay = clampedImageFrameDelay(delaysMs[index]);
+    if (into < delay) {
+      step.frame = index;
+      step.nextInMs = static_cast<unsigned>(delay - into);
+      step.finished = false;
+      return step;
+    }
+    into -= delay;
+  }
+
+  // Unreachable: `into` is less than the cycle, and the loop above subtracts
+  // the whole cycle. Answering with the last frame rather than asserting,
+  // because a wrong frame is better than a dead window.
+  step.frame = delaysMs.size() - 1;
+  return step;
+}
+
+} // namespace basalt

package/native/core/ImageBytes.cpp

@@ -101,7 +101,10 @@ bool readFile(const std::string &path, std::string *out, std::string *error) {
 
 } // namespace
 
-bool fetchImageBytes(const std::string &uri, std::string *out, std::string *error) {
+bool fetchImageBytes(const std::string &uri,
+                     std::string *out,
+                     std::string *error,
+                     const ImageProgress &onProgress) {
   out->clear();
 
   if (uri.empty()) {
@@ -143,6 +146,30 @@ bool fetchImageBytes(const std::string &uri, std::string *out, std::string *erro
     // Without this, libcurl installs a SIGALRM-based resolver timeout that is
     // not safe to use off the main thread.
     curl_easy_setopt(handle, CURLOPT_NOSIGNAL, 1L);
+
+    // `<Image onProgress>`. Only wired when somebody asked: libcurl's default
+    // is no progress callback at all, and turning it on for every fetch would
+    // be work for the overwhelming majority of images, which are small and
+    // local.
+    //
+    // XFERINFOFUNCTION rather than PROGRESSFUNCTION, which is the same callback
+    // with doubles and deprecated since 7.32. Returning non-zero aborts the
+    // transfer, so this returns zero whatever the callback does.
+    if (onProgress) {
+      curl_easy_setopt(handle, CURLOPT_NOPROGRESS, 0L);
+      curl_easy_setopt(handle, CURLOPT_XFERINFODATA, &onProgress);
+      curl_easy_setopt(
+          handle,
+          CURLOPT_XFERINFOFUNCTION,
+          +[](void *data, curl_off_t total, curl_off_t now, curl_off_t, curl_off_t) -> int {
+            const auto *report = static_cast<const ImageProgress *>(data);
+            if (report != nullptr && *report) {
+              (*report)(static_cast<long long>(now), static_cast<long long>(total));
+            }
+            return 0;
+          });
+    }
+
     const CURLcode result = curl_easy_perform(handle);
     long status = 0;
     curl_easy_getinfo(handle, CURLINFO_RESPONSE_CODE, &status);

package/native/core/ImageBytes.h

@@ -11,6 +11,7 @@
 
 #pragma once
 
+#include <functional>
 #include <string>
 
 namespace basalt {
@@ -22,8 +23,23 @@ namespace basalt {
 //   bare paths    treated as file paths, which is what a `require()`d asset
 //                 looks like once Metro has resolved it in a release bundle
 //
+// How much of an http fetch has arrived, which is what `<Image onProgress>`
+// reports. `total` is zero when the server sent no `Content-Length`, which is
+// not an error and is why it is passed on rather than turned into a fraction
+// here: an app showing a bar needs to know the difference between "half way"
+// and "no idea".
+//
+// Called from the fetching thread, repeatedly, and never after the fetch has
+// returned. Only an http or https URI reports anything: a file or a data URI
+// arrives whole, and inventing a 0% and a 100% for them would be reporting
+// progress that never existed.
+using ImageProgress = std::function<void(long long loaded, long long total)>;
+
 // Blocking, so call it off the thread that draws. Returns false and fills
 // `error` on failure, in which case `out` is left empty.
-bool fetchImageBytes(const std::string &uri, std::string *out, std::string *error);
+bool fetchImageBytes(const std::string &uri,
+                     std::string *out,
+                     std::string *error,
+                     const ImageProgress &onProgress = {});
 
 } // namespace basalt

package/native/core/ImageProgress.h

@@ -0,0 +1,85 @@
+// Which bytes of an image fetch are worth telling JavaScript about.
+//
+// `<Image onProgress>` is a prop an app writes to draw a bar, and the bytes
+// behind it arrive on libcurl's clock: `CURLOPT_XFERINFOFUNCTION` is called
+// roughly every time a socket read returns, which for a megabyte over a fast
+// link is thousands of times. Every one of those would be a Fabric event, a
+// JavaScript call and a React render, for a bar whose width is measured in
+// pixels and cannot show the difference.
+//
+// So the ticks are gated here, on whole percentages: a hundred events over a
+// download, which is more than a bar can resolve and few enough to be free.
+// The gate is in core rather than in each host's mounting manager because all
+// three mean the same thing by it, and because this way it is a thing a test
+// can say something about -- the hosts' half is a lookup and a lambda, and the
+// arithmetic is here.
+//
+// Two cases that are not a percentage, and both are real:
+//
+// **No `Content-Length`.** A chunked response has no total, which is not an
+// error: libcurl reports a growing `loaded` against a zero `total` and the
+// event carries both, so an app can show bytes where it cannot show a
+// fraction. There is nothing to throttle against, so every tick is reported.
+// Turning it into a fraction here -- against the bytes so far, say -- would be
+// inventing a denominator and would read as a bar that is always nearly full.
+//
+// **libcurl's opening tick.** The callback fires once before the response
+// headers have been read, with nothing loaded and nothing known. That one says
+// neither how much has arrived nor how much will, so it is not an event; an app
+// that sees it would show a zero-of-zero bar before the request had even been
+// answered.
+
+#pragma once
+
+#include <optional>
+
+namespace basalt {
+
+// One fetch's worth of gating. Belongs to the load it was made for, and is
+// called only from the thread doing that fetch -- which is why it needs no
+// lock: libcurl calls its progress function from the thread inside
+// `curl_easy_perform`, and that is one thread per handle.
+class ImageProgressTicker {
+ public:
+  // The fraction to report, or nothing when this tick is not worth an event.
+  //
+  // `loaded` and `total` are bytes, as libcurl counts them. A `total` of zero
+  // or less means the server did not say; see the note above.
+  std::optional<double> tick(long long loaded, long long total) {
+    if (loaded <= 0 && total <= 0) {
+      // Nothing arrived and nothing is known. See the note above.
+      return std::nullopt;
+    }
+    if (total <= 0) {
+      // Indeterminate: the event still carries `loaded` and a zero `total`,
+      // and the fraction is the only thing that cannot be answered.
+      return 0.0;
+    }
+    if (loaded < 0) {
+      loaded = 0;
+    }
+    if (loaded > total) {
+      // A server that sent more than it promised. Clamped rather than passed
+      // on, so an app drawing `progress * width` cannot overrun its bar.
+      loaded = total;
+    }
+
+    const int percent = static_cast<int>(loaded * 100 / total);
+    if (percent == reported_) {
+      return std::nullopt;
+    }
+    reported_ = percent;
+    return static_cast<double>(loaded) / static_cast<double>(total);
+  }
+
+  // Which whole percentage was last reported, or -1 before the first tick.
+  // For the tests; the hosts have no use for it.
+  int reportedPercent() const {
+    return reported_;
+  }
+
+ private:
+  int reported_{-1};
+};
+
+} // namespace basalt

package/native/core/LabelRegistry.h

@@ -0,0 +1,189 @@
+// Which view a `nativeID` names, and which views are waiting on one.
+//
+// `accessibilityLabelledBy` names other views by their `nativeID` -- "the label
+// for this field is that text over there" -- and nothing else in this project
+// needs to look a view up that way: the registry in core/MountingWalk.h is keyed
+// by tag, and the drag-and-drop code walks *up* from a hit test rather than
+// searching for an id. So this is the missing half, and it is shared because
+// both hosts need exactly the same bookkeeping and the ordering problem below is
+// not host-specific at all.
+//
+// ## The ordering problem
+//
+// A view can name an id that does not exist yet. Fabric mounts in tree order, so
+// a field labelled by the text *after* it is mounted before its label, and a
+// resolution done once at mount time would find nothing and stay wrong. The
+// relation also has to come apart again: a label that is unmounted leaves a
+// dangling reference, and a screen reader following it would read a view that is
+// no longer on screen.
+//
+// So this holds both sides and answers which relations have *changed*, which is
+// what a host applies. Asking after every transaction is cheap and is right
+// whatever order things mounted in.
+//
+// ## Two relations, one index
+//
+// `experimental_accessibilityOrder` asks the same question in a different
+// direction: a parent lists its children's `nativeID`s in the order a screen
+// reader should read them. Same bookkeeping, same ordering problem, same need
+// to report only what changed -- and the same `nativeID` index, which is why it
+// is here rather than in a second class. Two classes would mean two answers to
+// "which view is called that", and they would disagree the first time a view
+// changed its id.
+//
+// Header-only, like core/Backface.h, and free of React Native: it takes tags and
+// strings.
+
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+namespace basalt {
+
+class LabelRegistry {
+ public:
+  using Tag = std::int32_t;
+
+  // One view's relation, resolved: the tags its `accessibilityLabelledBy` ids
+  // name, in the order the app wrote them, and empty when none of them resolve.
+  struct Resolved {
+    Tag tag;
+    std::vector<Tag> labels;
+  };
+
+  // This view's `nativeID`. Empty forgets it, which is what a view that drops
+  // the prop means.
+  void setNativeId(Tag tag, const std::string &nativeId) {
+    const auto previous = nativeIdOf_.find(tag);
+    if (previous != nativeIdOf_.end()) {
+      if (previous->second == nativeId) {
+        return;
+      }
+      // Only if it is still ours: two views with the same nativeID is an app
+      // bug, and the second one to claim it owns it until it goes away.
+      const auto owner = tagOfNativeId_.find(previous->second);
+      if (owner != tagOfNativeId_.end() && owner->second == tag) {
+        tagOfNativeId_.erase(owner);
+      }
+      nativeIdOf_.erase(previous);
+    }
+    if (nativeId.empty()) {
+      return;
+    }
+    nativeIdOf_[tag] = nativeId;
+    tagOfNativeId_[nativeId] = tag;
+  }
+
+  // This view's `accessibilityLabelledBy`. Empty forgets it.
+  void setLabelledBy(Tag tag, std::vector<std::string> ids) {
+    if (ids.empty()) {
+      labelledBy_.erase(tag);
+      return;
+    }
+    labelledBy_[tag] = std::move(ids);
+  }
+
+  // This view's `experimental_accessibilityOrder`: the ids of its children, in
+  // the order they should be read. Empty forgets it.
+  void setAccessibilityOrder(Tag tag, std::vector<std::string> ids) {
+    if (ids.empty()) {
+      order_.erase(tag);
+      return;
+    }
+    order_[tag] = std::move(ids);
+  }
+
+  // A view that has gone away, on either side of either relation.
+  void forget(Tag tag) {
+    setNativeId(tag, "");
+    labelledBy_.erase(tag);
+    applied_.erase(tag);
+    order_.erase(tag);
+    appliedOrder_.erase(tag);
+  }
+
+  // Nothing to ask about: no view wants a relation, and none has one applied.
+  //
+  // Both halves matter. A host that checked only the first would skip the
+  // transaction in which the last relation went away, and the relation it had
+  // already applied would stay on the widget for the rest of the screen's life.
+  bool empty() const {
+    return labelledBy_.empty() && applied_.empty() && order_.empty()
+        && appliedOrder_.empty();
+  }
+
+  // The relations whose resolution has changed since the last call, and nothing
+  // else: applying an unchanged relation again would tell assistive technology
+  // that something happened when nothing did.
+  //
+  // An id that names no view yet resolves to nothing, and the view is reported
+  // again when the id turns up. A relation whose labels have all gone away is
+  // reported with an empty list, which is a host's cue to reset it.
+  std::vector<Resolved> changes() { return changesOf(labelledBy_, applied_, true); }
+
+  // The reading orders whose resolution has changed, on the same terms.
+  //
+  // An id that names nothing is dropped rather than skipping the whole order: a
+  // parent that lists four children and has three mounted should read those
+  // three in the order it gave, and take the fourth when it arrives.
+  std::vector<Resolved> orderChanges() { return changesOf(order_, appliedOrder_, false); }
+
+ private:
+  // `excludeSelf` is the difference between the two relations rather than an
+  // option: a view labelled by itself is an app bug worth ignoring, and a
+  // parent is never in its own reading order anyway, so for an order the test
+  // would only cost a comparison per id.
+  std::vector<Resolved> changesOf(
+      const std::unordered_map<Tag, std::vector<std::string>> &wanted,
+      std::unordered_map<Tag, std::vector<Tag>> &applied,
+      bool excludeSelf) {
+    std::vector<Resolved> changed;
+    for (const auto &[tag, ids] : wanted) {
+      std::vector<Tag> labels;
+      labels.reserve(ids.size());
+      for (const std::string &id : ids) {
+        const auto found = tagOfNativeId_.find(id);
+        if (found != tagOfNativeId_.end() && (!excludeSelf || found->second != tag)) {
+          labels.push_back(found->second);
+        }
+      }
+      const auto previous = applied.find(tag);
+      if (previous != applied.end() && previous->second == labels) {
+        continue;
+      }
+      applied[tag] = labels;
+      changed.push_back(Resolved{tag, std::move(labels)});
+    }
+
+    // A view that stopped asking: its relation was applied and is no longer
+    // wanted, so it is reported empty once and then forgotten.
+    for (auto it = applied.begin(); it != applied.end();) {
+      if (wanted.find(it->first) != wanted.end()) {
+        ++it;
+        continue;
+      }
+      if (!it->second.empty()) {
+        changed.push_back(Resolved{it->first, {}});
+      }
+      it = applied.erase(it);
+    }
+    return changed;
+  }
+
+  std::unordered_map<Tag, std::string> nativeIdOf_;
+  std::unordered_map<std::string, Tag> tagOfNativeId_;
+  std::unordered_map<Tag, std::vector<std::string>> labelledBy_;
+  // What each view's relation was last reported as, so an unchanged one is not
+  // reported twice.
+  std::unordered_map<Tag, std::vector<Tag>> applied_;
+  // The second relation: which children a view wants read, and what that was
+  // last reported as.
+  std::unordered_map<Tag, std::vector<std::string>> order_;
+  std::unordered_map<Tag, std::vector<Tag>> appliedOrder_;
+};
+
+} // namespace basalt

package/native/core/LegacyShadow.h

@@ -0,0 +1,90 @@
+// The four iOS shadow props, as the CSS box shadow they describe.
+//
+// `shadowColor`, `shadowOffset`, `shadowOpacity` and `shadowRadius` are React
+// Native's older spelling of a drop shadow, and they are everywhere in real
+// apps: every card, sheet and floating button written before `boxShadow`
+// existed sets them. They are also iOS-only. Android's view config does not
+// carry them, so on Android they do nothing at all and `elevation` is used
+// instead.
+//
+// ## The decision this header is
+//
+// These hosts honour them, rather than ignoring them as Android does. Two
+// reasons. The AppKit host is macOS, where react-native-macos honours them for
+// the same reason its iOS parent does -- the props describe a `CALayer` shadow
+// and the layer is right there. And a cross-platform app that asks for a shadow
+// means the shadow: dropping it on a desktop host would be a deliberate
+// difference from what the app's author saw, which is not what "ignored on this
+// platform" should mean on a platform that can draw it.
+//
+// They are converted here rather than drawn, so both hosts get one shadow list
+// and neither has a second shadow mechanism. What arrives is a `BoxShadow` with
+// CSS's meaning, which both view layers already know how to paint.
+//
+// ## The two conversions that are not identity
+//
+// `shadowRadius` is a `CALayer` blur radius, which is a gaussian standard
+// deviation; CSS's blur-radius is twice that. So the blur doubles, which is the
+// same factor each host already uses in the other direction when it hands a CSS
+// blur to its own compositor -- see the box shadow tests on both.
+//
+// `shadowOpacity` multiplies the colour's own alpha, as `CALayer.shadowOpacity`
+// does on top of `shadowColor`. An opacity of zero is iOS's default and means no
+// shadow, which is why nothing is produced for it.
+//
+// Both props keep their defaults from `BaseViewProps` -- offset (0, -3) and
+// radius 3 -- so a view that sets only `shadowColor` and `shadowOpacity` gets
+// the shadow iOS would give it.
+
+#pragma once
+
+#include <react/renderer/components/view/BaseViewProps.h>
+#include <react/renderer/graphics/BoxShadow.h>
+
+#include <optional>
+#include <vector>
+
+namespace basalt {
+
+// The shadow the four legacy props ask for, or nothing when they ask for none.
+inline std::optional<facebook::react::BoxShadow> legacyShadow(
+    const facebook::react::BaseViewProps &props) {
+  if (props.shadowOpacity <= 0.0 || !props.shadowColor) {
+    return std::nullopt;
+  }
+  facebook::react::ColorComponents components =
+      facebook::react::colorComponentsFromColor(props.shadowColor);
+  if (components.alpha <= 0.0F) {
+    return std::nullopt;
+  }
+  components.alpha *= static_cast<float>(props.shadowOpacity);
+  if (components.alpha > 1.0F) {
+    components.alpha = 1.0F;
+  }
+
+  facebook::react::BoxShadow shadow;
+  shadow.offsetX = props.shadowOffset.width;
+  shadow.offsetY = props.shadowOffset.height;
+  // A CALayer blur radius is a standard deviation; CSS's is twice one.
+  shadow.blurRadius = props.shadowRadius * 2;
+  shadow.spreadDistance = 0;
+  shadow.color = facebook::react::colorFromComponents(components);
+  shadow.inset = false;
+  return shadow;
+}
+
+// Every shadow a view casts, in CSS's order: first in the list is the one on
+// top. `boxShadow` comes first and the legacy shadow goes behind all of it,
+// which is both what iOS does -- the layer's own shadow is behind the extra
+// layers React Native adds for `boxShadow` -- and the only order where adding a
+// `boxShadow` to an old component cannot be hidden by the shadow it already had.
+inline std::vector<facebook::react::BoxShadow> allShadows(
+    const facebook::react::BaseViewProps &props) {
+  std::vector<facebook::react::BoxShadow> shadows = props.boxShadow;
+  if (const std::optional<facebook::react::BoxShadow> legacy = legacyShadow(props)) {
+    shadows.push_back(*legacy);
+  }
+  return shadows;
+}
+
+} // namespace basalt

package/native/core/LiveRegions.h

@@ -0,0 +1,114 @@
+// Which views are live regions, and what each of them last said.
+//
+// `accessibilityLiveRegion` is the prop for a status message: "saved", "three
+// results", "offline". It does not change how a view looks or what it reports
+// when a screen reader lands on it -- it asks for the new text to be *read out*
+// when it changes, without the reader being there. Neither toolkit models that
+// as a property of a view: GTK has `gtk_accessible_announce` and AppKit an
+// `NSAccessibilityAnnouncementRequested` notification, both of which happen at a
+// moment rather than being set.
+//
+// So honouring the prop is change detection, and that is what this holds: the
+// politeness each live region asked for, and the last thing each one said. A
+// host collects a region's current text after a transaction and asks here
+// whether that is news.
+//
+// ## Two rules that are the whole of it
+//
+// **The first text is not news.** Mounting a status line should not read it out:
+// nothing changed, the screen just appeared. So the first text a region is seen
+// with is remembered silently, and only a later difference is announced. Getting
+// this wrong is loud -- every screen with a status message would announce itself
+// on arrival.
+//
+// **The same text twice is not news either.** A view re-renders for every reason
+// under the sun, and React Native re-sends identical props on each mutation; a
+// region that announced on every transaction would talk over everything else in
+// the application.
+//
+// Header-only, like core/LabelRegistry.h, which solves the sibling problem for
+// `accessibilityLabelledBy`. It takes React Native's own politeness enum rather
+// than a copy of it: both mounting managers already know React Native, and a
+// second three-value enum with a mapping either side of it is two more places to
+// put `Polite` where `Assertive` belongs.
+
+#pragma once
+
+#include <react/renderer/components/view/AccessibilityPrimitives.h>
+
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+namespace basalt {
+
+using LiveRegionPoliteness = facebook::react::AccessibilityLiveRegion;
+
+class LiveRegionRegistry {
+ public:
+  using Tag = std::int32_t;
+
+  // This view's `accessibilityLiveRegion`. `None` forgets it, which is what a
+  // view that drops the prop means.
+  void setPoliteness(Tag tag, LiveRegionPoliteness politeness) {
+    if (politeness == LiveRegionPoliteness::None) {
+      regions_.erase(tag);
+      return;
+    }
+    Region &region = regions_[tag];
+    region.politeness = politeness;
+  }
+
+  // A view that has gone away. Its last text goes with it, so a region that
+  // comes back is new again rather than compared against a screen that is no
+  // longer there.
+  void forget(Tag tag) { regions_.erase(tag); }
+
+  bool empty() const { return regions_.empty(); }
+
+  // The live regions, in no particular order, for a host to collect text for.
+  std::vector<Tag> tags() const {
+    std::vector<Tag> tags;
+    tags.reserve(regions_.size());
+    for (const auto &[tag, region] : regions_) {
+      tags.push_back(tag);
+    }
+    return tags;
+  }
+
+  // What this region should say now, or nothing.
+  //
+  // Nothing covers three cases that are all ordinary: the view is not a live
+  // region, this is the first text it has been seen with, or the text has not
+  // changed. Empty text is remembered and never announced -- a region that
+  // cleared itself has nothing to read out, and announcing "" is silence with a
+  // beat of interruption in front of it.
+  std::optional<LiveRegionPoliteness> noticed(Tag tag, const std::string &text) {
+    const auto found = regions_.find(tag);
+    if (found == regions_.end()) {
+      return std::nullopt;
+    }
+    Region &region = found->second;
+    const bool first = !region.said.has_value();
+    const bool changed = !first && region.said.value() != text;
+    region.said = text;
+    if (first || !changed || text.empty()) {
+      return std::nullopt;
+    }
+    return region.politeness;
+  }
+
+ private:
+  struct Region {
+    LiveRegionPoliteness politeness{LiveRegionPoliteness::Polite};
+    // Absent until the region has been seen once, which is what tells a first
+    // sighting from a change.
+    std::optional<std::string> said;
+  };
+
+  std::unordered_map<Tag, Region> regions_;
+};
+
+} // namespace basalt