react-native-smooth-clip-view 0.3.0 → 0.4.1

package/README.md

@@ -1,449 +1,198 @@
 # react-native-smooth-clip-view
 
-[![npm version](https://img.shields.io/npm/v/react-native-smooth-clip-view.svg)](https://www.npmjs.com/package/react-native-smooth-clip-view)
+Layout-free animated rounded clipping for React Native Fabric.
 
-https://github.com/user-attachments/assets/899235b3-de69-46d7-b6db-61bc54d80df8
-
-<sub>Card zoom and shared-element gallery transitions, captured at 60fps — [direct clip](https://github.com/kbrattli/react-native-smooth-clip-view/blob/main/docs/media/smooth-clip-demo.mp4).</sub>
-
-## High-performance geometry animations for React Native
+`SmoothClipView` is a fixed viewport. Its controller moves a rounded aperture
+inside that viewport using raw host-local coordinates. Content is clipped by the
+aperture, an optional outset shadow may extend outside the aperture, and the host
+finally crops both. A full-screen host therefore accepts screen coordinates
+directly, including negative and off-screen frames.
 
-`react-native-smooth-clip-view` lets you animate `x`, `y`, `width`, `height`, and `borderRadius` with Reanimated without triggering expensive layout work on every frame.
+Use this library when a transition needs streamed gesture updates followed by
+native-owned timing or spring motion without animating Yoga layout. A regular
+Reanimated `View` with `overflow: 'hidden'` remains the simpler choice when
+layout-thread work and interruption snapshots are not concerns.
 
-Instead of resizing the Yoga layout, `SmoothClipView` keeps a fixed footprint and updates only the native clipping layer. This makes geometry-heavy animations smooth and inexpensive—even for shared-element transitions, zoom transitions, expanding cards, reveals, sheets, maps, and media.
+## Demo
 
-Use it for transitions that previously struggled with performance when animating layout dimensions directly.
+https://github.com/user-attachments/assets/899235b3-de69-46d7-b6db-61bc54d80df8
 
 ## Requirements
 
-- React Native 0.86 or newer with the New Architecture enabled
+- React Native 0.86 or newer with the New Architecture
+- React 19.2 or newer
 - React Native Reanimated 4.5 or newer
-- React Native Worklets 0.10 or newer
-- iOS 16.4 or newer
-- Android API 33 or newer
-
-The package supports iOS and Android. React Native Web and the legacy Paper
-architecture are not supported; keep imports and rendered usage behind native
-platform boundaries.
-
-## Installation
-
-Available from [npm](https://www.npmjs.com/package/react-native-smooth-clip-view):
+- React Native Worklets 0.10.1 or newer
+- Android API 24 or newer
 
 ```sh
 npm install react-native-smooth-clip-view react-native-reanimated react-native-worklets
-```
-
-For iOS, install pods after adding the package:
-
-```sh
 cd ios && pod install
 ```
 
-Follow the Reanimated installation instructions for your React Native setup.
-Expo SDK 57 configures the required Babel plugin through `babel-preset-expo`.
-
-## Usage
+## One clip
 
 ```tsx
-import { useState } from 'react';
-import { Button, StyleSheet, View } from 'react-native';
 import {
-  type ClipGeometry,
+  ClipEasings,
   SmoothClipView,
-  createClipPresentation,
-  useSmoothClipDriver,
+  useSmoothClipController,
 } from 'react-native-smooth-clip-view';
 
-const initialClip: ClipGeometry = {
-  x: 120,
-  y: 180,
-  width: 80,
-  height: 80,
-  radius: 40,
-};
-
-export function ClipExample() {
-  const [expanded, setExpanded] = useState(false);
-  const driver = useSmoothClipDriver(
-    createClipPresentation(initialClip, -initialClip.x, -initialClip.y)
-  );
+function Reveal() {
+  const clip = useSmoothClipController({
+    clip: { x: 24, y: 80, width: 96, height: 96, radius: 24 },
+    contentTranslateX: -24,
+    contentTranslateY: -80,
+    contentScale: 1,
+  });
 
-  const toggle = () => {
-    const next = !expanded;
-    setExpanded(next);
-    const clip = next
-      ? { x: 0, y: 0, width: 320, height: 480, radius: 24 }
-      : initialClip;
-    void driver.react.animateTo(
-      createClipPresentation(clip, -clip.x, -clip.y),
+  const open = () => {
+    clip.react.animateTo(
+      {
+        clip: { x: 0, y: 0, width: 390, height: 844, radius: 0 },
+        contentTranslateX: 0,
+        contentTranslateY: 0,
+        contentScale: 1,
+      },
       {
         type: 'timing',
-        duration: 450,
-        controlPoints: [0.42, 0, 0.58, 1],
+        duration: 400,
+        controlPoints: ClipEasings.easeOutCubic,
       }
     );
   };
 
   return (
-    <View>
-      <SmoothClipView driver={driver} style={styles.host}>
-        <View style={styles.content} />
-      </SmoothClipView>
-      <Button title="Toggle clip" onPress={toggle} />
-    </View>
+    <SmoothClipView controller={clip} style={{ flex: 1 }}>
+      {/* screen-sized transition content */}
+    </SmoothClipView>
   );
 }
-
-const styles = StyleSheet.create({
-  host: { width: 320, height: 480 },
-  content: { width: 320, height: 480, backgroundColor: '#112743' },
-});
 ```
 
-The same driver can be passed to multiple hosts. One native registry update
-fans the presentation out to all mounted hosts. The original seven-scalar V1
-protocol remains unchanged; V2 adds per-corner radii, continuous curves, and
-centered content scale. Interactive updates avoid Yoga and ShadowTree commits.
+One controller may have one mounted host at a time. Sequential unmount and
+remount is supported. In development, mounting the same controller in two hosts
+throws an error.
 
-For transitions whose endpoint is known, let Core Animation interpolate on the
-render server:
+## Worklet API
 
-```tsx
-const expandFromReact = () =>
-  driver.react.animateTo(
-    createClipPresentation(
-      { x: 0, y: 0, width: 320, height: 480, radius: 24 },
-      0,
-      0
-    ),
-    {
-      type: 'timing',
-      duration: 450,
-      controlPoints: [0.42, 0, 0.58, 1],
-    }
-  );
-```
+Call `clip.ui` methods from a UI-runtime worklet:
 
-Native timing, spring, and keyframed transitions have no app callback between
-setup and completion on iOS. Core Animation interpolates the clip and content
-translation as one presentation. Android runs one C++ frame-loop driven by the
-vsync clock with registry fanout; outline calculation and invalidation still
-run on its UI thread. Springs are physically integrated per geometry channel
-and finish when they settle below sub-pixel thresholds on both platforms.
-Retargeting starts from visible state.
-
-Blocked-thread behavior: a blocked JS thread never stalls a running
-transition on either platform — no JS runs on the frame path. A blocked
-main thread stalls it on Android (the frame loop and the View property
-writes are main-thread-only by platform design; the RenderThread only
-replays what the main thread records) but not on iOS, where the render
-server advances installed Core Animations out of process. The Android
-behavior is not recoverable through public APIs — RenderThread-driven
-property animation (`RenderNodeAnimator`, what ripples use) is hidden API —
-and it is also the coherent choice for this library: parallel Reanimated
-content runs on the main thread on both platforms, so on Android the clip
-and its content stall and resume together, while on iOS a main-thread stall
-lets the natively animated channels keep moving past any Reanimated-driven
-ones.
-The same driver can be grabbed by a gesture without a visual jump:
+```ts
+clip.ui.setFrame(presentation);
 
-```tsx
-const gesture = Gesture.Pan()
-  .onStart(() => {
-    const visible = driver.ui.beginInteraction();
-    dragStart.value = visible.clip.height;
-  })
-  .onUpdate((event) => {
-    const clip = geometryForDrag(dragStart.value, event.translationY);
-    // Per-frame hot path: writes straight to native without SharedValue
-    // bookkeeping. Assigning driver.presentation.value also works.
-    driver.ui.setScalars(clip.x, clip.y, clip.width, clip.height, clip.radius, 0, 0);
-  })
-  .onEnd((event) => {
-    // The release event is fresher than the last onUpdate (on Android,
-    // ACTION_UP carries a position no MOVE ever delivered). Pass the final
-    // geometry as `from` so the animation starts from exactly that value —
-    // it fuses a setScalars hot write with the handoff in one call.
-    const clip = geometryForDrag(dragStart.value, event.translationY);
-    // 'inherit' projects launch speed from the drag's last two samples. On
-    // Android that sampling is opt-in — create the driver with
-    // useSmoothClipDriver(initial, { velocityTracking: true }).
-    driver.ui.animateTo(createClipPresentation(expandedClip), {
-      type: 'spring',
-      initialVelocity: 'inherit',
-      from: createClipPresentation(clip),
-    });
-  });
+const run = clip.ui.animateTo(target, spring, 1);
+
+clip.ui.cancel(run); // optional; freezes at the visible frame
 ```
 
-## API
-
-### `SmoothClipView`
-
-`SmoothClipViewProps` extends React Native `ViewProps` and adds:
-
-| Prop       | Type               | Description                             |
-| ---------- | ------------------ | --------------------------------------- |
-| `driver`   | `SmoothClipDriver` | Reusable hybrid clip driver.            |
-| `children` | `ReactNode`        | Content rendered inside the fixed host. |
-
-The host hides itself, drops out of the accessibility tree, and stops accepting
-touches while the clip is empty. The two platforms draw the boundary where they
-actually stop rendering, which differs below one pixel: Android emits an integer
-`Outline`, which collapses to nothing under half a physical pixel, so an extent
-in `(0, 0.5)` px counts as empty there; iOS masks in floats and treats only a
-zero-or-negative extent as empty. A clip animating through that band therefore
-turns non-interactive one frame earlier on Android — matching what each platform
-puts on screen, which is the property worth keeping identical.
-
-### Driver
-
-- `useSmoothClipDriver(initialPresentation, options)` returns one hybrid driver
-  whose writable `presentation` SharedValue contains clip geometry and content
-  translation. Passing a `ClipGeometry` remains supported and initializes both
-  translations to zero.
-- `driver.ui` is the synchronous UI-worklet interface. `beginInteraction()`
-  freezes a transition at visible presentation state; `set()`, `animateTo()`,
-  and `cancel()` change ownership atomically.
-- `driver.ui.setScalars(x, y, width, height, radius, tx, ty)` is the per-frame
-  hot path: it writes geometry straight to native without touching
-  `driver.presentation`, skipping SharedValue bookkeeping for high-frequency
-  streams such as gestures. `driver.presentation.value` is stale after hot
-  writes by design; `beginInteraction()` remains the source of truth for
-  visible geometry, and `animateTo()` after hot writes starts from the native
-  registry's latest value rather than the stale SharedValue. To start from a
-  value fresher than the last hot write (a gesture's release sample), pass it
-  as `animation.from` — `animateTo` then performs the hot write and the
-  handoff in one call. Do not interleave `setScalars` with
-  `presentation.value` writes on the same driver.
-- `driver.ui.setPresentationScalars(x, y, width, height, topLeft, topRight,
-  bottomRight, bottomLeft, curveCode, tx, ty, scale)` is the V2 hot path.
-  `curveCode` is `0` for circular and `1` for continuous. V2 values are
-  validated as one transaction; widened values are never silently downgraded
-  onto a V1 native binary.
-- Spring `initialVelocity` is one normalized scalar along the current-to-target
-  trajectory, in units of the remaining distance per second (`1` covers the
-  remaining distance in one second). Every geometry channel continues with the
-  same normalized rate, so grab/release preserves the felt direction and
-  speed. `'inherit'` (the default) estimates the scalar from the last two
-  interactive samples on iOS and Android. On Android, sampling on the
-  `setScalars` hot path is **opt-in**: pass
-  `velocityTracking: true` to `useSmoothClipDriver` or `'inherit'` inherits
-  zero after a hot-write drag (a dev-mode warning flags this). **Behavior
-  change:** earlier releases always recorded on Android, so an existing
-  `setScalars`-drag → inherit-spring handoff keeps its momentum only after
-  adding the flag. The recording
-  is a clock read plus channel copies on every per-frame write, so drivers
-  that never hand off into an inherit spring skip it by default. iOS always
-  records, and Android's declarative `presentation.value` channel always
-  records too. How long the finger has been still since that last sample scales the
-  result: full credit for one frame (16.7 ms), then a linear decay to zero at
-  100 ms. A release straight out of a drag is therefore untouched, and holding
-  still before releasing bleeds the momentum off smoothly instead of keeping
-  all of it until 99 ms and none at 101 ms. Two writes landing inside the same frame
-  (< 4 ms apart, e.g. a release-sample `from` seed right after the last drag
-  write) coalesce into one sample, and an identical re-write is ignored, so a
-  fused handoff can neither zero nor inflate the inherited velocity.
-  Only interactive writes contribute samples. Internal freeze/join/resume and
-  static-finalization writes do not, so grabbing a native animation cannot
-  manufacture velocity for a later `'inherit'` spring; a subsequent drag (or
-  explicit `animation.from`) supplies the release samples instead.
-- `driver.react` exposes `beginInteraction`, `set`, `animateTo`, and `cancel`
-  as Promises (`setScalars` is UI-worklet-only). React code never blocks
-  waiting for main/UI-thread work. An immediate animation request resolves
-  before its completion callback is delivered.
-- `animateTo()` transfers ownership to native animation. Timing uses
-  cubic Bézier control points — `ClipEasings` exports exact-form presets
-  (`easeOutCubic` = `Easing.out(Easing.cubic)` etc.) so a parallel Reanimated
-  animation can run the identical curve without hand-deriving it; springs
-  accept mass, stiffness, damping, and an
-  explicit normalized velocity or `'inherit'` (the default). Keyframes accept
-  validated, monotonically increasing offsets from zero through one; there is
-  deliberately no keyframe easing field — playback is linear between offsets
-  and the frames encode the curve, which also expresses per-channel-nonlinear
-  paths that no single time-warp could reproduce. Every
-  kind accepts an optional `from` presentation — a fused take-ownership hot
-  write issued immediately before the handoff, so the animation starts from
-  exactly that value (pass `frames[0].presentation` for keyframes, which
-  interpolate absolutely). A non-finite `from` rejects the whole call; against
-  a held pending-animation latch, explicit `from` is the newer intent: it
-  cancels that latch once with `finished: false`, records/applies `from`, then
-  starts the replacement from that native value. Passive hook seeds and public
-  `set`/`setScalars` writes still leave a held latch intact. `from` behaves the
-  same on both platforms (it is driver-layer, not native): on iOS the seed
-  stops any running Core Animation, applies `from` to the model layer, and
-  installs timing, spring, or keyframe playback from that exact presentation in
-  the same start transaction.
-- `cancel()` freezes visible presentation by default. Pass `'target'` as its
-  behavior to jump to the requested endpoint.
-- `options.onAnimationComplete` fires exactly once per animation with its ID
-  and `finished` state, including cancellation, replacement, and native-side
-  rejection (`animateTo` then returns a fresh non-zero id whose single
-  `finished: false` completion follows — key completion handling by the
-  returned id, never by `0`). A valid pre-registration request carries its
-  authoritative interactive start, creates the missing driver state and
-  returns a real id. `0` — with no completion — is reserved for off-main,
-  invalid-id, or otherwise unsupported dispatch: a missing-state native request
-  with no authoritative start, any `driver.ui.animateTo` issued after the
-  driver's hook has unmounted, and an invalid-parameter request issued before
-  the driver's first seed reached native (validation rejections mint their
-  `finished: false` completion only once the native entry exists). (The
-  post-unmount case is decided on the UI runtime,
-  because a destroyed driver and a not-yet-seeded one are the same missing
-  registry entry to native — accepting it would build a latch nothing can start
-  and nothing can cancel.) A host is displayable only while it is attached,
-  foreground/window-visible, laid out, and positive-sized (the window's own
-  `hidden`/scene state is not consulted — RN's single always-visible window
-  makes it moot). Losing the last
-  displayable host mid-flight — including temporary detach, zero-size layout,
-  or app background — freezes and re-latches the exact remainder instead of
-  consuming duration offscreen. Foreground/reattach resumes the same animation
-  ID from that stored timing/keyframe phase or spring state.
-  Parallel Reanimated clocks do **not** pause with it: a `withTiming` started
-  beside `animateTo` keeps its wall-clock start, so after backgrounding it
-  completes on its first resumed frame while the native run still animates its
-  preserved remainder. Key teardown and state transitions off
-  `onAnimationComplete` (or re-synchronize on `AppState`) rather than off a
-  duration-matched Reanimated callback.
-  With multiple hosts on one driver, a host becomes an installed participant
-  only after its native animation starts. Temporary loss moves it to suspended;
-  a rejoin restores active participation. Unregistering an installed/suspended
-  host, or reaching completion while it remains suspended, makes the eventual
-  completion `finished: false`. A host that stayed deferred because it was
-  detached, unlaid-out, or zero-sized never poisons completion. `finished: true`
-  means every installed participant either ran to the end or rejoined and did so.
-- An `animateTo` issued before any host view can produce a visible frame (for
-  example from an effect in the same commit that mounts the host, or inside a
-  modal route whose subtree attaches to its window late) is held pending and
-  starts with its full duration at the first moment a registered host can
-  produce a frame — positive layout, window attach/visibility, and foreground
-  state must all be present. This also covers an animation worklet that runs before the
-  hook's seed worklet: the animation creates the state and the later passive
-  seed cannot reset its ownership or active id. A pending animation owns the
-  driver: ordinary take-ownership writes (`set`, `setScalars`, the hook's seed)
-  are dropped while it is held. Replace it with another `animateTo`, override
-  it with an explicit `animation.from`, or cancel it via `beginInteraction()`
-  or `cancel()`. If no view ever becomes displayable, it survives until it is
-  replaced, cancelled, or the driver is destroyed — at which point its single
-  `finished: false` completion is delivered.
-
-Do not call `driver.ui` from React code — it throws on the React runtime; use
-`driver.react` there. During a native transition, `driver.presentation.value`
-is the requested target, not a per-frame mirror of the native presentation
-layer. `beginInteraction()` returns geometry normalized against the host
-bounds, so a clip that extended beyond the host comes back clamped. Start
-gestures with `beginInteraction()`: interactive writes issued while native
-still owns rendering are dropped.
-
-### Group driver
-
-`useSmoothClipGroupDriver({ reduceMotion, onAnimationComplete })` coordinates
-multiple drivers with one native group ID and one completion. Its worklet-safe
-`ui` and Promise-based `react` interfaces expose:
-
-- `beginInteraction(drivers)` to freeze every overlapping group atomically and
-  return canonical visible snapshots in input order.
-- `snapshotCurrent(drivers)` to sample presentation and readiness without
-  changing ownership.
-- `setBatch(entries)` to validate every entry before committing one native
-  transaction.
-- `animateTo(entries, animation)` for shared timing, spring, or linear
-  keyframe progress. Membership is immutable for that group ID; a replacement
-  is a new atomically installed group.
-- `cancel(groupId, 'freeze' | 'finish')` to return every participant snapshot.
-
-Groups wait until all participants have a visible, attached, laid-out,
-positive-size host. The default `suspensionPolicy: 'pause'` freezes and
-re-latches the whole group if any participant loses readiness; `'finish'`
-applies every target. Complex-path native settlement is capability-gated—use
-`getSmoothClipCapabilities()` and keep streaming with `setBatch` when
-`autonomousComplexPathAnimation` is false.
-
-### `SmoothClipPresentation`
+Native terminal events are delivered on the React JavaScript runtime through
+one stable controller callback. Consumer callbacks are never retained in the
+UI runtime:
 
 ```ts
-type SmoothClipPresentation = Readonly<{
-  clip: ClipGeometry;
-  contentTranslateX: number;
-  contentTranslateY: number;
-  contentScale?: number;
-}>;
+const clip = useSmoothClipController(initialPresentation, {
+  onAnimationComplete(result) {
+    // result.completionTag is 1 for the tagged run above
+    // result.finished is true only when the target was reached
+  },
+});
 ```
 
-Use the content translation fields when a clipped viewport must reveal a
-fixed-size child without a separate Reanimated transform. Native transitions
-animate clip position, bounds, radius, and content translation together.
+The optional completion tag is a nonnegative 32-bit integer. Use it to identify
+UI-runtime runs without retaining a consumer worklet for the animation lifetime.
 
-### `ClipGeometry`
+`setFrame` canonicalizes the object in the worklet and makes one scalar JSI call.
+It does not update React state, animated props, Yoga, the ShadowTree, or a public
+SharedValue.
 
-```ts
-type ClipGeometry = Readonly<{
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-  radius: number;
-  topLeftRadius?: number;
-  topRightRadius?: number;
-  bottomRightRadius?: number;
-  bottomLeftRadius?: number;
-  curve?: 'circular' | 'continuous';
-}>;
-```
+`beginInteraction()` atomically interrupts native motion and returns its visible
+raw presentation. Apply the final gesture sample with `setFrame()` before calling
+it when the release must start from that exact frame.
 
-Values use React Native points/DIPs. Native code rejects non-finite updates,
-intersects the requested rectangle with the actual host bounds, prevents
-negative sizes, and proportionally scales overlapping corners with the CSS
-corner-normalization rule. Content scale is centered on the native content
-container; translation is independent and is not multiplied by scale.
+## React API
 
-### `normalizeClipGeometry`
+React-thread animation starts synchronously return a run object:
 
-`normalizeClipGeometry(geometry, bounds)` mirrors the native normalization
-contract for tests and non-native calculations. Native bounds remain
-authoritative at render time.
+```ts
+const run = clip.react.animateTo(target, {
+  type: 'spring',
+  stiffness: 180,
+  damping: 22,
+  velocity: 1.4,
+});
 
-## Migrating from 0.0.x
+// run.cancel(); // optional; freezes the visible frame and resolves false
+const finished = await run.finished;
+```
 
-Version 0.1.0 removes the `initialClip` and `animatedClip` props in favor of
-the driver API: create a driver with `useSmoothClipDriver(initialPresentation)`,
-pass it as the `driver` prop, and move per-frame updates from the
-`animatedClip` SharedValue to `driver.presentation.value` (or
-`driver.ui.setScalars`). Autonomous transitions move from Reanimated
-`withTiming`/`withSpring` to `driver.ui.animateTo` / `driver.react.animateTo`.
+Timing accepts `duration` and cubic-Bezier `controlPoints`. Spring accepts
+optional `mass`, `stiffness`, `damping`, normalized `velocity`, and
+`energyThreshold`. Both specifications accept `reduceMotion`. The physical
+defaults match Reanimated 4.5: mass `4`, stiffness `900`, damping `120`, and
+relative energy threshold `6e-9`. A spring is rejected when its resolved native
+trajectory could make `contentScale` nonpositive.
 
-## Layout and styling contract
+An animation requested before the host has a positive layout waits, then starts
+with its full duration. Host loss after motion starts freezes every member and
+resolves the transaction `false`. Replacement, cancellation, destruction, and
+rejection also settle once with `false`.
 
-- Give the host its fixed maximum `width` and `height`; clipping never changes
-  Yoga layout.
-- Put visual backgrounds inside `SmoothClipView`.
-- Keep borders, shadows, rotation, and anisotropic transforms on an outer
-  visual carrier rather than the clip host.
-- Uniform circular corners use platform fast paths. Unequal or continuous
-  corners use a fixed-topology portable path; Android intentionally does not
-  claim pixel identity with Apple's proprietary continuous curve.
+## Atomic groups
 
-## Example and development
+Store `controller.ref` when multiple clips must update or settle atomically:
 
-The [`example`](./example) workspace is an Expo SDK 57 app that exercises the
-package through its public import on iOS and Android.
+```ts
+const group = useSmoothClipGroup();
 
-```sh
-npm install
-npm run example -- ios
-npm run example -- android
-```
+group.ui.setFrames([
+  { clip: first.ref, frame: firstFrame },
+  { clip: second.ref, frame: secondFrame },
+]);
 
-Run the repository checks with:
+const snapshots = group.ui.beginInteraction([first.ref, second.ref]);
 
-```sh
-npm run lint
-npm run typecheck
-npm test
-npm run prepare
+const run = group.react.animateTo(
+  [
+    { clip: first.ref, target: firstTarget },
+    { clip: second.ref, target: secondTarget },
+  ],
+  { type: 'timing', duration: 320, controlPoints: ClipEasings.easeOutCubic }
+);
+
+const result = await run.finished;
 ```
 
+`group.ui.setFrames` uses one native batch call. `beginInteraction` snapshots and
+cancel snapshots preserve input order and report whether each clip currently has
+a displayable host. Controllers are implemented as one-member groups, so both
+APIs share validation, run ownership, and completion behavior.
+
+## Geometry and rendering
+
+- `x` and `y` are never intersected with the host.
+- Negative width and height canonicalize to zero.
+- Corner-overlap scaling follows CSS rules against the requested rectangle.
+- `contentTranslateX`, `contentTranslateY`, and positive `contentScale` animate
+  with the aperture.
+- Circular and continuous curves and independent corner radii are supported.
+- One outset `boxShadow` is supported. It escapes the aperture but not the host.
+- A fully off-host aperture is not touchable, even when only its shadow overlaps.
+- Descendant accessibility is hidden during autonomous native motion and restored
+  from aperture/host intersection at the endpoint.
+
+Use `getSmoothClipCapabilities()` when a consumer needs to decide whether a
+complex native path can be promoted on the current platform.
+
+## Performance contract
+
+- One worklet-to-native call per `ui.setFrame`, or per group batch.
+- Native timing and springs run without JS work between start and completion.
+- The shadow-disabled rendering path keeps no shadow drawing resources.
+- The fixed host is the maximum rendering viewport; consumers should size it to
+  the region in which content and shadow may appear.
+
 ## License
 
 MIT

package/android/build.gradle

@@ -1,7 +1,7 @@
 buildscript {
   ext.SmoothClipView = [
     kotlinVersion: "2.0.21",
-    minSdkVersion: 33,
+    minSdkVersion: 24,
     compileSdkVersion: 36,
     targetSdkVersion: 36
   ]
@@ -76,14 +76,11 @@ android {
   }
 
   defaultConfig {
-    // Outline.setPath only guarantees arbitrary path clipping from API 33.
-    // Keep this as a hard library floor: allowing a consuming root project to
-    // override it lower would make the V2 per-corner/continuous path silently
-    // unsupported at runtime.
+    // API 24-32 clip child drawing directly; API 33+ use path outlines.
     minSdkVersion SmoothClipView.minSdkVersion
     targetSdkVersion getExtOrDefault("targetSdkVersion")
-    // C++ resolves SmoothClipView by name and calls setClipPresentationDip via
-    // a cached jmethodID; consumer minification must not rename or strip them.
+    // C++ resolves SmoothClipView by name and calls its presentation setters via
+    // cached jmethodIDs; consumer minification must not rename or strip them.
     consumerProguardFiles "proguard-rules.pro"
 
     externalNativeBuild {

package/android/proguard-rules.pro

@@ -1,6 +1,6 @@
 # SmoothClipView is resolved from C++ by name (fbjni findClassStatic) and its
-# V1/V2 setClipPresentation*Dip / setClipPresentation*Px are invoked through
-# cached jmethodIDs; SmoothClipBindings registers native methods by name. None
+# presentation setters are invoked through cached jmethodIDs;
+# SmoothClipBindings registers native methods by name. None
 # of them may be renamed or stripped in consumer release builds.
 -keep class com.smoothclipview.SmoothClipView { *; }
 -keep class com.smoothclipview.SmoothClipBindings { *; }