react-native-parity-blur 0.1.0

package/lib/typescript/src/pipeline/units.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Canonical unit conversions (plan §5.1).
+ *
+ * INTERNAL MODULE. Pure functions, no side effects, no react-native imports.
+ *
+ *   blurRadius   = Gaussian sigma in dp (public unit)
+ *   sigmaPx      = blurRadius * displayScale         (device pixels)
+ *   sigmaSnapshot= sigmaPx / D                        (downsampled snapshot px)
+ *
+ * The blur backend always receives a parameter derived from sigmaSnapshot.
+ */
+import type { Downsample } from './types.js';
+/**
+ * Convert the public blurRadius (sigma in dp) to sigma in device pixels.
+ * Non-finite or negative inputs clamp to 0 (plan §28 safe clamping).
+ */
+export declare function sigmaPxFromDp(blurRadiusDp: number, displayScale: number): number;
+/**
+ * Convert device-pixel sigma to snapshot-domain sigma given a downsample
+ * factor D. D is a positive integer in {1,2,4,8}.
+ */
+export declare function sigmaSnapshotFromPx(sigmaPx: number, downsample: Downsample): number;
+//# sourceMappingURL=units.d.ts.map

package/lib/typescript/src/pipeline/units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../../../../src/pipeline/units.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAS,CAAC;AAE1C;;;GAGG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAIhF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM,CAGnF"}

package/lib/typescript/src/presets.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Material-like presets (plan §11, plan §41 / Milestone 8).
+ *
+ * A preset is nothing more than a fixed, explicit
+ * `{ blurRadius, saturation, overlayColor }` prop bundle. There is no
+ * hidden or platform-specific behavior: applying `BlurPresets.dark` is
+ * exactly equivalent to spreading that plain object onto `<BlurView>`
+ * yourself, and the resulting three numbers/strings go through the same
+ * calibrated pipeline as any other explicit props (docs/PIPELINE_SPEC.md).
+ * Because blurRadius/saturation/overlayColor are calibrated to match
+ * cross-platform (docs/CALIBRATION_REPORT.md — worst measured ΔE76 0.90,
+ * SSIM ≥ 0.983), a given preset renders the same on iOS and Android.
+ *
+ * These are *approximations* of the visual weight of iOS system materials
+ * (UIBlurEffect styles), chosen by eye against reasonable blurRadius /
+ * saturation / overlayColor values — they are not derived from, measured
+ * against, or guaranteed to match `UIVisualEffectView` output, and Android
+ * has no equivalent native material to match at all. Treat the names as a
+ * starting point, not a parity claim (plan §43 — nested/material stacking
+ * is deterministic, not an Apple material emulation).
+ *
+ * Usage:
+ * ```tsx
+ * <BlurView {...BlurPresets.dark} style={styles.sheet}>
+ *   {children}
+ * </BlurView>
+ * ```
+ *
+ * Every field is a plain public prop, so you can still override any one of
+ * them by spreading the preset first and your own prop second:
+ * ```tsx
+ * <BlurView {...BlurPresets.dark} blurRadius={30} />
+ * ```
+ *
+ * Or, for the same effect without spreading, pass the `preset` prop
+ * directly to `<BlurView>` (`src/BlurView.tsx`) — it resolves to this same
+ * object client-side before any explicit blurRadius/saturation/overlayColor
+ * prop is applied on top of it. Both forms are pure JS convenience; neither
+ * adds a native prop.
+ */
+/** One named preset: an explicit bundle of public BlurView props. */
+export interface BlurPreset {
+    /** Gaussian sigma in dp — see `BlurViewProps.blurRadius`. */
+    blurRadius: number;
+    /** See `BlurViewProps.saturation`. */
+    saturation: number;
+    /** See `BlurViewProps.overlayColor`. */
+    overlayColor: string;
+}
+/** Keys of {@link BlurPresets}. */
+export type BlurPresetName = 'ultraThin' | 'thin' | 'regular' | 'thick' | 'chrome' | 'light' | 'dark';
+/**
+ * Named material-like preset table. See the module doc comment above for
+ * semantics and the "not a parity claim" caveat.
+ */
+export declare const BlurPresets: Readonly<Record<BlurPresetName, BlurPreset>>;
+//# sourceMappingURL=presets.d.ts.map

package/lib/typescript/src/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../../src/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,mCAAmC;AACnC,MAAM,MAAM,cAAc,GACxB,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3E;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,UAAU,CAAC,CA2CpE,CAAC"}

package/lib/typescript/src/types.d.ts

@@ -0,0 +1,116 @@
+import type * as React from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { BlurPresetName } from './presets.js';
+/** Public blur mode (plan §20/§21). default: 'static'. */
+export type BlurMode = 'static' | 'live';
+/** Public quality tier (plan §13). default: 'balanced'. */
+export type BlurQuality = 'high' | 'balanced' | 'performance';
+/** Public downsample selector (plan §12). default: 'auto'. */
+export type BlurDownsample = 'auto' | 1 | 2 | 4 | 8;
+export interface BlurViewProps {
+    /**
+     * Gaussian sigma in dp (plan §5.1) — the same canonical unit on both
+     * platforms (iOS pt ≡ Android dp semantically). Internally converted to
+     * each native backend's own blur parameter (docs/PIPELINE_SPEC.md §2), so
+     * the same number produces calibrated matching visual weight on iOS and
+     * Android (worst measured ΔE76 0.90, SSIM ≥ 0.983 across the parity
+     * suite — docs/CALIBRATION_REPORT.md). `0` (or omitted) renders no blur.
+     * Non-finite or negative values clamp to 0 with a DEV warning.
+     * default: 0.
+     */
+    blurRadius?: number;
+    /**
+     * `'static'` captures the backdrop once (on mount, layout change, or a
+     * prop change that affects the capture) and presents a still blurred
+     * snapshot; call `refresh()` to recapture after the backdrop changes
+     * underneath it. `'live'` recaptures continuously (throttled by
+     * `maxFps`) while the view is on screen. default: 'static'.
+     */
+    mode?: BlurMode;
+    /**
+     * Named material-like preset (plan §11) resolved client-side to a base
+     * `{ blurRadius, saturation, overlayColor }` bundle before this
+     * component's own explicit props are applied on top — see
+     * `BlurPresets`/`BlurPresetName` in `presets.ts` for the exact values.
+     * Pure JS convenience: it does not add a native prop, and any of those
+     * three props passed explicitly alongside `preset` overrides the
+     * preset's value for that prop only. default: none.
+     */
+    preset?: BlurPresetName;
+    /**
+     * Straight-alpha color composited source-over the blurred + saturated
+     * result (docs/PIPELINE_SPEC.md §8) — the only tint anywhere in the
+     * pipeline; there is no hidden per-platform tint. An unparseable color
+     * resolves to "no overlay" with a DEV warning. default: 'transparent'
+     * (no overlay).
+     */
+    overlayColor?: string;
+    /**
+     * Post-blur saturation multiplier (docs/PIPELINE_SPEC.md §7), applied
+     * after blur and before the overlay: `1` = unchanged, `0` = Rec.709
+     * grayscale, values `> 1` boost saturation. Negative or non-finite values
+     * clamp to the default with a DEV warning. default: 1.
+     */
+    saturation?: number;
+    /**
+     * Consumer-friendly quality tier that biases automatic downsample
+     * selection (plan §13): `'high'` prefers 1x/2x snapshots, `'balanced'`
+     * prefers 2x/4x, `'performance'` prefers 4x/8x. Has no effect when
+     * `downsample` is an explicit numeric override. default: 'balanced'.
+     */
+    quality?: BlurQuality;
+    /**
+     * Snapshot downsample factor (plan §12). `'auto'` derives a factor from
+     * requested sigma, capture area, and `quality` (docs/PIPELINE_SPEC.md
+     * §4); `1 | 2 | 4 | 8` forces that exact factor for advanced tuning.
+     * default: 'auto'.
+     */
+    downsample?: BlurDownsample;
+    /**
+     * Upper bound on live-mode recapture rate, in frames per second. Ignored
+     * in `'static'` mode. Clamped to `[1, 120]` with a DEV warning outside
+     * that range. default: 30.
+     */
+    maxFps?: number;
+    /**
+     * Color rendered in place of a real blur wherever real blur is
+     * unavailable: Android below API 31 (no `RenderEffect`) or, on either
+     * platform, when the OS-level "Reduce Transparency" accessibility
+     * setting is on. Has no effect on a device/OS combination where real
+     * blur runs. default: none (renders fully transparent when the fallback
+     * path is active and no `fallbackColor` is set).
+     */
+    fallbackColor?: string;
+    /**
+     * Target view whose subtree should be captured as the blur backdrop,
+     * instead of the default (the content behind this `BlurView` within its
+     * own window) (plan §18). **Not implemented in v1** — accepted only to
+     * keep the public API shape stable for a later release; passing it
+     * currently has no native-side effect. Deferred to v1.1 — see
+     * docs/LIMITATIONS.md.
+     */
+    blurTarget?: React.RefObject<any>;
+    /** Content rendered on top of the blur; unaffected by it. */
+    children?: React.ReactNode;
+    /**
+     * Standard React Native view style. `borderRadius` (and other clipping
+     * styles) clip the blur output itself, not just the children (plan §31).
+     */
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * Imperative handle exposed via ref (plan §29).
+ */
+export interface BlurViewRef {
+    /**
+     * Schedules a coalesced recapture of the backdrop on the next valid
+     * frame — fully implemented end-to-end on both native backends (not a
+     * no-op). Repeated calls before the pending capture runs coalesce into a
+     * single recapture. Primarily useful in `mode="static"` after the
+     * backdrop has changed; in `mode="live"` the view is already recapturing
+     * continuously, so `refresh()` has no additional effect beyond nudging
+     * the next scheduled frame.
+     */
+    refresh(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAW,CAAC;AAEhD,0DAA0D;AAC1D,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEzC,2DAA2D;AAC3D,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,aAAa,CAAC;AAE9D,8DAA8D;AAC9D,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAEpD,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAEhB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IAExB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAE5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAElC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAE3B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;OAQG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB"}

package/package.json

@@ -0,0 +1,167 @@
+{
+  "name": "react-native-parity-blur",
+  "version": "0.1.0",
+  "description": "Cross-platform native backdrop blur for React Native (Fabric)",
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "react-native-parity-blur-source": "./src/index.ts",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "cpp",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace react-native-parity-blur-example",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "prepare": "bob build",
+    "typecheck": "tsc",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "test": "jest"
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "android",
+    "blur",
+    "backdrop-blur",
+    "glassmorphism",
+    "fabric",
+    "new-architecture"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lakhwindersingh/react-native-parity-blur.git"
+  },
+  "author": "Lakhwinder Singh <luckysingh781@gmail.com> (https://github.com/lakhwindersingh)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/lakhwindersingh/react-native-parity-blur/issues"
+  },
+  "homepage": "https://github.com/lakhwindersingh/react-native-parity-blur#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@commitlint/config-conventional": "^21.0.2",
+    "@eslint/compat": "^2.1.0",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^10.0.1",
+    "@jest/globals": "^29.7.0",
+    "@react-native/babel-preset": "0.85.0",
+    "@react-native/eslint-config": "0.85.0",
+    "@react-native/jest-preset": "0.85.0",
+    "@types/react": "^19.2.0",
+    "commitlint": "^21.0.2",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-ft-flow": "^3.0.11",
+    "eslint-plugin-prettier": "^5.5.6",
+    "jest": "^29.7.0",
+    "lefthook": "^2.1.9",
+    "prettier": "^3.8.3",
+    "react": "19.2.3",
+    "react-native": "0.85.0",
+    "react-native-builder-bob": "^0.43.0",
+    "turbo": "^2.9.16",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "workspaces": [
+    "example"
+  ],
+  "packageManager": "yarn@4.11.0",
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "codegenConfig": {
+    "name": "ParityBlurViewSpec",
+    "type": "all",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.parityblur"
+    },
+    "ios": {
+      "components": {
+        "ParityBlurView": {
+          "className": "ParityBlurView"
+        }
+      }
+    }
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "jest": {
+    "preset": "@react-native/jest-preset",
+    "testEnvironmentOptions": {
+      "customExportConditions": [
+        "require",
+        "react-native",
+        "react-native-parity-blur-source"
+      ]
+    },
+    "modulePathIgnorePatterns": [
+      "<rootDir>/example/node_modules",
+      "<rootDir>/lib/"
+    ]
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "create-react-native-library": {
+    "type": "fabric-view",
+    "languages": "kotlin-objc",
+    "tools": [
+      "eslint",
+      "jest",
+      "lefthook"
+    ],
+    "version": "0.63.0"
+  }
+}

package/src/BlurView.tsx

@@ -0,0 +1,195 @@
+import * as React from 'react';
+
+import NativeParityBlurView, {
+  Commands as NativeCommands,
+} from './ParityBlurViewNativeComponent';
+import {
+  DEFAULT_BLUR_RADIUS,
+  DEFAULT_DOWNSAMPLE,
+  DEFAULT_MAX_FPS,
+  DEFAULT_MODE,
+  DEFAULT_OVERLAY_COLOR,
+  DEFAULT_QUALITY,
+  DEFAULT_SATURATION,
+  MAX_MAX_FPS,
+  MIN_MAX_FPS,
+} from './defaults';
+import { BlurPresets } from './presets';
+import type { BlurDownsample, BlurViewProps, BlurViewRef } from './types';
+
+declare const __DEV__: boolean;
+
+const LOG_TAG = '[react-native-parity-blur]';
+
+function clampBlurRadius(value: number | undefined): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return DEFAULT_BLUR_RADIUS;
+  }
+  return value < 0 ? 0 : value;
+}
+
+function clampSaturation(value: number | undefined): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return DEFAULT_SATURATION;
+  }
+  return value < 0 ? 0 : value;
+}
+
+function clampMaxFps(value: number | undefined): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return DEFAULT_MAX_FPS;
+  }
+  return Math.min(MAX_MAX_FPS, Math.max(MIN_MAX_FPS, value));
+}
+
+/**
+ * Normalizes the public `downsample` prop (`'auto' | 1 | 2 | 4 | 8`) into the
+ * Int32 the native Fabric prop accepts, where `0` is a sentinel for `'auto'`.
+ * See the deviation note in ParityBlurViewNativeComponent.ts for why this
+ * isn't a string/numeric enum.
+ */
+function normalizeDownsample(
+  value: BlurDownsample | undefined
+): 0 | 1 | 2 | 4 | 8 {
+  if (value === undefined || value === 'auto') {
+    return 0;
+  }
+  if (value === 1 || value === 2 || value === 4 || value === 8) {
+    return value;
+  }
+  if (__DEV__) {
+    console.warn(
+      `${LOG_TAG} Invalid "downsample" value: ${JSON.stringify(
+        value
+      )}. Expected 'auto' | 1 | 2 | 4 | 8. Falling back to '${DEFAULT_DOWNSAMPLE}'.`
+    );
+  }
+  return 0;
+}
+
+type NativeInstance = React.ComponentRef<typeof NativeParityBlurView>;
+
+/**
+ * Public backdrop blur component (plan §28/§29/§30).
+ *
+ * Renders the native ParityBlurView host view backed by a real blur on both
+ * platforms: Android API 31+ real-time `RenderEffect` Gaussian blur (older
+ * Android renders `fallbackColor` instead — real CPU blur is intentionally
+ * out of scope, plan §44), iOS `MPSImageGaussianBlur`. `refresh()` is fully
+ * wired to a native coalesced recapture (plan §29). See
+ * docs/PIPELINE_SPEC.md for the canonical pipeline both backends implement
+ * and docs/CALIBRATION_REPORT.md for measured cross-platform parity.
+ */
+export const BlurView = React.forwardRef<BlurViewRef, BlurViewProps>(
+  function BlurView(props, ref) {
+    const {
+      preset,
+      blurRadius,
+      mode = DEFAULT_MODE,
+      overlayColor,
+      saturation,
+      quality = DEFAULT_QUALITY,
+      downsample,
+      maxFps,
+      fallbackColor,
+      // Accepted for public-API shape stability (plan §18); not yet wired
+      // to native capture logic. Deferred to v1.1 — see docs/LIMITATIONS.md.
+      blurTarget: _blurTarget,
+      children,
+      style,
+    } = props;
+
+    // A preset (plan §11) is pure JS sugar for a base
+    // { blurRadius, saturation, overlayColor } bundle — resolved here,
+    // client-side, with no native awareness of presets at all. Any of
+    // those three props passed explicitly above still wins per-prop.
+    const presetProps = preset ? BlurPresets[preset] : undefined;
+    const resolvedBlurRadius = blurRadius ?? presetProps?.blurRadius;
+    const resolvedSaturation = saturation ?? presetProps?.saturation;
+    const resolvedOverlayColor =
+      overlayColor ?? presetProps?.overlayColor ?? DEFAULT_OVERLAY_COLOR;
+
+    const nativeRef = React.useRef<NativeInstance>(null);
+
+    React.useImperativeHandle(
+      ref,
+      (): BlurViewRef => ({
+        refresh() {
+          if (nativeRef.current) {
+            NativeCommands.refresh(nativeRef.current);
+          }
+        },
+      }),
+      []
+    );
+
+    if (__DEV__) {
+      if (preset !== undefined && !(preset in BlurPresets)) {
+        console.warn(
+          `${LOG_TAG} Unknown "preset" value: ${JSON.stringify(preset)}. Ignoring.`
+        );
+      }
+      if (
+        blurRadius !== undefined &&
+        (typeof blurRadius !== 'number' ||
+          !Number.isFinite(blurRadius) ||
+          blurRadius < 0)
+      ) {
+        console.warn(
+          `${LOG_TAG} "blurRadius" must be a finite number >= 0. Received: ${blurRadius}. Clamping to ${clampBlurRadius(
+            blurRadius
+          )}.`
+        );
+      }
+      if (
+        saturation !== undefined &&
+        (typeof saturation !== 'number' ||
+          !Number.isFinite(saturation) ||
+          saturation < 0)
+      ) {
+        console.warn(
+          `${LOG_TAG} "saturation" must be a finite number >= 0. Received: ${saturation}. Clamping to ${clampSaturation(
+            saturation
+          )}.`
+        );
+      }
+      if (
+        maxFps !== undefined &&
+        (typeof maxFps !== 'number' ||
+          !Number.isFinite(maxFps) ||
+          maxFps < MIN_MAX_FPS ||
+          maxFps > MAX_MAX_FPS)
+      ) {
+        console.warn(
+          `${LOG_TAG} "maxFps" must be a finite number between ${MIN_MAX_FPS} and ${MAX_MAX_FPS}. Received: ${maxFps}. Clamping to ${clampMaxFps(
+            maxFps
+          )}.`
+        );
+      }
+    }
+
+    const safeBlurRadius = clampBlurRadius(resolvedBlurRadius);
+    const safeSaturation = clampSaturation(resolvedSaturation);
+    const safeMaxFps = clampMaxFps(maxFps);
+    const safeDownsample = normalizeDownsample(downsample);
+
+    return (
+      <NativeParityBlurView
+        ref={nativeRef}
+        style={style}
+        blurRadius={safeBlurRadius}
+        mode={mode}
+        overlayColor={resolvedOverlayColor}
+        saturation={safeSaturation}
+        quality={quality}
+        downsample={safeDownsample}
+        maxFps={safeMaxFps}
+        fallbackColor={fallbackColor}
+      >
+        {children}
+      </NativeParityBlurView>
+    );
+  }
+);
+
+export default BlurView;

package/src/ParityBlurViewNativeComponent.ts

@@ -0,0 +1,82 @@
+/**
+ * Fabric codegen spec for the ParityBlurView native host view.
+ *
+ * Every public prop from plan §28 is plumbed through to native, and the
+ * `refresh()` Fabric command is wired end-to-end to a real coalesced
+ * recapture. Both native backends (Android Kotlin, iOS Swift) implement the
+ * real capture/blur/saturate/overlay pipeline defined in
+ * docs/PIPELINE_SPEC.md — this file only declares the codegen shape, not
+ * the behavior.
+ *
+ * Deviation from plan §28 (documented in the Milestone 1 report): the public
+ * `downsample` prop is `'auto' | 1 | 2 | 4 | 8` (see src/types.ts). Fabric
+ * codegen's TypeScript parser rejects a union that mixes string and numeric
+ * literals for one prop ("Mixed types are not supported"), and a plain
+ * string enum with numeric-looking values ('1', '2', ...) is also unsafe
+ * because the iOS/C++ generator turns each enum option into a bare
+ * identifier (`ParityBlurViewDownsample::1` is not valid C++). Instead this
+ * native prop is a plain Int32 where `0` is a sentinel for `'auto'` and
+ * `1 | 2 | 4 | 8` pass through unchanged. `src/BlurView.tsx` performs the
+ * 'auto' <-> 0 translation; native code treats 0 as "auto".
+ *
+ * Note: this file deliberately imports everything from the 'react-native'
+ * package root rather than deep 'react-native/Libraries/...' paths. This
+ * project's tsconfig opts into the `react-native-strict-api` custom
+ * condition, and react-native's package.json `exports` map explicitly
+ * blocks deep `Libraries/*` subpath imports under that condition -- so
+ * `codegenNativeCommands`, `codegenNativeComponent`, and the CodegenTypes
+ * (Double/Int32/WithDefault) must come from the root barrel, which
+ * re-exports all three for exactly this reason.
+ *
+ * Also note: do NOT re-export `CodegenTypes.WithDefault`/`Double`/`Int32` as
+ * local generic type aliases (an earlier draft of this file did, to shorten
+ * the qualified names). @react-native/codegen's alias resolution does plain
+ * textual substitution with no generic instantiation, so a chain like
+ * `NativeBlurMode -> WithDefault<'static'|'live','static'> -> (local
+ * `WithDefault<Type,Value>` alias) -> CodegenTypes.WithDefault<Type,Value>`
+ * loses the real type arguments and fails with "The default value in
+ * WithDefault must be string, number, boolean or null." Referencing
+ * `CodegenTypes.WithDefault<...>` directly (qualified) avoids the extra
+ * alias hop and keeps the real arguments intact.
+ */
+import {
+  codegenNativeCommands,
+  codegenNativeComponent,
+  type CodegenTypes,
+  type ColorValue,
+  type HostComponent,
+  type ViewProps,
+} from 'react-native';
+import type * as React from 'react';
+
+type NativeBlurMode = CodegenTypes.WithDefault<'static' | 'live', 'static'>;
+type NativeBlurQuality = CodegenTypes.WithDefault<
+  'high' | 'balanced' | 'performance',
+  'balanced'
+>;
+
+export interface NativeProps extends ViewProps {
+  blurRadius?: CodegenTypes.WithDefault<CodegenTypes.Double, 0>;
+  mode?: NativeBlurMode;
+  overlayColor?: ColorValue;
+  saturation?: CodegenTypes.WithDefault<CodegenTypes.Double, 1>;
+  quality?: NativeBlurQuality;
+  // 0 = 'auto' sentinel; see file-level deviation note above.
+  downsample?: CodegenTypes.WithDefault<CodegenTypes.Int32, 0>;
+  maxFps?: CodegenTypes.WithDefault<CodegenTypes.Int32, 30>;
+  fallbackColor?: ColorValue;
+}
+
+type ComponentType = HostComponent<NativeProps>;
+
+interface NativeCommands {
+  refresh: (viewRef: React.ComponentRef<ComponentType>) => void;
+}
+
+export const Commands: NativeCommands = codegenNativeCommands<NativeCommands>({
+  supportedCommands: ['refresh'],
+});
+
+export default codegenNativeComponent<NativeProps>(
+  'ParityBlurView'
+) as ComponentType;

package/src/defaults.ts

@@ -0,0 +1,20 @@
+import type { BlurDownsample, BlurMode, BlurQuality } from './types';
+
+export const DEFAULT_BLUR_RADIUS = 0;
+export const DEFAULT_MODE: BlurMode = 'static';
+export const DEFAULT_OVERLAY_COLOR = 'transparent';
+export const DEFAULT_SATURATION = 1;
+export const DEFAULT_QUALITY: BlurQuality = 'balanced';
+export const DEFAULT_DOWNSAMPLE: BlurDownsample = 'auto';
+export const DEFAULT_MAX_FPS = 30;
+
+export const MIN_MAX_FPS = 1;
+export const MAX_MAX_FPS = 120;
+
+export const ALLOWED_DOWNSAMPLE_VALUES: ReadonlyArray<BlurDownsample> = [
+  'auto',
+  1,
+  2,
+  4,
+  8,
+];