react-native-parity-blur 0.1.0

package/android/src/main/java/com/parityblur/PipelineMath.kt

@@ -0,0 +1,202 @@
+package com.parityblur
+
+import kotlin.math.ceil
+import kotlin.math.floor
+import kotlin.math.max
+import kotlin.math.min
+
+/**
+ * Kotlin mirror of `src/pipeline/units.ts`, `src/pipeline/captureRect.ts`,
+ * `src/pipeline/downsample.ts`, `src/pipeline/saturation.ts`, and the `sourceOver` half of
+ * `src/pipeline/overlay.ts`. This is the executable form of docs/PIPELINE_SPEC.md §1-§4, §7 on
+ * the Android side; `android/src/test/.../PipelineFixturesTest.kt` asserts every function here
+ * against `test/pipeline-fixtures.json` within 1e-6.
+ *
+ * Pure Double/Int arithmetic, NO android.* imports -- testable as a plain JVM unit test.
+ *
+ * Deviation note (documented, not a pipeline behavior change): `overlay.ts`'s `parseColor` is
+ * NOT mirrored here. Android's `overlayColor` native prop is a `ColorValue` already parsed into
+ * an ARGB Int by React Native's own color parser before it reaches native code (see
+ * ParityBlurViewNativeComponent.ts / ParityBlurViewManager), so there is no string-parsing step
+ * on the native side to mirror. `sourceOver` IS mirrored below for the fixture suite even though
+ * the runtime presentation path does not call it directly -- see ParityBlurView's overlay
+ * comment for why a plain Canvas draw of the (already-parsed) overlay color is mathematically
+ * equivalent source-over compositing on the opaque blurred destination.
+ */
+object PipelineMath {
+
+  /** Axis-aligned rectangle, target-local device px unless documented otherwise. */
+  data class Rect(val x: Double, val y: Double, val width: Double, val height: Double)
+
+  /** Straight-alpha RGBA colour, channels normalised to [0, 1]. */
+  data class RGBA(val r: Double, val g: Double, val b: Double, val a: Double)
+
+  // ---------------------------------------------------------------- units.ts
+
+  /** blurRadius (sigma in dp) -> sigma in device px. Non-finite/non-positive inputs clamp to 0. */
+  fun sigmaPxFromDp(blurRadiusDp: Double, displayScale: Double): Double {
+    if (!blurRadiusDp.isFinite() || blurRadiusDp <= 0) return 0.0
+    if (!displayScale.isFinite() || displayScale <= 0) return 0.0
+    return blurRadiusDp * displayScale
+  }
+
+  /** Device-px sigma -> snapshot-domain sigma given downsample factor D. */
+  fun sigmaSnapshotFromPx(sigmaPx: Double, downsample: Int): Double {
+    if (!sigmaPx.isFinite() || sigmaPx <= 0) return 0.0
+    return sigmaPx / downsample
+  }
+
+  // ----------------------------------------------------------- captureRect.ts
+
+  /** Gaussian support margin in device px (plan §7): ceil(K * sigmaPx). */
+  fun supportMarginPx(sigmaPx: Double, k: Double = AndroidBlurCalibration.CAPTURE_SUPPORT_K): Double {
+    if (!sigmaPx.isFinite() || sigmaPx <= 0) return 0.0
+    return ceil(k * sigmaPx)
+  }
+
+  /** Intersection of two rects; zero-size rect if they do not overlap. */
+  fun intersectRect(a: Rect, b: Rect): Rect {
+    val x0 = max(a.x, b.x)
+    val y0 = max(a.y, b.y)
+    val x1 = min(a.x + a.width, b.x + b.width)
+    val y1 = min(a.y + a.height, b.y + b.height)
+    val width = max(0.0, x1 - x0)
+    val height = max(0.0, y1 - y0)
+    if (width == 0.0 || height == 0.0) return Rect(x0, y0, 0.0, 0.0)
+    return Rect(x0, y0, width, height)
+  }
+
+  /**
+   * Expand the visible blur rect by the Gaussian support margin and clamp to the target bounds
+   * (plan §7). CLAMP handles the outer edge where the margin was cut off (plan §8).
+   */
+  fun expandCaptureRect(
+    visibleRect: Rect,
+    targetBounds: Rect,
+    sigmaPx: Double,
+    k: Double = AndroidBlurCalibration.CAPTURE_SUPPORT_K
+  ): Rect {
+    val margin = supportMarginPx(sigmaPx, k)
+    val expanded = Rect(
+      x = visibleRect.x - margin,
+      y = visibleRect.y - margin,
+      width = visibleRect.width + 2 * margin,
+      height = visibleRect.height + 2 * margin
+    )
+    return intersectRect(expanded, targetBounds)
+  }
+
+  /** Area of a rect in device px^2 (downsample-selection helper). */
+  fun rectArea(r: Rect): Double = r.width * r.height
+
+  /**
+   * Map a clamped device-px capture rect into integer snapshot pixels for downsample factor D.
+   * LOCKED rounding rule (PIPELINE_SPEC §3.3): origin FLOORS, far edge CEILS (conservative
+   * cover) -- every device pixel of the capture rect is guaranteed to land in the snapshot rect.
+   */
+  fun snapshotRectFor(captureRectPx: Rect, downsample: Int): Rect {
+    val x = floor(captureRectPx.x / downsample)
+    val y = floor(captureRectPx.y / downsample)
+    val farX = ceil((captureRectPx.x + captureRectPx.width) / downsample)
+    val farY = ceil((captureRectPx.y + captureRectPx.height) / downsample)
+    return Rect(x, y, max(0.0, farX - x), max(0.0, farY - y))
+  }
+
+  /**
+   * Fractional snapshot-px crop rect selecting the visible region out of the (larger) snapshot
+   * rect after blur. The fractional origin remainder in [0,1) snapshot px is resolved by the
+   * bilinear upsample -- do not round it away (PIPELINE_SPEC §3.4).
+   */
+  fun cropRectFor(visibleRect: Rect, snapshotRect: Rect, downsample: Int): Rect {
+    return Rect(
+      x = visibleRect.x / downsample - snapshotRect.x,
+      y = visibleRect.y / downsample - snapshotRect.y,
+      width = visibleRect.width / downsample,
+      height = visibleRect.height / downsample
+    )
+  }
+
+  // ------------------------------------------------------------ downsample.ts
+
+  private val DOWNSAMPLE_FACTORS = intArrayOf(8, 4, 2, 1)
+
+  /** Largest allowed factor in {8,4,2,1} that is <= cap (never below 1). */
+  private fun largestFactorAtMost(cap: Double): Int {
+    for (factor in DOWNSAMPLE_FACTORS) {
+      if (factor <= cap) return factor
+    }
+    return 1
+  }
+
+  /** Per-quality ceiling on the downsample factor (plan §13). */
+  fun qualityMaxDownsample(quality: String): Int = when (quality) {
+    "high" -> AndroidBlurCalibration.QUALITY_MAX_DOWNSAMPLE_HIGH
+    "performance" -> AndroidBlurCalibration.QUALITY_MAX_DOWNSAMPLE_PERFORMANCE
+    else -> AndroidBlurCalibration.QUALITY_MAX_DOWNSAMPLE_BALANCED
+  }
+
+  /**
+   * Resolve the auto-selected downsample factor: the largest factor in {8,4,2,1} satisfying ALL
+   * of the quality ceiling, the sigma floor, and the small-capture area ceiling
+   * (PIPELINE_SPEC §4).
+   */
+  fun autoDownsample(sigmaPx: Double, captureAreaPx: Double, quality: String): Int {
+    if (!sigmaPx.isFinite() || sigmaPx <= 0) return 1
+
+    val maxByQuality = qualityMaxDownsample(quality)
+    val maxBySigma = floor(sigmaPx / AndroidBlurCalibration.MIN_SIGMA_SNAPSHOT)
+    val area = if (captureAreaPx.isFinite()) captureAreaPx else 0.0
+    val maxByArea = if (area < AndroidBlurCalibration.SMALL_CAPTURE_AREA_PX) 2.0 else 8.0
+
+    val cap = minOf(maxByQuality.toDouble(), maxBySigma, maxByArea)
+    return largestFactorAtMost(cap)
+  }
+
+  /**
+   * Resolve the public `downsample` prop (0 = 'auto' sentinel; see
+   * ParityBlurViewNativeComponent.ts) to a concrete factor.
+   */
+  fun resolveDownsample(prop: Int, sigmaPx: Double, captureAreaPx: Double, quality: String): Int {
+    if (prop == 0) return autoDownsample(sigmaPx, captureAreaPx, quality)
+    return prop
+  }
+
+  // ------------------------------------------------------------- saturation.ts
+
+  /**
+   * Row-major 4x5 saturation matrix (20 numbers), matching Android's ColorMatrix layout and
+   * mirroring `saturation.ts` exactly. `s = 1` -> identity; `s = 0` -> luminance grayscale.
+   */
+  fun saturationMatrix(
+    s: Double,
+    lr: Double = AndroidBlurCalibration.LUMA_R,
+    lg: Double = AndroidBlurCalibration.LUMA_G,
+    lb: Double = AndroidBlurCalibration.LUMA_B
+  ): DoubleArray {
+    val t = 1 - s
+    return doubleArrayOf(
+      t * lr + s, t * lg, t * lb, 0.0, 0.0,
+      t * lr, t * lg + s, t * lb, 0.0, 0.0,
+      t * lr, t * lg, t * lb + s, 0.0, 0.0,
+      0.0, 0.0, 0.0, 1.0, 0.0
+    )
+  }
+
+  /** Float32 copy of [saturationMatrix], the shape android.graphics.ColorMatrix expects. */
+  fun saturationMatrixFloat(s: Double): FloatArray =
+    FloatArray(20) { saturationMatrix(s)[it].toFloat() }
+
+  // --------------------------------------------------------------- overlay.ts
+
+  /**
+   * Straight-alpha source-over composite: `src` over `dst`. Mirrors `overlay.ts` `sourceOver`
+   * exactly. Exercised by the fixture suite; the runtime presentation path uses a direct Canvas
+   * draw instead (see deviation note above).
+   */
+  fun sourceOver(src: RGBA, dst: RGBA): RGBA {
+    val outA = src.a + dst.a * (1 - src.a)
+    if (outA <= 0) return RGBA(0.0, 0.0, 0.0, 0.0)
+    fun blend(sc: Double, dc: Double) = (sc * src.a + dc * dst.a * (1 - src.a)) / outA
+    return RGBA(blend(src.r, dst.r), blend(src.g, dst.g), blend(src.b, dst.b), outA)
+  }
+}

package/android/src/main/java/com/parityblur/PixelCopySnapshotProvider.kt

@@ -0,0 +1,108 @@
+package com.parityblur
+
+import android.app.Activity
+import android.graphics.Rect
+import android.os.Handler
+import android.os.Looper
+import android.view.PixelCopy
+import android.view.ViewGroup
+import android.view.Window
+import com.facebook.react.uimanager.ThemedReactContext
+import kotlin.math.roundToInt
+
+/**
+ * GPU-composited first-capture provider (M5 finding, amending plan §14.1 a second time).
+ *
+ * The software-canvas provider cannot rasterize HARDWARE bitmaps (Fresco decodes RN `Image`s to
+ * Config.HARDWARE on modern devices; drawing one into a software Canvas is skipped), so any
+ * image-backed backdrop went missing from captures — observed on-device as black blur strips
+ * over an Image fixture. [PixelCopy] reads the SurfaceFlinger-composited window content instead:
+ * hardware bitmaps, TextureViews, everything on screen — and scales into a smaller destination
+ * bitmap, giving us the downsample step for free.
+ *
+ * Constraint: PixelCopy sees the FULL composited frame, including this blur view's own output —
+ * so it is only safe while the view has never presented anything (first capture; the
+ * presentation node is empty and children have not yet been committed above an empty region...
+ * children ARE composited, so the capture may include children committed in the same region).
+ * Callers therefore use it ONLY for the first capture after mount, scheduled before the view's
+ * first presentation reaches the screen; RE-captures keep the software provider (its
+ * hardware-bitmap gap on recapture is a documented v1 limitation, plan §43).
+ *
+ * Async by nature: results arrive on the main handler; callers must re-validate generation and
+ * attachment before presenting (plan §23 — this is exactly what generation tokens exist for).
+ */
+object PixelCopySnapshotProvider {
+
+  fun capture(
+    view: ParityBlurView,
+    target: ViewGroup,
+    blurRadiusDp: Double,
+    downsampleProp: Int,
+    quality: String,
+    engine: BlurEngine,
+    onResult: (SoftwareSnapshotProvider.Result?) -> Unit
+  ) {
+    val window = windowFor(view)
+    if (window == null) {
+      onResult(null)
+      return
+    }
+    val plan = SoftwareSnapshotProvider.computePlan(view, target, blurRadiusDp, downsampleProp, quality)
+    if (plan == null) {
+      onResult(null)
+      return
+    }
+
+    val d = plan.downsample
+    // Snapshot rect in WINDOW device px (snapshot px * D, offset by the target's position).
+    val decor = window.decorView
+    val srcRect = Rect(
+      (plan.targetLocX + plan.snapshotRect.x * d).roundToInt(),
+      (plan.targetLocY + plan.snapshotRect.y * d).roundToInt(),
+      (plan.targetLocX + (plan.snapshotRect.x + plan.snapshotRect.width) * d).roundToInt(),
+      (plan.targetLocY + (plan.snapshotRect.y + plan.snapshotRect.height) * d).roundToInt()
+    )
+    // The ceil'd far edge can overhang the window by < D px; clamp (edge error <= 1 snapshot px
+    // inside the gaussian support margin -- invisible, and CLAMP tiling covers the boundary).
+    if (!srcRect.intersect(Rect(0, 0, decor.width, decor.height))) {
+      onResult(null)
+      return
+    }
+
+    val bitmap = engine.acquireBitmap(plan.snapW, plan.snapH)
+    try {
+      PixelCopy.request(
+        window,
+        srcRect,
+        bitmap,
+        { copyResult ->
+          if (copyResult == PixelCopy.SUCCESS) {
+            onResult(
+              SoftwareSnapshotProvider.Result(
+                bitmap = bitmap,
+                cropRect = plan.cropRect,
+                downsample = plan.downsample,
+                noBlur = plan.noBlur,
+                radiusPlatform = plan.radiusPlatform
+              )
+            )
+          } else {
+            engine.releaseBitmap(bitmap)
+            onResult(null)
+          }
+        },
+        Handler(Looper.getMainLooper())
+      )
+    } catch (t: Throwable) {
+      // e.g. IllegalArgumentException("Window doesn't have a backing surface") during teardown.
+      engine.releaseBitmap(bitmap)
+      onResult(null)
+    }
+  }
+
+  private fun windowFor(view: ParityBlurView): Window? {
+    val ctx = view.context
+    val activity = (ctx as? ThemedReactContext)?.currentActivity ?: ctx as? Activity
+    return activity?.window
+  }
+}

package/android/src/main/java/com/parityblur/SoftwareSnapshotProvider.kt

@@ -0,0 +1,173 @@
+package com.parityblur
+
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.view.ViewGroup
+import java.util.Collections
+import java.util.WeakHashMap
+import kotlin.math.max
+
+/**
+ * Marker for software (in-tree) capture passes (plan §14.2; M0-REPORT finding 1).
+ *
+ * A software [Canvas] makes [ViewGroup] call each child's `draw(Canvas)`, where
+ * [ParityBlurView]'s override can bail out for the duration of the pass. On the HARDWARE path
+ * `ViewGroup.dispatchDraw` instead records a LIVE REFERENCE to each child's RenderNode without
+ * ever calling `draw(Canvas)` -- a draw-override exclusion is invisible there, and an in-tree
+ * RenderNode capture forms a reference cycle that crashes the RenderThread (SIGSEGV,
+ * device-verified in M0 on a Pixel 6a). Static v1 therefore captures ONLY via this software
+ * provider (plan §14.1 amendment); a structural (RenderNode) live provider is Milestone 6 scope
+ * and requires the blur view to sit OUTSIDE the captured subtree by construction.
+ */
+object CapturePass {
+  @Volatile
+  var active: Boolean = false
+    private set
+
+  /** Every registered ParityBlurView presentation surface bails out of draw() during a pass. */
+  val registered: MutableSet<ParityBlurView> = Collections.newSetFromMap(WeakHashMap())
+
+  fun <T> run(block: () -> T): T {
+    check(!active) { "nested capture pass" }
+    active = true
+    try {
+      return block()
+    } finally {
+      active = false
+    }
+  }
+}
+
+/**
+ * The static-mode capture provider (plan §14.1 as amended by M0-REPORT): rasterize the capture
+ * target into a downsampled ARGB_8888 bitmap via a software Canvas (draw-override exclusion
+ * works there; no RenderNode references exist, so no cycle is possible), producing a frozen
+ * copy -- true static semantics. GPU blur/saturation are applied afterward by the caller via a
+ * RenderNode carrying a RenderEffect chain on the resulting bitmap
+ * ([ParityBlurView.presentCapture]).
+ */
+object SoftwareSnapshotProvider {
+
+  /** Everything [ParityBlurView] needs to build/refresh its presentation RenderNode. */
+  class Result(
+    val bitmap: Bitmap,
+    val cropRect: PipelineMath.Rect,
+    val downsample: Int,
+    val noBlur: Boolean,
+    val radiusPlatform: Float
+  )
+
+  /**
+   * Capture [target] cropped/expanded around [view]'s current on-screen bounds (pipeline steps
+   * 1-7, PIPELINE_SPEC §9) and return a downsampled bitmap plus the crop rect needed to present
+   * just the visible region back out. Returns null when the view/target are not presently in a
+   * capturable state -- callers gate this behind [ParityBlurView]'s state machine (plan §14.4),
+   * but this function re-checks defensively since it is the last word before allocating a bitmap.
+   */
+  /**
+   * The geometry every provider shares (PIPELINE_SPEC §3): identical math regardless of HOW the
+   * pixels are captured, so provider choice can never change blur geometry.
+   */
+  internal class Plan(
+    val snapshotRect: PipelineMath.Rect,
+    val cropRect: PipelineMath.Rect,
+    val downsample: Int,
+    val snapW: Int,
+    val snapH: Int,
+    val targetLocX: Int,
+    val targetLocY: Int,
+    val noBlur: Boolean,
+    val radiusPlatform: Float
+  )
+
+  internal fun computePlan(
+    view: ParityBlurView,
+    target: ViewGroup,
+    blurRadiusDp: Double,
+    downsampleProp: Int,
+    quality: String
+  ): Plan? {
+    if (!view.isAttachedToWindow || view.width <= 0 || view.height <= 0) return null
+    if (target.width <= 0 || target.height <= 0) return null
+
+    val density = view.resources.displayMetrics.density.toDouble()
+    val sigmaPx = PipelineMath.sigmaPxFromDp(blurRadiusDp, density)
+
+    val viewLoc = IntArray(2)
+    val targetLoc = IntArray(2)
+    view.getLocationInWindow(viewLoc)
+    target.getLocationInWindow(targetLoc)
+    // Target-local device px. getLocationInWindow() already reflects ancestor scroll offsets and
+    // transforms applied up to the window, so no separate scroll-offset bookkeeping is needed
+    // (plan §18 coordinate conversion: view -> window -> target-local).
+    val visibleRect = PipelineMath.Rect(
+      x = (viewLoc[0] - targetLoc[0]).toDouble(),
+      y = (viewLoc[1] - targetLoc[1]).toDouble(),
+      width = view.width.toDouble(),
+      height = view.height.toDouble()
+    )
+    val targetBounds = PipelineMath.Rect(0.0, 0.0, target.width.toDouble(), target.height.toDouble())
+
+    val captureRectPx = PipelineMath.expandCaptureRect(visibleRect, targetBounds, sigmaPx)
+    if (captureRectPx.width <= 0 || captureRectPx.height <= 0) return null
+
+    val downsample = PipelineMath.resolveDownsample(
+      downsampleProp,
+      sigmaPx,
+      PipelineMath.rectArea(captureRectPx),
+      quality
+    )
+    val snapshotRect = PipelineMath.snapshotRectFor(captureRectPx, downsample)
+    val cropRect = PipelineMath.cropRectFor(visibleRect, snapshotRect, downsample)
+    val sigmaSnapshot = PipelineMath.sigmaSnapshotFromPx(sigmaPx, downsample)
+    val blurParam = AndroidBlurCalibration.radiusForSigma(sigmaSnapshot)
+
+    return Plan(
+      snapshotRect = snapshotRect,
+      cropRect = cropRect,
+      downsample = downsample,
+      snapW = max(1, snapshotRect.width.toInt()),
+      snapH = max(1, snapshotRect.height.toInt()),
+      targetLocX = targetLoc[0],
+      targetLocY = targetLoc[1],
+      noBlur = blurParam.noBlur,
+      radiusPlatform = blurParam.radiusPlatform.toFloat()
+    )
+  }
+
+  fun capture(
+    view: ParityBlurView,
+    target: ViewGroup,
+    blurRadiusDp: Double,
+    downsampleProp: Int,
+    quality: String,
+    engine: BlurEngine
+  ): Result? {
+    val plan = computePlan(view, target, blurRadiusDp, downsampleProp, quality) ?: return null
+    val snapshotRect = plan.snapshotRect
+    val cropRect = plan.cropRect
+    val downsample = plan.downsample
+    val snapW = plan.snapW
+    val snapH = plan.snapH
+
+    val bitmap = engine.acquireBitmap(snapW, snapH)
+    val softCanvas = Canvas(bitmap)
+    // LOCKED rounding rule (PIPELINE_SPEC §3.3): the snapshot origin is FLOORED, so the canvas
+    // must translate by the floored*D device-px origin -- NOT the raw (possibly fractional)
+    // capture-rect origin -- to keep the bitmap's pixel (0,0) aligned with snapshotRect (0,0).
+    softCanvas.scale(1f / downsample, 1f / downsample)
+    softCanvas.translate(
+      (-(snapshotRect.x * downsample)).toFloat(),
+      (-(snapshotRect.y * downsample)).toFloat()
+    )
+    CapturePass.run { target.draw(softCanvas) }
+
+    return Result(
+      bitmap = bitmap,
+      cropRect = cropRect,
+      downsample = downsample,
+      noBlur = plan.noBlur,
+      radiusPlatform = plan.radiusPlatform
+    )
+  }
+}

package/android/src/main/java/com/parityblur/WindowBlurContext.kt

@@ -0,0 +1,116 @@
+package com.parityblur
+
+import android.view.Choreographer
+import android.view.View
+import android.view.ViewTreeObserver
+import java.util.Collections
+import java.util.WeakHashMap
+
+/**
+ * Per-window active-view registry + capture scheduling (plan §4, §14.3, §14.4, §20, §21, §39).
+ * One instance per native window (keyed by the window's root view in [BlurEngine]) --
+ * NEVER one scheduler per [ParityBlurView] (plan §45.6).
+ *
+ * STATIC mode: capture requests (refresh(), layout/prop changes) coalesce to ONE capture per
+ * view at the next frame boundary via [Choreographer.postFrameCallback] -- never synchronously
+ * inside JS-command dispatch, never invalidating from preDraw (plan §45.8).
+ *
+ * LIVE mode (Milestone 6): ONE [ViewTreeObserver.OnPreDrawListener] per window, installed only
+ * while at least one live view is registered and removed when the last leaves (plan §24: zero
+ * scheduler work when no live blur is active). Each pre-draw tick:
+ *   1. filters views by the visibility heuristic (plan §24),
+ *   2. applies the per-view maxFps throttle (plan §21: respect elapsed time),
+ *   3. recaptures INSIDE the in-flight frame -- the re-recorded RenderNode propagates its own
+ *      damage, so no invalidate() is issued from preDraw (M0-proven; plan §45).
+ * Captures here are synchronous software captures (see [ParityBlurView.performLiveCapture]),
+ * so backpressure (plan §22) is inherent: at most one capture per view per frame, and a slow
+ * frame simply delays the next tick -- no queue can form.
+ */
+class WindowBlurContext(private val rootView: View) {
+
+  /** All currently-attached ParityBlurView instances in this window (weak, for bookkeeping). */
+  private val activeViews: MutableSet<ParityBlurView> =
+    Collections.newSetFromMap(WeakHashMap())
+
+  private val pendingCaptures = LinkedHashSet<ParityBlurView>()
+  private var frameCallbackScheduled = false
+
+  private val frameCallback = Choreographer.FrameCallback {
+    frameCallbackScheduled = false
+    // Snapshot-and-clear before iterating: a capture triggered from within this callback
+    // schedules a NEW frame instead of mutating the set being iterated right now.
+    val batch = pendingCaptures.toList()
+    pendingCaptures.clear()
+    for (view in batch) {
+      if (view.isAttachedToWindow) {
+        view.performScheduledCapture()
+      }
+    }
+  }
+
+  // ------------------------------------------------------------------- live (Milestone 6)
+
+  private val liveViews: MutableSet<ParityBlurView> =
+    Collections.newSetFromMap(WeakHashMap())
+  private var preDrawInstalled = false
+
+  private val preDrawListener = ViewTreeObserver.OnPreDrawListener {
+    val now = System.nanoTime()
+    for (view in liveViews) {
+      if (view.isLiveEligible(now)) {
+        view.performLiveCapture(now)
+      }
+    }
+    true
+  }
+
+  fun register(view: ParityBlurView) {
+    activeViews.add(view)
+  }
+
+  fun unregister(view: ParityBlurView) {
+    activeViews.remove(view)
+    pendingCaptures.remove(view)
+    unregisterLive(view)
+  }
+
+  fun registerLive(view: ParityBlurView) {
+    liveViews.add(view)
+    if (!preDrawInstalled) {
+      val vto = rootView.viewTreeObserver
+      if (vto.isAlive) {
+        vto.addOnPreDrawListener(preDrawListener)
+        preDrawInstalled = true
+        ParityBlurDebug.log { "scheduler-install window=${System.identityHashCode(rootView)}" }
+      }
+    }
+  }
+
+  fun unregisterLive(view: ParityBlurView) {
+    liveViews.remove(view)
+    if (liveViews.isEmpty() && preDrawInstalled) {
+      val vto = rootView.viewTreeObserver
+      if (vto.isAlive) vto.removeOnPreDrawListener(preDrawListener)
+      preDrawInstalled = false
+      ParityBlurDebug.log { "scheduler-uninstall window=${System.identityHashCode(rootView)}" }
+    }
+  }
+
+  /**
+   * Coalesce a capture request for [view] to the next valid frame boundary. Repeated calls
+   * before the frame fires collapse into one capture (plan §14.4/§20).
+   */
+  fun scheduleCapture(view: ParityBlurView) {
+    pendingCaptures.add(view)
+    if (!frameCallbackScheduled) {
+      frameCallbackScheduled = true
+      Choreographer.getInstance().postFrameCallback(frameCallback)
+    }
+  }
+
+  fun cancelScheduledCapture(view: ParityBlurView) {
+    pendingCaptures.remove(view)
+  }
+
+  fun isEmpty(): Boolean = activeViews.isEmpty()
+}