feat: NonScalingOverlay translate-only marker overlay

.gitignore

@@ -40,6 +40,9 @@ android.iml
 #
 example/ios/Pods
 
+# Expo Go is the deploy path; example/ios/ is regenerable prebuild output.
+example/ios/
+
 # node.js
 #
 node_modules/

SPECS.md

@@ -38,8 +38,8 @@ Exported from `src/index.tsx`:
 - `ReactNativeZoomableViewProps` — prop type
 - `ReactNativeZoomableViewRef` — imperative handle
 - `ZoomableViewEvent` — `{ zoomLevel, offsetX, offsetY, originalWidth, originalHeight }`
-- `useZoomableViewContext()` — hook returning `{ zoom, inverseZoom, inverseZoomStyle, offsetX, offsetY }` for descendants
-- `FixedSize` — wrapper that keeps absolutely-positioned children at constant visual size regardless of zoom
+- `useZoomableViewContext()` — hook returning `{ zoom, offsetX, offsetY }` for descendants
+- `NonScalingOverlay` — translate-only overlay component; markers position via `left: 'X%' / top: 'Y%'` and render at 1:1 screen size at every zoom level. Typically used via the `renderOverlay` prop on `ReactNativeZoomableView`; can also be mounted manually with explicit `contentWidth`/`contentHeight`/`wrapperWidth`/`wrapperHeight` numeric props plus SharedValue `zoom`/`offsetX`/`offsetY` (and optional `rotation`).
 - `applyContainResizeMode`, `getImageOriginOnTransformSubject`, `viewportPositionToImagePosition` — coordinate helpers
 
 ---
@@ -317,7 +317,7 @@ This major replaces the class-component PanResponder/Animated implementation wit
 ### New public exports
 
 - `useZoomableViewContext()`
-- `FixedSize`
+- `NonScalingOverlay` (with `renderOverlay` prop on `ReactNativeZoomableView` as the primary entry point)
 - `ReactNativeZoomableViewRef` typed imperative handle
 - `applyContainResizeMode`, `getImageOriginOnTransformSubject`, `viewportPositionToImagePosition`
 

example/App.tsx

@@ -1,5 +1,4 @@
 import {
-  FixedSize,
   ReactNativeZoomableView,
   ReactNativeZoomableViewRef,
 } from '@openspacelabs/react-native-zoomable-view';
@@ -27,12 +26,16 @@ import Animated, {
 } from 'react-native-reanimated';
 import { ReText } from 'react-native-redash';
 
-import { applyContainResizeMode } from '../src/helper/coordinateConversion';
 import { styles } from './style';
 
 const kittenSize = 800;
-const uri = `https://placekitten.com/${kittenSize}/${kittenSize}`;
-const imageSize = { width: kittenSize, height: kittenSize };
+// `placekitten.com` has been offline for an extended period. Lorem Picsum
+// is the reliable drop-in (CDN-backed via Cloudflare, accepts the same
+// `/<W>/<H>` URL shape). Loses the cat theme — placecats.com is the
+// cat-themed alternative — but Picsum's reliability matters more for an
+// example app that needs to actually render the image on every fresh
+// install.
+const uri = `https://picsum.photos/${kittenSize}/${kittenSize}`;
 
 const stringifyPoint = (point?: { x: number; y: number }) =>
   point ? `${Math.round(point.x)}, ${Math.round(point.y)}` : 'Off map';
@@ -209,7 +212,22 @@ export default function App() {
   });
 
   const staticPinPosition = { x: size.width / 2, y: size.height / 2 };
-  const { size: contentSize } = applyContainResizeMode(imageSize, size);
+
+  // Capture the source dims via `onLoad` so the contents View can be
+  // sized to match the image's aspect ratio. With matching aspect, RN's
+  // resizeMode 'contain' produces zero letterbox — the rendered-pixel
+  // frame equals the element frame — and the contents View's onLayout
+  // gives `NonScalingOverlay` the exact `contentWidth`/`contentHeight`
+  // it needs (no separate `applyContainResizeMode` step).
+  const [imageSourceSize, setImageSourceSize] = useState<{
+    width: number;
+    height: number;
+  }>({ width: kittenSize, height: kittenSize });
+  const sourceAspect = imageSourceSize.width / imageSourceSize.height;
+  const [contentSize, setContentSize] = useState<{
+    width: number;
+    height: number;
+  }>({ width: 0, height: 0 });
 
   const Wrapper = modal ? PageSheetModal : View;
 
@@ -250,23 +268,102 @@ export default function App() {
             // Give these to the zoomable view so it can apply the boundaries around the actual content.
             // Need to make sure the content is actually centered and the width and height are
             // measured when it's rendered naturally. Not the intrinsic sizes.
-            contentWidth={contentSize?.width ?? 0}
-            contentHeight={contentSize?.height ?? 0}
+            contentWidth={contentSize.width}
+            contentHeight={contentSize.height}
+            renderOverlay={
+              showMarkers
+                ? () => {
+                    // Wrapper ≈ box minus its 5pt border each side. The
+                    // lib doesn't expose its `wrapperSize` directly, but
+                    // `box.width/height - 10` reproduces it on this
+                    // example. Used only for the debug HUD.
+                    const wrapperApproxW = Math.max(0, size.width - 10);
+                    const wrapperApproxH = Math.max(0, size.height - 10);
+                    return (
+                      <>
+                        {/* DEBUG: visualize the overlay's bounding box.
+                            Sized 100% × 100% of the overlay so it tracks
+                            contentSize × zoom and reveals where the
+                            translate-only overlay is actually painting on
+                            screen. Example-only — remove for production. */}
+                        <View style={styles.overlayDebugBox} />
+                        {/* DEBUG HUD pinned to overlay's top-left so it
+                            tracks the overlay's transform and provides
+                            the live numbers used by the translate math
+                            (translateX/Y at z=1, ox=oy=0). */}
+                        <Text style={styles.overlayDebugHud}>
+                          NSOL wW≈{Math.round(wrapperApproxW)} wH≈
+                          {Math.round(wrapperApproxH)} cW=
+                          {Math.round(contentSize.width)} cH=
+                          {Math.round(contentSize.height)} tXjs=
+                          {Math.round(
+                            wrapperApproxW / 2 - contentSize.width / 2
+                          )}{' '}
+                          tYjs=
+                          {Math.round(
+                            wrapperApproxH / 2 - contentSize.height / 2
+                          )}
+                        </Text>
+                        {[20, 40, 60, 80].map((left) =>
+                          [20, 40, 60, 80].map((top) => (
+                            <View
+                              key={`${left}x${top}`}
+                              style={[
+                                styles.marker,
+                                {
+                                  left: `${left}%`,
+                                  top: `${top}%`,
+                                },
+                              ]}
+                            />
+                          ))
+                        )}
+                      </>
+                    );
+                  }
+                : undefined
+            }
           >
-            <View style={styles.contents}>
-              <Image style={styles.img} source={{ uri }} />
-
-              {showMarkers &&
-                [20, 40, 60, 80].map((left) =>
-                  [20, 40, 60, 80].map((top) => (
-                    <FixedSize left={left} top={top} key={`${left}x${top}`}>
-                      <View style={styles.marker} />
-                    </FixedSize>
-                  ))
-                )}
+            <View
+              // `aspectRatio` constrains the contents View to the
+              // source's aspect, so resizeMode:contain produces zero
+              // letterbox — the element frame == the rendered-pixel
+              // frame. Combined with `maxWidth/maxHeight: '100%'` and
+              // `alignSelf: 'center'`, the element fits within the
+              // wrapper on whichever axis is binding (width on a tall
+              // wrapper, height on a wide wrapper) without overflow.
+              // `onLayout` then gives `NonScalingOverlay` the exact
+              // contentSize directly — no extra contain math required.
+              style={[styles.contents, { aspectRatio: sourceAspect }]}
+              onLayout={(e) => {
+                const { width, height } = e.nativeEvent.layout;
+                setContentSize((prev) =>
+                  prev.width === width && prev.height === height
+                    ? prev
+                    : { width, height }
+                );
+              }}
+            >
+              <Image
+                style={styles.img}
+                source={{ uri }}
+                onLoad={(e) => {
+                  const src = e.nativeEvent.source;
+                  setImageSourceSize((prev) =>
+                    prev.width === src.width && prev.height === src.height
+                      ? prev
+                      : { width: src.width, height: src.height }
+                  );
+                }}
+              />
             </View>
           </ReactNativeZoomableView>
         </View>
+        <Text>
+          DBG contentSize: {Math.round(contentSize.width)}×
+          {Math.round(contentSize.height)} box: {Math.round(size.width)}×
+          {Math.round(size.height)}
+        </Text>
         <Text>onStaticPinPositionChange: {stringifyPoint(pin)}</Text>
         <ReText text={movePinText} style={{ color: 'black' }} />
         <Button

example/package.json

@@ -21,7 +21,8 @@
     "react-native-gesture-handler": "~2.28.0",
     "react-native-reanimated": "~4.1.1",
     "react-native-redash": "18.1.5",
-    "react-native-web": "~0.21.0"
+    "react-native-web": "~0.21.0",
+    "react-native-worklets": "0.5.1"
   },
   "devDependencies": {
     "@babel/core": "^7.20.0",

example/style.ts

@@ -1,11 +1,22 @@
-import { StyleSheet } from 'react-native';
+import { Dimensions, StyleSheet } from 'react-native';
+
+// Box width must fit the device viewport. A fixed pt width (e.g. 480)
+// exceeds smaller screens (iPhone 12 Pro = 390pt), pushing part of the
+// rendered image off-screen. The overlay places dots as percentages of
+// contentSize (the rendered-image frame); when contentSize is wider
+// than the visible screen, dots at 20%/80% of content land at ~14%/86%
+// of what the user sees. `width: '100%'` doesn't work here because the
+// nested container chain uses `alignItems: 'center'`, which leaves the
+// parent's cross-axis intrinsic-sized — '100%' resolves to 0.
+// Subtracting 40 leaves a 20pt margin from each screen edge.
+const BOX_WIDTH = Dimensions.get('window').width - 40;
 
 export const styles = StyleSheet.create({
   box: {
     borderWidth: 5,
     flexShrink: 1,
     height: 600,
-    width: 480,
+    width: BOX_WIDTH,
   },
   container: {
     alignItems: 'center',
@@ -15,8 +26,18 @@ export const styles = StyleSheet.create({
     padding: 20,
   },
   contents: {
+    // `alignSelf: 'stretch'` anchors the cross-axis (width) to the
+    // parent's full width; the `aspectRatio` set inline at render time
+    // from the loaded image's source dims then derives the main-axis
+    // (height). Together they size the contents View to match the
+    // image's aspect exactly — resizeMode:contain produces zero
+    // letterbox, so the element frame == the rendered-pixel frame.
+    // The parent's `justifyContent: 'center'` centers it vertically.
+    // (Suitable when the child fits within the parent's main-axis at
+    // parent-width × aspect — true for the picsum square in 340×590.
+    // For arbitrary aspects, additionally clamp via
+    // `maxHeight: '100%'` and pre-compute the binding axis externally.)
     alignSelf: 'stretch',
-    flex: 1,
   },
   img: {
     height: '100%',
@@ -35,4 +56,31 @@ export const styles = StyleSheet.create({
     top: '50%',
     width: 20,
   },
+  // Example-only debug visualization for NonScalingOverlay's bounding
+  // box. Filling 100% × 100% of the overlay shows where the
+  // translate-only layer is actually painting — useful for verifying
+  // alignment at every zoom level. Not exported by the library.
+  overlayDebugBox: {
+    backgroundColor: 'rgba(255,0,0,0.18)',
+    borderColor: 'magenta',
+    borderWidth: 2,
+    bottom: 0,
+    left: 0,
+    position: 'absolute',
+    right: 0,
+    top: 0,
+  },
+  // Floating HUD anchored to the overlay's top-left corner — shows the
+  // wrapper / content / translate numbers used by NonScalingOverlay's
+  // transform math, so visual misalignment can be cross-checked against
+  // raw values without leaving the screen.
+  overlayDebugHud: {
+    backgroundColor: 'yellow',
+    color: 'black',
+    fontSize: 9,
+    left: 0,
+    position: 'absolute',
+    top: 0,
+    width: 280,
+  },
 });