feat: NonScalingOverlay translate-only marker overlay

[thomasttvo]

Adds NonScalingOverlay, a translate-only marker overlay sibling of the zoom subject — markers stay visually constant (no scale-comp work in consumer code) while still tracking the underlying content's translation. Replaces the old FixedSize model.

Key changes

• src/components/NonScalingOverlay.tsx (new) — translate-only overlay component
• src/components/StaticPin.tsx — built on the overlay; per-pin scale comp goes away
• src/components/FixedSize.tsx — removed (redundant after overlay lands)
• src/ReactNativeZoomableViewContext.tsx — drop inverseZoom / inverseZoomStyle (dead after FixedSize removal)
• example/ — Expo prebuild hygiene, image source swap (placekitten → picsum), metro peer dedupe, container sizing via aspectRatio

Test Plan

• Example app: pinch / pan with default StaticPin — pin stays visually constant size at all zoom levels
• Example app: rotate, then pinch — pin tracks content translation without scale distortion
• Diana smoke test against this beta tarball (NonScalingOverlay used by Diana's pin overlay)

🤖 Generated with Claude Code

[cursor]

PR Summary

Medium Risk
Adds a new overlay rendering path tied into the zoom/pan transform pipeline and updates public docs/contracts around callbacks/worklets, which may affect consumers relying on prior overlay/static-pin and gesture callback behavior.

Overview
Adds NonScalingOverlay, a translate-only overlay that tracks pan/zoom (and optional rotation) while keeping overlay children at constant on-screen size, and wires it into ReactNativeZoomableView via the renderOverlay pattern.

Updates the public contract/docs (README.md, SPECS.md) to reflect the current Reanimated/RNGH implementation: worklet-thread callbacks (*Worklet), updated static-pin move callback (onStaticPinPositionMoveWorklet), ref method signatures (including moveStaticPinTo), and various naming/semantics clarifications.

Modernizes the Expo example to exercise the overlay/static-pin/worklet APIs (including modal usage), adds the Reanimated Babel plugin, improves Metro peer-dependency deduping when aliasing src/, upgrades example dependencies, and tightens repo hygiene (ignore regenerated example/ios).

^{Reviewed by Cursor Bugbot for commit 8d9151b. Configure here.}

[thomasttvo]

@claude review once

[claude]

🔴 NonScalingOverlay: useAnimatedStyle's explicit deps array [contentWidth, contentHeight, wrapperWidth, wrapperHeight] omits rotation, but the worklet reads rotationValue.value (= rotation ?? zeroRotation). Consumers who toggle the optional rotation prop between undefined and a SharedValue — a pattern explicitly enabled by the JSDoc and SPECS.md L42 — silently freeze rotation at 0 because no listed dep changes, so the worklet is never re-created. Fix: include rotation (the prop reference) in the deps array.

Extended reasoning...

What goes wrong

NonScalingOverlay.tsx:99-103 passes an explicit deps array to useAnimatedStyle:

const overlayStyle = useAnimatedStyle(() => {
  const z = zoom.value;
  const ox = offsetX.value;
  const oy = offsetY.value;
  const r = rotationValue.value;
  ...
}, [contentWidth, contentHeight, wrapperWidth, wrapperHeight]);

An explicit deps array overrides Reanimated/Babel's auto-detection — only the listed values control when the worklet is re-serialized to the UI thread. SharedValue auto-tracking subscriptions are established at worklet-creation time, so whichever SharedValue is read in the captured worklet body is the one Reanimated subscribes to.

The worklet reads from rotationValue, which is derived per render at line 80:

const zeroRotation = useSharedValue(0);
const rotationValue = rotation ?? zeroRotation;

Neither rotation nor rotationValue is in the deps array.

Step-by-step proof

Consider a consumer using the documented pattern (the rotation prop is public per SPECS.md L42 and the JSDoc on NonScalingOverlayProps.rotation):

const [rotationOn, setRotationOn] = useState(false);
const rotSv = useSharedValue(0);

<NonScalingOverlay
  rotation={rotationOn ? rotSv : undefined}
  zoom={zoom} offsetX={offsetX} offsetY={offsetY}
  contentWidth={cw} contentHeight={ch}
  wrapperWidth={ww} wrapperHeight={wh}
/>

1. Mount with rotationOn=false. rotation is undefined, so rotationValue = zeroRotation. The worklet is created closing over zeroRotation; Reanimated subscribes to zeroRotation (which never changes).
2. User flips rotationOn to true (no content/wrapper resize). rotation is now rotSv, so on this render rotationValue = rotSv. None of [contentWidth, contentHeight, wrapperWidth, wrapperHeight] changed, so the worklet is not re-created — the UI thread keeps executing the original body which still references the captured zeroRotation.
3. Consumer animates rotSv.value via gesture or withTiming. Reanimated is not subscribed to rotSv (auto-tracking was on zeroRotation), so the worklet does not re-run. The overlay's rotate transform stays at 0rad.
4. Symmetrically, swapping SharedValue identity (rotation={enabled ? svA : svB}) suffers the same fate — the worklet keeps the original SharedValue binding regardless of swap.

Why existing code doesn't prevent it

The zeroRotation = useSharedValue(0) indirection was introduced specifically to make the transform list shape identical in the rotated/non-rotated cases (per the JSDoc comment at line 75-78), but it has the side effect that rotationValue is always a fresh local binding rather than the prop itself. There is no useLayoutEffect mirroring the prop into a stable inner SharedValue either.

The in-tree call site at ReactNativeZoomableView.tsx:1736-1744 does not pass rotation, so the library's own renderOverlay path is unaffected — but the prop is exported (NonScalingOverlayProps from src/index.tsx) and SPECS.md L42 explicitly documents manual mounting with (and optional rotation). A first-party consumer hitting this would observe a silent failure with no error.

Fix

Include rotation (the prop itself, treating undefined as a sentinel) in the deps array:

}, [contentWidth, contentHeight, wrapperWidth, wrapperHeight, rotation]);

rotation is either undefined or a stable SharedValue reference, so this only invalidates the worklet at the toggle/swap moment — not per gesture frame. Alternative: mirror the prop into a single inner useSharedValue and update it via useLayoutEffect whenever the prop reference changes; the worklet would then always close over the same stable SharedValue.

Severity

Normal — this is a new public-API correctness bug introduced by this PR. The in-tree usage doesn't exercise it, but rotation is a documented, exported, optional prop and the toggle/swap pattern is the natural way a consumer would gate rotation on user input.

[claude]

🟡 The example app ships debug-only visualizations the author themselves flagged for removal: overlayDebugBox (red 18%-opacity rect with magenta border), overlayDebugHud (yellow text overlay with raw transform math), and a DBG contentSize: Text line below the zoomable view — all with comments saying "Example-only — remove for production". Separately, the inline comment on the contents View (around lines 320-336) describes maxWidth/maxHeight: '100%' and alignSelf: 'center' styles that don't exist anywhere — styles.contents only sets alignSelf: 'stretch', and the style.ts comment is the accurate one. Either delete the debug surfaces and fix the comment before merge, or gate them behind a __DEV__ toggle.

Extended reasoning...

Two cleanup items in example/App.tsx, both example-only

1. Debug surfaces marked "remove for production" still ship unconditionally

Three debug-only render outputs are committed:

• example/App.tsx:288-289 — <View style={styles.overlayDebugBox} />, immediately preceded by the comment /* DEBUG: visualize the overlay's bounding box. ... Example-only — remove for production. */. The style itself (example/style.ts:60-72) is a magenta-bordered, 18%-opacity red rect filling the overlay; its own comment reads Example-only debug visualization for NonScalingOverlay's bounding box. ... Not exported by the library.
• example/App.tsx:290-306 — yellow overlayDebugHud Text pinned to the overlay's top-left, displaying raw transform math: NSOL wW≈… wH≈… cW=… cH=… tXjs=… tYjs=…. Style at example/style.ts:73-85.
• example/App.tsx:362-366 — <Text>DBG contentSize: …×… box: …×…</Text> rendered below the zoomable view (outside the showMarkers gate — it always renders).

The overlay debug surfaces are gated only by showMarkers, which is a user-facing toggle defaulting to true. The DBG Text below has no gate at all.

2. App.tsx contents-View comment contradicts the actual styles

example/App.tsx:320-336 (the comment on the contents <View>) describes the layout strategy as:

Combined with maxWidth/maxHeight: '100%' and alignSelf: 'center', the element fits within the wrapper on whichever axis is binding…

But example/style.ts:28-41 (styles.contents) only sets alignSelf: 'stretch'. There is no maxWidth, no maxHeight, and alignSelf is stretch, not center. The only inline override applied at use time is { aspectRatio: sourceAspect }. The neighboring style.ts comment (alignSelf: 'stretch' anchors cross-axis, aspectRatio derives main-axis, parent's justifyContent: 'center' centers it vertically) is the accurate description — so the two comments actively contradict each other.

Step-by-step proof

Take example/App.tsx at HEAD on this branch, render in a simulator with default props (showMarkers = true, the initial state on line 196):

1. renderOverlay fires the truthy branch (line 273-330).
2. The overlay tree contains <View style={styles.overlayDebugBox} /> — a magenta-bordered, red 18%-opacity rectangle fills the entire overlay region.
3. <Text style={styles.overlayDebugHud}>NSOL wW≈… cH=…</Text> paints a yellow band of debug math across the top of the image.
4. Below the zoom box, <Text>DBG contentSize: …×… box: …×…</Text> renders unconditionally — flipping showMarkers off does not hide it.

For the comment mismatch: grep -n 'maxWidth\|maxHeight\|alignSelf' example/style.ts returns exactly one match — alignSelf: 'stretch' inside styles.contents. The strings maxWidth, maxHeight, and alignSelf: 'center' cited by the App.tsx comment do not appear anywhere in the file.

Why this is "nit" severity

This is the example app, not library source — published consumers are unaffected. The library exports NonScalingOverlay and the renderOverlay prop; the debug rectangles, HUD, and DBG line live in the consumer-side demo and never reach the npm artifact. But the example app is the library's primary public demo ("Example app: pinch / pan with default StaticPin" appears in this PR's own test plan), and the author's own "Example-only — remove for production" annotation is the strongest possible evidence the items are unintentional carryover from development.

Fix

Either:

• Delete the three debug surfaces (App.tsx:288-306, App.tsx:362-366) and the two style entries (style.ts:56-85) before merge, OR
• Wrap each in an if (__DEV__ && debug) (or a dedicated state toggle distinct from showMarkers) so the default demo experience is clean.

Either way, update the App.tsx contents-View comment (lines 320-336) to match what's actually applied — drop the maxWidth/maxHeight / alignSelf: center description and reference the same alignSelf: stretch + aspectRatio explanation that the style.ts comment already gives.

[claude]

🟡 NonScalingOverlay early-return guard misses wrapper dimensions. The check at src/components/NonScalingOverlay.tsx:108 only short-circuits on !contentWidth || !contentHeight, but the transform math (wrapperW/2 - z*contentW/2, wrapperH/2 - z*contentH/2) is equally sensitive to wrapper dimensions — when those are still 0 (between mount and the wrapper's onLayout firing), the overlay paints one frame at (-contentW/2, -contentH/2) (off the top-left) before settling. Fix: extend the guard to all four — if (!contentWidth || !contentHeight || !wrapperWidth || !wrapperHeight) return null;

Extended reasoning...

What the bug is

NonScalingOverlay's early-return guard at src/components/NonScalingOverlay.tsx:108 is asymmetric with the transform math it is supposed to protect:

transform: [
  { translateX: wrapperWidth / 2 - (z * contentWidth) / 2 },
  { translateY: wrapperHeight / 2 - (z * contentHeight) / 2 },
  { rotate: `${r}rad` },
  { translateX: z * ox },
  { translateY: z * oy },
],
// ...
if (!contentWidth || !contentHeight) return null;

The author's own comment on lines 105-107 articulates the invariant correctly — "real dimensions" (plural) are required — but the guard only enforces it for half the inputs. When wrapperWidth/wrapperHeight are 0 but contentWidth/contentHeight have non-zero values, the worklet runs and the first two translates collapse to -(z*contentW)/2 and -(z*contentH)/2, painting the overlay roughly half its width and half its height off the top-left for one frame before re-rendering with the real wrapper dims.

Why existing code doesn't prevent it

In src/ReactNativeZoomableView.tsx (~L82), wrapperSize initializes as { width: 0, height: 0 } and only updates when the wrapper View's onLayout fires. NonScalingOverlay is mounted at L1734 with wrapperWidth={wrapperSize.width} / wrapperHeight={wrapperSize.height} and contentWidth={propContentWidth ?? 0} / contentHeight={propContentHeight ?? 0}. The documented public-API pattern (per SPECS.md and the JSDoc on NonScalingOverlayProps) lets a consumer pass contentWidth/contentHeight as static numeric props, which means those values are non-zero on the very first render while wrapperSize is still {0, 0}. The guard at line 108 lets the render through; the worklet computes the misposition.

Step-by-step proof

Consumer code (matches the documented API):

<ReactNativeZoomableView
  contentWidth={500}
  contentHeight={500}
  renderOverlay={() => <Marker />}
>
  ...
</ReactNativeZoomableView>

1. Initial render of ReactNativeZoomableView: wrapperSize state = { width: 0, height: 0 } (declared on L82, never written yet).
2. NonScalingOverlay mounts with contentWidth=500, contentHeight=500, wrapperWidth=0, wrapperHeight=0, zoom.value=1, offsetX=offsetY=0.
3. Guard at L108 evaluates !500 || !500 → false || false → false — does not return null.
4. useAnimatedStyle worklet computes translateX = 0/2 - (1 * 500)/2 = -250, translateY = -250.
5. First commit paints the overlay 250pt off the top-left of the wrapper — visible as a one-frame flash before settling.
6. The wrapper's onLayout fires (a tick later), setWrapperSize({width: W, height: H}) runs, the next commit paints the overlay correctly.

Impact

A one-frame flash on initial mount (and on any wrapper resize that lands wrapperSize to {0,0} momentarily) for consumers who use the documented pattern of passing static contentWidth/contentHeight numeric props. The example app happens to mask this because it derives contentSize from a child View's onLayout (after the image loads), so contentSize is also {0,0} until well after wrapperSize lands — but consumers following the public-API docs (or driving the overlay from known image dimensions, animation source, etc.) hit it. Not a persistent bug, just a visual transient at mount.

Fix

One-line, matching the comment's own stated invariant:

if (!contentWidth || !contentHeight || !wrapperWidth || !wrapperHeight) return null;

[thomasttvo]

Test suite added (24 tests, 4 suites)

Added test infrastructure + 24 tests covering NonScalingOverlay and the renderOverlay integration surface — all 14 EC-NSO edge cases pulled from PR #151's review now have regression tests.

Commits:

• e76d21f chore(test): add jest + RTL + reanimated mock infra
• d41f10d refactor(NonScalingOverlay): extract computeOverlayTransform + unit tests
• 0ae8f80 test(NonScalingOverlay): component tests for EC-NSO-1, 2, 7, 8, 9 (also contains the CI test-step addition + the ## NonScalingOverlay contract section in SPECS.md — commit message under-reports the content; see diff for full picture)
• a22d18e test(RNZV): renderOverlay integration tests for EC-NSO-10–14

Coverage map:

Layer	Tests	Edge cases
computeOverlayTransform unit	9	EC-NSO-3, 4, 5, 6 + numerics
<NonScalingOverlay> component (RTL + reanimated/mock)	9	EC-NSO-1, 2, 7, 8, 9
ReactNativeZoomableView.renderOverlay integration (RTL + RNGH mock)	6	EC-NSO-10, 11, 12, 13, 14

Test infra:

• Jest 29, @testing-library/react-native v12, react-test-renderer@18.3.1, react-native-reanimated/mock, RNGH jestSetup + inline RNGH mock for ReactNativeZoomableView integration imports.
• New CI step in .github/workflows/lint.yml: yarn test --ci --runInBand.
• SPECS.md now has a ## NonScalingOverlay contract section codifying the prop shape, transform formula, static-style rules, mount-order rules, and wrapperSize mirror semantics.

Follow-up planned (separate commits, same PR): the rest of SPECS.md — gesture state machine, double-tap, zoom helpers, static-pin behavior, etc. Researcher is inventorying now.