react-native-parity-blur 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Lakhwinder Singh
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ParityBlur.podspec

@@ -0,0 +1,20 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "ParityBlur"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/lakhwindersingh/react-native-parity-blur.git", :tag => "#{s.version}" }
+
+  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  s.private_header_files = "ios/**/*.h"
+
+  install_modules_dependencies(s)
+end

package/README.md

@@ -0,0 +1,198 @@
+# react-native-parity-blur
+
+Cross-platform native backdrop blur for React Native (New Architecture / Fabric).
+
+## Why
+
+Every React Native blur library today wraps a different native primitive with a different
+default look — `UIVisualEffectView` on iOS, a custom renderscript/RenderEffect approximation on
+Android — and ships no cross-platform definition of what a given "blur amount" should look like.
+The result: the same prop value produces a visibly different blur on each platform, and there is
+no way to reason about it other than eyeballing a device.
+
+`react-native-parity-blur` starts from one canonical, documented blur pipeline
+(docs/PIPELINE_SPEC.md) — a single Gaussian-sigma unit, a single capture/downsample/blur/
+saturate/overlay order, the same edge handling, the same color space — and implements it natively
+on both platforms: real `RenderEffect` on Android (API 31+), real `MPSImageGaussianBlur` on iOS.
+The two backends were then calibrated against each other on physical devices
+(docs/CALIBRATION_REPORT.md): across 110 measured strip comparisons, the worst per-strip color
+difference is **ΔE76 0.90** and the lowest structural similarity is **SSIM 0.983** — i.e. the same
+`blurRadius` really does mean the same thing on both platforms, not just approximately.
+
+## Installation
+
+```sh
+npm install react-native-parity-blur
+```
+
+or
+
+```sh
+yarn add react-native-parity-blur
+```
+
+This library ships native Kotlin and Swift code and requires **autolinking** (no manual native
+setup) and a native rebuild after install (`pod install` for iOS, then a full app rebuild — a
+JS-only reload is not enough).
+
+### Requirements
+
+- **React Native 0.76+ with the New Architecture (Fabric) enabled.** This is a Fabric-only
+  package (`create-react-native-library` type `fabric-view`); it does not support the legacy
+  (Paper) renderer.
+- **iOS**: real blur on all supported iOS versions via Metal Performance Shaders.
+- **Android**: real blur requires **API 31+** (`RenderEffect`). Below API 31 there is no CPU blur
+  fallback by design (plan §44) — the view instead renders `fallbackColor` as a flat color. Set a
+  `fallbackColor` close to your intended blurred backdrop's average color so older devices still
+  look reasonable.
+- iOS "Reduce Transparency" (accessibility) forces the same `fallbackColor` fallback path on iOS,
+  for the same reason system blur is disabled there.
+
+## Quick start
+
+```tsx
+import { BlurView } from 'react-native-parity-blur';
+
+function BottomSheet() {
+  return (
+    <BlurView
+      style={{ position: 'absolute', left: 0, right: 0, bottom: 0, height: 280 }}
+      blurRadius={20}
+      overlayColor="rgba(16,16,16,0.35)"
+      saturation={1.4}
+      fallbackColor="rgba(20,20,20,0.92)"
+    >
+      <Text>Sharp content on top of a blurred backdrop</Text>
+    </BlurView>
+  );
+}
+```
+
+By default (`mode="static"`), the backdrop is captured once — on mount and on layout/relevant-prop
+changes — and presented as a still blurred snapshot. If content behind the view changes afterward
+without a layout change, call `refresh()` (see below) or switch to `mode="live"`.
+
+## The canonical unit: `blurRadius`
+
+`blurRadius` is a **Gaussian sigma expressed in dp** (density-independent pixels — iOS `pt` and
+Android `dp` are treated as the same unit). It is *not* a platform-native blur-radius parameter:
+internally it's converted to whatever each backend's real API expects (Android's `RenderEffect`
+radius, iOS's MPS sigma — see docs/PIPELINE_SPEC.md §2), so you write one number and get a
+calibrated, matching blur weight on both platforms. There is no "roughly similar" — see
+[Parity](#parity) below for the measured numbers.
+
+## Props
+
+| Prop | Type | Default | Semantics |
+|---|---|---|---|
+| `blurRadius` | `number` | `0` | Gaussian sigma in dp — the canonical cross-platform blur unit (see above). `0` (or omitted) renders no blur. Negative/non-finite values clamp to `0` with a DEV warning. |
+| `mode` | `'static' \| 'live'` | `'static'` | `'static'` captures the backdrop once (mount/layout/relevant-prop change) and shows a still snapshot — call `refresh()` after further backdrop changes. `'live'` recaptures continuously, throttled by `maxFps`, while the view is visible. |
+| `preset` | `BlurPresetName` | none | Named material-like preset (see [Presets](#presets)) resolved client-side to `{ blurRadius, saturation, overlayColor }` before this component's own explicit props are layered on top. Pure JS sugar — no native prop is added. |
+| `overlayColor` | `string` (color) | `'transparent'` | Straight-alpha color composited source-over the blurred + saturated result — the only tint anywhere in the pipeline (no hidden per-platform tint). Unparseable colors resolve to "no overlay" with a DEV warning. |
+| `saturation` | `number` | `1` | Post-blur, pre-overlay saturation multiplier: `1` = unchanged, `0` = Rec.709 grayscale, `>1` = boosted. Negative/non-finite values clamp to `1` with a DEV warning. |
+| `quality` | `'high' \| 'balanced' \| 'performance'` | `'balanced'` | Biases automatic downsample selection: `high` prefers 1×/2× snapshots, `balanced` prefers 2×/4×, `performance` prefers 4×/8×. No effect when `downsample` is an explicit number. |
+| `downsample` | `'auto' \| 1 \| 2 \| 4 \| 8` | `'auto'` | Snapshot downsample factor. `'auto'` derives a factor from sigma, capture area, and `quality`; an explicit factor overrides selection for advanced tuning. |
+| `maxFps` | `number` | `30` | Upper bound on live-mode recapture rate. Ignored in `'static'` mode. Clamped to `[1, 120]` with a DEV warning outside that range. |
+| `fallbackColor` | `string` (color) | none | Color rendered instead of real blur wherever real blur is unavailable (Android < API 31, or "Reduce Transparency" on either platform). No effect where real blur runs. If unset, the fallback path renders fully transparent. |
+| `blurTarget` | `React.RefObject<any>` | none | **Not implemented in v1** — accepted only to keep the public API shape stable; passing it currently has no effect. See [Known limitations](docs/LIMITATIONS.md). Planned for v1.1. |
+| `children` | `React.ReactNode` | — | Rendered on top of the blur, unaffected by it. |
+| `style` | `StyleProp<ViewStyle>` | — | Standard RN view style. `borderRadius` (and other clip styles) clip the blur output itself, not just the children. |
+
+Imperative ref:
+
+```tsx
+const blurRef = useRef<BlurViewRef>(null);
+// ...
+<BlurView ref={blurRef} mode="static" blurRadius={20}>
+  {children}
+</BlurView>
+// later, after the backdrop behind it changed:
+blurRef.current?.refresh();
+```
+
+`refresh()` schedules a coalesced recapture on the next valid frame — it is a real, fully wired
+native command on both platforms (not a stub). Repeated calls before the pending capture runs
+coalesce into a single recapture, so it's safe to call from scroll/animation callbacks.
+
+## Presets
+
+A preset is nothing more than a fixed `{ blurRadius, saturation, overlayColor }` bundle — plain
+public props, no hidden or platform-specific backend behavior (plan §11). Spread one directly:
+
+```tsx
+import { BlurPresets } from 'react-native-parity-blur';
+
+<BlurView {...BlurPresets.dark} style={styles.sheet}>
+  {children}
+</BlurView>
+```
+
+or pass the name via the `preset` prop, still overridable per-field:
+
+```tsx
+<BlurView preset="dark" blurRadius={30} style={styles.sheet}>
+  {children}
+</BlurView>
+```
+
+Available presets: `ultraThin`, `thin`, `regular`, `thick`, `chrome`, `light`, `dark`. These are
+deterministic approximations of common material "weights" (inspired by, but not measured against,
+iOS system materials) — see `src/presets.ts` for the exact values and rationale. Because
+`blurRadius`/`saturation`/`overlayColor` are calibrated cross-platform, any preset renders the same
+on iOS and Android.
+
+## Static vs. live mode
+
+- **`mode="static"`** (default): capture happens once, then the blurred result is a cheap static
+  presentation with no ongoing per-frame cost — measured at **0 rendered frames over 6s of idle
+  time** on Android (docs/HARDENING_REPORT.md). Use this for bottom sheets, modals, and any
+  backdrop that only changes on discrete events (call `refresh()` after those events).
+- **`mode="live"`** continuously recaptures the backdrop, throttled to `maxFps` (default 30) and
+  paused automatically when the view isn't visible. Use this for blur over actively scrolling or
+  animating content (e.g. a blurred header above a scrolling list). It costs strictly more than
+  static — see [Performance](docs/PERFORMANCE.md) for measured numbers and when the extra cost is
+  and isn't worth it, and note iOS live is the more expensive of the two platforms' live paths.
+
+## Parity
+
+Measured on physical devices (Android Pixel 6a API 36, iOS iPhone 14 Pro) across 5 blur radii × 6
+color/contrast fixtures × clear/tinted variants — 110 valid strip comparisons
+(docs/CALIBRATION_REPORT.md):
+
+| Metric | Worst observed | Notes |
+|---|---|---|
+| Per-strip mean ΔE76 (color) | **0.90** | at σ=32dp on a full-frame luminance ramp (screen-edge capture-support truncation); every other strip ≤ 0.64 |
+| Per-strip SSIM (structural similarity) | **0.983** | same worst-case strip; all others ≥ 0.995 |
+| Edge-crossing displacement | ≤ 0.96 dp | sub-pixel on both device rasters |
+| Overlay/saturation tint residual | ≤ 1.45 /255 | confirms the overlay and saturation math match on both platforms |
+| Convolution color space | gamma-space on both | confirmed via a checkerboard gamma-midpoint discriminator |
+
+The framing is deliberately "perceptually matched within documented tolerance," not pixel-identical
+— exact pixel identity isn't guaranteed (and isn't the goal) across OS versions, GPU vendors, and
+device scales. See docs/CALIBRATION_REPORT.md for the full methodology and per-fixture breakdown,
+and docs/PIPELINE_SPEC.md for the locked pipeline both backends implement.
+
+## Known limitations & performance
+
+- [docs/LIMITATIONS.md](docs/LIMITATIONS.md) — cross-window/Modal capture, surface-backed content
+  (video/camera/maps), static-mode staleness, iOS live cost, nested-blur semantics, `blurTarget`
+  status, and more.
+- [docs/PERFORMANCE.md](docs/PERFORMANCE.md) — measured frame/GPU costs, static-vs-live guidance,
+  downsample/quality tuning, `maxFps` guidance.
+- [docs/PIPELINE_SPEC.md](docs/PIPELINE_SPEC.md) — the normative, language-neutral pipeline spec
+  both native backends implement.
+- [docs/CALIBRATION_REPORT.md](docs/CALIBRATION_REPORT.md) — the full parity measurement report.
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+- [Code of conduct](CODE_OF_CONDUCT.md)
+
+## License
+
+MIT
+
+---
+
+Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)

package/android/build.gradle

@@ -0,0 +1,57 @@
+buildscript {
+  ext.ParityBlur = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return ParityBlur[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.parityblur"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+
+  // Minimal JVM unit-test setup for the Milestone 3 pipeline-fixture parity suite
+  // (android/src/test/java/com/parityblur/PipelineFixturesTest.kt). Pure JUnit4 -- the
+  // AndroidBlurCalibration/PipelineMath classes under test have no android.* imports, so no
+  // Robolectric/instrumentation is needed.
+  testImplementation "junit:junit:4.13.2"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

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

@@ -0,0 +1,82 @@
+package com.parityblur
+
+/**
+ * Locked calibration constants (docs/PIPELINE_SPEC.md §1-2, plan §5.2, §10, §12-13).
+ *
+ * Exact Kotlin mirror of `src/pipeline/constants.ts` + `src/pipeline/androidCalibration.ts`.
+ * This is the SINGLE home for the HWUI sigma<->radius relation and the other locked pipeline
+ * constants on the Android side (plan §45.10: do not hard-code Android conversion logic
+ * throughout the codebase). `android/src/test/.../PipelineFixturesTest.kt` asserts these
+ * functions match `test/pipeline-fixtures.json` within 1e-6.
+ *
+ * All math here is pure Double arithmetic with NO android.* imports, so it is testable as a
+ * plain JVM unit test without Robolectric.
+ */
+object AndroidBlurCalibration {
+
+  /**
+   * HWUI RenderEffect Gaussian relation, verified exact on a Pixel 6a (API 36) in M0:
+   * `sigma = HWUI_SIGMA_SLOPE * radiusPlatform + HWUI_SIGMA_INTERCEPT`.
+   */
+  const val HWUI_SIGMA_SLOPE: Double = 0.57735
+  const val HWUI_SIGMA_INTERCEPT: Double = 0.5
+
+  /**
+   * Below this snapshot-domain sigma the inverse radius is non-positive, so we emit a no-blur
+   * passthrough instead of feeding a bogus radius to RenderEffect.createBlurEffect. Equal to
+   * HWUI_SIGMA_INTERCEPT by construction (radius 0 <=> sigma 0.5).
+   */
+  const val ANDROID_MIN_BLUR_SIGMA: Double = HWUI_SIGMA_INTERCEPT
+
+  /** Gaussian support multiplier for capture expansion (plan §7). */
+  const val CAPTURE_SUPPORT_K: Double = 3.0
+
+  /** Auto-downsample: keep sigmaSnapshot = sigmaPx / D >= this many snapshot px. */
+  const val MIN_SIGMA_SNAPSHOT: Double = 1.0
+
+  /**
+   * Auto-downsample: captures with area (device px^2) below this are capped at 2x.
+   * 256 * 256 device px.
+   */
+  const val SMALL_CAPTURE_AREA_PX: Double = 256.0 * 256.0
+
+  /** Auto-downsample: per-quality ceiling on the downsample factor (plan §13). */
+  const val QUALITY_MAX_DOWNSAMPLE_HIGH: Int = 2
+  const val QUALITY_MAX_DOWNSAMPLE_BALANCED: Int = 4
+  const val QUALITY_MAX_DOWNSAMPLE_PERFORMANCE: Int = 8
+
+  /** Rec. 709 luminance coefficients (plan §10), used by the saturation matrix. */
+  const val LUMA_R: Double = 0.2126
+  const val LUMA_G: Double = 0.7152
+  const val LUMA_B: Double = 0.0722
+
+  /**
+   * Result of [radiusForSigma]. [radiusPlatform] is always >= 0; it is 0 when [noBlur] is true.
+   * `radiusPlatform` is intentionally Double (not Float) so the pure-math mirror can be asserted
+   * against the fixture table within 1e-6 -- callers cast to Float only at the RenderEffect call
+   * site.
+   */
+  data class BlurParam(val noBlur: Boolean, val radiusPlatform: Double)
+
+  /**
+   * Forward relation, exposed for tests/verification: the sigma HWUI produces for a given
+   * platform radius.
+   */
+  fun sigmaForRadius(radiusPlatform: Double): Double =
+    HWUI_SIGMA_SLOPE * radiusPlatform + HWUI_SIGMA_INTERCEPT
+
+  /**
+   * Inverse relation: the platform radius required to achieve a target snapshot-domain sigma.
+   * Below the intercept this returns a no-blur result. Monotonically non-decreasing in
+   * sigmaSnapshot. Exact mirror of androidCalibration.ts `radiusForSigma`.
+   */
+  fun radiusForSigma(sigmaSnapshot: Double): BlurParam {
+    if (!sigmaSnapshot.isFinite() || sigmaSnapshot <= ANDROID_MIN_BLUR_SIGMA) {
+      return BlurParam(noBlur = true, radiusPlatform = 0.0)
+    }
+    return BlurParam(
+      noBlur = false,
+      radiusPlatform = (sigmaSnapshot - HWUI_SIGMA_INTERCEPT) / HWUI_SIGMA_SLOPE
+    )
+  }
+}

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

@@ -0,0 +1,132 @@
+package com.parityblur
+
+import android.content.ComponentCallbacks2
+import android.content.Context
+import android.content.res.Configuration
+import android.graphics.Bitmap
+import android.util.Log
+import android.view.View
+import java.util.WeakHashMap
+
+/**
+ * Process-wide blur engine (plan §4, §14.5, §26, §27).
+ *
+ * Created LAZILY on first eligible capture -- NEVER at class load / package init / module
+ * import. API<31 and no-blur-only [ParityBlurView] instances must never call [get] (plan §27,
+ * §45.1); enforcing that is the caller's responsibility (see ParityBlurView.isRealBlurSupported).
+ *
+ * Holds:
+ *  - trim-memory registration (ComponentCallbacks2) that clears the bitmap pool under memory
+ *    pressure (plan §26).
+ *  - a small bitmap pool keyed by (width, height), capped in retained bytes (plan §14.5: a pool
+ *    is justified here because the software capture path allocates a bitmap per capture --
+ *    M0-REPORT "Plan amendments" #2).
+ *  - a weak per-window registry of [WindowBlurContext] (plan §4), keyed by each window's root
+ *    view so contexts disappear with their window and are never a source of leaks.
+ */
+class BlurEngine private constructor() : ComponentCallbacks2 {
+
+  private val bitmapPool = HashMap<Long, MutableList<Bitmap>>()
+  private var pooledBytes = 0L
+
+  private val windowContexts = WeakHashMap<View, WindowBlurContext>()
+
+  @Synchronized
+  fun windowContextFor(rootView: View): WindowBlurContext {
+    return windowContexts.getOrPut(rootView) { WindowBlurContext(rootView) }
+  }
+
+  @Synchronized
+  fun releaseWindowContext(rootView: View) {
+    windowContexts.remove(rootView)
+  }
+
+  /** Acquire a pooled ARGB_8888 bitmap sized exactly (width x height), or allocate one. */
+  @Synchronized
+  fun acquireBitmap(width: Int, height: Int): Bitmap {
+    val key = poolKey(width, height)
+    val bucket = bitmapPool[key]
+    val reused = if (!bucket.isNullOrEmpty()) bucket.removeAt(bucket.size - 1) else null
+    if (reused != null && !reused.isRecycled) {
+      pooledBytes -= reused.allocationByteCount.toLong()
+      reused.eraseColor(0)
+      return reused
+    }
+    return Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888)
+  }
+
+  /** Return a bitmap to the pool for reuse, capping total retained bytes (plan §14.5). */
+  @Synchronized
+  fun releaseBitmap(bitmap: Bitmap) {
+    if (bitmap.isRecycled) return
+    val size = bitmap.allocationByteCount.toLong()
+    if (pooledBytes + size > MAX_POOL_BYTES) {
+      // Do not grow unbounded and do not evict-and-thrash; just drop this one (plan §45.13:
+      // do not pool large resources without measured need -- keep the cap conservative).
+      return
+    }
+    val key = poolKey(bitmap.width, bitmap.height)
+    val bucket = bitmapPool.getOrPut(key) { mutableListOf() }
+    bucket.add(bitmap)
+    pooledBytes += size
+  }
+
+  @Synchronized
+  private fun clearPool() {
+    for (bucket in bitmapPool.values) {
+      for (bmp in bucket) if (!bmp.isRecycled) bmp.recycle()
+      bucket.clear()
+    }
+    bitmapPool.clear()
+    pooledBytes = 0L
+  }
+
+  // ------------------------------------------------------- ComponentCallbacks2 (plan §26)
+
+  @Suppress("DEPRECATION")
+  override fun onTrimMemory(level: Int) {
+    if (level >= ComponentCallbacks2.TRIM_MEMORY_RUNNING_LOW ||
+      level == ComponentCallbacks2.TRIM_MEMORY_UI_HIDDEN
+    ) {
+      Log.d(TAG, "onTrimMemory($level): clearing bitmap pool ($pooledBytes bytes)")
+      clearPool()
+    }
+  }
+
+  override fun onConfigurationChanged(newConfig: Configuration) = Unit
+
+  @Suppress("OVERRIDE_DEPRECATION")
+  override fun onLowMemory() {
+    clearPool()
+  }
+
+  companion object {
+    private const val TAG = "ParityBlur.Engine"
+
+    /** Conservative retained-bitmap cap; snapshots are already downsampled (plan §14.5). */
+    private const val MAX_POOL_BYTES = 16L * 1024 * 1024 // 16 MiB
+
+    @Volatile
+    private var instance: BlurEngine? = null
+
+    /**
+     * Lazily create (or return) the process-wide engine. MUST be called only from the first
+     * eligible real-blur capture path -- never from class init, static fields, or fallback-only
+     * view code (plan §27, §45.1).
+     */
+    fun get(context: Context): BlurEngine {
+      instance?.let { return it }
+      synchronized(this) {
+        instance?.let { return it }
+        val created = BlurEngine()
+        context.applicationContext.registerComponentCallbacks(created)
+        instance = created
+        ParityBlurDebug.log { "engine-init" }
+        return created
+      }
+    }
+
+    private fun poolKey(width: Int, height: Int): Long =
+      (width.toLong() shl 32) or (height.toLong() and 0xffffffffL)
+  }
+}

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

@@ -0,0 +1,24 @@
+package com.parityblur
+
+import android.util.Log
+
+/**
+ * Milestone 7 laziness/lifecycle instrumentation (plan §42.4, §40).
+ *
+ * Gated behind [ENABLED], which defaults to `false` so a shipped build pays zero cost here (no
+ * fields mutated, no string built, no log call made -- the `inline` + constant-folded branch is
+ * dropped by the compiler). Flip to `true` only for local hardening runs to prove:
+ *   - package import -> no engine init (nothing logs before the first eligible capture)
+ *   - first eligible BlurView -> "engine-init" logs exactly once per process
+ *   - live registration -> "scheduler-install"/"scheduler-uninstall" bracket the live window
+ *   - detach -> "instance-release" logs for every ParityBlurView, live or static
+ */
+internal object ParityBlurDebug {
+  const val ENABLED = false // debug-only laziness/lifecycle instrumentation (plan §42.4); flip true for local hardening runs
+
+  private const val TAG = "ParityBlur.Debug"
+
+  inline fun log(event: () -> String) {
+    if (ENABLED) Log.d(TAG, event())
+  }
+}

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

@@ -0,0 +1,17 @@
+package com.parityblur
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import com.facebook.react.uimanager.ViewManager
+
+class ParityBlurViewPackage : BaseReactPackage() {
+  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
+    return listOf(ParityBlurViewManager())
+  }
+
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? = null
+
+  override fun getReactModuleInfoProvider() = ReactModuleInfoProvider { emptyMap() }
+}