@shopify/react-native-skia 2.12.0-next.1 → 2.12.0

package/cpp/jsi/NativeObject.h

@@ -8,14 +8,14 @@
 #include <jsi/jsi.h>
 #include <memory>
 #include <mutex>
-#include <optional>
 #include <string>
 #include <type_traits>
+#include <typeindex>
 #include <unordered_map>
 #include <utility>
 
 #include "jsi/BoxedNativeObject.h"
-#include "jsi/RuntimeAwareCache.h" // Use Skia's RuntimeAwareCache
+#include "jsi/JSICache.h"
 
 // Forward declare to avoid circular dependency
 namespace RNJsi {
@@ -37,45 +37,6 @@ static constexpr size_t kMinMemoryPressure = 256;
 // Forward declaration
 template <typename Derived> class NativeObject;
 
-/**
- * Per-runtime cache entry for a prototype object.
- * Uses std::optional<jsi::Object> so the prototype is stored directly
- * without extra indirection.
- */
-struct PrototypeCacheEntry {
-  std::optional<jsi::Object> prototype;
-};
-
-/**
- * Wrapper for static RuntimeAwareCache that handles hot reload.
- *
- * When used with static storage (like prototype caches), the cache persists
- * across hot reloads. But the JSI objects inside become invalid when the
- * runtime is destroyed. This wrapper tracks which runtime the cache was
- * created for and allocates a new cache when the runtime changes.
- *
- * The old cache is intentionally leaked - we cannot safely destroy JSI
- * objects after their runtime is gone.
- */
-template <typename T> struct StaticRuntimeAwareCache {
-  RNJsi::RuntimeAwareCache<T> *cache = nullptr;
-  jsi::Runtime *cacheRuntime = nullptr;
-
-  RNJsi::RuntimeAwareCache<T> &get(jsi::Runtime &rt) {
-    auto mainRuntime = RNJsi::BaseRuntimeAwareCache::getMainJsRuntime();
-    if (&rt == mainRuntime && cacheRuntime != mainRuntime) {
-      // Main runtime changed (hot reload) - allocate new cache, leak old one
-      cache = new RNJsi::RuntimeAwareCache<T>();
-      cacheRuntime = mainRuntime;
-    }
-    if (cache == nullptr) {
-      cache = new RNJsi::RuntimeAwareCache<T>();
-      cacheRuntime = mainRuntime;
-    }
-    return *cache;
-  }
-};
-
 /**
  * Base class for native objects using the NativeState pattern.
  *
@@ -112,29 +73,20 @@ public:
   using IsNativeObject = std::true_type;
 
   /**
-   * Get the prototype cache for this type.
-   * Each NativeObject<Derived> type has its own static cache.
-   * Uses StaticRuntimeAwareCache to properly handle runtime lifecycle
-   * and hot reload (where the main runtime is destroyed and recreated).
-   *
-   * Callers must hold getPrototypeCacheMutex(): the cache is reached
-   * concurrently from the main JS thread (create()) and from worklet
-   * runtime threads (BoxedNativeObject::unbox() -> installPrototype()).
+   * Key under which this class's prototype is stored in the per-runtime
+   * JSICache: the C++ type of Derived.
    */
-  static RNJsi::RuntimeAwareCache<PrototypeCacheEntry> &
-  getPrototypeCache(jsi::Runtime &runtime) {
-    static StaticRuntimeAwareCache<PrototypeCacheEntry> cache;
-    return cache.get(runtime);
+  static JSICache::PrototypeKey prototypeKey() {
+    return std::type_index(typeid(Derived));
   }
 
   /**
-   * Per-class mutex guarding getPrototypeCache() and prototype
-   * installation. Serializes the StaticRuntimeAwareCache pointer swap
-   * (hot reload) and the per-runtime cache lookups.
+   * Returns this class's prototype on `runtime`, or nullptr if it has not
+   * been installed there yet. The prototype is owned by the runtime (see
+   * JSICache), so the pointer is valid for as long as `runtime` is.
    */
-  static std::mutex &getPrototypeCacheMutex() {
-    static std::mutex mutex;
-    return mutex;
+  static jsi::Object *getCachedPrototype(jsi::Runtime &runtime) {
+    return JSICache::get(runtime).getPrototype(prototypeKey());
   }
 
   /**
@@ -142,10 +94,21 @@ public:
    * Called automatically by create(), but can be called manually.
    */
   static void installPrototype(jsi::Runtime &runtime) {
-    std::lock_guard<std::mutex> lock(getPrototypeCacheMutex());
-    auto &entry = getPrototypeCache(runtime).get(runtime);
-    if (entry.prototype.has_value()) {
-      return; // Already installed
+    ensurePrototype(runtime);
+  }
+
+  /**
+   * Look up (and install on first use) the prototype for this runtime.
+   *
+   * The returned reference is owned by the runtime's JSICache and stays
+   * valid for as long as the runtime does (std::unordered_map keeps
+   * references to its elements stable across rehashes). No locking is
+   * needed: a jsi::Runtime is single-threaded and its cache is only ever
+   * touched from its own thread.
+   */
+  static jsi::Object &ensurePrototype(jsi::Runtime &runtime) {
+    if (auto *cached = getCachedPrototype(runtime)) {
+      return *cached; // Already installed on this runtime
     }
 
     // Create prototype object
@@ -262,8 +225,9 @@ public:
           });
     });
 
-    // Cache the prototype
-    entry.prototype = std::move(prototype);
+    // Hand the prototype to the runtime-owned cache
+    return JSICache::get(runtime).setPrototype(prototypeKey(),
+                                               std::move(prototype));
   }
 
   /**
@@ -274,13 +238,7 @@ public:
    * created internally by the native code).
    */
   static void installConstructor(jsi::Runtime &runtime) {
-    installPrototype(runtime);
-
-    std::lock_guard<std::mutex> lock(getPrototypeCacheMutex());
-    auto &entry = getPrototypeCache(runtime).get(runtime);
-    if (!entry.prototype.has_value()) {
-      return;
-    }
+    auto &prototype = ensurePrototype(runtime);
 
     // Create a constructor function that throws when called directly
     auto ctor = jsi::Function::createFromHostFunction(
@@ -294,10 +252,10 @@ public:
 
     // Set the prototype property on the constructor
     // This is what makes `instanceof` work
-    ctor.setProperty(runtime, "prototype", *entry.prototype);
+    ctor.setProperty(runtime, "prototype", prototype);
 
     // Set constructor property on prototype pointing back to constructor
-    entry.prototype->setProperty(runtime, "constructor", ctor);
+    prototype.setProperty(runtime, "constructor", ctor);
 
     // Install on global
     runtime.global().setProperty(runtime, Derived::CLASS_NAME, std::move(ctor));
@@ -308,8 +266,6 @@ public:
    */
   static jsi::Value create(jsi::Runtime &runtime,
                            std::shared_ptr<Derived> instance) {
-    installPrototype(runtime);
-
     // Store creation runtime for logging etc.
     instance->setCreationRuntime(&runtime);
 
@@ -319,18 +275,13 @@ public:
     // Attach native state
     obj.setNativeState(runtime, instance);
 
-    // Set prototype
+    // Install (on first use) and apply the prototype
     {
-      std::lock_guard<std::mutex> lock(getPrototypeCacheMutex());
-      auto &entry = getPrototypeCache(runtime).get(runtime);
-      if (entry.prototype.has_value()) {
-        // Use Object.setPrototypeOf to set the prototype
-        auto objectCtor =
-            runtime.global().getPropertyAsObject(runtime, "Object");
-        auto setPrototypeOf =
-            objectCtor.getPropertyAsFunction(runtime, "setPrototypeOf");
-        setPrototypeOf.call(runtime, obj, *entry.prototype);
-      }
+      auto &prototype = ensurePrototype(runtime);
+      auto objectCtor = runtime.global().getPropertyAsObject(runtime, "Object");
+      auto setPrototypeOf =
+          objectCtor.getPropertyAsFunction(runtime, "setPrototypeOf");
+      setPrototypeOf.call(runtime, obj, prototype);
     }
 
     // Set memory pressure hint for GC

package/cpp/jsi/ViewProperty.h

@@ -1,40 +1,16 @@
 #pragma once
 
-#include <atomic>
 #include <functional>
 #include <jsi/jsi.h>
 #include <memory>
 #include <string>
 #include <variant>
 
-#include "RuntimeLifecycleMonitor.h"
 #include "api/JsiSkPicture.h"
 
 namespace RNJsi {
 namespace jsi = facebook::jsi;
 
-class RuntimeAwareRuntimeGuard : public RuntimeLifecycleListener {
-public:
-  explicit RuntimeAwareRuntimeGuard(jsi::Runtime &runtime)
-      : _runtime(&runtime) {
-    RuntimeLifecycleMonitor::addListener(runtime, this);
-  }
-
-  ~RuntimeAwareRuntimeGuard() override {
-    auto runtime = _runtime.load();
-    if (runtime != nullptr) {
-      RuntimeLifecycleMonitor::removeListener(*runtime, this);
-    }
-  }
-
-  void onRuntimeDestroyed(jsi::Runtime *) override { _runtime.store(nullptr); }
-
-  jsi::Runtime *getRuntime() const { return _runtime.load(); }
-
-private:
-  std::atomic<jsi::Runtime *> _runtime;
-};
-
 class ViewProperty {
 public:
   ViewProperty(jsi::Runtime &runtime, const jsi::Value &value) {

package/cpp/rnskia/RNDawnContext.h

@@ -147,7 +147,8 @@ public:
     vkBegin.newLayout = 0;
     beginAccessDesc.nextInChain = &vkBegin;
 #endif
-    bool success = memory.BeginAccess(texture, &beginAccessDesc);
+    bool success =
+        memory.BeginAccess(texture, &beginAccessDesc) == wgpu::Status::Success;
 
     if (success) {
       skgpu::graphite::BackendTexture betFromView =

package/cpp/rnskia/RNDawnWindowContext.h

@@ -82,6 +82,7 @@ private:
     config.width = _width;
     config.height = _height;
     config.presentMode = wgpu::PresentMode::Fifo;
+    config.usage = supportedSurfaceUsage();
 #ifdef __APPLE__
     config.alphaMode = wgpu::CompositeAlphaMode::Premultiplied;
 #endif
@@ -93,6 +94,27 @@ private:
 #endif
   }
 
+  // Graphite needs more than RenderAttachment on the swapchain texture:
+  // TextureBinding so a render pass can reload the existing contents through
+  // LoadOp::ExpandResolveTexture (any backdrop filter or mid-frame readback
+  // splits the pass), and CopySrc for copy tasks. Only request what the
+  // surface reports as supported.
+  wgpu::TextureUsage supportedSurfaceUsage() {
+    wgpu::TextureUsage usage = wgpu::TextureUsage::RenderAttachment;
+    wgpu::SurfaceCapabilities capabilities;
+    if (_surface.GetCapabilities(_device.GetAdapter(), &capabilities) !=
+        wgpu::Status::Success) {
+      return usage;
+    }
+    for (auto extra :
+         {wgpu::TextureUsage::TextureBinding, wgpu::TextureUsage::CopySrc}) {
+      if (capabilities.usages & extra) {
+        usage |= extra;
+      }
+    }
+    return usage;
+  }
+
   bool surfaceSupportsFormat(wgpu::TextureFormat format) {
     wgpu::SurfaceCapabilities capabilities;
     if (_surface.GetCapabilities(_device.GetAdapter(), &capabilities) !=

package/cpp/rnskia/RNSkManager.cpp

@@ -9,8 +9,6 @@
 #include "RNSkView.h"
 #include "api/JsiSkApi.h"
 
-#include "jsi/RuntimeAwareCache.h"
-
 namespace RNSkia {
 namespace jsi = facebook::jsi;
 
@@ -21,10 +19,6 @@ RNSkManager::RNSkManager(
     : _jsRuntime(jsRuntime), _platformContext(platformContext),
       _jsCallInvoker(jsCallInvoker),
       _viewApi(std::make_shared<RNSkJsiViewApi>(platformContext)) {
-
-  // Register main runtime
-  RNJsi::BaseRuntimeAwareCache::setMainJsRuntime(_jsRuntime);
-
   // Install bindings
   installBindings();
 }

package/cpp/rnskia/RNSkPlatformContext.h

@@ -96,9 +96,6 @@ public:
   virtual sk_sp<SkSurface>
   makeOffscreenSurface(int width, int height, bool useP3ColorSpace = false) = 0;
 
-  virtual std::shared_ptr<WindowContext>
-  makeContextFromNativeSurface(void *surface, int width, int height) = 0;
-
   /**
    * Creates an image from a native buffer.
    * - On iOS, this is a `CVPixelBufferRef`

package/cpp/skia/include/core/RasterContext.h

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#ifndef RasterContext_DEFINED
+#define RasterContext_DEFINED
+
+#include "include/core/SkRefCnt.h"
+
+#include <memory>
+
+class SkContext;
+struct SkContextOptions;
+
+namespace SkContexts {
+
+// Creates a context for SkContext with only Software Rasterization
+std::unique_ptr<SkContext> MakeRaster(const SkContextOptions& options);
+
+}  // namespace SkContexts
+
+#endif  // RasterContext_DEFINED

package/cpp/skia/include/core/SkCanvas.h

@@ -2529,7 +2529,6 @@ private:
     std::unique_ptr<SkRasterHandleAllocator> fAllocator;
 
     SkSurface_Base*  fSurfaceBase;
-    virtual SkSurface_Base* getSurfaceBase() const { return fSurfaceBase; }
     void setSurfaceBase(SkSurface_Base* sb) {
         fSurfaceBase = sb;
     }

package/cpp/skia/include/core/SkContext.h

@@ -0,0 +1,62 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#ifndef SkContext_DEFINED
+#define SkContext_DEFINED
+
+#include "include/core/SkRefCnt.h"
+#include "include/private/SkAPI.h"
+
+class SkContextPriv;
+class SkResourceCache;
+class SkSharedContext;
+class SkStrikeCache;
+class SkTraceMemoryDump;
+class SkTypefaceCache;
+struct SkContextOptions;
+
+/**
+ * @brief SkContext is a central context object that serves as the mandatory first point of
+ * initialization for all Skia clients. SkContext consolidates global state, management of shared
+ * resources, and internal caches.
+ */
+class SK_API SkContext final {
+public:
+    SkContext(const SkContext&) = delete;
+    SkContext(SkContext&&) = delete;
+    SkContext& operator=(const SkContext&) = delete;
+    SkContext& operator=(SkContext&&) = delete;
+
+    ~SkContext();
+
+    SkContextPriv priv();
+    const SkContextPriv priv() const;
+
+private:
+    SkContext(sk_sp<SkSharedContext>);
+
+    SkResourceCache* resourceCache() const;
+    SkStrikeCache* fontCache() const;
+    SkTypefaceCache* typefaceCache() const;
+
+    size_t fontCacheLimit() const;
+    size_t setFontCacheLimit(size_t bytes);
+    size_t fontCacheUsed() const;
+
+    int fontCacheCountLimit() const;
+    int setFontCacheCountLimit(int count);
+    int fontCacheCountUsed() const;
+
+    void purgeFontCache();
+    void purgePinnedFontCache();
+
+    void dumpMemoryStatistics(SkTraceMemoryDump* dump);
+
+    sk_sp<SkSharedContext> fSharedContext;
+};
+
+#endif  // SkContext_DEFINED

package/cpp/skia/include/core/SkContextOptions.h

@@ -0,0 +1,15 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#ifndef SkContextOptions_DEFINED
+#define SkContextOptions_DEFINED
+
+#include "include/private/SkAPI.h"
+
+struct SK_API SkContextOptions {};
+
+#endif  // SkContextOptions_DEFINED

package/cpp/skia/include/core/SkMilestone.h

@@ -5,5 +5,5 @@
  * found in the LICENSE file.
  */
 #ifndef SK_MILESTONE
-#define SK_MILESTONE 152
+#define SK_MILESTONE 154
 #endif

package/cpp/skia/include/core/SkPicture.h

@@ -16,12 +16,16 @@
 #include <atomic>
 #include <cstddef>
 #include <cstdint>
+#include <memory>
 
+class SkBBoxHierarchy;
 class SkCanvas;
 class SkData;
 class SkMatrix;
+class SkRecord;
 class SkStream;
 class SkWStream;
+class SkSnapshotArray;
 enum class SkFilterMode;
 struct SkDeserialProcs;
 struct SkSerialProcs;
@@ -33,8 +37,8 @@ struct SkSerialProcs;
     SkPicture records drawing commands made to SkCanvas. The command stream may be
     played in whole or in part at a later time.
 
-    SkPicture is an abstract class. SkPicture may be generated by SkPictureRecorder
-    or SkDrawable, or from SkPicture previously saved to SkData or SkStream.
+    SkPicture may be generated by SkPictureRecorder or SkDrawable, or from a
+    SkPicture previously saved to SkData or SkStream.
 
     SkPicture may contain any SkCanvas drawing command, as well as one or more
     SkCanvas matrix or SkCanvas clip. SkPicture has a cull SkRect, which is used as
@@ -84,7 +88,8 @@ public:
         @param procs  custom serial data decoders; may be nullptr
         @return       SkPicture constructed from data
     */
-    static sk_sp<SkPicture> MakeFromData(const void* data, size_t size,
+    static sk_sp<SkPicture> MakeFromData(const void* data,
+                                         size_t size,
                                          const SkDeserialProcs* procs = nullptr);
 
     /** \class SkPicture::AbortCallback
@@ -133,7 +138,7 @@ public:
 
         example: https://fiddle.skia.org/c/@Picture_playback
     */
-    virtual void playback(SkCanvas* canvas, AbortCallback* callback = nullptr) const = 0;
+    void playback(SkCanvas* canvas, AbortCallback* callback = nullptr) const;
 
     /** Returns cull SkRect for this picture, passed in when SkPicture was created.
         Returned SkRect does not specify clipping SkRect for SkPicture; cull is hint
@@ -146,7 +151,7 @@ public:
 
         example: https://fiddle.skia.org/c/@Picture_cullRect
     */
-    virtual SkRect cullRect() const = 0;
+    SkRect cullRect() const { return fCullRect; }
 
     /** Returns a non-zero value unique among SkPicture in Skia process.
 
@@ -212,11 +217,12 @@ public:
 
         @param nested  if true, include the op-counts of nested pictures as well, else
                        just return count the ops in the top-level picture.
-        @return  approximate operation count
+        @return  approximate operation count. If 0 is returned, we say the SkPicture is "empty"
+                    meaning its cullRect is the result of an SkRect::MakeEmpty().
 
         example: https://fiddle.skia.org/c/@Picture_approximateOpCount
     */
-    virtual int approximateOpCount(bool nested = false) const = 0;
+    int approximateOpCount(bool nested = false) const;
 
     /** Returns the approximate byte size of SkPicture. Does not include large objects
         referenced by SkPicture.
@@ -225,7 +231,7 @@ public:
 
         example: https://fiddle.skia.org/c/@Picture_approximateBytesUsed
     */
-    virtual size_t approximateBytesUsed() const = 0;
+    size_t approximateBytesUsed() const;
 
     /** Return a new shader that will draw with this picture.
      *
@@ -240,18 +246,23 @@ public:
      *                  bounds.
      *  @return     Returns a new shader object. Note: this function never returns null.
      */
-    sk_sp<SkShader> makeShader(SkTileMode tmx, SkTileMode tmy, SkFilterMode mode,
-                               const SkMatrix* localMatrix, const SkRect* tileRect) const;
+    sk_sp<SkShader> makeShader(SkTileMode tmx,
+                               SkTileMode tmy,
+                               SkFilterMode mode,
+                               const SkMatrix* localMatrix,
+                               const SkRect* tileRect) const;
 
     sk_sp<SkShader> makeShader(SkTileMode tmx, SkTileMode tmy, SkFilterMode mode) const {
         return this->makeShader(tmx, tmy, mode, nullptr, nullptr);
     }
 
 private:
-    // Allowed subclasses.
-    SkPicture();
-    friend class SkBigPicture;
-    friend class SkEmptyPicture;
+    SkPicture(const SkRect& cull,
+              sk_sp<const SkRecord> record,
+              std::unique_ptr<const SkSnapshotArray> drawablePicts,
+              sk_sp<const SkBBoxHierarchy> bbh,
+              size_t approxBytesUsedBySubPictures);
+
     friend class SkPicturePriv;
 
     void serialize(SkWStream*, const SkSerialProcs*, class SkRefCntSet* typefaces,
@@ -273,9 +284,6 @@ private:
     static bool BufferIsSKP(class SkReadBuffer*, struct SkPictInfo*);
     friend bool SkPicture_StreamIsSKP(SkStream*, struct SkPictInfo*);
 
-    // Returns NULL if this is not an SkBigPicture.
-    virtual const class SkBigPicture* asSkBigPicture() const { return nullptr; }
-
     static bool IsValidPictInfo(const struct SkPictInfo& info);
     static sk_sp<SkPicture> Forwardport(const struct SkPictInfo&,
                                         const class SkPictureData*,
@@ -284,7 +292,17 @@ private:
     struct SkPictInfo createHeader() const;
     class SkPictureData* backport() const;
 
-    uint32_t fUniqueID;
+    // When fRecord is nullptr, then we treat the SkPicture as a "placeholder"
+    // placeholders provide the bare minimum to operate on an SkPicture
+    bool isPlaceholder() const { return !fRecord; }
+
+    const uint32_t fUniqueID;
+    const SkRect fCullRect;
+    const size_t fApproxBytesUsedBySubPictures;
+    const sk_sp<const SkRecord> fRecord;
+    const std::unique_ptr<const SkSnapshotArray> fDrawablePicts;
+    const sk_sp<const SkBBoxHierarchy> fBBH;
+
     mutable std::atomic<bool> fAddedToCache{false};
 };
 

package/cpp/skia/include/core/SkRecorder.h

@@ -7,7 +7,9 @@
 #ifndef SkRecorder_DEFINED
 #define SkRecorder_DEFINED
 
+#include "include/core/SkPicture.h"
 #include "include/private/SkAPI.h"
+#include "include/private/SkTArray.h"
 
 class SkCanvas;
 class SkSurface;
@@ -34,11 +36,17 @@ public:
 
     virtual skcpu::Recorder* cpuRecorder() = 0;
 
+protected:
+    skia_private::TArray<sk_sp<SkPicture>> fCapturedPictures;
+
 private:
 
     /**
     * Attempts to create and return an SkCaptureCanvas that wraps the provided base canvas.
     * Returns nullptr if capture is not enabled.
+    *
+    * TODO: When implementing in all Recorder subclasses, see if the implementations can be shared
+    * and moved here.
     */
     virtual SkCanvas* makeCaptureCanvas(SkCanvas*) = 0;
     virtual void createCaptureBreakpoint(SkSurface*) = 0;

package/cpp/skia/include/core/SkSerialProcs.h

@@ -47,8 +47,7 @@ using SkSerialTypefaceProc = SkSerialReturnType (*)(SkTypeface*, void* ctx);
 using SkDeserialPictureProc = sk_sp<SkPicture> (*)(const void* data, size_t length, void* ctx);
 
 /**
- *  Called with the encoded form of an image. The proc can return an image object, or if it
- *  returns nullptr, then Skia will take its default action to try to create an image from the data.
+ *  Called with the encoded form of an image. If this is not set, no image decoding will be done.
  *
  *  This will also be used to decode the internal mipmap layers that are saved on some images.
  *
@@ -60,14 +59,11 @@ using SkDeserialPictureProc = sk_sp<SkPicture> (*)(const void* data, size_t leng
  *  must make a copy of any data they needed after the proc finishes, since the data will go away
  *  after serialization ends.
  */
-#if !defined(SK_LEGACY_DESERIAL_IMAGE_PROC)
-using SkDeserialImageProc = sk_sp<SkImage> (*)(const void* data, size_t length, void* ctx);
-#else
 using SkDeserialImageProc = sk_sp<SkImage> (*)(const void* data,
                                                size_t length,
                                                std::optional<SkAlphaType>,
                                                void* ctx);
-#endif
+
 using SkDeserialImageFromDataProc = sk_sp<SkImage> (*)(sk_sp<SkData>,
                                                        std::optional<SkAlphaType>,
                                                        void* ctx);

package/cpp/skia/include/effects/SkImageFilters.h

@@ -414,12 +414,21 @@ public:
      * This allows Skia to provide sampleable values for the image filter without worrying about
      * boundary conditions.
      *
+     * By default the output of a runtime shader is unbounded, since Skia cannot know what colors
+     * the SkSL will produce for pixels outside of its inputs' bounds. If
+     * 'restrictOutputToInputBounds' is true, the caller promises that the SkSL evaluates to
+     * transparent black wherever its child shaders are transparent black, so the filter's output
+     * bounds can be restricted to the union of its inputs' output bounds (the source image's
+     * bounds when 'input' is null). This lets downstream filters (e.g. a blur with a non-decal
+     * tile mode) see the original content bounds instead of an unbounded result.
+     *
      * This requires a GPU backend or SkSL to be compiled in.
     */
     static sk_sp<SkImageFilter> RuntimeShader(const SkRuntimeEffectBuilder& builder,
                                               SkScalar sampleRadius,
                                               std::string_view childShaderName,
-                                              sk_sp<SkImageFilter> input);
+                                              sk_sp<SkImageFilter> input,
+                                              bool restrictOutputToInputBounds = false);
 
     /**
      *  Create a filter that fills the output with the per-pixel evaluation of the SkShader produced
@@ -453,13 +462,17 @@ public:
      * childShaderNames) will be evaluated with coordinates at most 'maxSampleRadius' away from the
      * coordinate provided to the runtime shader itself.
      *
+     * If 'restrictOutputToInputBounds' is true, the filter's output bounds are restricted to the
+     * union of its inputs' output bounds; see the single-child variant for details.
+     *
      *  This requires a GPU backend or SkSL to be compiled in.
      */
     static sk_sp<SkImageFilter> RuntimeShader(const SkRuntimeEffectBuilder& builder,
                                               SkScalar maxSampleRadius,
                                               std::string_view childShaderNames[],
                                               const sk_sp<SkImageFilter> inputs[],
-                                              int inputCount);
+                                              int inputCount,
+                                              bool restrictOutputToInputBounds = false);
 
     enum class Dither : bool {
         kNo = false,