react-native-parity-blur 0.1.0

package/src/index.ts

@@ -0,0 +1,10 @@
+export { BlurView, default } from './BlurView';
+export type {
+  BlurDownsample,
+  BlurMode,
+  BlurQuality,
+  BlurViewProps,
+  BlurViewRef,
+} from './types';
+export { BlurPresets } from './presets';
+export type { BlurPreset, BlurPresetName } from './presets';

package/src/pipeline/androidCalibration.ts

@@ -0,0 +1,64 @@
+/**
+ * Android RenderEffect calibration (plan §5.2).
+ *
+ * INTERNAL MODULE. The single place the HWUI sigma<->radius relation lives on
+ * the TypeScript side; the Kotlin `AndroidBlurCalibration` must mirror it
+ * exactly. Verified on a Pixel 6a (API 36) in M0: radiusForSigma(10) exactly
+ * equals 16.454486... (matching the on-device measurement 16.45449).
+ *
+ * Relation (HWUI):  sigma = SLOPE * radiusPlatform + INTERCEPT
+ * Inverse:          radiusPlatform = (sigma - INTERCEPT) / SLOPE
+ *
+ * When sigmaSnapshot <= INTERCEPT (0.5) the inverse is non-positive, so we
+ * clamp to a no-blur passthrough rather than feeding a bogus radius to
+ * RenderEffect.createBlurEffect (plan §5.2 "no-op blur" for very small sigma).
+ */
+
+import {
+  ANDROID_MIN_BLUR_SIGMA,
+  HWUI_SIGMA_INTERCEPT,
+  HWUI_SIGMA_SLOPE,
+} from './constants';
+
+export interface AndroidBlurParam {
+  /** True when the requested blur collapses to a no-op passthrough. */
+  noBlur: boolean;
+  /**
+   * Platform radius to pass to RenderEffect.createBlurEffect. 0 when noBlur.
+   * Always >= 0.
+   */
+  radiusPlatform: number;
+}
+
+/**
+ * Forward relation, exposed for tests/verification: the sigma that HWUI
+ * produces for a given platform radius.
+ */
+export function sigmaForRadius(radiusPlatform: number): number {
+  return 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.
+ */
+export function radiusForSigma(sigmaSnapshot: number): AndroidBlurParam {
+  if (!Number.isFinite(sigmaSnapshot) || sigmaSnapshot <= ANDROID_MIN_BLUR_SIGMA) {
+    return { noBlur: true, radiusPlatform: 0 };
+  }
+  return {
+    noBlur: false,
+    radiusPlatform: (sigmaSnapshot - HWUI_SIGMA_INTERCEPT) / HWUI_SIGMA_SLOPE,
+  };
+}
+
+/**
+ * iOS MPSImageGaussianBlur takes the snapshot-domain sigma directly (plan §5.3).
+ * Provided here for symmetry so both platform mappings live in the reference.
+ * Sigma at or below 0 means no blur.
+ */
+export function iosSigmaForSigma(sigmaSnapshot: number): number {
+  if (!Number.isFinite(sigmaSnapshot) || sigmaSnapshot <= 0) return 0;
+  return sigmaSnapshot;
+}

package/src/pipeline/captureRect.ts

@@ -0,0 +1,172 @@
+/**
+ * Capture-rect math (plan §7, §12).
+ *
+ * INTERNAL MODULE. All rectangles here are in TARGET-LOCAL DEVICE PIXELS unless
+ * a field/return is explicitly documented as snapshot pixels.
+ *
+ * Pipeline of this module:
+ *   1. supportMarginPx  — Gaussian support margin = ceil(K * sigmaPx)
+ *   2. expandCaptureRect — expand visible rect by margin, clamp to target bounds
+ *   3. snapshotRectFor   — map the clamped device-px rect into integer snapshot
+ *                          pixels (floor origin, ceil far edge = conservative
+ *                          cover)
+ *   4. cropRectFor       — the sub-region of the snapshot that maps back to the
+ *                          visible rect (fractional, snapshot px)
+ *   5. cropRectToViewPx  — inverse mapping used to prove round-tripping
+ *
+ * Rounding rule (LOCKED): in the snapshot domain the origin FLOORS and the far
+ * edge CEILS, so `size = ceil(farEdge/D) - floor(origin/D)`. This is the
+ * conservative reading of "floor for origin, ceil for size": it guarantees
+ * every device pixel of the clamped capture rect is covered by the snapshot
+ * rect, at the cost of at most one extra snapshot pixel per side. A naive
+ * `floor(origin), ceil(width)` would fail to cover the far edge and is NOT used.
+ */
+
+import { CAPTURE_SUPPORT_K } from './constants';
+import type { Downsample, Rect } from './types';
+
+/** Gaussian support margin in device px (plan §7): ceil(K * sigmaPx). */
+export function supportMarginPx(sigmaPx: number, k: number = CAPTURE_SUPPORT_K): number {
+  if (!Number.isFinite(sigmaPx) || sigmaPx <= 0) return 0;
+  return Math.ceil(k * sigmaPx);
+}
+
+/** Intersection of two rects; empty (zero-size) rect if they do not overlap. */
+export function intersectRect(a: Rect, b: Rect): Rect {
+  const x0 = Math.max(a.x, b.x);
+  const y0 = Math.max(a.y, b.y);
+  const x1 = Math.min(a.x + a.width, b.x + b.width);
+  const y1 = Math.min(a.y + a.height, b.y + b.height);
+  const width = Math.max(0, x1 - x0);
+  const height = Math.max(0, y1 - y0);
+  if (width === 0 || height === 0) {
+    return { x: x0, y: y0, width: 0, height: 0 };
+  }
+  return { x: x0, y: y0, width, height };
+}
+
+/**
+ * Expand the visible blur rect by the Gaussian support margin and clamp to the
+ * target bounds. Returns a float device-px rect (plan §7). The margin only
+ * covers content that exists inside the target; CLAMP handles the outer edge
+ * where the margin was cut off (plan §8).
+ */
+export function expandCaptureRect(
+  visibleRect: Rect,
+  targetBounds: Rect,
+  sigmaPx: number,
+  k: number = CAPTURE_SUPPORT_K
+): Rect {
+  const margin = supportMarginPx(sigmaPx, k);
+  const 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 (helper for downsample selection). */
+export function rectArea(r: Rect): number {
+  return r.width * r.height;
+}
+
+/**
+ * Map a clamped device-px capture rect into integer snapshot pixels for
+ * downsample factor D. Floor the origin, ceil the far edge (conservative
+ * cover). The returned rect is in SNAPSHOT PIXELS (indices), so its device-px
+ * footprint is `snapshotRect * D`.
+ */
+export function snapshotRectFor(captureRectPx: Rect, downsample: Downsample): Rect {
+  const x = Math.floor(captureRectPx.x / downsample);
+  const y = Math.floor(captureRectPx.y / downsample);
+  const farX = Math.ceil((captureRectPx.x + captureRectPx.width) / downsample);
+  const farY = Math.ceil((captureRectPx.y + captureRectPx.height) / downsample);
+  return { x, y, width: Math.max(0, farX - x), height: Math.max(0, farY - y) };
+}
+
+/**
+ * The fractional crop rect, in SNAPSHOT PIXELS, that selects the visible region
+ * out of the (larger) snapshot rect after blur. Because the snapshot origin was
+ * floored, the crop origin carries a fractional remainder in [0, 1) snapshot px
+ * which the upsample step resolves with bilinear sampling (plan §12).
+ *
+ *   cropX = visibleRect.x / D  -  snapshotRect.x
+ *   cropW = visibleRect.width / D
+ */
+export function cropRectFor(
+  visibleRect: Rect,
+  snapshotRect: Rect,
+  downsample: Downsample
+): Rect {
+  return {
+    x: visibleRect.x / downsample - snapshotRect.x,
+    y: visibleRect.y / downsample - snapshotRect.y,
+    width: visibleRect.width / downsample,
+    height: visibleRect.height / downsample,
+  };
+}
+
+/**
+ * Inverse of {@link cropRectFor}: map a snapshot-px crop rect back to
+ * target-local device px. Used to verify round-tripping (should recover the
+ * original visible rect within half a snapshot pixel = D/2 device px).
+ */
+export function cropRectToViewPx(
+  cropRect: Rect,
+  snapshotRect: Rect,
+  downsample: Downsample
+): Rect {
+  return {
+    x: (snapshotRect.x + cropRect.x) * downsample,
+    y: (snapshotRect.y + cropRect.y) * downsample,
+    width: cropRect.width * downsample,
+    height: cropRect.height * downsample,
+  };
+}
+
+export interface CapturePlan {
+  /** Input visible blur rect (target-local device px). */
+  visibleRect: Rect;
+  /** Gaussian support margin (device px). */
+  marginPx: number;
+  /** Expanded + clamped capture rect (target-local device px, float). */
+  captureRectPx: Rect;
+  /** Capture area used for downsample selection (device px^2). */
+  captureAreaPx: number;
+  /** Selected downsample factor. */
+  downsample: Downsample;
+  /** Integer snapshot-pixel rect to allocate/blur. */
+  snapshotRect: Rect;
+  /** Fractional snapshot-px crop rect selecting the visible region. */
+  cropRect: Rect;
+}
+
+/**
+ * Assemble the full capture plan for a given visible rect, target bounds,
+ * sigmaPx and pre-resolved downsample factor. Downsample resolution lives in
+ * downsample.ts and takes `captureAreaPx` from this same computation, so the
+ * caller sequences: expand -> area -> resolveDownsample -> buildCapturePlan.
+ */
+export function buildCapturePlan(
+  visibleRect: Rect,
+  targetBounds: Rect,
+  sigmaPx: number,
+  downsample: Downsample,
+  k: number = CAPTURE_SUPPORT_K
+): CapturePlan {
+  const marginPx = supportMarginPx(sigmaPx, k);
+  const captureRectPx = expandCaptureRect(visibleRect, targetBounds, sigmaPx, k);
+  const snapshotRect = snapshotRectFor(captureRectPx, downsample);
+  const cropRect = cropRectFor(visibleRect, snapshotRect, downsample);
+  return {
+    visibleRect,
+    marginPx,
+    captureRectPx,
+    captureAreaPx: rectArea(captureRectPx),
+    downsample,
+    snapshotRect,
+    cropRect,
+  };
+}

package/src/pipeline/color.ts

@@ -0,0 +1,66 @@
+/**
+ * Color parsing for the overlay prop.
+ *
+ * INTERNAL MODULE. Parses the subset of CSS color syntaxes React Native
+ * accepts for a string color prop into straight-alpha RGBA in [0,1]:
+ *   - 'transparent'
+ *   - #rgb / #rgba / #rrggbb / #rrggbbaa
+ *   - rgb(r,g,b) / rgba(r,g,b,a)   (r,g,b integer 0-255, a float 0-1)
+ *
+ * Any unrecognised value returns a fully-transparent color (no overlay), which
+ * is the documented default (plan §11). The native backends parse the same
+ * prop with their platform color parsers; this reference fixes the expected
+ * numeric result for parity fixtures.
+ */
+
+import type { RGBA } from './types';
+
+export const TRANSPARENT: RGBA = { r: 0, g: 0, b: 0, a: 0 };
+
+function clamp01(v: number): number {
+  return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+
+function hexPair(s: string): number {
+  return parseInt(s, 16) / 255;
+}
+
+/** Parse a color string into straight-alpha RGBA. Unrecognised -> transparent. */
+export function parseColor(input: string | null | undefined): RGBA {
+  if (input == null) return TRANSPARENT;
+  const s = input.trim().toLowerCase();
+  if (s === 'transparent') return TRANSPARENT;
+
+  if (s.startsWith('#')) {
+    const hex = s.slice(1);
+    if (hex.length === 3 || hex.length === 4) {
+      const r = hexPair(hex[0]! + hex[0]!);
+      const g = hexPair(hex[1]! + hex[1]!);
+      const b = hexPair(hex[2]! + hex[2]!);
+      const a = hex.length === 4 ? hexPair(hex[3]! + hex[3]!) : 1;
+      return { r, g, b, a };
+    }
+    if (hex.length === 6 || hex.length === 8) {
+      const r = hexPair(hex.slice(0, 2));
+      const g = hexPair(hex.slice(2, 4));
+      const b = hexPair(hex.slice(4, 6));
+      const a = hex.length === 8 ? hexPair(hex.slice(6, 8)) : 1;
+      return { r, g, b, a };
+    }
+    return TRANSPARENT;
+  }
+
+  const m = s.match(/^rgba?\(([^)]+)\)$/);
+  if (m) {
+    const parts = m[1]!.split(',').map((p) => p.trim());
+    if (parts.length === 3 || parts.length === 4) {
+      const r = clamp01(parseFloat(parts[0]!) / 255);
+      const g = clamp01(parseFloat(parts[1]!) / 255);
+      const b = clamp01(parseFloat(parts[2]!) / 255);
+      const a = parts.length === 4 ? clamp01(parseFloat(parts[3]!)) : 1;
+      if ([r, g, b, a].every((v) => Number.isFinite(v))) return { r, g, b, a };
+    }
+  }
+
+  return TRANSPARENT;
+}

package/src/pipeline/constants.ts

@@ -0,0 +1,65 @@
+/**
+ * Locked calibration constants for the canonical pipeline.
+ *
+ * INTERNAL MODULE. These are the single source of truth for the reference
+ * implementation. Native backends must mirror these exact values. Per the
+ * plan (§5.2, §38) constants remain provisional until the parity milestone,
+ * but M0 device verification already confirmed the HWUI relation on API 36.
+ */
+
+/**
+ * HWUI RenderEffect Gaussian relation, verified exact on a Pixel 6a (API 36)
+ * in M0: `sigma = HWUI_SIGMA_SLOPE * radiusPlatform + HWUI_SIGMA_INTERCEPT`.
+ * Isolated here so a future version-aware calibration can override it in one
+ * place (plan §5.2). Do NOT inline these anywhere else.
+ */
+export const HWUI_SIGMA_SLOPE = 0.57735;
+export const HWUI_SIGMA_INTERCEPT = 0.5;
+
+/**
+ * Below this snapshot-domain sigma the Android RenderEffect relation inverts
+ * to a non-positive radius, so we emit a no-blur passthrough instead. Equal to
+ * HWUI_SIGMA_INTERCEPT by construction (radius 0 <=> sigma 0.5).
+ */
+export const ANDROID_MIN_BLUR_SIGMA = HWUI_SIGMA_INTERCEPT;
+
+/** Gaussian support multiplier for capture expansion (plan §7). */
+export const CAPTURE_SUPPORT_K = 3;
+
+/**
+ * Auto-downsample: target lower bound on snapshot-domain sigma. Keeping
+ * sigmaSnapshot at or above this prevents over-downsampling that would make
+ * the kernel degenerate (plan §12). 1 snapshot px.
+ */
+export const MIN_SIGMA_SNAPSHOT = 1.0;
+
+/**
+ * Auto-downsample: captures with area (device px^2) below this are considered
+ * "small" and are never downsampled beyond 2x — aggressive reduction of a tiny
+ * region buys no meaningful performance while degrading quality.
+ * 256 * 256 device px.
+ */
+export const SMALL_CAPTURE_AREA_PX = 256 * 256;
+
+/**
+ * Auto-downsample: per-quality ceiling on the downsample factor (plan §13).
+ *   high        -> prefer 1x or 2x
+ *   balanced    -> prefer 2x or 4x
+ *   performance -> prefer 4x or 8x
+ */
+export const QUALITY_MAX_DOWNSAMPLE: Record<
+  'high' | 'balanced' | 'performance',
+  1 | 2 | 4 | 8
+> = {
+  high: 2,
+  balanced: 4,
+  performance: 8,
+};
+
+/**
+ * Rec. 709 luminance coefficients (plan §10). Sum to 1.0. Used for the
+ * saturation matrix on both platforms.
+ */
+export const LUMA_R = 0.2126;
+export const LUMA_G = 0.7152;
+export const LUMA_B = 0.0722;

package/src/pipeline/downsample.ts

@@ -0,0 +1,74 @@
+/**
+ * Auto downsample selection (plan §12, §13).
+ *
+ * INTERNAL MODULE. Deterministic function of (sigmaPx, captureAreaPx, quality)
+ * -> D in {1,2,4,8}. Both backends must select identically for identical input.
+ *
+ * The chosen factor is the largest allowed value that satisfies ALL of three
+ * independent ceilings, then snapped down to a real factor in {1,2,4,8}:
+ *
+ *   1. quality ceiling   — QUALITY_MAX_DOWNSAMPLE[quality]
+ *   2. sigma floor        — keep sigmaSnapshot = sigmaPx / D >= MIN_SIGMA_SNAPSHOT,
+ *                            i.e. D <= floor(sigmaPx / MIN_SIGMA_SNAPSHOT)
+ *   3. area ceiling       — tiny captures (< SMALL_CAPTURE_AREA_PX) never exceed 2x
+ *
+ * See docs/PIPELINE_SPEC.md for the locked decision table.
+ */
+
+import {
+  MIN_SIGMA_SNAPSHOT,
+  QUALITY_MAX_DOWNSAMPLE,
+  SMALL_CAPTURE_AREA_PX,
+} from './constants';
+import type { BlurDownsample, BlurQuality, Downsample } from './types';
+import { DOWNSAMPLE_FACTORS } from './types';
+
+/** Largest allowed factor in {8,4,2,1} that is <= cap (never below 1). */
+function largestFactorAtMost(cap: number): Downsample {
+  for (const factor of DOWNSAMPLE_FACTORS) {
+    if (factor <= cap) return factor;
+  }
+  return 1;
+}
+
+/**
+ * Resolve the auto-selected downsample factor.
+ *
+ * @param sigmaPx      device-pixel sigma (blurRadius * displayScale)
+ * @param captureAreaPx expanded capture area in device px^2
+ * @param quality      quality tier
+ */
+export function autoDownsample(
+  sigmaPx: number,
+  captureAreaPx: number,
+  quality: BlurQuality
+): Downsample {
+  // No blur requested -> never downsample.
+  if (!Number.isFinite(sigmaPx) || sigmaPx <= 0) return 1;
+
+  const maxByQuality = QUALITY_MAX_DOWNSAMPLE[quality];
+
+  // Sigma floor: keep snapshot sigma at/above the minimum useful value.
+  const maxBySigma = Math.floor(sigmaPx / MIN_SIGMA_SNAPSHOT);
+
+  // Area ceiling: small captures are capped at 2x.
+  const area = Number.isFinite(captureAreaPx) ? captureAreaPx : 0;
+  const maxByArea = area < SMALL_CAPTURE_AREA_PX ? 2 : 8;
+
+  const cap = Math.min(maxByQuality, maxBySigma, maxByArea);
+  return largestFactorAtMost(cap);
+}
+
+/**
+ * Resolve a public `downsample` prop to a concrete factor. An explicit numeric
+ * value is honoured verbatim; 'auto' delegates to {@link autoDownsample}.
+ */
+export function resolveDownsample(
+  prop: BlurDownsample,
+  sigmaPx: number,
+  captureAreaPx: number,
+  quality: BlurQuality
+): Downsample {
+  if (prop === 'auto') return autoDownsample(sigmaPx, captureAreaPx, quality);
+  return prop;
+}

package/src/pipeline/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Canonical pipeline reference implementation — INTERNAL barrel.
+ *
+ * This module is the executable form of docs/PIPELINE_SPEC.md: pure TypeScript,
+ * no react-native imports, no side effects. Native backends (Kotlin / Swift)
+ * must reproduce these exact rules.
+ *
+ * IMPORTANT: this barrel is intentionally NOT re-exported from src/index.ts.
+ * It is a spec/testing artifact, not part of the package's public API.
+ */
+
+export * from './types';
+export * from './constants';
+export * from './units';
+export * from './androidCalibration';
+export * from './downsample';
+export * from './captureRect';
+export * from './saturation';
+export * from './color';
+export * from './overlay';

package/src/pipeline/overlay.ts

@@ -0,0 +1,46 @@
+/**
+ * Overlay source-over compositing (plan §11).
+ *
+ * INTERNAL MODULE. The overlay color (straight alpha, parsed from the prop) is
+ * the SOURCE; the saturated blur result is the DESTINATION. Applied AFTER
+ * saturation, BEFORE final clipping (plan §6 step 10). This is the only tint in
+ * the pipeline — no hidden platform tint is permitted.
+ *
+ * Straight-alpha (non-premultiplied) source-over, per channel:
+ *
+ *   outA = srcA + dstA * (1 - srcA)
+ *   outC = (srcC*srcA + dstC*dstA*(1 - srcA)) / outA    (outA > 0)
+ *          0                                             (outA = 0)
+ *
+ * In v1 the capture surface is an opaque backdrop, so dstA = 1 and this reduces
+ * to the familiar linear blend  outC = srcC*srcA + dstC*(1 - srcA), outA = 1.
+ * The general form is implemented so the reference stays correct if a future
+ * version captures translucent backdrops.
+ */
+
+import type { RGBA } from './types';
+
+/**
+ * Source-over composite of a straight-alpha source over a straight-alpha
+ * destination. Returns straight-alpha RGBA.
+ */
+export function sourceOver(src: RGBA, dst: RGBA): RGBA {
+  const outA = src.a + dst.a * (1 - src.a);
+  if (outA <= 0) return { r: 0, g: 0, b: 0, a: 0 };
+  const blend = (sc: number, dc: number) =>
+    (sc * src.a + dc * dst.a * (1 - src.a)) / outA;
+  return {
+    r: blend(src.r, dst.r),
+    g: blend(src.g, dst.g),
+    b: blend(src.b, dst.b),
+    a: outA,
+  };
+}
+
+/**
+ * Convenience: composite an overlay color over an opaque (alpha=1) blurred
+ * pixel — the v1 case. Equivalent to sourceOver(overlay, {..dst, a:1}).
+ */
+export function overlayOnOpaque(overlay: RGBA, dst: RGBA): RGBA {
+  return sourceOver(overlay, { r: dst.r, g: dst.g, b: dst.b, a: 1 });
+}

package/src/pipeline/saturation.ts

@@ -0,0 +1,65 @@
+/**
+ * Saturation color matrix (plan §10).
+ *
+ * INTERNAL MODULE. One canonical 4x5 color matrix (Android ColorMatrix layout:
+ * 4 output rows R,G,B,A; 5 columns R,G,B,A,offset) using Rec.709 luminance
+ * coefficients. Applied AFTER blur, BEFORE overlay (plan §6 step 9).
+ *
+ * For saturation s and luma coefficients (lr,lg,lb) with t = 1 - s:
+ *
+ *   R' = (t*lr + s)*R +  t*lg*G     +  t*lb*B
+ *   G' =  t*lr*R     + (t*lg + s)*G +  t*lb*B
+ *   B' =  t*lr*R     +  t*lg*G      + (t*lb + s)*B
+ *   A' = A
+ *
+ *   s = 1 -> identity;  s = 0 -> luminance grayscale;  s > 1 -> more saturated.
+ *
+ * The alpha row is untouched and there is no offset column (all offsets 0).
+ * The matrix operates on the same channel representation the backend blurs in
+ * (gamma-space, straight color for the opaque v1 backdrop). It does NOT itself
+ * premultiply — see docs/PIPELINE_SPEC.md §Color.
+ */
+
+import { LUMA_B, LUMA_G, LUMA_R } from './constants';
+
+/**
+ * Row-major 4x5 saturation matrix (20 numbers), matching Android's
+ * ColorMatrix and directly transcribable to a Metal 4x4 + bias.
+ */
+export function saturationMatrix(
+  s: number,
+  lr: number = LUMA_R,
+  lg: number = LUMA_G,
+  lb: number = LUMA_B
+): number[] {
+  const t = 1 - s;
+  return [
+    t * lr + s, t * lg, t * lb, 0, 0,
+    t * lr, t * lg + s, t * lb, 0, 0,
+    t * lr, t * lg, t * lb + s, 0, 0,
+    0, 0, 0, 1, 0,
+  ];
+}
+
+/**
+ * Apply a 4x5 saturation matrix to a straight-alpha RGBA tuple (channels in
+ * [0,1]). Returned RGB is clamped to [0,1]; alpha is passed through untouched.
+ * Reference for backend parity tests.
+ */
+export function applySaturation(
+  matrix: number[],
+  r: number,
+  g: number,
+  b: number,
+  a: number
+): { r: number; g: number; b: number; a: number } {
+  const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);
+  const m = matrix;
+  return {
+    // Indices per row-major 4x5 layout.
+    r: clamp01(m[0]! * r + m[1]! * g + m[2]! * b + m[3]! * a + m[4]!),
+    g: clamp01(m[5]! * r + m[6]! * g + m[7]! * b + m[8]! * a + m[9]!),
+    b: clamp01(m[10]! * r + m[11]! * g + m[12]! * b + m[13]! * a + m[14]!),
+    a: m[15]! * r + m[16]! * g + m[17]! * b + m[18]! * a + m[19]!,
+  };
+}

package/src/pipeline/types.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared value types for the canonical pipeline reference implementation.
+ *
+ * INTERNAL MODULE. Nothing here is re-exported from src/index.ts. These types
+ * describe the language-neutral contract that both native backends implement;
+ * they are the executable form of docs/PIPELINE_SPEC.md.
+ */
+
+import type { BlurDownsample, BlurQuality } from '../types';
+
+/** Integer downsample factor actually used by the pipeline (never 'auto'). */
+export type Downsample = 1 | 2 | 4 | 8;
+
+/** The four concrete downsample factors, largest first (selection order). */
+export const DOWNSAMPLE_FACTORS: readonly Downsample[] = [8, 4, 2, 1];
+
+/**
+ * Axis-aligned rectangle. Units are documented per-field by the producing
+ * function (device px in target-local space, or snapshot px). Origin is the
+ * top-left corner; width/height grow right/down.
+ */
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Straight-alpha RGBA colour, all channels normalised to [0, 1]. */
+export interface RGBA {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+export type { BlurDownsample, BlurQuality };

package/src/pipeline/units.ts

@@ -0,0 +1,32 @@
+/**
+ * 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';
+
+/**
+ * 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 function sigmaPxFromDp(blurRadiusDp: number, displayScale: number): number {
+  if (!Number.isFinite(blurRadiusDp) || blurRadiusDp <= 0) return 0;
+  if (!Number.isFinite(displayScale) || displayScale <= 0) return 0;
+  return blurRadiusDp * displayScale;
+}
+
+/**
+ * Convert device-pixel sigma to snapshot-domain sigma given a downsample
+ * factor D. D is a positive integer in {1,2,4,8}.
+ */
+export function sigmaSnapshotFromPx(sigmaPx: number, downsample: Downsample): number {
+  if (!Number.isFinite(sigmaPx) || sigmaPx <= 0) return 0;
+  return sigmaPx / downsample;
+}